opschain entity bulk-create

Included from Basic tier

opschain entity bulk-create <parent-path> --file <batch.yaml|batch.json>

Creates a batch of entities under one parent in set-based writes — the lane for recording many schemas, racks or rooms at once. The file is YAML or JSON with one items list; each item takes code, name and an optional description, and any other key is refused before anything is sent.

items:
  - code: orders
    name: Orders
    description: Order headers
  - code: order_lines
    name: Order lines

{"items": [{"code": "orders", "name": "Orders"}, {"code": "order_lines", "name": "Order lines"}]}

opschain entity bulk-create shop/environments/prod/entities/orders_schema --file tables.yaml
Created: 2  Failed: 0  (2 item(s) in 1 batch(es) under /projects/shop/environments/prod/entities/orders_schema)

Each item is created or refused on its own: a bad or taken code, a name already used, a duplicate within the batch, or a path a deleted entity still reserves fails that item alone, printed as Failed <code>: <reason>, and the rest are created. Per-item refusals do not change the exit code — read the Failed: count (or the failed field of -o json).

The server takes at most 1000 items per write. A larger file is split into consecutive batches of 1000 and the totals are summed. If the server refuses a whole batch (for example the parent is missing, or your session needs step-up), the command stops, exits 1 and states how many items earlier batches already submitted, with their created and failed counts, and the first item number that was not sent. Re-running the same file is safe: items already created fail by name as taken codes.

-o, --output json|yaml emits parent_path, batches, created, failed and one results row per item (code, node_id, outcome, error), in file order.

Flags

Flag	Meaning
-f, --file <path>	YAML or JSON batch file (required).

Exit codes

Code	Meaning
0	Every batch was answered (per-item refusals included).
1	The server refused a whole batch — missing or unreadable parent, a parent kind that cannot hold entities, the embedded store, an authorisation step-up.
2	Usage error — no --file, an unreadable or malformed file, an unknown key, no items, an item with a blank code, no server target.

See also

• opschain docs resources/entity — the batch item and result shapes.