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

Materialize 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.

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
fromCollectionstring

The collection to snapshot into the dataset.

Send exactly one of fromCollection and fromQuery.

A collection name: a letter or underscore, then letters, digits or underscores.

fromQuerystring

The saved Studio Query (stq_...) whose result to snapshot into the dataset.

Send exactly one of fromCollection and fromQuery.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUESend exactly one of `fromCollection` or `fromQuery`, and the source's columns must map onto the dataset.
400K9O_DATASET_QUERY_SOURCE_AMBIGUOUSThe saved query does not read exactly one collection.
400K9O_DATASET_RESIDENCY_SOURCE_MISMATCHThe collection holds per-subject personal data and the dataset is `shared`.
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.
403K9O_FORBIDDENPlatform telemetry datasets are read-only.
404K9O_NOT_FOUNDThe project was not found for this caller (project service tokens and extension tokens cannot call this endpoint).
404K9O_COLLECTION_NOT_FOUNDThe source collection does not exist.
404K9O_STUDIO_QUERY_NOT_FOUNDThe saved query does not exist.
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
503K9O_ANALYTICS_UNAVAILABLEThe region's analytics storage is not available yet; retry later.
Response body (200)
data *object

The snapshot written into the dataset: what was read, written and refused.

datasetId *string

The target dataset's id (dset_...).

sourceCollectionstring

The collection read.

Present when the request sent fromCollection.

fromQuerystring

The Studio Query read (stq_...).

Present when the request sent fromQuery.

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 region=eu/occurred_at=2026-08-30.

bytesWritteninteger

Bytes written to storage.

Present only when something was written.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.materialize('<datasetSlug>', {})

Showing example in TypeScript

Request example
{
  "fromCollection": "string",
  "fromQuery": "string"
}
Response example (200)
{
  "data": {
    "datasetId": "string",
    "sourceCollection": "string",
    "fromQuery": "string",
    "rowsRead": 0,
    "ingested": 0,
    "rejected": 0,
    "partitionsTouched": [
      "string"
    ],
    "bytesWritten": 0
  }
}

More in Analytics & Intelligence