Write Data Store

​

What it does

​

Parameters

​

Key behaviors

• upsert is the way to save keyed rows — “save this user’s score for this deal” is one call, with no select-first and no race. It needs a unique index on the conflict keys. The result reports whether the row was inserted or updated.
• Optimistic concurrency — pass if_match with the version you last read (e.g. an updated_at); if another writer changed the row first, the write is skipped and the current row is returned so you can reconcile.
• batch is atomic — several mutations in one transaction, all committed or none. Use it for coordinated multi-row changes.
• update and delete require at least one filter — a guard against accidentally rewriting a whole table.
• Errors carry the raw Postgres code (for example 23505 for a unique violation) plus the constraint name, so callers can branch on the code rather than parse a message.
• bulk_load is file transport — for rows the agent is moving (imports, daily syncs from an external system), not reasoning about. The agent writes JSONL to the sandbox with execute_python, then one bulk_load call streams it server-side in a single transaction — the rows never pass through model context. mode: upsert with conflict_keys makes a daily refresh idempotent. More than 5 malformed lines aborts the whole load rather than half-loading a garbled file.

​

Common use cases

​

Insert rows

operation: insert
knowledge_base_id: 954
table: project_stages
rows:
  - { stage_name: Kickoff, status: pending, sort_order: 1 }

​

Upsert a keyed row

operation: upsert
knowledge_base_id: 954
table: scores
row: { deal_name: Project Oak, partner_name: Sarah Chen, score: 8 }
conflict_keys: [deal_name, partner_name]

​

Related

• Manage Data Store — create tables, columns, views
• Query Data Store — read data with SQL
• Data Stores — the feature overview