Batch Write

tools.batch_write() -> ToolBatchWriteResponse

post/api/v1/tools/batch-write

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

ParametersExpand Collapse

tables: Dict[str, Iterable[Dict[str, object]]]

Map of table_name to list of records to insert.

options: Optional[Options]

Options for controlling batch write behavior.

dry_run: Optional[bool]

If True, validate without committing changes.

match_on: Optional[Dict[str, SequenceNotStr[str]]]

For upsert: which columns to match on, per table. Example: {"production_run": ["run_code"]}

mode: Optional[Literal["insert", "upsert"]]

'insert' creates new records, and fails if the record already exists. 'upsert' creates or updates based on match_on columns.

Accepts one of the following:

"insert"

"upsert"

return_records: Optional[bool]

If True, include created/updated records in response.

ReturnsExpand Collapse

class ToolBatchWriteResponse: …

Response from a successful batch write.

refs: Dict[str, str]

Map of _ref labels to their created IDs.

summary: Dict[str, Summary]

Count of created/updated records per table.

created: Optional[int]

Number of records created.

updated: Optional[int]

Number of records updated.

plan: Optional[Plan]

Execution plan returned by dry_run.

insert_order: List[str]

Order in which tables will be inserted.

operations: List[Dict[str, object]]

Operations that would be performed.

records: Optional[Dict[str, List[Dict[str, object]]]]

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

success: Optional[bool]

Whether the operation succeeded.

Batch Write

from labric import Labric

client = Labric(
    api_key="My API Key",
)
response = client.tools.batch_write(
    tables={
        "foo": [{
            "foo": "bar"
        }]
    },
)
print(response.refs)

{
  "refs": {
    "foo": "string"
  },
  "summary": {
    "foo": {
      "created": 0,
      "updated": 0
    }
  },
  "plan": {
    "insert_order": [
      "string"
    ],
    "operations": [
      {
        "foo": "bar"
      }
    ]
  },
  "records": {
    "foo": [
      {
        "foo": "bar"
      }
    ]
  },
  "success": true
}

Returns Examples

{
  "refs": {
    "foo": "string"
  },
  "summary": {
    "foo": {
      "created": 0,
      "updated": 0
    }
  },
  "plan": {
    "insert_order": [
      "string"
    ],
    "operations": [
      {
        "foo": "bar"
      }
    ]
  },
  "records": {
    "foo": [
      {
        "foo": "bar"
      }
    ]
  },
  "success": true
}