feat(records): aggregate endpoint by andersfylling · Pull Request #2705 · cognitedata/cognite-sdk-python

andersfylling · 2026-06-25T08:50:26Z

Description

Introduces support for the aggregate endpoint for the Records collection.

Co-authored-by: Cursor <cursoragent@cursor.com>

Resolve conflicts with filter/sync PRs (#2698, #2699). Reuse TimeRange and RecordTargetUnits in the aggregate endpoint for consistency with filter and sync. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…eneric base tests Aggregate request builders raise NotImplementedError in _load and result classes have non-standard constructors, so they cannot participate in the generic dump/load round-trip tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

codecov · 2026-06-30T09:34:43Z

Codecov Report

❌ Patch coverage is 99.74619% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.72%. Comparing base (8b99b98) to head (26cb596).

Files with missing lines	Patch %	Lines
...gnite/client/data_classes/data_modeling/records.py	99.59%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2705      +/-   ##
==========================================
+ Coverage   93.71%   93.72%   +0.01%     
==========================================
  Files         504      504              
  Lines       51294    51680     +386     
==========================================
+ Hits        48070    48439     +369     
- Misses       3224     3241      +17

Files with missing lines	Coverage Δ
cognite/client/_api/data_modeling/records.py	`97.50% <100.00%> (+0.48%)`	⬆️
cognite/client/_sync_api/data_modeling/records.py	`100.00% <100.00%> (ø)`
...nite/client/data_classes/data_modeling/__init__.py	`100.00% <ø> (ø)`
...s_unit/test_api/test_data_modeling/test_records.py	`100.00% <100.00%> (ø)`
tests/tests_unit/test_base.py	`98.94% <100.00%> (+<0.01%)`	⬆️
...gnite/client/data_classes/data_modeling/records.py	`99.24% <99.59%> (+1.17%)`	⬆️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…aggregate classes from base tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…perty Encapsulates the parsed bucket list behind a private attribute so callers can't mutate cached state, and drops the redundant one-line docstrings that only restated the class names. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

gemini-code-assist

Code Review

This pull request introduces record aggregation capabilities to the data modeling records API, adding async and sync aggregate methods alongside various typed aggregate request builders and result classes. The review feedback suggests refactoring RecordsAggregate to not inherit from CogniteResource since it functions as a request builder rather than a DTO, which will also simplify unit test exclusions. Additionally, it is recommended to use a more specific type hint for the aggregates parameter to avoid the use of Any.

haakonvt · 2026-07-14T13:41:56Z

+                >>> res = client.data_modeling.records.aggregate(
+                ...     stream_id="my-stream",
+                ...     aggregates={
+                ...         "avg_temp": Avg(["my-space", "sensor", "temperature"]),


Let's make it more clear that this is a property reference.

Ref docs:

the first segment is the space that the container belongs to,
the second segment is the container external id,
the third segment is the property id inside the container.

specified the property key in the examples

haakonvt · 2026-07-14T13:45:37Z

I think we should keep these out of cognite/client/data_classes/data_modeling/__init__.py and only in ...records.py

just a heads up it will be inconsistent with the other data classes that are accessible there. Do you want purely aggregate related classes, or all records/streams classes to be in their own module?

I've prefixed the response agg types with records, and then i moved the builder types into the records module. Do you want me to move the response types into records as well?

haakonvt · 2026-07-17T11:58:16Z

+
+        Examples:
+
+            Aggregate average temperature using typed helpers:


I also wonder a bit about these examples - they feel like examples of what kind of data that belongs in the Datapoints service, not the Records service. Could you ask Claude to come up with different examples? 😅

re-used the examples from the cognite api docs

haakonvt · 2026-07-17T12:05:31Z

+    @classmethod
+    def _load(cls, resource: dict[str, Any]) -> Self:
+        raise NotImplementedError(f"{cls.__name__} is a request builder and cannot be loaded from API responses")


In v7 of the SDK, load was made public so that all request and response classes could be dumped (and loaded back) into config files, thus the _load method here need to be supported.

haakonvt · 2026-07-17T12:16:35Z

+        for result_cls in (
+            UniqueValuesAggregateResult,
+            NumberHistogramAggregateResult,
+            TimeHistogramAggregateResult,
+            FilterAggregateResult,
+        ):
+            if result_cls._buckets_key in resource:
+                return result_cls._load(resource)


Same comment here, I would rather have you build a mapping as a module-level constant for constant-time lookup

haakonvt · 2026-07-17T12:17:06Z

+    def __init__(self, raw_result: dict[str, Any]) -> None:
+        self._raw_result = raw_result
+
+    def dump(self, camel_case: bool = True) -> dict[str, Any]:
+        return self._raw_result


This seem a bit lazy tbh 😆 This camel_case param is being ignored

haakonvt · 2026-07-17T12:18:16Z

+    def __init__(self, raw_bucket: dict[str, Any]) -> None:
+        self._raw_bucket = raw_bucket
+        self.count = raw_bucket["count"]
+        self.value = raw_bucket.get("value")
+        self.interval_start = raw_bucket.get("intervalStart")
+        self.aggregates = raw_bucket.get("aggregates", {})
+        self.results = {
+            aggregate_id: RecordsAggregateResult._load(result)
+            for aggregate_id, result in self.aggregates.items()
+            if isinstance(result, dict)
+        }
+
+    @classmethod
+    def _load(cls, resource: dict[str, Any]) -> Self:
+        return cls(resource)


This init looks like load

haakonvt · 2026-07-17T12:21:15Z

+
+    Args:
+        aggregates (dict[str, Any]): Aggregate results keyed by the client-defined aggregate IDs.
+        typing (TypeInformation | None): Optional property typing metadata.


Feels weird to me to have this typing info randomly put here, but I guess you are just mimicking DMS? Should we consider dropping that from /aggregate until someone requests it?

it's part of the documentation, so lets keep it so users get a familiar sense when using the python sdk.

haakonvt · 2026-07-17T12:22:34Z

+            },
+        }
+
+    def test_records_aggregation_dump_round_trip(self) -> None:


Tested automatically, unless you opted out

Co-authored-by: Håkon V. Treider <haakonvt@gmail.com>

move out of dms module, switch to dump only, and add a bunch more tests

erlendvollset · 2026-07-22T14:59:10Z

+        return {"property": self.property}
+
+
+class Avg(_PropertyAggregate):


Any reason we can't reuse the existing classes in data_classes/aggregations?

Those seem to be designed around views, and have different logic for refering to a property. We also have aggregates that aren't handled there++. So to me it got a bit messy, and I went with our own. Though I hope we can consolidate over time.

Those seem to be designed around views

There's no mention of views there, so not sure what you're referring to.

have different logic for refering to a property.

I thought we were referencing properties in the same way everywhere? What's the deviation?

We also have aggregates that aren't handled there

You can add new aggregates to that module

andersfylling and others added 2 commits June 25, 2026 10:49

feat(records): add aggregate endpoint

66221d4

Co-authored-by: Cursor <cursoragent@cursor.com>

feat(records): add aggregate helpers

dd98ac8

Co-authored-by: Cursor <cursoragent@cursor.com>

andersfylling changed the title ~~feat(records): add aggregate endpoint~~ feat(records): aggregate endpoint Jun 30, 2026

andersfylling and others added 3 commits June 30, 2026 10:53

Merge origin/master into aggregate branch

6653552

Resolve conflicts with filter/sync PRs (#2698, #2699). Reuse TimeRange and RecordTargetUnits in the aggregate endpoint for consistency with filter and sync. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: import ordering and docstring example for aggregate

389eee2

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

andersfylling and others added 4 commits June 30, 2026 12:49

Merge branch 'master' into andersfylling/records/aggregate-pr1

b353db4

feat(records): add typed aggregate examples to docstring and exclude …

ce4149c

…aggregate classes from base tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Merge branch 'master' into andersfylling/records/aggregate-pr1

d46279c

andersfylling marked this pull request as ready for review July 12, 2026 20:23

andersfylling requested review from a team as code owners July 12, 2026 20:23

gemini-code-assist Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread cognite/client/data_classes/data_modeling/records.py Outdated

Comment thread cognite/client/_api/data_modeling/records.py Outdated

haakonvt reviewed Jul 17, 2026

View reviewed changes

andersfylling and others added 14 commits July 20, 2026 14:39

Update cognite/client/data_classes/data_modeling/records.py

a607d83

Co-authored-by: Håkon V. Treider <haakonvt@gmail.com>

update code example

12524ec

dont use sequence[str]

6c37d01

unroll loops for aggregate results

100c3c1

split up responsibilities of init/load/dump

23d7777

remove redundant load/dump test

bed39fb

commit to using proper types for aggs

4b3d786

rewrite aggs

4b4bf0a

move out of dms module, switch to dump only, and add a bunch more tests

cleanup the aggs examples

a209fb3

prefix records agg result types with Records

aedf329

Merge branch 'master' into andersfylling/records/aggregate-pr1

9935753

whops, re-add load support to the agg request types

04309fe

add unknown aggregate type

a0f7ab7

stricter types

26cb596

erlendvollset reviewed Jul 22, 2026

View reviewed changes

rename Avg => Average

6385ad3

andersfylling requested review from erlendvollset and haakonvt July 22, 2026 16:23

		return {"property": self.property}


		class Avg(_PropertyAggregate):

Uh oh!

Conversation

andersfylling commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

codecov Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

haakonvt Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

andersfylling commented Jun 25, 2026 •

edited

Loading

codecov Bot commented Jun 30, 2026 •

edited

Loading

haakonvt Jul 17, 2026 •

edited

Loading