tools

Batch Write

View as Markdown
Write records to multiple tables in a single transaction. 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.

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.

successbooleanDefaults to true
Whether the operation succeeded.
job_execution_idstring or null
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 null

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

planobject or null

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