diff --git a/cognite/client/data_classes/filters.py b/cognite/client/data_classes/filters.py index 1dee70ec69..01629f3d5e 100644 --- a/cognite/client/data_classes/filters.py +++ b/cognite/client/data_classes/filters.py @@ -255,6 +255,14 @@ class And(CompoundFilter): Args: *filters (Filter): The filters to combine. + + + Example: + + Combine an In and an Equals filter:: + + >>> from cognite.client.data_classes.filters import And, Equals, In + >>> filter = And(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"])) """ _filter_name = "and" @@ -266,6 +274,13 @@ class Or(CompoundFilter): Args: *filters (Filter): The filters to combine. + + Example: + + Combine an In and an Equals filter:: + + >>> from cognite.client.data_classes.filters import Or, Equals, In + >>> filter = Or(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"])) """ _filter_name = "or" @@ -277,6 +292,13 @@ class Not(CompoundFilter): Args: filter (Filter): The filter to negate. + + Example: + + Negate an Equals filter: + + >>> from cognite.client.data_classes.filters import Or, Equals + >>> filter = Not(Equals(("some", "property"), 42)) """ _filter_name = "not" @@ -296,6 +318,15 @@ class Nested(Filter): scope (PropertyReference): The direct relation property to traverse. filter (Filter): The filter to apply. + Example: + + Filter on a related node's property: + + >>> from cognite.client.data_classes.filters import Nested, Equals + >>> filter = Nested( + ... ("somespace", "somecontainer", "related"), + ... Equals(("somespace", "somecontainer", "someProperty"), 42) + ... ) """ _filter_name = "nested" @@ -310,7 +341,15 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class MatchAll(Filter): - """A filter that matches all instances.""" + """A filter that matches all instances. + + Example: + + Match everything: + + >>> from cognite.client.data_classes.filters import MatchAll + >>> filter = MatchAll() + """ _filter_name = "matchAll" @@ -325,6 +364,13 @@ class HasData(Filter): Args: containers (Sequence[tuple[str, str] | ContainerId] | None): Containers to check for data. views (Sequence[tuple[str, str, str] | ViewId] | None): Views to check for data. + + Example: + + Filter on having data in a specific container: + + >>> from cognite.client.data_classes.filters import HasData + >>> filter = HasData(containers=[("somespace", "somecontainer")]) """ _filter_name = "hasData" @@ -362,6 +408,13 @@ class Range(FilterWithProperty): gte (FilterValue | None): Greater than or equal to. lt (FilterValue | None): Less than. lte (FilterValue | None): Less than or equal to. + + Example: + + Retrieve all instances with a property value greater than 42: + + >>> from cognite.client.data_classes.filters import Range + >>> filter = Range(("some", "property"), gt=42) """ _filter_name = "range" @@ -405,6 +458,14 @@ class Overlaps(Filter): gte (FilterValue | None): Greater than or equal to. lt (FilterValue | None): Less than. lte (FilterValue | None): Less than or equal to. + + + Example: + + Retrieve all instances with a range overlapping with the range (42, 100): + + >>> from cognite.client.data_classes.filters import Overlaps + >>> filter = Overlaps(("some", "startProperty"), ("some", "endProperty"), gt=42, lt=100) """ _filter_name = "overlaps" @@ -449,6 +510,13 @@ class Equals(FilterWithPropertyAndValue): Args: property (PropertyReference): The property to filter on. value (FilterValue): The value to filter on. + + Example: + + Retrieve all instances where the property value equals 42: + + >>> from cognite.client.data_classes.filters import Equals + >>> filter = Equals(("some", "property"), 42) """ _filter_name = "equals" @@ -461,6 +529,13 @@ class In(FilterWithPropertyAndValueList): Args: property (PropertyReference): The property to filter on. values (FilterValueList): The values to filter on. + + Example: + + Retrieve all instances where the property value equals 42 or 43: + + >>> from cognite.client.data_classes.filters import In + >>> filter = In(("some", "property"), [42, 43]) """ _filter_name = "in" @@ -472,6 +547,13 @@ class Exists(FilterWithProperty): Args: property (PropertyReference): The property to filter on. + + Example: + + Retrieve all instances where the property value is set: + + >>> from cognite.client.data_classes.filters import Exists + >>> filter = Exists(("some", "property")) """ _filter_name = "exists" @@ -484,6 +566,13 @@ class Prefix(FilterWithPropertyAndValue): Args: property (PropertyReference): The property to filter on. value (FilterValue): The value to filter on. + + Example: + + Retrieve all instances where the property value starts with "somePrefix_": + + >>> from cognite.client.data_classes.filters import Prefix + >>> filter = Prefix(("some", "property"), "somePrefix_") """ _filter_name = "prefix" @@ -496,6 +585,13 @@ class ContainsAny(FilterWithPropertyAndValueList): Args: property (PropertyReference): The property to filter on. values (FilterValueList): The value to filter on. + + Example: + + Retrieve all instances where the property value contains either 42 or 43: + + >>> from cognite.client.data_classes.filters import ContainsAny + >>> filter = ContainsAny(("some", "property"), [42, 43]) """ _filter_name = "containsAny" @@ -508,6 +604,13 @@ class ContainsAll(FilterWithPropertyAndValueList): Args: property (PropertyReference): The property to filter on. values (FilterValueList): The value to filter on. + + Example: + + Retrieve all instances where the property value contains both 42 and 43: + + >>> from cognite.client.data_classes.filters import ContainsAll + >>> filter = ContainsAll(("some", "property"), [42, 43]) """ _filter_name = "containsAll"