Skip to main content
POST/analytics/{datasetSlug}/rollups

Create Rollup

Creates a continuous rollup that folds a stream into this dataset over fixed windows.

Body:

  • slug.
  • source.
  • dimensions (up to 16).
  • measures (up to 64; count, or last, sum, avg, min, max, count_distinct, p50, p95, p99 over a column).
  • windowSeconds (at least 60).
  • reattestIntervalDays (7, 30, 90 or 365; default 90).
  • Exactly one of subjectField (per-subject data, suppressed below the cohort threshold) or nonPersonal: true.

The rollup keeps running only while its configuration is re-attested within the interval.

Returns the rollup and its read and subscribe endpoints.

Requires the datasets:write permission (PROJECT_ADMIN or PROJECT_AUTHOR by default).

Callers must be members of the project (an organization role alone does not grant access); project service tokens and extension tokens cannot call it.

Parameters
datasetSlug *path

The Dataset's slug.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
slug *string

The rollup's slug: 1 to 63 lowercase letters, digits and hyphens, unique in the project.

It can't be changed later; the rollup's read and subscribe paths use it.

subjectFieldstring

The source event field that names the data subject: letters, digits and underscores, not starting with a digit.

With it, each cell counts distinct subjects and a cell with too few is suppressed; the target dataset must then be a shared dataset that declares a suppressed column of type bool.

Send this or nonPersonal: true, not both.

nonPersonalboolean

Send true to declare that the source carries no personal data.

Send this or subjectField, not both.

source *string

The stream to fold: the slug of a Pulse Stream in this project, or logs, metrics or traces for the project's telemetry.

dimensionsstring[]

The source fields each cell is grouped by: at most 16, unique, each letters, digits and underscores, not starting with a digit. window_start and suppressed are reserved.

Omit it for one cell per window.

measures *object[]

What each cell computes: 1 to 64 measures.

name *string

The measure's name: letters, digits and underscores, not starting with a digit, unique in the rollup.

It is the measure's key in each cell. window_start and suppressed are reserved.

agg *string

The aggregation: count, last, sum, avg, min, max, count_distinct, p50, p95 or p99.

columnstring

The source field to aggregate.

Required for every aggregation except count, which must not send one.

windowSeconds *integer

The width of each cell's time window, in seconds.

At least 60.

reattestIntervalDaysany

How many days each attestation lasts: 7, 30, 90 or 365.

Default 90.

When it runs out, the rollup stops folding until someone re-attests it.

One of: 7
or: 30
or: 90
or: 365
Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_REQUEST_SHAPEThe request body does not match the schema.
400K9O_INVALID_FIELD_VALUEA field is invalid: slug, source, dimensions, measures, window, re-attest interval, or neither / both of `subjectField` and `nonPersonal`.
401K9O_UNAUTHENTICATEDThe caller is not signed in.
403K9O_ACCESS_DENIEDThe caller is not a member of this project; an organization role alone does not grant access.
403K9O_IAM_POLICY_DENIEDThe caller's role or IAM policy does not grant datasets:write.
404K9O_NOT_FOUNDThe project was not found for this caller (project service tokens and extension tokens cannot call this endpoint).
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
409K9O_ALREADY_EXISTSA rollup with this slug already exists.
409K9O_PENDING_CHANGE_ALREADY_EXISTSA rollup for this dataset and source already exists.
Response body (200)
data *object

A rollup, the state of its folding, and the paths to read it.

id *string

rollup_ id.

slug *string

The rollup's slug, unique in the project.

Its read and subscribe paths use it.

subjectField *any

The source event field that names the data subject.

Null when the rollup declares nonPersonal instead (or, for a rollup made before declarations were required, neither).

One of: string
or: null
nonPersonal *boolean

True when the rollup's creator declared that its source carries no personal data.

datasetSlug *string

The dataset the rollup writes to.

source *string

The source the rollup folds: a Pulse Stream's slug, or a telemetry signal name.

Falls back to the stored stream id when the stream has been deleted.

dimensions *string[]

The fields each cell is grouped by, in declared order (at most 16).

measures *object[]

The declared measures, in order (at most 64).

name *string

The measure's name: its key in each cell's measures.

agg *string

count, last, sum, avg, min, max, count_distinct, p50, p95 or p99.

columnstring

The source field aggregated.

Absent for count.

windowSeconds *integer

The width of each cell's time window, in seconds.

enabled *boolean

Whether the rollup is set to fold.

reattestIntervalDays *integer

How many days each attestation lasts: 7, 30, 90 or 365.

attestedAt *string <date-time>

When a person last confirmed the rollup (created or re-attested it).

expiresAt *string <date-time>

attestedAt plus reattestIntervalDays.

After it the rollup stops folding until it is re-attested.

attestationStatus *"active" | "expiring_soon" | "expired"

expiring_soon within 14 days of expiresAt.

cursorSequence *any

The source sequence the last committed fold reached, as a decimal string.

Null until a fold has written a cell.

One of: string
or: null
lastFoldAt *any

When the last fold ran.

Null if it has never run.

One of: string <date-time>
or: null
lastFoldStatus *any

How the last fold ended: ok for a clean fold, otherwise why it did not fold (for example attestation_expired, stale_principal_denied, dataset_gone, write_error or failed).

Null if it has never run.

One of: string
or: null
createdAt *string <date-time>

When the rollup was created.

endpoints *object

Absolute paths: /@<project>/rollups/<slug>/read and /subscribe.

read *string

The path to read the rollup's cells.

subscribe *string

The path to subscribe to the rollup's cells as they change.

meta *object

Request metadata: cost, timing and correlation ids.

cost *object

Metered usage for this request; empty when nothing was metered.

timing *object
gatewayMs *number
totalMs *number
context *object
requestId *string
traceId *string
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.rollups.create('<datasetSlug>', {})

Showing example in TypeScript

Request example
{
  "slug": "string",
  "subjectField": "string",
  "nonPersonal": false,
  "source": "string",
  "dimensions": [
    "string"
  ],
  "measures": [
    {
      "name": "string",
      "agg": "string",
      "column": "string"
    }
  ],
  "windowSeconds": 0,
  "reattestIntervalDays": 7
}
Response example (200)
{
  "data": {
    "id": "string",
    "slug": "string",
    "subjectField": "string",
    "nonPersonal": false,
    "datasetSlug": "string",
    "source": "string",
    "dimensions": [
      "string"
    ],
    "measures": [
      {
        "name": "string",
        "agg": "string",
        "column": "string"
      }
    ],
    "windowSeconds": 0,
    "enabled": false,
    "reattestIntervalDays": 0,
    "attestedAt": "string",
    "expiresAt": "string",
    "attestationStatus": "active",
    "cursorSequence": "string",
    "lastFoldAt": "string",
    "lastFoldStatus": "string",
    "createdAt": "string",
    "endpoints": {
      "read": "string",
      "subscribe": "string"
    }
  },
  "meta": {
    "timing": {
      "gatewayMs": 0,
      "totalMs": 0
    },
    "context": {
      "requestId": "string",
      "traceId": "string",
      "projectId": "string"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Analytics & Intelligence