From ac2956c1e227e9b744d980a153863973b28bf4da Mon Sep 17 00:00:00 2001 From: Dan Tasse Date: Tue, 25 Aug 2026 15:56:54 -0400 Subject: [PATCH] docs: add comments about metadata conventions --- docs/src/js/classes/Table.md | 11 +++++++++++ docs/src/js/interfaces/FieldMetadataUpdate.md | 3 ++- nodejs/lancedb/table.ts | 14 +++++++++++++- python/python/lancedb/table.py | 12 ++++++++++++ rust/lancedb/src/table.rs | 17 ++++++++++++++++- rust/lancedb/src/table/schema_evolution.rs | 4 +++- 6 files changed, 57 insertions(+), 4 deletions(-) diff --git a/docs/src/js/classes/Table.md b/docs/src/js/classes/Table.md index 06dc8479e..5ff2265e9 100644 --- a/docs/src/js/classes/Table.md +++ b/docs/src/js/classes/Table.md @@ -1292,6 +1292,17 @@ abstract updateFieldMetadata(updates): Promise Update per-field (column) metadata. +The following keys are treated specially, by convention, and should be +used when appropriate: + +- `lancedb:description`: for a human-readable description of a field. +- `lancedb:tag:(tag_name)`: for a user-defined key-value tag. +- `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and + `feature_v2` might be in the same logical_column. +- `lancedb:status`: for status options (`production`, `candidate`, + `deprecated`, `archived`) to designate the current life cycle state of + this column. + #### Parameters * **updates**: [`FieldMetadataUpdate`](../interfaces/FieldMetadataUpdate.md)[] diff --git a/docs/src/js/interfaces/FieldMetadataUpdate.md b/docs/src/js/interfaces/FieldMetadataUpdate.md index 38c675630..a85e3e7a0 100644 --- a/docs/src/js/interfaces/FieldMetadataUpdate.md +++ b/docs/src/js/interfaces/FieldMetadataUpdate.md @@ -17,7 +17,8 @@ metadata: Record; ``` Metadata key/value pairs. Merged into the field's existing metadata by -default; a value of `null` deletes that key. +default; a value of `null` deletes that key. See +[Table.updateFieldMetadata](../classes/Table.md#updatefieldmetadata) for the conventional `lancedb:*` keys. *** diff --git a/nodejs/lancedb/table.ts b/nodejs/lancedb/table.ts index 28603cca9..71ee08ee5 100644 --- a/nodejs/lancedb/table.ts +++ b/nodejs/lancedb/table.ts @@ -628,6 +628,17 @@ export abstract class Table { /** * Update per-field (column) metadata. + * + * The following keys are treated specially, by convention, and should be + * used when appropriate: + * + * - `lancedb:description`: for a human-readable description of a field. + * - `lancedb:tag:(tag_name)`: for a user-defined key-value tag. + * - `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and + * `feature_v2` might be in the same logical_column. + * - `lancedb:status`: for status options (`production`, `candidate`, + * `deprecated`, `archived`) to designate the current life cycle state of + * this column. * @param {FieldMetadataUpdate[]} updates One or more per-field updates. Each * update's metadata is merged into the field's existing metadata by default; * a value of `null` deletes that key, and `replace: true` swaps the whole map. @@ -1538,7 +1549,8 @@ export interface FieldMetadataUpdate { path: string; /** * Metadata key/value pairs. Merged into the field's existing metadata by - * default; a value of `null` deletes that key. + * default; a value of `null` deletes that key. See + * {@link Table.updateFieldMetadata} for the conventional `lancedb:*` keys. */ metadata: Record; /** If true, replace the field's entire metadata map instead of merging. */ diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py index b3cab006e..ced2d55ef 100644 --- a/python/python/lancedb/table.py +++ b/python/python/lancedb/table.py @@ -2120,12 +2120,24 @@ class Table(ABC): ---------- updates : dict One or more dicts, each with: + - "path": str — dot-path to the field (e.g. "embedding" or "a.b.c"). - "metadata": dict[str, str | None] — keys to set; a value of ``None`` deletes that key. - "replace": bool, optional — replace the field's whole metadata map instead of merging (default False). + The following keys are treated specially, by convention, and should + be used when appropriate: + + - "lancedb:description": for a human-readable description of a field. + - "lancedb:tag:(tag_name)" for a user-defined key-value tag. + - "lancedb:logical_column" for a column grouping; e.g. "feature_v1" + and "feature_v2" might be in the same logical_column. + - "lancedb:status" for status options ("production", "candidate", + "deprecated", "archived") to designate the current life cycle + state of this column. + Returns ------- UpdateFieldMetadataResult diff --git a/rust/lancedb/src/table.rs b/rust/lancedb/src/table.rs index efc36d260..e44a78515 100644 --- a/rust/lancedb/src/table.rs +++ b/rust/lancedb/src/table.rs @@ -1752,7 +1752,22 @@ impl Table { self.inner.alter_columns(alterations).await } - /// Update per-field metadata (merges by default). + /// Update per-field (column) metadata. + /// + /// Each [`FieldMetadataUpdate`] is merged into the field's existing metadata + /// by default; use [`FieldMetadataUpdate::remove`] to delete a key, or + /// [`FieldMetadataUpdate::replace`] to swap the field's entire metadata map. + /// + /// The following keys are treated specially, by convention, and should be + /// used when appropriate: + /// + /// - `lancedb:description`: for a human-readable description of a field. + /// - `lancedb:tag:(tag_name)`: for a user-defined key-value tag. + /// - `lancedb:logical_column`: for a column grouping; e.g. `feature_v1` and + /// `feature_v2` might be in the same logical_column. + /// - `lancedb:status`: for status options (`production`, `candidate`, + /// `deprecated`, `archived`) to designate the current life cycle state of + /// this column. pub async fn update_field_metadata( &self, updates: &[FieldMetadataUpdate], diff --git a/rust/lancedb/src/table/schema_evolution.rs b/rust/lancedb/src/table/schema_evolution.rs index d10a45eea..4f8dc811a 100644 --- a/rust/lancedb/src/table/schema_evolution.rs +++ b/rust/lancedb/src/table/schema_evolution.rs @@ -55,7 +55,9 @@ pub struct DropColumnsResult { pub struct FieldMetadataUpdate { /// Dot-separated path to the field (e.g. `"embedding"` or `"address.zip"`). pub path: String, - /// Keys to set (`Some`) or delete (`None`). + /// Keys to set (`Some`) or delete (`None`). See + /// [`Table::update_field_metadata`](crate::Table::update_field_metadata) for + /// the conventional `lancedb:*` keys. pub metadata: HashMap>, /// If `true`, replace the field's entire metadata map instead of merging. pub replace: bool,