From 67716dc3ffa070d2460d88c75bc449a64e6c9042 Mon Sep 17 00:00:00 2001
From: "i.nueske" <i.nueske@indiscale.com>
Date: Wed, 30 Oct 2024 14:24:28 +0100
Subject: [PATCH] DOC: Update filter tutorial
---
src/doc/tutorials/complex_data_models.rst | 41 ++++++++++++-----------
1 file changed, 22 insertions(+), 19 deletions(-)
diff --git a/src/doc/tutorials/complex_data_models.rst b/src/doc/tutorials/complex_data_models.rst
index e2043ef1..b33bc9ae 100644
--- a/src/doc/tutorials/complex_data_models.rst
+++ b/src/doc/tutorials/complex_data_models.rst
@@ -91,39 +91,42 @@ entities. A short example:
r = db.Record()
p1 = db.Property(id=101, name="Property 1")
p2 = db.Property(id=102, name="Property 2")
- p3 = db.Property(name="Property")
+ p3_1 = db.Property(id=103, name="Property 3")
+ p3_2 = db.Property(id=103, name="Property 3")
p4 = db.Property(name="Property")
- r.add_property(p1).add_property(p2).add_property(p3).add_property(p4)
+ p5 = db.Property(name="Property")
+ r.add_property(p1).add_property(p2).add_property(p3_1)
+ r.add_property(p3_2).add_property(p4).add_property(p5)
properties = r.properties
# As r only has one property with id 101, this returns a list containing only p1
properties.filter(pid=101)
# Result: [p1]
- # Filtering with name="Property" returns both p3 and p4, as they share their name
+ # Filtering with name="Property" returns both p4 and p5, as they share their name
properties.filter(name="Property")
- # Result: [p3, p4]
+ # Result: [p4, p5]
# Filtering with name="Property 1" and id=102 returns both p1 and p2, because
# any property matching either criterion is returned:
properties.filter(name="Property 1", pid="102")
# Result: [p1, p2]
+ p6 = db.Property(name="Property 2")
+ r.add_property(p6)
# If we want to find properties matching one specific property, we can also filter using
- # the entity itself. In this case, only properties matching both name and id are returned:
- p5 = db.Property(name="Property 2")
- r.add_property(p5)
- properties.filter(p5)
- # Result: [p5]
- properties.filter(name=p5.name, pid=p5.id)
- # Result: [p2, p5], because p2 and p5 share a name
- properties.filter(p3)
- # Result: [p3, p4], because p3 and p4 share both their name and id
-
- # However, if you want to retrieve only instances of the property itself, this can be
- # done using the parameter check_equality, which enforces that all entities in the returned
- # list are equal to the parameter.
- properties.filter(p3, check_equality=True)
- # Result: [p3]
+ # the entity itself. In this case, only properties matching both name and id are returned,
+ # as long as both are set.
+ properties.filter(p2)
+ # Result: [p2]
+ # As p6 does not have an id yet, both candidates matching its name are returned
+ properties.filter(p6)
+ # Result: [p2, p6]
+ # Similarly if we match using name and id parameters, all candidates matching either are returned
+ properties.filter(name=p2.name, pid=p2.id)
+ # Result: [p2, p6], because p2 and p6 share a name
+ # And if both name and id match, there may also be several results when matching an entity
+ properties.filter(p3_1)
+ # Result: [p3_1, p3_2], because they share both their name and id
The filter function of ParentList works analogously.
--
GitLab