Write data

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.

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 as each table write is applied, and any failure rolls back the whole request. The write is recorded under a job execution, created if none is given. 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.

Requires an API key with the write scope.