Files
lancedb/docs/web/sql/ddl/namespace.mdx
T
Jack Ye e8a8dd1b2a feat(sql): use server-issued catalog listing tokens (#5026)
Migrates SQL-backed catalog listing APIs to `LIMIT ... FROM
'<page-token>'` and server-issued Arrow continuation metadata.
Namespace-specific APIs send an explicit `IN` schema clause, including
`IN "public"` for root, so raw SQL can default to all namespaces.

```sql
SHOW VIEWS LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100 FROM '<page-token>';
SHOW VIEWS IN other_db.team$ml LIMIT 100;
```

SDK clients forward opaque tokens unchanged, preserve empty
continuations, and decode identifier columns by name. Removes legacy
cursor reconstruction and updates the SQL reference and Python Flight
fixture. Public docs cover optional direct schema paths, all-namespace
defaults, and the shared pagination syntax across every catalog listing.
2026-11-15 08:55:42 +08:00

207 lines
8.1 KiB
Plaintext

---
title: "Namespace"
sidebarTitle: "Namespace"
description: "Create, alter, describe, list, and drop namespace paths with SQL."
icon: folder-tree
keywords: ["namespace", "schema", "create schema", "create namespace", "describe schema", "show namespaces", "drop schema", "sql"]
availability:
embedded: unavailable
enterprise: available
---
A [namespace](/management/namespace) is addressed in SQL as a `SCHEMA`, the
standard's name for the same concept. A **schema** is a complete namespace
path, optionally qualified by a database; a nested path occupies one
backtick-quoted identifier with `$` between components, such as
`` analytics.`team$features` ``. A **namespace**, as a separate keyword, names
one path component, relative to an explicit parent schema or the session's
current schema -- it cannot contain `$` or be qualified with a database.
For single-object commands, `SCHEMA` never accepts `IN`. `NAMESPACE` accepts `IN` followed by a complete
schema identifier. Names are lowercased unless quoted.
## CREATE SCHEMA and CREATE NAMESPACE {#create}
Create a namespace using its complete schema path:
<CodeGroup>
```sql SQL icon="database"
CREATE SCHEMA analytics
CREATE SCHEMA db1.`ns1$ns2`
CREATE SCHEMA IF NOT EXISTS `ns1$ns2`
```
</CodeGroup>
Alternatively, create the same namespace by naming its component and parent:
<CodeGroup>
```sql SQL icon="database"
CREATE NAMESPACE features IN team
```
</CodeGroup>
To supply creation metadata and tolerate an existing namespace:
<CodeGroup>
```sql SQL icon="database"
CREATE NAMESPACE IF NOT EXISTS features IN analytics.team
WITH (owner = 'search-team', purpose = 'retrieval')
```
</CodeGroup>
A nested namespace is one backtick-quoted name with `$` between its
components: `` db1.`ns1$ns2` `` creates `ns2` inside `ns1` in database `db1`.
Both forms create namespaces in the same catalog, and missing ancestors are
created automatically -- the part before the first dot is always the
database. `public` is the database's root namespace, which is never created
or dropped.
`IF NOT EXISTS` makes the statement a no-op rather than an error when the
namespace is already there, though it does not replace an existing
namespace's properties. Without it, an existing target is an error.
Properties are string values stored on the target only; implicitly created
ancestors receive no properties, and duplicate property keys are errors.
The result has `operation`, `name`, and `status` columns. The operation is
`CREATE SCHEMA` for either spelling; the name is the resolved path and the
status is `created`.
<Note>
Creation requires `CREATE NAMESPACE` on the database and the parent
namespace -- the same privileges the
[namespace REST API](/management/namespace) checks. The caller becomes the
owner of each newly created namespace, including implicitly created
ancestors. See [Grant](/sql/ddl/grant#privileges) for the full privilege
list a namespace accepts.
</Note>
## ALTER SCHEMA and ALTER NAMESPACE {#alter}
| Operation | SCHEMA syntax | NAMESPACE syntax |
| --- | --- | --- |
| Set metadata | `` ALTER SCHEMA `team$features` SET (purpose = 'retrieval') `` | `ALTER NAMESPACE features IN team SET (purpose = 'retrieval')` |
| Remove metadata | `` ALTER SCHEMA `team$features` UNSET (purpose) `` | `ALTER NAMESPACE features IN team UNSET (purpose)` |
`SET` adds or replaces the listed string properties, preserving other keys.
`UNSET` removes the listed keys; a missing key is ignored. Lists must be
nonempty, and duplicate keys are errors. Quote a key containing punctuation,
for example `SET ("owner.team" = 'search')`.
Each statement updates metadata atomically and preserves unrelated
concurrent changes. Metadata changes do not change ownership or grants. Use
`DESCRIBE` to read the updated properties. A missing namespace is an error.
<Note>
Requires `USAGE` on the database and the namespace, and `OWNERSHIP` on the
namespace itself.
</Note>
<Note>
`ALTER` metadata is supported by native manifest-backed databases. Legacy
directory and external catalogs report an unsupported-operation error. The
implicit `public` root and the read-only `system` database cannot be
altered.
</Note>
The result has `operation`, `name`, and `status` columns, with operation
`ALTER SCHEMA` for either spelling and status `altered`.
## DESCRIBE SCHEMA and DESCRIBE NAMESPACE {#describe}
<CodeGroup>
```sql SQL icon="database"
DESCRIBE SCHEMA analytics.`team$features`
DESCRIBE NAMESPACE features IN analytics.team
DESC NAMESPACE features IN team
```
</CodeGroup>
Returns one row with `name` (the complete `$`-joined schema path) and
`properties` (a JSON object). An unannotated namespace returns `{}`. A
missing namespace is an error. `DESC` is an alias for `DESCRIBE`.
<Note>
Requires `USAGE` on the database and the namespace.
</Note>
## SHOW SCHEMAS and SHOW NAMESPACES {#show}
```sql
SHOW SCHEMAS LIMIT 100;
SHOW SCHEMAS LIMIT 100 FROM '<page-token>';
SHOW NAMESPACES IN analytics.team LIMIT 100;
SHOW NAMESPACES IN analytics.team LIMIT 100 FROM '<page-token>';
```
Both commands return two non-null string columns: `namespace_path`, the
parent path as a compact JSON array, and `name`, the unqualified child name.
Results are ordered by parent path components, then name, and omit namespaces
the caller cannot use.
`SHOW SCHEMAS` and `SHOW NAMESPACES` are equivalent listings. Without `IN`,
both list recursively in the current database, include the implicit `public`
root, and ignore the session namespace. With `IN`, both list immediate children
of the selected parent. A schema path can appear directly: `IN team$features`;
a database qualifier is optional. `IN public` selects the current database root,
and `IN analytics.public` selects another database's root.
Page through results using `LIMIT n [FROM '<page-token>']`. Read the opaque
`lancedb.next_page_token` from the Arrow result schema metadata and pass it back
unchanged with the same object type and scope. Stop when no token is returned;
a short or empty page can still carry a continuation. See
[catalog listing pagination](/sql/pagination).
## DROP SCHEMA and DROP NAMESPACE {#drop}
<CodeGroup>
```sql SQL icon="database"
DROP SCHEMA analytics.`team$features`
DROP NAMESPACE IF EXISTS features IN analytics.team RESTRICT
DROP NAMESPACE team CASCADE
```
</CodeGroup>
The default, `RESTRICT`, refuses a namespace with children or objects --
tables, views and other objects inside must be dropped explicitly first. In
native manifest-backed databases, `CASCADE` instead removes the namespace
and all descendant bindings atomically in one catalog commit, then submits
a background job that cleans up their storage; deployments without cascade
support reject it. A storage integration used by an attached database
blocks the drop of its namespace.
<Note>
Requires `USAGE` and `OWNERSHIP` on the namespace. A dropped Secret is
eligible for immediate deletion even when jobs still reference it: a
process that already holds the value keeps it for the rest of its run, but
a later launch that needs the Secret can fail once it's gone.
</Note>
`RESTRICT` returns `operation`, `name`, and `status`, with status `dropped`
or `not_found`. `CASCADE` returns `operation`, `job_id`, and `status`, with
status `dropping`, or an empty job ID and `not_found` for a missing target
with `IF EXISTS`. Inspect a cascade drop's child jobs with
[`SHOW JOBS FOR JOB`](/sql/ddl/job#show). Both spellings report operation
`DROP SCHEMA`.
## Correcting invalid syntax {#errors}
| Invalid form | Use instead |
| --- | --- |
| `CREATE SCHEMA child IN parent` | `CREATE NAMESPACE child IN parent` or `` CREATE SCHEMA `parent$child` `` |
| `` DESCRIBE NAMESPACE `parent$child` `` | `` DESCRIBE SCHEMA `parent$child` `` or `DESCRIBE NAMESPACE child IN parent` |
| `DROP NAMESPACE analytics.child` | `DROP NAMESPACE child IN analytics.public` |
## What to read next {#next}
<CardGroup cols={2}>
<Card title="Database" icon="database" href="/sql/ddl/database">
Attaching the database a namespace lives in.
</Card>
<Card title="Namespace" icon="folder-tree" href="/management/namespace">
The SDK equivalent, and how a namespace fits the catalog hierarchy.
</Card>
<Card title="Table" icon="table" href="/sql/ddl/table">
Creating tables inside a namespace.
</Card>
</CardGroup>