Skip to Content
We are live but in Staging 🎉
TablesAPI ReferenceExecute (SQL)INSERT

INSERT

INSERT shapes. The planner classifies each statement by whether the target table has merge_keys and the source — VALUES, multi-VALUES, or SELECT. For the RPC contract and full enum reference, see the Execute hub.

Keyed inserts

PK tables route every insert through the write log → compactor MERGE on next drain. Safe for concurrent writes; visible immediately under freshness=STRONG.

KEYED_INSERT_SINGLE

Single-row insert into a PK table.

INSERT INTO events (id, user_id, occurred_at, event_type, payload)
VALUES (1, 'u-101', TIMESTAMP '2026-05-27 10:00:00', 'click', '{"page":"/pricing"}');

Response:

{
  "write": {
    "rowsWritten": "1",
    "strategy": "WRITE_STRATEGY_KEYED_INSERT_SINGLE",
    "pendingDrain": true,
    "targetTable": "events"
  }
}

KEYED_INSERT_BULK

Multi-row VALUES into a PK table.

INSERT INTO events (id, user_id, occurred_at, event_type, payload) VALUES
  (1, 'u-101', TIMESTAMP '2026-05-27 10:00:00', 'click',    '{"page":"/pricing"}'),
  (2, 'u-101', TIMESTAMP '2026-05-27 10:01:00', 'click',    '{"page":"/signup"}'),
  (3, 'u-102', TIMESTAMP '2026-05-27 10:02:00', 'purchase', '{"sku":"A-12","amount":49.99}');

Response: strategy: WRITE_STRATEGY_KEYED_INSERT_BULK, rowsWritten: "3".

KEYED_INSERT_FROM_SELECT

INSERT ... SELECT into a PK table — K3 materializes the source rows, then bulk-appends to the write log.

-- Backfill click_summary from the events table
INSERT INTO click_summary (user_id, n)
SELECT user_id, COUNT(*) FROM events
WHERE event_type = 'click'
GROUP BY user_id;

Response: strategy: WRITE_STRATEGY_KEYED_INSERT_FROM_SELECT.

Non-keyed inserts (Delta-direct)

NON_KEYED_INSERT

Single or multi-row insert into a table without merge_keys. Appended directly to Delta — no write log.

-- audit_log has no PK
INSERT INTO audit_log (ts, actor, action, target) VALUES
  (CURRENT_TIMESTAMP, 'admin', 'optimize', 'events'),
  (CURRENT_TIMESTAMP, 'admin', 'vacuum',   'events');

Response:

{
  "write": {
    "rowsWritten": "2",
    "strategy": "WRITE_STRATEGY_NON_KEYED_INSERT",
    "pendingDrain": false,
    "targetTable": "audit_log"
  }
}

NON_KEYED_INSERT_FROM_SELECT

INSERT ... SELECT into a no-PK target. K3 materializes the SELECT then bulk-appends to Delta.

INSERT INTO event_archive
SELECT * FROM events WHERE occurred_at < TIMESTAMP '2025-01-01 00:00:00';

See also

SELECTUPDATE