/analytics/{datasetSlug}Create Dataset
Creates a dataset at the slug in the path.
Body:
displayName.columns(1 to 512, each{name, type}with typestring,int32,int64,float64,bool,date,timestamp,json,bytesordecimal(p,s)).- Optional
partitionBy. residencyClass(per-subjectorshared).- Optional
storageTarget({kind: "managed"}or{kind: "byos", bindingId}).
A timestamp partition key needs a transform such as :day; region is added automatically.
Slugs are lowercase identifiers, some words are reserved, and a slug is never reissued, even after the dataset is deleted.
A project holds at most 200 datasets (429 K9O_DATASET_LIMIT_EXCEEDED).
Returns 201 with the dataset and its endpoints.
Requires the datasets:create 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.
| datasetSlug * | path | The Dataset's slug. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| displayName * | string | The name shown for the dataset, 1 to 200 characters. |
| columns * | object[] | The dataset's columns, in order: 1 to 512, with unique names. |
| name * | string | The column's name, unique in the dataset. |
| type * | string |
|
| partitionBy | string[] | Up to 16 partition keys, each a declared column. A Only |
| residencyClass * | "per-subject" | "shared" |
|
| storageTarget | any | Where to keep the dataset's files: |
| One of: object | ||
| kind * | "managed" | Platform-managed storage. |
| or: object | ||
| kind * | "byos" | A storage location you connected. |
| bindingId * | string | The storage location's binding id. It must be live, and not the location that holds the audit anchors. |
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | Created | |
| 400 | K9O_INVALID_REQUEST_SHAPE | The request body does not match the schema. |
| 400 | K9O_DATASET_INVALID | The slug is reserved, invalid or already used (slugs are never reissued), or a column, type or partition key is invalid. |
| 400 | K9O_DATASET_STORAGE_TARGET_INVALID | The storage location in `storageTarget` does not exist or is retired. |
| 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:create. |
| 404 | K9O_NOT_FOUND | The project was not found for this caller (project service tokens and extension tokens cannot call this endpoint). |
| 409 | K9O_STATE_CONFLICT | The chosen storage location is write-once and cannot hold a dataset. |
| 429 | K9O_DATASET_LIMIT_EXCEEDED | The project already has the maximum number of datasets (200). |
| data * | object | The dataset that was created, with the paths to write, query and upload to. |
| id * | string |
|
| slug * | string | The dataset's name, unique in the project. Queries refer to it as |
| displayName * | string | The name shown for the dataset. |
| schema * | object[] | The declared columns, in order. |
| name * | string | The column's name. |
| type * | string |
|
| partitionKeys * | string[] | Always starts with |
| residencyClass * | "per-subject" | "shared" |
|
| storageTarget * | any | Where the dataset's files are kept: |
| One of: object | ||
| kind * | "managed" | Platform-managed storage. |
| or: object | ||
| kind * | "byos" | A storage location you connected. |
| bindingId * | string | The storage location's binding id. |
| createdAt * | string <date-time> | When the dataset was created. |
| retiredAt * | null | Always null: a retired dataset reads as absent. |
| endpoints * | object | Relative paths: |
| write * | string | The path to write rows to, relative to the dataset. |
| query * | string | The path to query the dataset, relative to the dataset. |
| upload * | string | The path to upload a CSV or JSON file to, relative to the dataset. |
| 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 | |
| projectId | string | |
| warnings | object[] | |
| code * | string | |
| message * | string | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.create('<datasetSlug>', {})Showing example in TypeScript
{
"displayName": "string",
"columns": [
{
"name": "string",
"type": "string"
}
],
"partitionBy": [
"string"
],
"residencyClass": "per-subject",
"storageTarget": {
"kind": "managed"
}
}{
"data": {
"id": "string",
"slug": "string",
"displayName": "string",
"schema": [
{
"name": "string",
"type": "string"
}
],
"partitionKeys": [
"string"
],
"residencyClass": "per-subject",
"storageTarget": {
"kind": "managed"
},
"createdAt": "string",
"endpoints": {
"write": "string",
"query": "string",
"upload": "string"
}
},
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}