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.
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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
Name of the job an auto-created execution belongs to. Defaults to ‘Off-Platform Manual Job’.
Response
Primary key of every row labeled with _ref.