Aggregate instances

async AsyncCogniteClient.data_modeling.instances.aggregate(
view: ViewId,
aggregates: MetricAggregation | dict | Sequence[MetricAggregation | dict],
group_by: str | SequenceNotStr[str] | None = None,
instance_type: Literal['node', 'edge'] = 'node',
query: str | None = None,
properties: str | SequenceNotStr[str] | None = None,
target_units: list[TargetUnit] | None = None,
space: str | SequenceNotStr[str] | None = None,
filter: Filter | dict[str, Any] | None = None,
limit: int | None = 25,
) → AggregatedNumberedValue | list[AggregatedNumberedValue] | InstanceAggregationResultList

Aggregate data across nodes/edges.

Parameters:

  • view (ViewId) – View to aggregate over.

  • aggregates (MetricAggregation | dict | Sequence[MetricAggregation | dict]) – The properties to aggregate over.

  • group_by (str | SequenceNotStr[str] | None) – The selection of fields to group the results by when doing aggregations. You can specify up to 5 items to group by.

  • instance_type (Literal['node', 'edge']) – The type of instance.

  • query (str | None) – Optional query string. The API will parse the query string, and use it to match the text properties on elements to use for the aggregate(s).

  • properties (str | SequenceNotStr[str] | None) – Optional list of properties you want to apply the query to. If you do not list any properties, you search through text fields by default.

  • target_units (list[TargetUnit] | None) – Properties to convert to another unit. The API can only convert to another unit if a unit has been defined as part of the type on the underlying container being queried.

  • space (str | SequenceNotStr[str] | None) – Restrict instance aggregate query to the given space (or list of spaces).

  • filter (Filter | dict[str, Any] | None) – Advanced filtering of instances.

  • limit (int | None) – Maximum number of instances to return. Defaults to 25. Will return the maximum number of results (1000) if set to None, -1, or math.inf.

Returns:

Node or edge aggregation results.

Return type:

AggregatedNumberedValue | list[AggregatedNumberedValue] | InstanceAggregationResultList

Examples

Get the average run time in minutes for pumps grouped by release year:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.aggregations import Average
>>> from cognite.client.data_classes.data_modeling import ViewId
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> avg_run_time = Average("runTimeMinutes")
>>> view_id = ViewId("mySpace", "PumpView", "v1")
>>> res = client.data_modeling.instances.aggregate(
...     view_id, avg_run_time, group_by="releaseYear"
... )