Query instances

async AsyncCogniteClient.data_modeling.instances.query( query: Query, include_typing: bool = False, debug: DebugParameters | None = None, ) → QueryResult

Advanced query interface for nodes/edges.

The Data Modelling API exposes an advanced query interface. The query interface supports parameterization, recursive edge traversal, chaining of result sets, and granular property selection.

Parameters:

query (Query) – Query.
include_typing (bool) – Should we return property type information as part of the result?
debug (DebugParameters | None) – Debug settings for profiling and troubleshooting.

Returns:

The resulting nodes and/or edges from the query.

Return type:

QueryResult

Examples

Find work orders created before 2023 sorted by title:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.data_modeling.query import (
...     Query,
...     Select,
...     NodeResultSetExpression,
...     EdgeResultSetExpression,
...     SourceSelector,
... )
>>> from cognite.client.data_classes.filters import Range, Equals
>>> from cognite.client.data_classes.data_modeling.ids import ViewId
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> work_order_id = ViewId("mySpace", "WorkOrderView", "v1")
>>> pump_id = ViewId("mySpace", "PumpView", "v1")
>>> query = Query(
...     with_={
...         "work_orders": NodeResultSetExpression(
...             filter=Range(work_order_id.as_property_ref("createdYear"), lt=2023)
...         ),
...         "work_orders_to_pumps": EdgeResultSetExpression(
...             from_="work_orders",
...             filter=Equals(
...                 ["edge", "type"],
...                 {"space": work_order_id.space, "externalId": "WorkOrder.asset"},
...             ),
...         ),
...         "pumps": NodeResultSetExpression(from_="work_orders_to_pumps"),
...     },
...     select={
...         "pumps": Select(
...             [SourceSelector(pump_id, ["name"])],
...             sort=[InstanceSort(pump_id.as_property_ref("name"))],
...         ),
...     },
... )
>>> res = client.data_modeling.instances.query(query)

To convert units, specify what your target units are in the SourceSelector. You can either use a UnitReference or a UnitSystemReference. Note that in order for a property to be converted, they need to have a unit defined in the underlying container.

>>> from cognite.client.data_classes.data_modeling.data_types import (
...     UnitReference,
...     UnitSystemReference,
... )
>>> selected_source = SourceSelector(
...     source=ViewId("my-space", "my-xid", "v1"),
...     properties=["f32_prop1", "f32_prop2", "f64_prop1", "f64_prop2"],
...     target_units=[
...         TargetUnit("f32_prop1", UnitReference("pressure:kilopa")),
...         TargetUnit("f32_prop2", UnitReference("pressure:barg")),
...         TargetUnit("f64_prop1", UnitSystemReference("SI")),
...         TargetUnit("f64_prop2", UnitSystemReference("Imperial")),
...     ],
... )

To select all properties, use ‘[*]’ in your SourceSelector:

>>> SourceSelector(source=ViewId("my-space", "my-xid", "v1"), properties=["*"])

To debug and/or profile your query, you can use the debug parameter:

>>> from cognite.client.data_classes.data_modeling.debug import DebugParameters
>>> debug_params = DebugParameters(
...     emit_results=False,
...     include_plan=True,  # Include the postgres execution plan
...     include_translated_query=True,  # Include the internal representation of the query.
...     profile=True,
... )
>>> res = client.data_modeling.instances.query(query, debug=debug_params)
>>> print(res.debug)