Filters

The filter language provides a set of classes that can be used to construct complex queries for filtering data. Each filter class represents a specific filtering criterion, allowing users to tailor their queries to their specific needs.

The filter classes can be shared both by the classic CDF resources (like Assets, Time Series, Events, Files etc) and Data Modelling (Views and Instances).

When filtering on Data Modelling, the filter can be used on any container property. These can be referenced directly with a tuple notation like: ('space', 'view_external_id/view_version', 'property'), or, which is usually more convenient, one can use the as_property_ref method on the View or ViewID object like: myView.as_property_ref('property').

Below is an overview of the available filters:

Filter

Base class for all filters

class cognite.client.data_classes.filters.Filter

dump(camel_case_property: bool = False) → dict[str, Any]

Dump the filter to a dictionary.

Parameters: camel_case_property (bool) – Whether to camel case the property names. Defaults to False. Typically, when the filter is used in data modeling, the property names should not be changed, while when used with Assets, Events, Sequences, or Files, the property names should be camel cased.
Returns: The filter as a dictionary.
Return type: dict[str, Any]

Logical Operators

And

The And filter performs a logical AND operation on multiple filters, requiring all specified conditions to be true for an item to match the filter.

final class cognite.client.data_classes.filters.And(*filters: Filter)

A filter that combines multiple filters with a logical AND.

Parameters: *filters (Filter) – The filters to combine.

Example

A filter that combines an Equals and an In filter:

Using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import And, Equals, In
>>> flt = And(
...     Equals(("space", "view_xid/version", "some_property"), 42),
...     In(("space", "view_xid/version", "another_property"), ["a", "b", "c"]))

Using the View.as_property_ref method to reference the property:

>>> from cognite.client.data_classes.filters import And, Equals, In
>>> flt = And(
...     Equals(my_view.as_property_ref("some_property"), 42),
...     In(my_view.as_property_ref("another_property"), ["a", "b", "c"]))

Using the “&” operator:

>>> flt = Equals("age", 42) & Equals("name", "Alice")

Not

The Not filter performs a logical NOT operation on a sub-filter.

final class cognite.client.data_classes.filters.Not(filter: Filter)

A filter that negates another filter.

Parameters: filter (Filter) – The filter to negate.

Example

A filter that negates an Equals filter:

Using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Equals, Not
>>> is_42 = Equals(("space", "view_xid/view_version", "some_property"), 42)
>>> flt = Not(is_42)

Using the View.as_property_ref method to reference the property:

>>> is_42 = Equals(my_view.as_property_ref("some_property"), 42)
>>> flt = Not(is_42)

Using the “~” operator:

>>> flt = ~Equals("name", "Bob")

Or

The Or filter performs a logical OR operation on multiple filters, requiring at least one specified condition to be true for an item to match the filter.

final class cognite.client.data_classes.filters.Or(*filters: Filter)

A filter that combines multiple filters with a logical OR.

Parameters: *filters (Filter) – The filters to combine.

Example

A filter that combines an Equals and an In filter:

Using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Or, Equals, In
>>> flt = Or(
...     Equals(("space", "view_xid/version", "some_property"), 42),
...     In(("space", "view_xid/version", "another_property"), ["a", "b", "c"]))

Using the View.as_property_ref method to reference the property:

>>> flt = Or(
...     Equals(my_view.as_property_ref("some_property"), 42),
...     In(my_view.as_property_ref("another_property"), ["a", "b", "c"]))

Using the “|” operator:

>>> flt = Equals("name", "Bob") | Equals("name", "Alice")

Standard Filters

Equals

The Equals filter checks if a property is equal to a specified value.

Filters results based on whether the property equals the provided value.

Parameters

property (PropertyReference) – The property to filter on.
value (FilterValue) – The value to filter on.

Example

Filter than can be used to retrieve items where the property value equals 42:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Equals
>>> flt = Equals(("space", "view_xid/version", "some_property"), 42)

Composing the property reference using the View.as_property_ref method:
```
>>> flt = Equals(my_view.as_property_ref("some_property"), 42)
```

Exists

The Exists filter checks if a property exists.

final class cognite.client.data_classes.filters.Exists(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty)

Filters results based on whether the property is set or not.

Parameters: property (PropertyReference) – The property to filter on.

Example

Filter than can be used to retrieve items where the property value is set:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Exists
>>> flt = Exists(("space", "view_xid/version", "some_property"))

Composing the property reference using the View.as_property_ref method:
```
>>> flt = Exists(my_view.as_property_ref("some_property"))
```

ContainsAll

The ContainsAll filter checks if an item contains all specified values for a given property.

Returns results where the referenced property contains _all_ of the provided values.

Parameters

property (PropertyReference) – The property to filter on.
values (FilterValueList) – The value to filter on.

Example

Filter than can be used to retrieve items where the property value contains both 42 and 43:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import ContainsAll
>>> flt = ContainsAll(("space", "view_xid/version", "some_property"), [42, 43])

Composing the property reference using the View.as_property_ref method:

>>> flt = ContainsAll(my_view.as_property_ref("some_property"), [42, 43])

ContainsAny

The ContainsAny filter checks if an item contains any of the specified values for a given property.

Returns results where the referenced property contains _any_ of the provided values.

When comparing two arrays, In and ContainsAny behave the same way. But ContainsAny does not allow you filter on a primitive property. i.e in sudo code:

>>> [1,2,3] in [3,4,5] => true
>>> 1 in [1,2,3] => ERROR

Parameters

property (PropertyReference) – The property to filter on.
values (FilterValueList) – The value(s) to filter on.

Example

Filter than can be used to retrieve items where the property value contains either 42 or 43:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import ContainsAny
>>> flt = ContainsAny(("space", "view_xid/version", "some_property"), [42, 43])

Composing the property reference using the View.as_property_ref method:

>>> flt = ContainsAny(my_view.as_property_ref("some_property"), [42, 43])

In

The In filter checks if a property’s value is in a specified list.

Filters results based on whether the property equals one of the provided values.

When comparing two arrays, In and ContainsAny behave the same way. But In also allows you filter on a primitive property. i.e:

>>> [1,2,3] in [3,4,5] => true
>>> 1 in [1,2,3] => true

Parameters

property (PropertyReference) – The property to filter on.
values (FilterValueList) – The value(s) to filter on.

Example

Filter than can be used to retrieve items where the property value equals 42 or 43 (or both):

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import In
>>> filter = In(("space", "view_xid/version", "some_property"), [42, 43])

Composing the property reference using the View.as_property_ref method:

>>> filter = In(my_view.as_property_ref("some_property"), [42, 43])

Overlaps

The Overlaps filter checks if two ranges overlap.

final class cognite.client.data_classes.filters.Overlaps(start_property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, end_property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, gt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, gte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, lt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, lte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None)

Filters results based whether or not the provided range overlaps with the range given by the start and end properties.

Parameters

start_property (PropertyReference) – The property to filter on.
end_property (PropertyReference) – The property to filter on.
gt (FilterValue | None) – Greater than.
gte (FilterValue | None) – Greater than or equal to.
lt (FilterValue | None) – Less than.
lte (FilterValue | None) – Less than or equal to.

Example

Filter that can be used to retrieve all instances with a range overlapping with (42, 100):

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Overlaps
>>> flt = Overlaps(
...     ("space", "view_xid/version", "some_start_property"),
...     ("space", "view_xid/version", "some_end_property"),
...     gt=42, lt=100)

Composing the property reference using the View.as_property_ref method:

>>> flt = Overlaps(
...     my_view.as_property_ref("some_start_property"),
...     my_view.as_property_ref("some_end_property"),
...     gt=42, lt=100)

Prefix

The Prefix filter checks if a string property starts with a specified prefix.

Prefix filter results based on whether the property starts with the provided value. When the property is a list, the list starts with the provided values.

Parameters

property (PropertyReference) – The property to filter on.
value (FilterValue) – The value to filter on.

Example

Filter than can be used to retrieve items where the property value starts with “somePrefix”:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Prefix
>>> flt = Prefix(("space", "view_xid/version", "some_property"), "somePrefix")

Composing the property reference using the View.as_property_ref method:

>>> flt = Prefix(my_view.as_property_ref("some_property"), "somePrefix")

Filter that can be used to retrieve items where the property is a list of e.g. integers that starts with [1, 2, 3]:

>>> flt = Prefix(my_view.as_property_ref("some_list_property"), [1, 2, 3])

Range

The Range filter checks if a numeric property’s value is within a specified range that can be open-ended.

final class cognite.client.data_classes.filters.Range(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, gt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, gte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, lt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None, lte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, PropertyReferenceValue, ParameterValue]] = None)

Filters results based on a range of values.

Parameters

property (PropertyReference) – The property to filter on.
gt (FilterValue | None) – Greater than.
gte (FilterValue | None) – Greater than or equal to.
lt (FilterValue | None) – Less than.
lte (FilterValue | None) – Less than or equal to.

Example

Filter that can be used to retrieve all instances with a property value greater than 42:

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Range
>>> flt = Range(("space", "view_xid/version", "some_property"), gt=42)

Composing the property reference using the View.as_property_ref method:

>>> flt = Range(my_view.as_property_ref("some_property"), gt=42)

Search

The Search filter performs a full-text search on a specified property.

final class cognite.client.data_classes.filters.Search(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, value: str | float | bool | collections.abc.Sequence | collections.abc.Mapping[str, Any] | cognite.client.data_classes.labels.Label | cognite.client.utils._identifier.InstanceId | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

InAssetSubtree

The InAssetSubtree filter checks if an item belongs to a specified asset subtree.

Filters results based on whether item/resource is connected to an asset with an ID (or external ID) that is in the subtree rooted at any of the provided IDs.

Parameters

property (PropertyReference) – The property to filter on, e.g. ‘assetId’ or ‘assetExternalId’.
values (FilterValueList) – The value(s) to filter on.

Example

Count the number of documents with a related asset in a subtree rooted at any of the specified external IDs, e.g. ‘Plant_1’ and ‘Plant_2’:

>>> client.documents.aggregate_count(
...     filter=filters.InAssetSubtree(
...         property=DocumentProperty.asset_external_ids,
...         values=['Plant_1', 'Plant_2'],
...     )
... )

Geo Filters

GeoJSON

The GeoJSON filter performs geometric queries using GeoJSON representations.

class cognite.client.data_classes.filters.GeoJSON(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, geometry: Geometry)

GeoJSONDisjoint

The GeoJSONDisjoint filter checks if two geometric shapes are disjoint.

final class cognite.client.data_classes.filters.GeoJSONDisjoint(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, geometry: Geometry)

GeoJSONIntersects

The GeoJSONIntersects filter checks if two geometric shapes intersect.

final class cognite.client.data_classes.filters.GeoJSONIntersects(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, geometry: Geometry)

GeoJSONWithin

The GeoJSONWithin filter checks if one geometric shape is within another.

final class cognite.client.data_classes.filters.GeoJSONWithin(property: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, geometry: Geometry)

Data Modeling-Specific Filters

SpaceFilter

The SpaceFilter filters instances from one or more specific space(s).

class cognite.client.data_classes.filters.SpaceFilter(space: Union[str, SequenceNotStr[str]], instance_type: Literal['node', 'edge'] = 'node')

Filters instances based on the space.

Parameters

space (str | SequenceNotStr[str]) – The space (or spaces) to filter on.
instance_type (Literal['node', 'edge']) – Type of instance to filter on. Defaults to “node”.

Example

Filter than can be used to retrieve nodes from space “space1” or “space2”:

>>> from cognite.client.data_classes.filters import SpaceFilter
>>> flt = SpaceFilter(["space1", "space2"])

Filter than can be used to retrieve edges only from “space3”:

>>> flt = SpaceFilter("space3", instance_type="edge")

HasData

The HasData filter checks if an instance has data for a given property.

final class cognite.client.data_classes.filters.HasData(containers: Sequence[tuple[str, str] | ContainerId] | None = None, views: Sequence[tuple[str, str, str] | ViewId] | None = None)

Return only instances that have data in the provided containers/views.

Parameters

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, by using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import HasData
>>> flt = HasData(containers=[("some_space", "container_xid")])

Filter on having data in a specific view by using a ViewId:

>>> my_view = ViewId(space="some_space", external_id="view_xid", version="view_version")
>>> flt = HasData(views=[my_view])

MatchAll

The MatchAll filter matches all instances.

final class cognite.client.data_classes.filters.MatchAll

A filter that matches all instances.

Example

A filter that matches all instances:

>>> from cognite.client.data_classes.filters import MatchAll
>>> flt = MatchAll()

Nested

The Nested filter applies a filter to the node pointed to by a direct relation property.

final class cognite.client.data_classes.filters.Nested(scope: str | tuple[str, ...] | list[str] | cognite.client.data_classes._base.EnumProperty, filter: Filter)

A filter to apply to the node at the other side of a direct relation.

Parameters

scope (PropertyReference) – The direct relation property to traverse.
filter (Filter) – The filter to apply.

Example

Assume you have two Views, viewA and viewB. viewA has a direct relation to viewB called “viewB-ID”, and we want to filter the nodes on viewA based on the property “viewB-Property” on viewB.

A filter using a tuple to reference the property:

>>> from cognite.client.data_classes.filters import Nested, Equals
>>> flt = Nested(
...     scope=("space", "viewA_xid/view_version", "viewB-ID"),
...     filter=Equals(("space", "viewB_xid/view_version", "viewB-Property"), 42))

Composing the property reference using the View.as_property_ref method:

>>> flt = Nested(
...     scope=viewA.as_property_ref("viewB-ID"),
...     filter=Equals(viewB.as_property_ref("viewB-Property"), 42))