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 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').

Base Instance Properties: Certain properties like externalId, space, createdTime, and lastUpdatedTime are base properties on the instance itself (not in a container/view). To filter on these, use the syntax ("node", "property_name") or ("edge", "property"name). For example:

from cognite.client.data_classes.filters import Prefix, Equals

# Filter nodes where externalId starts with "SomeCustomer"
flt = Prefix(("node", "externalId"), "SomeCustomer")

# Filter edges in a specific space
flt = Equals(("edge", "space"), "my_space")

All filters inherit from the base class Filter (cognite.client.data_classes.filters.Filter).

Below is an overview of the available filters:

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.

final class cognite.client.data_classes.filters.Equals(property: Union[str, SequenceNotStr[str], 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.data_modeling.data_types.DirectRelationReference | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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)
```

Filter on special node properties like space (these are properties on the node itself, not in a view):

>>> # Filter nodes in a specific space
>>> flt = Equals(("node", "space"), "my_space")
>>> # Other special node properties: "externalId", "createdTime", "lastUpdatedTime"

Exists

The Exists filter checks if a property exists.

final class cognite.client.data_classes.filters.Exists(property: Union[str, SequenceNotStr[str], 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.

final class cognite.client.data_classes.filters.ContainsAll(property: Union[str, SequenceNotStr[str], EnumProperty], values: collections.abc.Sequence[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.data_modeling.data_types.DirectRelationReference] | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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.

final class cognite.client.data_classes.filters.ContainsAny(property: Union[str, SequenceNotStr[str], EnumProperty], values: collections.abc.Sequence[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.data_modeling.data_types.DirectRelationReference] | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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.

final class cognite.client.data_classes.filters.In(property: Union[str, SequenceNotStr[str], EnumProperty], values: collections.abc.Sequence[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.data_modeling.data_types.DirectRelationReference] | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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])

Filter on special node properties like externalId (these are properties on the node itself, not in a view):

>>> # Filter nodes with specific externalIds
>>> filter = In(("node", "externalId"), ["sensor_1", "sensor_2", "sensor_3"])
>>> # Other special node properties: "space", "createdTime", "lastUpdatedTime"

Overlaps

The Overlaps filter checks if two ranges overlap.

final class cognite.client.data_classes.filters.Overlaps(start_property: Union[str, SequenceNotStr[str], EnumProperty], end_property: Union[str, SequenceNotStr[str], EnumProperty], gt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, gte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, lt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, lte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, 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.

final class cognite.client.data_classes.filters.Prefix(property: Union[str, SequenceNotStr[str], 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.data_modeling.data_types.DirectRelationReference | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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])

Filter on special node properties like externalId (these are properties on the node itself, not in a view):

>>> # Filter nodes where externalId starts with "SomeCustomer"
>>> flt = Prefix(("node", "externalId"), "SomeCustomer")
>>> # Other special node properties: "space", "createdTime", "lastUpdatedTime"

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: Union[str, SequenceNotStr[str], EnumProperty], gt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, gte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, lt: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, PropertyReferenceValue, ParameterValue]] = None, lte: Optional[Union[str, float, bool, Sequence, Mapping[str, Any], Label, InstanceId, DirectRelationReference, 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: Union[str, SequenceNotStr[str], 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.data_modeling.data_types.DirectRelationReference | 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.

final class cognite.client.data_classes.filters.InAssetSubtree(property: Union[str, SequenceNotStr[str], EnumProperty], values: collections.abc.Sequence[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.data_modeling.data_types.DirectRelationReference] | cognite.client.data_classes.filters.PropertyReferenceValue | cognite.client.data_classes.filters.ParameterValue)

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'],
...     )
... )

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")

IsNull

The IsNull filter checks if a property is null.

class cognite.client.data_classes.filters.IsNull(property: SequenceNotStr[str])

Data modeling filter for instances whose property is null, effectively a negated Exists-filter.

Parameters: property (SequenceNotStr[str]) – The property to filter on.

Example

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

A filter using a tuple to reference the property:

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

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

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])

InstanceReferences

The InstanceReferences filter matches instances with fully qualified references (space + externalId) equal to _any_ of the provided references.

class cognite.client.data_classes.filters.InstanceReferences(references: collections.abc.Sequence[cognite.client.utils._identifier.InstanceId] | collections.abc.Sequence[tuple[str, str]])

Data modeling filter which matches instances with these fully qualified references.

Parameters: references (Sequence[InstanceId] | Sequence[tuple[str, str]]) – The instance references.

Example

Filter than can be used to retrieve instances where their space/externalId matches any of the provided values:

A filter using a tuple as instance reference:

>>> from cognite.client.data_classes.filters import InstanceReferences, InstanceId
>>> flt = InstanceReferences([("someSpace", "someExternalId")])

Composing the instance references using the InstanceId class:

>>> flt = InstanceReferences([InstanceId("someSpace", "someExternalId")])

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: Union[str, SequenceNotStr[str], 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))

Geo Filters

GeoJSON

The GeoJSON filter performs geometric queries using GeoJSON representations.

class cognite.client.data_classes.filters.GeoJSON(property: Union[str, SequenceNotStr[str], EnumProperty], geometry: Geometry)

GeoJSONDisjoint

The GeoJSONDisjoint filter checks if two geometric shapes are disjoint.

final class cognite.client.data_classes.filters.GeoJSONDisjoint(property: Union[str, SequenceNotStr[str], EnumProperty], geometry: Geometry)

GeoJSONIntersects

The GeoJSONIntersects filter checks if two geometric shapes intersect.

final class cognite.client.data_classes.filters.GeoJSONIntersects(property: Union[str, SequenceNotStr[str], EnumProperty], geometry: Geometry)

GeoJSONWithin

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

final class cognite.client.data_classes.filters.GeoJSONWithin(property: Union[str, SequenceNotStr[str], EnumProperty], geometry: Geometry)