Skip to navigation

Write data

View as Markdown

Insert, upsert, update, or delete rows across tables, and write raw series, in a single transaction.

Table writes target the organization’s tables from get_schema or core tables such as experiment, operation, and carrier. They are applied in request order, so one request can create a sample and then the measurements that reference it: label a row with “_ref”: “s1” and point at it with “@s1” from a foreign key column of any later row. A foreign key may also be a lookup object such as {“name”: “S-001”} that matches exactly one row that existed before the request. Primary keys are generated when omitted where the table allows it, and are always returned in input order.

The operationsubject and entityderivation core tables link rows of other tables. Their object_id, parent_id, and child_id columns name a row of the table given beside them, by id or by an “@s1” reference to an earlier row. These tables take only insert and delete. An insert that repeats a stored link returns the stored row. An operation subject with a role fills in the role of a stored subject of the same entity that has none.

A series holds the points of one parent row in a raw table as one list per column. Writing a series replaces the parent’s existing series in that table, so repeating a write is safe. The server fills in the primary key, the parent foreign key, and an integer order column.

Every row, series, and lookup is checked before anything is written, and all of those problems are reported together in errors. Each has a path naming its place in the request, such as tables[1].rows[0].sample. Keys for upsert, update, and delete are matched, and linked rows are checked, as each table write is applied. Any failure rolls back the whole request. The write is recorded under the given job execution, the running job’s execution when called from a job script, or a new one. Reverting that execution deletes the rows it created along with their series. Updates, deletes, and series written to existing parents are not undone.

The request body must be under 4.5 MB, which the row and series value limits keep most requests within.

A write that waits too long on rows other writes are changing fails with 429 and changes nothing. Retry it after the Retry-After header’s delay.

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.
tableslist of objectsOptional
Table writes, applied in order. A row may reference only rows that appear before it. At most 10,000 rows across all table writes.
serieslist of objectsOptional
Raw series, applied after the table writes. Writing a series replaces any series the parent already has in that table. At most 250,000 values across all columns of all series.
job_execution_idstring or nullOptionalformat: "uuid"
Job execution to record this write under. When omitted, a job script's write uses the running job's execution. Other writes get a new execution, returned so the write can be reverted as a unit.
job_namestring or nullOptional

Name of the job an auto-created execution belongs to. Defaults to ‘Off-Platform Manual Job’.

dry_runbooleanOptionalDefaults to false
Run every validation and constraint check, then roll back instead of committing.
return_rowsbooleanOptionalDefaults to false
Include the written rows of each table write in its result.

Response

OK
job_execution_idstring or null
Job execution the write was recorded under, for reverting it. Null on a dry run.
tableslist of objects
One result per table write, in request order.
serieslist of objects
One result per series, in request order.
refsmap from strings to strings

Primary key of every row labeled with _ref.

Errors

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