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
/v1/databases/{database_id}/rollupsList the rollups on a database's tables. Filter by schema, or by schema and table.
Path parameters
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
Query parameters
| Name | Type | Description |
|---|---|---|
schema_name | string | Only rollups on tables of this schema |
table_name | string | Only rollups on this table; requires schema_name |
Response 200 — The rollups
| Name | Type | Description |
|---|---|---|
rollups (required) | Rollup[] |
Fields of rollups
| Name | Type | Description |
|---|---|---|
rollups[].bucket_width_secs (required) | integer | Width of each time bucket, in seconds. |
rollups[].covered_until | string | End (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) | string | When the rollup was declared. |
rollups[].database_id (required) | string | Database that holds the table. |
rollups[].dimensions (required) | string[] | Columns rows are grouped by, besides the time bucket. |
rollups[].error | string | Why the build failed, when status is build_failed; null otherwise. |
rollups[].failed_at | string | When the build failed, when status is build_failed; null otherwise. |
rollups[].filter | string | Condition a row must pass to be kept; absent when every row is kept. |
rollups[].id (required) | string | Rollup ID. |
rollups[].measures (required) | RollupMeasure[] | The measures, as declared. |
rollups[].measures[].centroids | integer | For 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[].column | string | Column 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) | string | Schema of the table. |
rollups[].status (required) | RollupStatus | A 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) | string | The table the rollup is declared on. |
rollups[].time_column (required) | string | Timestamp column rows are bucketed by. |
rollups[].updated_at (required) | string | When the rollup last changed. |
rollups[].window_secs | integer | How 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
| Status | Description |
|---|---|
400 | table_name without schema_name |
404 | No such database |
Declare a rollup on a table
/v1/databases/{database_id}/rollupsDeclare 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
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
Request body
| Name | Type | Description |
|---|---|---|
bucket_width_secs (required) | integer | Width 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 |
dimensions | string[] | Columns to group by, besides the time bucket. A query can also filter on these columns and still use the rollup. |
filter | string | SQL 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) | string | Schema that holds the table. |
table_name (required) | string | Table to roll up. |
time_column (required) | string | Timestamp column to bucket rows by. It must have no time zone, or be in UTC. |
window_secs | integer | How 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
| Name | Type | Description |
|---|---|---|
measures[].centroids | integer | For 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[].column | string | Column 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
| Name | Type | Description |
|---|---|---|
job_id | string | Background 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) | Rollup | A rollup on a database's table: what it keeps, and its state. Queries use it only when status is ready. |
Fields of rollup
| Name | Type | Description |
|---|---|---|
rollup.bucket_width_secs (required) | integer | Width of each time bucket, in seconds. |
rollup.covered_until | string | End (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) | string | When the rollup was declared. |
rollup.database_id (required) | string | Database that holds the table. |
rollup.dimensions (required) | string[] | Columns rows are grouped by, besides the time bucket. |
rollup.error | string | Why the build failed, when status is build_failed; null otherwise. |
rollup.failed_at | string | When the build failed, when status is build_failed; null otherwise. |
rollup.filter | string | Condition a row must pass to be kept; absent when every row is kept. |
rollup.id (required) | string | Rollup ID. |
rollup.measures (required) | RollupMeasure[] | The measures, as declared. |
rollup.measures[].centroids | integer | For 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[].column | string | Column 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) | string | Schema of the table. |
rollup.status (required) | RollupStatus | A 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) | string | The table the rollup is declared on. |
rollup.time_column (required) | string | Timestamp column rows are bucketed by. |
rollup.updated_at (required) | string | When the rollup last changed. |
rollup.window_secs | integer | How 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
| Status | Description |
|---|---|
400 | The declaration does not fit the table |
404 | No such database or table |
409 | An identical rollup already exists, or the table's window differs |
Get a rollup
/v1/databases/{database_id}/rollups/{rollup_id}Get a rollup: its definition, its status, and how far its build has come.
Path parameters
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
rollup_id (required) | string | Rollup ID |
Response 200 — The rollup
| Name | Type | Description |
|---|---|---|
bucket_width_secs (required) | integer | Width of each time bucket, in seconds. |
covered_until | string | End (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) | string | When the rollup was declared. |
database_id (required) | string | Database that holds the table. |
dimensions (required) | string[] | Columns rows are grouped by, besides the time bucket. |
error | string | Why the build failed, when status is build_failed; null otherwise. |
failed_at | string | When the build failed, when status is build_failed; null otherwise. |
filter | string | Condition a row must pass to be kept; absent when every row is kept. |
id (required) | string | Rollup ID. |
measures (required) | RollupMeasure[] | The measures, as declared. |
schema_name (required) | string | Schema of the table. |
status (required) | RollupStatus | A 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) | string | The table the rollup is declared on. |
time_column (required) | string | Timestamp column rows are bucketed by. |
updated_at (required) | string | When the rollup last changed. |
window_secs | integer | How 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
| Name | Type | Description |
|---|---|---|
measures[].centroids | integer | For 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[].column | string | Column 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
| Status | Description |
|---|---|
404 | No such database or rollup |
Drop a rollup
/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
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
rollup_id (required) | string | Rollup ID |
Response 204 — The rollup was dropped
Errors
| Status | Description |
|---|---|
404 | No such database or rollup |
Rebuild a rollup
/v1/databases/{database_id}/rollups/{rollup_id}/rebuildStart 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
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
rollup_id (required) | string | Rollup ID |
Response 202 — The build was started
| Name | Type | Description |
|---|---|---|
job_id | string | Background 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) | Rollup | A rollup on a database's table: what it keeps, and its state. Queries use it only when status is ready. |
Fields of rollup
| Name | Type | Description |
|---|---|---|
rollup.bucket_width_secs (required) | integer | Width of each time bucket, in seconds. |
rollup.covered_until | string | End (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) | string | When the rollup was declared. |
rollup.database_id (required) | string | Database that holds the table. |
rollup.dimensions (required) | string[] | Columns rows are grouped by, besides the time bucket. |
rollup.error | string | Why the build failed, when status is build_failed; null otherwise. |
rollup.failed_at | string | When the build failed, when status is build_failed; null otherwise. |
rollup.filter | string | Condition a row must pass to be kept; absent when every row is kept. |
rollup.id (required) | string | Rollup ID. |
rollup.measures (required) | RollupMeasure[] | The measures, as declared. |
rollup.measures[].centroids | integer | For 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[].column | string | Column 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) | string | Schema of the table. |
rollup.status (required) | RollupStatus | A 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) | string | The table the rollup is declared on. |
rollup.time_column (required) | string | Timestamp column rows are bucketed by. |
rollup.updated_at (required) | string | When the rollup last changed. |
rollup.window_secs | integer | How 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
| Status | Description |
|---|---|
404 | No such database or rollup |
409 | The rollup is ready, is being dropped, or is already being built |
Set a rollup's window
/v1/databases/{database_id}/rollups/{rollup_id}/windowSet 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
| Name | Type | Description |
|---|---|---|
database_id (required) | string | Database ID |
rollup_id (required) | string | Rollup ID |
Request body
| Name | Type | Description |
|---|---|---|
window_secs (required) | integer | How 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
| Name | Type | Description |
|---|---|---|
bucket_width_secs (required) | integer | Width of each time bucket, in seconds. |
covered_until | string | End (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) | string | When the rollup was declared. |
database_id (required) | string | Database that holds the table. |
dimensions (required) | string[] | Columns rows are grouped by, besides the time bucket. |
error | string | Why the build failed, when status is build_failed; null otherwise. |
failed_at | string | When the build failed, when status is build_failed; null otherwise. |
filter | string | Condition a row must pass to be kept; absent when every row is kept. |
id (required) | string | Rollup ID. |
measures (required) | RollupMeasure[] | The measures, as declared. |
schema_name (required) | string | Schema of the table. |
status (required) | RollupStatus | A 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) | string | The table the rollup is declared on. |
time_column (required) | string | Timestamp column rows are bucketed by. |
updated_at (required) | string | When the rollup last changed. |
window_secs | integer | How 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
| Name | Type | Description |
|---|---|---|
measures[].centroids | integer | For 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[].column | string | Column 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
| Status | Description |
|---|---|
400 | The window is zero or too large |
404 | No such database or rollup |
409 | The rollup is being dropped, or its table was replaced |