mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-16 15:46:55 +00:00
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.
207 lines
8.1 KiB
Plaintext
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>
|