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

Not

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

final class cognite.client.data_classes.filters.Not(*filters: 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)
    

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

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, Tuple[str, ...], List[str], EnumProperty], value: Union[str, float, bool, Sequence, Mapping[str, Any], Label, PropertyReferenceValue, 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)
    

Exists

The Exists filter checks if a property exists.

final class cognite.client.data_classes.filters.Exists(property: Union[str, Tuple[str, ...], List[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, Tuple[str, ...], List[str], EnumProperty], values: Union[Sequence[Union[str, float, bool, Sequence, Mapping[str, Any], Label]], PropertyReferenceValue, 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, Tuple[str, ...], List[str], EnumProperty], values: Union[Sequence[Union[str, float, bool, Sequence, Mapping[str, Any], Label]], PropertyReferenceValue, 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, Tuple[str, ...], List[str], EnumProperty], values: Union[Sequence[Union[str, float, bool, Sequence, Mapping[str, Any], Label]], PropertyReferenceValue, 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])
    

Overlaps

The Overlaps filter checks if two ranges overlap.

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

Prefix filter results based on whether the (text) property starts with 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 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")
    

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: PropertyReference, gt: FilterValue | None = None, gte: FilterValue | None = None, lt: FilterValue | None = None, lte: FilterValue | None = 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)
    

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, Tuple[str, ...], List[str], EnumProperty], value: Union[str, float, bool, Sequence, Mapping[str, Any], Label, PropertyReferenceValue, ParameterValue])

Geo Filters

GeoJSON

The GeoJSON filter performs geometric queries using GeoJSON representations.

class cognite.client.data_classes.filters.GeoJSON(property: Union[str, Tuple[str, ...], List[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, Tuple[str, ...], List[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, Tuple[str, ...], List[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, Tuple[str, ...], List[str], 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: str | Sequence[str], instance_type: Literal['node', 'edge'] = 'node')

Filters instances based on the space.

Parameters
  • space (str | Sequence[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: Union[str, Tuple[str, ...], List[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))