Skip to main content
Records are immutable or mutable data objects, depending on the stream template, that are stored in a stream. You create records by ingesting data into a stream. For a comprehensive guide on records, including detailed behavior, uniqueness constraints, and how they relate to streams, see About records and streams. Records have a similar shape to instances in the Data Modeling service, and their schema is defined by the containers referenced as sources. Each record also links to the space it belongs to, enabling space-based access control.
Every record has a required top-level externalId property, which you can use in some queries to retrieve or aggregate records.
  • Mutable records: The externalId and space properties uniquely identify records for write operations (create/upsert/delete).
  • Immutable records: The uniqueness of the space + externalId pair is not enforced, allowing multiple records with the same identifier to exist.

​
Rate and concurrency limits

For Records rate and concurrency limits, including mutable vs immutable stream budgets, see API rate limits.

​
Ingest records

Create the spaces, containers, views, and properties in data modeling before you ingest records. You need read access to those containers or views, and write access to the record space. Each entry in sources writes one container or one view. When the source is a view, properties are keyed by the view property names, and that one source writes every container the view maps. A view can be a record source when usedFor is record and streamId is the stream you are writing. Create and manage those views with the data modeling views operations.

​
Upsert records

Upsert is available only on mutable streams. Each upsert replaces the whole record. Send every property you want to keep. Properties you omit are not kept from the previous version. See Records.

​
Delete records

Delete is available only on mutable streams. Identifiers that do not exist are ignored. Deletes are eventually consistent. Other operations usually stop returning the record within a few seconds. Sync returns a tombstone, with the top-level fields and a deleted status, for at least 3 days after the delete.

​
Aggregates

Record aggregates fall into three groups:
  • Metric aggregates, such as sum, min, max, and count, compute one value.
  • Bucket aggregates, such as uniqueValues, timeHistogram, and filters, group records. This matches groupBy on data modeling instances.
  • Pipeline aggregates, such as movingFunction, run on the metrics of a parent histogram. They do not run on the records inside those buckets.
You can nest bucket aggregates. A metric reads properties from one view, or from one or more containers, not from a view and containers together. Top-level properties such as space, createdTime, and lastUpdatedTime are not property sources. The request filter and targetUnits are not limited that way.
Last modified on November 2, 2026