/analytics/{datasetSlug}/materializeMaterialize Collection
Copies rows into the dataset from exactly one source: fromCollection (a collection name) or fromQuery (a saved Studio query id that reads a single collection).
The source is read with the caller's own row-level access.
Returns counts (rowsRead, ingested, rejected) and the partitions touched.
Copying a collection that holds per-subject personal data into a shared dataset is refused (400 K9O_DATASET_RESIDENCY_SOURCE_MISMATCH).
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.
Returns 503 K9O_ANALYTICS_UNAVAILABLE until the region's analytics storage is provisioned.
| datasetSlug * | path | The Dataset's slug. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| fromCollection | string | The collection to snapshot into the dataset. Send exactly one of A collection name: a letter or underscore, then letters, digits or underscores. |
| fromQuery | string | The saved Studio Query ( Send exactly one of |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | Send exactly one of `fromCollection` or `fromQuery`, and the source's columns must map onto the dataset. |
| 400 | K9O_DATASET_QUERY_SOURCE_AMBIGUOUS | The saved query does not read exactly one collection. |
| 400 | K9O_DATASET_RESIDENCY_SOURCE_MISMATCH | The collection holds per-subject personal data and the dataset is `shared`. |
| 401 | K9O_UNAUTHENTICATED | The caller is not signed in. |
| 403 | K9O_ACCESS_DENIED | The caller is not a member of this project; an organization role alone does not grant access. |
| 403 | K9O_IAM_POLICY_DENIED | The caller's role or IAM policy does not grant datasets:write. |
| 403 | K9O_FORBIDDEN | Platform telemetry datasets are read-only. |
| 404 | K9O_NOT_FOUND | The project was not found for this caller (project service tokens and extension tokens cannot call this endpoint). |
| 404 | K9O_COLLECTION_NOT_FOUND | The source collection does not exist. |
| 404 | K9O_STUDIO_QUERY_NOT_FOUND | The saved query does not exist. |
| 404 | K9O_DATASET_NOT_FOUND | No active dataset with this slug exists in the project. |
| 503 | K9O_ANALYTICS_UNAVAILABLE | The region's analytics storage is not available yet; retry later. |
| data * | object | The snapshot written into the dataset: what was read, written and refused. |
| datasetId * | string | The target dataset's id ( |
| sourceCollection | string | The collection read. Present when the request sent |
| fromQuery | string | The Studio Query read ( Present when the request sent |
| rowsRead * | integer | Rows read from the source, as the caller's own row-level access allowed. |
| ingested * | integer | Rows written to the dataset. |
| rejected * | integer | Rows the dataset write refused. |
| partitionsTouched * | string[] | The partition paths written, region first, such as |
| bytesWritten | integer | Bytes written to storage. Present only when something was written. |
| meta * | any |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.materialize('<datasetSlug>', {})Showing example in TypeScript
{
"fromCollection": "string",
"fromQuery": "string"
}{
"data": {
"datasetId": "string",
"sourceCollection": "string",
"fromQuery": "string",
"rowsRead": 0,
"ingested": 0,
"rejected": 0,
"partitionsTouched": [
"string"
],
"bytesWritten": 0
}
}