Set a composite primary key
Replace a table's whole primary-key column set in one atomic operation - single, composite, or cleared.
set_primary_key replaces a table's entire primary-key column set in one
call and one Delta commit. Send the full list you want: one column for a simple
key, several for a composite key, an empty list to clear the key. The key is
validated as a combination - columns that aren't unique on their own are
accepted as long as the combination is.
Use this instead of toggling is_primary_key per column via
column settings: the
per-column route validates each column cumulatively, so a composite key whose
first column has duplicates is rejected before you can add the second.
Before you start
- Requires the
tables:modifyscope (Builder or Admin; on a workspace-owned config, your workspace role governs). - The columns must already exist - add them first.
Set the key
# composite key
eddytor set primary-key eddytor sales orders --columns region,order_seq
# single-column key
eddytor set primary-key eddytor sales orders --columns order_id
# clear the key (bare --columns is the explicit "empty list")
eddytor set primary-key eddytor sales orders --columns--columns is required - omitting it errors instead of silently clearing the key.
PUT /v1/tables/eddytor/cfg_xxx/<uuid>_orders/primary-key
Authorization: Bearer edd_live_…
{ "columns": ["region", "order_seq"] }An empty columns array clears the key.
set_primary_key(table="eddytor.cfg_xxx.<uuid>_orders",
columns=["region", "order_seq"])Column order in the list doesn't matter, and re-sending the current set is a no-op - no new table version is written.
What it does
- Validates the combination once. One duplicate scan over the full column list. Existing data with duplicate combinations rejects the request.
- Applies everything in one commit. New key columns are marked, columns
removed from the key are demoted, and
is_uniqueis synced - as a single Delta version. There is no partial state to clean up after a failure. - Manages
is_uniquefor you. A single-column key is marked unique; the columns of a composite key are marked not individually unique (they are unique together). Columns demoted out of the key keep their previousis_uniqueflag.
Good to know
is_unique on a key column is derived from the key
shape, changing it manually via
column settings is
rejected with Cannot change 'isUnique' on primary-key column …. Change the key
itself instead.If it's rejected
| Error | Cause → fix |
|---|---|
Cannot set primary key (region, order_seq): key has 3 duplicate combination(s) | Existing rows collide on the proposed key. Find them with GROUP BY … HAVING COUNT(*) > 1 via SQL, fix the data, retry. Counts cap at at least 5. |
Column 'x' not found | Typo, or the column doesn't exist yet → add it. |
Column 'x' appears more than once in the primary key list | De-duplicate the list. |