Write rows to dataset table

POST

/dataset-tables/{tableId}/rows

Production API

Write data to a dataset table. Supports JSON, CSV, Parquet, or Arrow IPC format.

Query Parameters:

mode: Write operation mode
- append: Insert new rows without checking for duplicates (fastest)
- upsert: Insert new rows or update existing rows by primary key
- overwrite: Replace all existing data in the table
- delete: Delete rows by primary key
idempotency_key: Optional key for exactly-once semantics
skip_validation: Skip schema validation (faster but riskier)

Content Types:

application/json: Body is array of row objects (or array of PKs for delete)
text/csv or application/csv: CSV file with header row
application/parquet: Parquet binary file
application/vnd.apache.arrow.stream: Body is raw Arrow IPC bytes

CSV/Parquet Requirements:

Column names matched case-insensitively
Values automatically coerced to schema types
Maximum file size: 100MB per request
For delete mode, full rows accepted (primary key columns extracted automatically)

Authorizations

bearerAuth
cookieAuth

Parameters

Path Parameters

tableId

required

Unique identifier of the table to retrieve

string

Unique identifier of the table to retrieve

Query Parameters

mode

required

Write operation mode

string

Allowed values: upsert append delete overwrite

Write operation mode

idempotency_key

Unique key for exactly-once write semantics

string

Unique key for exactly-once write semantics

skip_validation

Skip schema validation for faster writes

boolean

nullable

Skip schema validation for faster writes

Responses

200

Rows written successfully

object

rows_affected

required

Total number of rows affected by the operation

number

rows_inserted

Number of new rows inserted

number

rows_updated

Number of existing rows updated

number

rows_deleted

Number of rows deleted

number

dataset_version

required

New table version after the operation

number

duration_ms

required

Operation duration in milliseconds

number

warnings

Non-fatal warnings encountered during the operation

Array<string>

usage

Object store I/O metrics for billing

object

getOptsCold

required

GET operations (full object fetch) - cache miss

number

getOptsWarm

required

GET operations (full object fetch) - cache hit

number

getRangeCold

required

Range read operations - cache miss

number

getRangeWarm

required

Range read operations - cache hit

number

getRangesCold

required

Multi-range read operations - cache miss

number

getRangesWarm

required

Multi-range read operations - cache hit

number

headCold

required

HEAD (metadata) operations - cache miss

number

headWarm

required

HEAD (metadata) operations - cache hit

number

listCold

required

LIST operations (directory listing) - cache miss

number

listWarm

required

LIST operations (directory listing) - cache hit

number

putOperations

required

PUT operations (writes are never cached)

number

deleteOperations

required

DELETE operations

number

cacheHitRatePercent

required

Overall cache hit rate as a percentage (0-100)

number

readBytesCold

required

Total bytes read from upstream storage (cache miss)

number

readBytesWarm

required

Total bytes read from L2 cache (cache hit)

number

writeBytes

required

Total bytes written (PUT operations)

number

400

Bad Request - Validation error or invalid input

object

error

required

string

code

string

details

nullable

retryable

boolean

401

Unauthorized - Authentication required or invalid token

object

error

required

string

code

string

details

nullable

retryable

boolean

403

Forbidden - Insufficient permissions

object

error

required

string

code

string

details

nullable

retryable

boolean

404

Not Found - Resource does not exist

object

error

required

string

code

string

details

nullable

retryable

boolean

413

Payload Too Large - Request body exceeds size limit

object

error

required

string

code

string

details

nullable

retryable

boolean

500

Internal Server Error - Unexpected server error

object

error

required

string

code

string

details

nullable

retryable

boolean