Skip to navigation
Tools

Batch Write

Deprecated
View as Markdown

Write records to multiple tables in a single transaction.

Deprecated: use write_data (client.data.write), which also writes raw series and supports update and delete.

Supports:

  • Batch references: Use “_ref” to label records, “@refname” to reference them
  • Natural keys: Use human-readable values for foreign keys (e.g., recipe name)
  • Automatic FK ordering: Tables are inserted in dependency order
  • Upsert mode: Update existing records based on match columns
  • Dry run: Validate without committing changes

Committed writes are recorded against a job execution (created automatically if not supplied) and the job_execution_id is returned, so the write can be reverted as a unit.

Requires an API key with the write scope.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
tablesmap from strings to lists of maps from strings to anyRequired

Map of table_name to list of records to insert.

optionsobject or nullOptional

Optional write options (mode, match_on, dry_run, return_records).

Response

OK
summarymap from strings to objects

Count of created/updated records per table.

refsmap from strings to strings

Map of _ref labels to their created IDs.

successbooleanOptionalDefaults to true
Whether the operation succeeded.
job_execution_idstring or nullOptional
The job execution this write was recorded under. Use it to revert the write as a unit. Null for dry runs.
recordsmap from strings to lists of maps from strings to any or nullOptional

Created/updated records (only if return_records=True).

planobject or nullOptional

Execution plan (only if dry_run=True).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error