Skip to main content
POST/analytics/{datasetSlug}

Create Dataset

Creates a dataset at the slug in the path.

Body:

  • displayName.
  • columns (1 to 512, each {name, type} with type string, int32, int64, float64, bool, date, timestamp, json, bytes or decimal(p,s)).
  • Optional partitionBy.
  • residencyClass (per-subject or shared).
  • 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.

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

string, int32, int64, float64, bool, date, timestamp, json, bytes, or decimal(p,s) with a precision of 1 to 38 and a scale of 0 to p.

partitionBystring[]

Up to 16 partition keys, each a declared column.

A timestamp or date column may take a transform, <column>:year, :month, :day or :hour; a bare timestamp is refused.

Only string, bool, int32, int64 and date columns can be partition keys without a transform. region is added first automatically; don't declare it.

residencyClass *"per-subject" | "shared"

per-subject: rows hold data about individual people, sealed per person and kept in that person's region. shared: rows are not about any one person.

storageTargetany

Where to keep the dataset's files: managed (the default) for platform-managed storage, or byos with the bindingId of a storage location you connected.

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.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_REQUEST_SHAPEThe request body does not match the schema.
400K9O_DATASET_INVALIDThe slug is reserved, invalid or already used (slugs are never reissued), or a column, type or partition key is invalid.
400K9O_DATASET_STORAGE_TARGET_INVALIDThe storage location in `storageTarget` does not exist or is retired.
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:create.
404K9O_NOT_FOUNDThe project was not found for this caller (project service tokens and extension tokens cannot call this endpoint).
409K9O_STATE_CONFLICTThe chosen storage location is write-once and cannot hold a dataset.
429K9O_DATASET_LIMIT_EXCEEDEDThe project already has the maximum number of datasets (200).
Response body (201)
data *object

The dataset that was created, with the paths to write, query and upload to.

id *string

dset_ id.

slug *string

The dataset's name, unique in the project.

Queries refer to it as dataset.<slug>.

displayName *string

The name shown for the dataset.

schema *object[]

The declared columns, in order.

name *string

The column's name.

type *string

string, int32, int64, float64, bool, date, timestamp, json, bytes, or decimal(p,s).

partitionKeys *string[]

Always starts with region, then the declared partitionBy keys.

residencyClass *"per-subject" | "shared"

per-subject: rows hold data about individual people, sealed per person and kept in that person's region. shared: rows are not about any one person.

storageTarget *any

Where the dataset's files are kept: managed for platform-managed storage, or byos with the bindingId of a storage location you connected.

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: <slug>/write, <slug>/query, <slug>/upload.

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
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.create('<datasetSlug>', {})

Showing example in TypeScript

Request example
{
  "displayName": "string",
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "partitionBy": [
    "string"
  ],
  "residencyClass": "per-subject",
  "storageTarget": {
    "kind": "managed"
  }
}
Response example (201)
{
  "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"
      }
    ]
  }
}

More in Analytics & Intelligence