diff --git a/docs/src/operations/ddl/.pages b/docs/src/operations/ddl/.pages index bd8c6daf1..2ea2d686e 100644 --- a/docs/src/operations/ddl/.pages +++ b/docs/src/operations/ddl/.pages @@ -8,9 +8,11 @@ nav: - show-tables.md - describe-table.md - alter-table.md + - set-unenforced-primary-key.md - show-tblproperties.md - drop-table.md - create-index.md + - drop-index.md - show-indexes.md - create-branch.md - drop-branch.md diff --git a/docs/src/operations/ddl/set-unenforced-primary-key.md b/docs/src/operations/ddl/set-unenforced-primary-key.md new file mode 100644 index 000000000..424471a9b --- /dev/null +++ b/docs/src/operations/ddl/set-unenforced-primary-key.md @@ -0,0 +1,56 @@ +# SET UNENFORCED PRIMARY KEY + +Declare primary key columns on a Lance table. + +!!! warning "Spark Extension Required" + This feature requires the Lance Spark SQL extension to be enabled. See [Spark SQL Extensions](../../config.md#spark-sql-extensions) for configuration details. + +## Overview + +The `SET UNENFORCED PRIMARY KEY` command records the primary key columns of a table as schema field metadata. Uniqueness is **not** enforced: no write path validates the declared columns, so duplicate values are accepted. + +## Syntax + +=== "SQL" + ```sql + ALTER TABLE SET UNENFORCED PRIMARY KEY ( [, ...]); + ``` + +Column order is significant and is recorded alongside the declaration. + +## Examples + +### Single-column primary key + +=== "SQL" + ```sql + ALTER TABLE lance.db.users SET UNENFORCED PRIMARY KEY (id); + ``` + +### Composite primary key + +=== "SQL" + ```sql + ALTER TABLE lance.db.users SET UNENFORCED PRIMARY KEY (id, name); + ``` + +## Output + +The `SET UNENFORCED PRIMARY KEY` command returns the following information: + +| Column | Type | Description | +|-----------------------|--------|--------------------------------------------------------------| +| `status` | String | The result status (`OK`). | +| `primary_key_columns` | String | The declared columns, comma-separated, in the order given. | + +## How It Works + +The command commits a new table version that attaches `lance-schema:unenforced-primary-key` field metadata to each declared column, together with its one-based position in the key. Because the change is a normal commit, earlier versions keep their original schema and remain available for time travel. + +## Notes and Limitations + +- The declaration is **write-once**. Setting a primary key on a table that already has one fails; it cannot be changed or removed afterwards. +- Columns must be non-nullable. Declare them `NOT NULL` when running [`CREATE TABLE`](create-table.md). +- Columns must be primitive leaf fields. Struct and other nested columns are rejected. +- The same column may not be listed twice. +- Branch and tag identifiers are read-only, so the command is rejected against them. diff --git a/docs/src/operations/dml/.pages b/docs/src/operations/dml/.pages index 057a3360b..d389c8525 100644 --- a/docs/src/operations/dml/.pages +++ b/docs/src/operations/dml/.pages @@ -1,6 +1,7 @@ title: DML nav: - insert-into.md + - insert-overwrite.md - update.md - delete.md - add-columns.md