From 8dc0dc17cf3761c842982201bc26b7d43a08a1cd Mon Sep 17 00:00:00 2001 From: Brendan Clement Date: Fri, 9 Oct 2026 13:44:42 -0700 Subject: [PATCH] docs: add naming rules for databases, namespaces, tables and views One page states the characters and lengths each kind of name can have, following the rules lancedb #4490 centralizes, with examples. It says what enforces them today: the embedded library checks table characters but not length, a directory namespace accepts more, the SDKs check db:// names only from the first release that includes #4490 (none yet), and a deployment can accept a longer name at creation and fail on it later. Readers are told to keep to the rules regardless. Limits, table creation and namespaces link to it. --- docs/web/basics/limits.mdx | 4 +- docs/web/basics/naming.mdx | 72 +++++++++++++++++++++++++++++ docs/web/docs.json | 3 +- docs/web/ingestion/create-table.mdx | 3 +- docs/web/management/namespace.mdx | 2 +- 5 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 docs/web/basics/naming.mdx diff --git a/docs/web/basics/limits.mdx b/docs/web/basics/limits.mdx index 69815fbab..858c45663 100644 --- a/docs/web/basics/limits.mdx +++ b/docs/web/basics/limits.mdx @@ -26,7 +26,9 @@ deployment. A name must not be empty, and must not contain `$` or `:` -- both are reserved as path delimiters, so a name holding one could not be addressed unambiguously. Length is counted in characters, not bytes. These lengths are a deployment's -limits; the embedded library does not limit name length. +limits; the embedded library does not limit name length. Keep to them anyway, +and to the characters in [Naming rules](/basics/naming), which says what each +connection and version checks. ## Jobs {#jobs} diff --git a/docs/web/basics/naming.mdx b/docs/web/basics/naming.mdx new file mode 100644 index 000000000..2c5373278 --- /dev/null +++ b/docs/web/basics/naming.mdx @@ -0,0 +1,72 @@ +--- +title: "Naming rules" +sidebarTitle: "Naming Rules" +description: "The names a database, namespace, table or view can have, and which versions check them." +icon: signature +keywords: ["names", "naming", "table name", "namespace name", "identifier", "characters", "limits"] +--- + +A name ends up in a storage path, in a deployment's URLs, and in the identifiers +that [authorization](/governance/authorization) records, so not every string +works as one. A name that follows the rules on this page works on every +connection. Some connections accept more today, as +[below](#which-versions-check-them), but treat these rules as the contract. + +## The rules {#rules} + +| Object | Characters | Length | +| --- | --- | --- | +| Table, materialized view | ASCII letters and digits, `-`, `_`, `.` | 1 to 128 characters | +| View | ASCII letters and digits, `-`, `_`, `.` | 1 to 128 characters | +| Namespace | each component: ASCII letters and digits, `-`, `_`, `.` | 1 to 64 characters a component; at most 10 components | +| Database | ASCII letters and digits, `-`, `_`, `.`, and `/` between components | up to 64 characters | +| Branch | anything but `$` and `:` | 1 to 64 characters | +| Secret | ASCII letters and digits, `-`, `_`, `.` | 1 to 128 characters | +| Function {/* if functions launched */} | ASCII letters and digits, `_` -- no `-` or `.` | 1 to 128 characters | + +And for every name: + +- It can't be empty, and neither can any component of a namespace path or a + database name. +- It can't be `.` or `..`, nor can any of its components. +- A namespace path whose first component is `public` can't have a second one. + +`$` and `:` are never in a name: a deployment writes a namespace path and a +table as one identifier joined by `$`, and a database and a table, or a table +and a branch, joined by `:`. + +## Examples {#examples} + +| Name | | +| --- | --- | +| `documents`, `user-events.v2`, `train_2026` | valid table names | +| `["prod", "search"]` | a valid two-component namespace path | +| `my table` | refused: a space | +| `orders$2026` | refused: `$` joins a namespace and a table | +| `résumés` | refused: not ASCII | +| `["public", "search"]` | refused: `public` can't have a child | + +## Which versions check them {#which-versions-check-them} + +The rules come from lancedb +[#4490](https://github.com/lancedb/lancedb/pull/4490), which gives the SDKs and +deployments one set of name checks. What enforces them depends on the +connection and the version: + +- **The embedded library** refuses a table name with any other character, and + `.` and `..`, but sets no length limit beyond what the filesystem allows. A + directory namespace accepts other characters in namespace names. +- **The SDKs on a `db://` connection** check every name above before sending a + request, from the first release that includes #4490. As of v0.41.0-beta.2, no + release does: earlier releases send names to the deployment unchecked. +- **A deployment** checks names itself, but not on every path in every version. + Some accept a longer name when a table is created and then fail on it later -- + when the table is dropped, or in background work on it. + +So keep to the rules even where a longer or unusual name is accepted: a name +that works today on one connection can fail on another, or later on the same +one. + +See [Limits](/basics/limits#names) for the other bounds, and +[Namespaces](/management/namespace#namespace-paths-and-names) for how a path is +built. diff --git a/docs/web/docs.json b/docs/web/docs.json index 990dc6c7a..c06bd4c9b 100644 --- a/docs/web/docs.json +++ b/docs/web/docs.json @@ -272,7 +272,8 @@ "basics/jobs", "tables/consistency", "basics/guarantees", - "basics/limits" + "basics/limits", + "basics/naming" ] }, { diff --git a/docs/web/ingestion/create-table.mdx b/docs/web/ingestion/create-table.mdx index b3eb3824e..ff431107c 100644 --- a/docs/web/ingestion/create-table.mdx +++ b/docs/web/ingestion/create-table.mdx @@ -55,7 +55,8 @@ the rows come later. ## Create a table with data {#create-a-table-with-data} -Initialize a LanceDB connection and create a table +Initialize a LanceDB connection and create a table. A table's name follows the +[naming rules](/basics/naming). diff --git a/docs/web/management/namespace.mdx b/docs/web/management/namespace.mdx index 560499f4a..c400a2763 100644 --- a/docs/web/management/namespace.mdx +++ b/docs/web/management/namespace.mdx @@ -56,7 +56,7 @@ namespace inside the `prod` namespace. The empty path, `[]`, means the root name Each component is a name, not a filesystem path segment, and can't be empty. Keep each one to letters, numbers, underscores, hyphens, and periods, so the same identifier is usable everywhere: a local directory namespace accepts other characters too, but other namespace implementations and -deployments can refuse them. +deployments can refuse them. [Naming rules](/basics/naming) has the lengths and the other limits. ## Directory namespaces {#directory-namespaces}