Aggregates

Aggregates summarise the items matching a query instead of returning them. Each Aggregate subclass here represents one aggregate and serialises to the request body the API expects; each Result subclass is what that aggregate comes back as.

The classes are shared between the data modeling aggregate endpoints and are therefore not named after any single one of them. Properties are referenced by their full container path, e.g. Average(["mySpace", "myContainer", "temp"]). Import the module by its own path:

from cognite.client.data_classes.data_modeling import aggregates as aggs

res = client.data_modeling.records.aggregate(
    stream_id="my-stream",
    aggregates={
        "per_day": aggs.TimeHistogram(
            ["mySpace", "Game", "startTime"],
            calendar_interval="1d",
            aggregates={"games": aggs.Count()},
        ),
    },
)

per_day = res["per_day"]  # aggs.TimeHistogramResult
for bucket in per_day.buckets:
    print(bucket.interval_start, bucket.aggregates["games"].value)

Note

These are not the same classes as the identically named ones in cognite.client.data_classes.aggregations, which belong to the instances.aggregate endpoint and reference view properties by identifier instead.

Aggregate data classes

Typed aggregate request builders and results shared by the data modeling aggregate endpoints.

The classes here describe wire shapes that are endpoint-independent, so they are deliberately not named after any single endpoint: Records uses them today, and the upcoming data modeling aggregate endpoint - which is modelled on the Records one - will reuse them. Aggregate and its subclasses are the request side; Result and its subclasses are what the API returns.

Nothing in this module is exported through cognite.client.data_classes.data_modeling. That namespace already re-exports cognite.client.data_classes.aggregations, which defines its own Average, Count, Min, Max and Sum for instances.aggregate. Keeping this module reachable only by its own path is what lets the two families share those names without either shadowing the other. Import it as:

from cognite.client.data_classes.data_modeling import aggregates as aggs

The two families are independent: Aggregate is unrelated to the legacy Aggregation, and because both use the same wire keys (avg, count, …), Aggregate.load() only ever returns members of this family.

class cognite.client.data_classes.data_modeling.aggregates.Aggregate

Bases: CogniteResource

Base class for typed aggregate request builders.

Aggregates are request bodies: they serialize via dump() and can be loaded back from that same representation via load(), so an aggregate spec round-trips through a config file.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.Average(property: SequenceNotStr[str])

Bases: Aggregate

Average aggregate over a container property.

class cognite.client.data_classes.data_modeling.aggregates.Bucket( count: int, value: Any | None = None, interval_start: float | str | None = None, aggregates: dict[str, Result] | None = None, )

Bases: CogniteResource

One bucket of a BucketResult.

Parameters:

count (int) – Number of matched items in this bucket.
value (Any) – The unique property value this bucket represents, for UniqueValues.
interval_start (float | str | None) – Lower bound of this bucket, for the histograms.
aggregates (dict[str, Result] | None) – Results of the aggregates nested under this bucket, keyed by the client-defined aggregate IDs.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.BucketResult( buckets: Sequence[Bucket], )

Bases: Result

Result of an aggregate that buckets the matched items.

Parameters:: buckets (Sequence[Bucket]) – The buckets the aggregate produced.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.Count( property: SequenceNotStr[str] | None = None, )

Bases: Aggregate

Count matched items, or non-null values when property is provided.

class cognite.client.data_classes.data_modeling.aggregates.Filters( filters: Sequence[Filter | dict[str, Any]], aggregates: Mapping[str, Aggregate | dict[str, Any]] | None = None, )

Bases: Aggregate

Bucket matched items by a list of filter expressions.

class cognite.client.data_classes.data_modeling.aggregates.FiltersResult( buckets: Sequence[Bucket], )

Bases: BucketResult

Result of a Filters aggregate.

class cognite.client.data_classes.data_modeling.aggregates.Max(property: SequenceNotStr[str])

Bases: Aggregate

Maximum aggregate over a property.

class cognite.client.data_classes.data_modeling.aggregates.MetricResult(aggregate: str, value: Any)

Bases: Result

Result of a metric aggregate (Average, Count, Min, Max, Sum).

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.Min(property: SequenceNotStr[str])

Bases: Aggregate

Minimum aggregate over a property.

class cognite.client.data_classes.data_modeling.aggregates.MovingFunction( buckets_path: str, window: int, function: MovingFunctions, )

Bases: Aggregate

Smooth a histogram’s buckets by re-aggregating them over a sliding window.

Nested inside a NumberHistogram or TimeHistogram, it reads one of that histogram’s own aggregates bucket by bucket and reduces every window consecutive buckets to one value - a 7-day moving average of a daily count, say - so a trend stays readable through the noise in individual buckets. buckets_path names the sibling aggregate to read, or "_count" for the buckets’ own item counts.

class cognite.client.data_classes.data_modeling.aggregates.MovingFunctionResult(fn_value: float)

Bases: Result

Result of a MovingFunction aggregate.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.MovingFunctions(value)

Bases: str, Enum

How a MovingFunction reduces each window of buckets to a single number.

MAX, MIN and SUM take that statistic over the window. UNWEIGHTED_AVG averages the window; LINEAR_WEIGHTED_AVG averages it too, but weights the most recent buckets highest, so it follows a trend more closely at the cost of being noisier.

The wire values carry a MovingFunctions. prefix, but the unprefixed suffix (e.g. "sum") is also accepted, so MovingFunctions("sum") is MovingFunctions.SUM.

class cognite.client.data_classes.data_modeling.aggregates.NumberHistogram( property: SequenceNotStr[str], interval: float, aggregates: Mapping[str, Aggregate | dict[str, Any]] | None = None, hard_bounds: Mapping[str, float] | None = None, )

Bases: Aggregate

Bucket numeric property values into fixed-width intervals.

class cognite.client.data_classes.data_modeling.aggregates.NumberHistogramResult( buckets: Sequence[Bucket], )

Bases: BucketResult

Result of a NumberHistogram aggregate.

class cognite.client.data_classes.data_modeling.aggregates.Result

Bases: CogniteResource

Base class for typed aggregate results.

One result type corresponds to each request builder above; load() dispatches on the wire key the API returns.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.Sum(property: SequenceNotStr[str])

Bases: Aggregate

Sum aggregate over a container property.

class cognite.client.data_classes.data_modeling.aggregates.TimeHistogram( property: SequenceNotStr[str], *, calendar_interval: str | None = None, fixed_interval: str | None = None, aggregates: Mapping[str, Aggregate | dict[str, Any]] | None = None, hard_bounds: Mapping[str, str] | None = None, )

Bases: Aggregate

Bucket timestamp values into calendar or fixed time intervals.

class cognite.client.data_classes.data_modeling.aggregates.TimeHistogramResult( buckets: Sequence[Bucket], )

Bases: BucketResult

Result of a TimeHistogram aggregate.

class cognite.client.data_classes.data_modeling.aggregates.UniqueValues( property: SequenceNotStr[str], aggregates: Mapping[str, Aggregate | dict[str, Any]] | None = None, size: int | None = None, )

Bases: Aggregate

Bucket matched items by unique property values.

class cognite.client.data_classes.data_modeling.aggregates.UniqueValuesResult( buckets: Sequence[Bucket], )

Bases: BucketResult

Result of a UniqueValues aggregate.

class cognite.client.data_classes.data_modeling.aggregates.UnknownAggregate(raw: dict[str, Any])

Bases: Aggregate

Fallback for aggregate request shapes this SDK version does not model yet.

Preserves the raw request body verbatim so an unknown or newer aggregate type still round-trips through dump()/load() instead of failing. The request builders’ dump() is always camelCase, so the payload is returned as-is regardless of camel_case.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.data_modeling.aggregates.UnknownResult(raw_result: dict[str, Any])

Bases: Result

Fallback for aggregate result shapes this SDK version does not model yet.

Preserves the raw payload verbatim so nothing is lost, snake-casing the API keys on request.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]