API Reference›Rollups
API Reference

Rollups

Declare rollups on a database's tables: pre-aggregated rows, one per time bucket and set of dimension values, that answer matching aggregate queries without reading the whole table. Queries use a rollup on their own when it can answer them, and their response says whether one was used. Declaring a rollup limits how the table's older rows can be changed: see the declare endpoint.

List a database's rollups

GET/v1/databases/{database_id}/rollups

List the rollups on a database's tables. Filter by schema, or by schema and table.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID

Query parameters

NameTypeDescription
schema_namestringOnly rollups on tables of this schema
table_namestringOnly rollups on this table; requires schema_name

Response 200 — The rollups

NameTypeDescription
rollups (required)Rollup[]
Fields of rollups
NameTypeDescription
rollups[].bucket_width_secs (required)integerWidth of each time bucket, in seconds.
rollups[].covered_untilstringEnd (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while building, and after the table is replaced it describes the old table until the rollup is rebuilt.
rollups[].created_at (required)stringWhen the rollup was declared.
rollups[].database_id (required)stringDatabase that holds the table.
rollups[].dimensions (required)string[]Columns rows are grouped by, besides the time bucket.
rollups[].errorstringWhy the build failed, when status is build_failed; null otherwise.
rollups[].failed_atstringWhen the build failed, when status is build_failed; null otherwise.
rollups[].filterstringCondition a row must pass to be kept; absent when every row is kept.
rollups[].id (required)stringRollup ID.
rollups[].measures (required)RollupMeasure[]The measures, as declared.
rollups[].measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
rollups[].measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
rollups[].measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
rollups[].schema_name (required)stringSchema of the table.
rollups[].status (required)RollupStatusA rollup's state. Queries use a rollup only when it is ready. - building: building its first rows. - ready: can answer queries. - needs_rebuild: a change to its table it cannot follow; it needs a rebuild. - dropping: being dropped. - build_failed: the build failed. Progress is kept; request a rebuild to resume.
rollups[].table_name (required)stringThe table the rollup is declared on.
rollups[].time_column (required)stringTimestamp column rows are bucketed by.
rollups[].updated_at (required)stringWhen the rollup last changed.
rollups[].window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared.
Example response
{
  "rollups": [
    {
      "bucket_width_secs": 3600,
      "covered_until": "2026-11-18T16:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "database_id": "dbid01h9xyz",
      "dimensions": [
        "region"
      ],
      "error": "string",
      "failed_at": "2026-01-01T00:00:00Z",
      "filter": "status <> 'error'",
      "id": "rlup01h9xyz",
      "measures": [
        {
          "kind": "count"
        },
        {
          "kind": "numeric",
          "column": "amount"
        }
      ],
      "schema_name": "public",
      "status": "building",
      "table_name": "events",
      "time_column": "ts",
      "updated_at": "2026-01-01T00:00:00Z",
      "window_secs": 3600
    }
  ]
}

Errors

StatusDescription
400table_name without schema_name
404No such database

Declare a rollup on a table

POST/v1/databases/{database_id}/rollups

Declare a rollup: pre-aggregated rows of one table, one per time bucket and set of dimension values, which answer matching aggregate queries without reading the whole table. Answers are the same as reading the table. The table must hold data, and its time column must be a timestamp with no time zone or in UTC.

The rollup starts as building and becomes ready when its build catches up with the table; poll the returned job or the rollup. When job_id is null the build could not be started: rebuild the rollup to start it.

A query uses a ready rollup when it aggregates with count, sum, avg, min, max, or approx_percentile_cont / approx_median at the declared centroids (approximate answers only); groups by the time column in buckets that are a multiple of bucket_width_secs, and by dimensions; filters only on dimensions and the time column; and, when the rollup has a filter, contains each of its AND-joined parts written the same way. min and max of a floating-point column are always read from the table. The query's response says whether a rollup was used.

Declaring a rollup changes how the table can be written. Rows whose time is older than window_secs can no longer be changed or deleted, and SQL DELETE and UPDATE on the table are refused: change rows with a keyed load whose key includes the time column. Appends are always allowed, and so is replacing the table, after which its rollups need a rebuild and queries read the table until then. A fork of the database does not carry rollups, and dropping the table drops them. A rollup cannot be changed: drop it and declare a new one, which builds from the start.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID

Request body

NameTypeDescription
bucket_width_secs (required)integerWidth of each time bucket, in seconds. Buckets align to the Unix epoch, in UTC. A query uses the rollup when its own time buckets are a multiple of this width. Min: 1
dimensionsstring[]Columns to group by, besides the time bucket. A query can also filter on these columns and still use the rollup.
filterstringSQL condition a row must pass to be kept; omit it to keep every row. A query uses the rollup only when its WHERE clause contains each AND-joined part written the same way, and the condition must be deterministic (no subqueries, aggregates, now() or random()).
measures (required)RollupMeasure[]Aggregates each rollup row keeps.
schema_name (required)stringSchema that holds the table.
table_name (required)stringTable to roll up.
time_column (required)stringTimestamp column to bucket rows by. It must have no time zone, or be in UTC.
window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted; later edits are refused, appends are always allowed. Shared by every rollup on the table: the first sets it (default one hour), later ones must match or omit it. Min: 1
Fields of measures
NameTypeDescription
measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
Example request
{
  "bucket_width_secs": 3600,
  "dimensions": [
    "region"
  ],
  "filter": "status <> 'error'",
  "measures": [
    {
      "kind": "count"
    },
    {
      "kind": "numeric",
      "column": "amount"
    }
  ],
  "schema_name": "public",
  "table_name": "events",
  "time_column": "ts",
  "window_secs": 3600
}

Response 201 — The rollup was declared

NameTypeDescription
job_idstringBackground job that builds the rollup: poll GET /v1/jobs/{job_id} to follow it; the rollup becomes ready once the build catches up with the table. Null when the build could not be started: the rollup stays building, and rebuilding it starts the build.
rollup (required)RollupA rollup on a database's table: what it keeps, and its state. Queries use it only when status is ready.
Fields of rollup
NameTypeDescription
rollup.bucket_width_secs (required)integerWidth of each time bucket, in seconds.
rollup.covered_untilstringEnd (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while building, and after the table is replaced it describes the old table until the rollup is rebuilt.
rollup.created_at (required)stringWhen the rollup was declared.
rollup.database_id (required)stringDatabase that holds the table.
rollup.dimensions (required)string[]Columns rows are grouped by, besides the time bucket.
rollup.errorstringWhy the build failed, when status is build_failed; null otherwise.
rollup.failed_atstringWhen the build failed, when status is build_failed; null otherwise.
rollup.filterstringCondition a row must pass to be kept; absent when every row is kept.
rollup.id (required)stringRollup ID.
rollup.measures (required)RollupMeasure[]The measures, as declared.
rollup.measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
rollup.measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
rollup.measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
rollup.schema_name (required)stringSchema of the table.
rollup.status (required)RollupStatusA rollup's state. Queries use a rollup only when it is ready. - building: building its first rows. - ready: can answer queries. - needs_rebuild: a change to its table it cannot follow; it needs a rebuild. - dropping: being dropped. - build_failed: the build failed. Progress is kept; request a rebuild to resume.
rollup.table_name (required)stringThe table the rollup is declared on.
rollup.time_column (required)stringTimestamp column rows are bucketed by.
rollup.updated_at (required)stringWhen the rollup last changed.
rollup.window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared.
Example response
{
  "job_id": "jobs01h9xyz",
  "rollup": {
    "bucket_width_secs": 3600,
    "covered_until": "2026-11-18T16:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "database_id": "dbid01h9xyz",
    "dimensions": [
      "region"
    ],
    "error": "string",
    "failed_at": "2026-01-01T00:00:00Z",
    "filter": "status <> 'error'",
    "id": "rlup01h9xyz",
    "measures": [
      {
        "kind": "count"
      },
      {
        "kind": "numeric",
        "column": "amount"
      }
    ],
    "schema_name": "public",
    "status": "building",
    "table_name": "events",
    "time_column": "ts",
    "updated_at": "2026-01-01T00:00:00Z",
    "window_secs": 3600
  }
}

Errors

StatusDescription
400The declaration does not fit the table
404No such database or table
409An identical rollup already exists, or the table's window differs

Get a rollup

GET/v1/databases/{database_id}/rollups/{rollup_id}

Get a rollup: its definition, its status, and how far its build has come.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID
rollup_id (required)stringRollup ID

Response 200 — The rollup

NameTypeDescription
bucket_width_secs (required)integerWidth of each time bucket, in seconds.
covered_untilstringEnd (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while building, and after the table is replaced it describes the old table until the rollup is rebuilt.
created_at (required)stringWhen the rollup was declared.
database_id (required)stringDatabase that holds the table.
dimensions (required)string[]Columns rows are grouped by, besides the time bucket.
errorstringWhy the build failed, when status is build_failed; null otherwise.
failed_atstringWhen the build failed, when status is build_failed; null otherwise.
filterstringCondition a row must pass to be kept; absent when every row is kept.
id (required)stringRollup ID.
measures (required)RollupMeasure[]The measures, as declared.
schema_name (required)stringSchema of the table.
status (required)RollupStatusA rollup's state. Queries use a rollup only when it is ready. - building: building its first rows. - ready: can answer queries. - needs_rebuild: a change to its table it cannot follow; it needs a rebuild. - dropping: being dropped. - build_failed: the build failed. Progress is kept; request a rebuild to resume.
table_name (required)stringThe table the rollup is declared on.
time_column (required)stringTimestamp column rows are bucketed by.
updated_at (required)stringWhen the rollup last changed.
window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared.
Fields of measures
NameTypeDescription
measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
Example response
{
  "bucket_width_secs": 3600,
  "covered_until": "2026-11-18T16:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "database_id": "dbid01h9xyz",
  "dimensions": [
    "region"
  ],
  "error": "string",
  "failed_at": "2026-01-01T00:00:00Z",
  "filter": "status <> 'error'",
  "id": "rlup01h9xyz",
  "measures": [
    {
      "kind": "count"
    },
    {
      "kind": "numeric",
      "column": "amount"
    }
  ],
  "schema_name": "public",
  "status": "building",
  "table_name": "events",
  "time_column": "ts",
  "updated_at": "2026-01-01T00:00:00Z",
  "window_secs": 3600
}

Errors

StatusDescription
404No such database or rollup

Drop a rollup

DELETE/v1/databases/{database_id}/rollups/{rollup_id}

Drop a rollup and its rows. The table does not change. Returns once the rollup is gone, which can take up to two minutes when a build step is running on it. When the last rollup on a table is dropped, the table's write window no longer applies.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID
rollup_id (required)stringRollup ID

Response 204 — The rollup was dropped

Errors

StatusDescription
404No such database or rollup

Rebuild a rollup

POST/v1/databases/{database_id}/rollups/{rollup_id}/rebuild

Start building a rollup again, in the background, and return the build job. A needs_rebuild rollup (left that way when its table is replaced) is emptied and rebuilt; queries read the table until the build finishes. A build_failed rollup, or a building one whose build is not running, resumes where it stopped.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID
rollup_id (required)stringRollup ID

Response 202 — The build was started

NameTypeDescription
job_idstringBackground job that builds the rollup: poll GET /v1/jobs/{job_id} to follow it; the rollup becomes ready once the build catches up with the table. Null when the build could not be started: the rollup stays building, and rebuilding it starts the build.
rollup (required)RollupA rollup on a database's table: what it keeps, and its state. Queries use it only when status is ready.
Fields of rollup
NameTypeDescription
rollup.bucket_width_secs (required)integerWidth of each time bucket, in seconds.
rollup.covered_untilstringEnd (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while building, and after the table is replaced it describes the old table until the rollup is rebuilt.
rollup.created_at (required)stringWhen the rollup was declared.
rollup.database_id (required)stringDatabase that holds the table.
rollup.dimensions (required)string[]Columns rows are grouped by, besides the time bucket.
rollup.errorstringWhy the build failed, when status is build_failed; null otherwise.
rollup.failed_atstringWhen the build failed, when status is build_failed; null otherwise.
rollup.filterstringCondition a row must pass to be kept; absent when every row is kept.
rollup.id (required)stringRollup ID.
rollup.measures (required)RollupMeasure[]The measures, as declared.
rollup.measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
rollup.measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
rollup.measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
rollup.schema_name (required)stringSchema of the table.
rollup.status (required)RollupStatusA rollup's state. Queries use a rollup only when it is ready. - building: building its first rows. - ready: can answer queries. - needs_rebuild: a change to its table it cannot follow; it needs a rebuild. - dropping: being dropped. - build_failed: the build failed. Progress is kept; request a rebuild to resume.
rollup.table_name (required)stringThe table the rollup is declared on.
rollup.time_column (required)stringTimestamp column rows are bucketed by.
rollup.updated_at (required)stringWhen the rollup last changed.
rollup.window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared.
Example response
{
  "job_id": "jobs01h9xyz",
  "rollup": {
    "bucket_width_secs": 3600,
    "covered_until": "2026-11-18T16:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "database_id": "dbid01h9xyz",
    "dimensions": [
      "region"
    ],
    "error": "string",
    "failed_at": "2026-01-01T00:00:00Z",
    "filter": "status <> 'error'",
    "id": "rlup01h9xyz",
    "measures": [
      {
        "kind": "count"
      },
      {
        "kind": "numeric",
        "column": "amount"
      }
    ],
    "schema_name": "public",
    "status": "building",
    "table_name": "events",
    "time_column": "ts",
    "updated_at": "2026-01-01T00:00:00Z",
    "window_secs": 3600
  }
}

Errors

StatusDescription
404No such database or rollup
409The rollup is ready, is being dropped, or is already being built

Set a rollup's window

PUT/v1/databases/{database_id}/rollups/{rollup_id}/window

Set how long after a row's time it can still be changed or deleted. This applies to every rollup on the same table. Appends are always allowed. Nothing is rebuilt: a wider window applies as time passes, and a narrower one at the next refresh.

Path parameters

NameTypeDescription
database_id (required)stringDatabase ID
rollup_id (required)stringRollup ID

Request body

NameTypeDescription
window_secs (required)integerHow long, in seconds, after a row's time it can still be changed or deleted. Applies to every rollup on the table. Min: 1
Example request
{
  "window_secs": 21600
}

Response 200 — The rollup, with its new window

NameTypeDescription
bucket_width_secs (required)integerWidth of each time bucket, in seconds.
covered_untilstringEnd (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while building, and after the table is replaced it describes the old table until the rollup is rebuilt.
created_at (required)stringWhen the rollup was declared.
database_id (required)stringDatabase that holds the table.
dimensions (required)string[]Columns rows are grouped by, besides the time bucket.
errorstringWhy the build failed, when status is build_failed; null otherwise.
failed_atstringWhen the build failed, when status is build_failed; null otherwise.
filterstringCondition a row must pass to be kept; absent when every row is kept.
id (required)stringRollup ID.
measures (required)RollupMeasure[]The measures, as declared.
schema_name (required)stringSchema of the table.
status (required)RollupStatusA rollup's state. Queries use a rollup only when it is ready. - building: building its first rows. - ready: can answer queries. - needs_rebuild: a change to its table it cannot follow; it needs a rebuild. - dropping: being dropped. - build_failed: the build failed. Progress is kept; request a rebuild to resume.
table_name (required)stringThe table the rollup is declared on.
time_column (required)stringTimestamp column rows are bucketed by.
updated_at (required)stringWhen the rollup last changed.
window_secsintegerHow long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared.
Fields of measures
NameTypeDescription
measures[].centroidsintegerFor approx_percentile only: the summary's accuracy, as the centroids argument of approx_percentile_cont. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: 1–1000
measures[].columnstringColumn to aggregate. Required for every kind except count, which counts all rows when it is omitted.
measures[].kind (required)"count" or "sum" or "min" or "max" or "numeric" or "approx_percentile"The aggregate a measure keeps. - count: number of rows, or with a column, rows where it is not null. - sum, min, max: that aggregate of column. - numeric: count, sum, min and max of column, enough to answer count, sum, avg, min and max queries on it. avg of a decimal column is always read from the table. - approx_percentile: a summary of column that answers approx_percentile_cont and approx_median queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with centroids.
Example response
{
  "bucket_width_secs": 3600,
  "covered_until": "2026-11-18T16:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "database_id": "dbid01h9xyz",
  "dimensions": [
    "region"
  ],
  "error": "string",
  "failed_at": "2026-01-01T00:00:00Z",
  "filter": "status <> 'error'",
  "id": "rlup01h9xyz",
  "measures": [
    {
      "kind": "count"
    },
    {
      "kind": "numeric",
      "column": "amount"
    }
  ],
  "schema_name": "public",
  "status": "building",
  "table_name": "events",
  "time_column": "ts",
  "updated_at": "2026-01-01T00:00:00Z",
  "window_secs": 3600
}

Errors

StatusDescription
400The window is zero or too large
404No such database or rollup
409The rollup is being dropped, or its table was replaced