> ## Documentation Index > Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt > Use this file to discover all available pages before exploring further. # Namespace > Create, alter, describe, list, and drop namespace paths with SQL. **Applies to:** Embedded ❌, Enterprise ✅ A [namespace](https://docs.lancedb.com/management/namespace.md) 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. `SCHEMA` never accepts `IN`. `NAMESPACE` accepts `IN` followed by a complete schema identifier. Names are lowercased unless quoted. ## CREATE SCHEMA and CREATE NAMESPACE Create a namespace using its complete schema path: ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} CREATE SCHEMA analytics CREATE SCHEMA db1.`ns1$ns2` CREATE SCHEMA IF NOT EXISTS `ns1$ns2` ``` Alternatively, create the same namespace by naming its component and parent: ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} CREATE NAMESPACE features IN team ``` To supply creation metadata and tolerate an existing namespace: ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} CREATE NAMESPACE IF NOT EXISTS features IN analytics.team WITH (owner = 'search-team', purpose = 'retrieval') ``` 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](https://docs.lancedb.com/management/namespace.md) checks. The caller becomes the > owner of each newly created namespace, including implicitly created > ancestors. See [Grant](https://docs.lancedb.com/sql/ddl/grant.md#privileges) for the full privilege > list a namespace accepts. ## ALTER SCHEMA and ALTER NAMESPACE | 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] > > `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. The result has `operation`, `name`, and `status` columns, with operation `ALTER SCHEMA` for either spelling and status `altered`. ## DESCRIBE SCHEMA and DESCRIBE NAMESPACE ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} DESCRIBE SCHEMA analytics.`team$features` DESCRIBE NAMESPACE features IN analytics.team DESC NAMESPACE features IN team ``` 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. ## SHOW SCHEMAS and SHOW NAMESPACES ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} SHOW SCHEMAS SHOW NAMESPACES SHOW NAMESPACES IN analytics.team ``` `SHOW SCHEMAS` returns complete paths in the current database, recursively, including `public` when the caller can use it. It does not accept `IN`. `SHOW NAMESPACES` lists only immediate child names under the session's current schema. `IN` selects a different parent schema, optionally in another database -- use `IN public` for the current database's root, or `IN analytics.public` for another database's root. A missing parent is an error. Both forms return a sorted `name` column and omit namespaces the caller cannot use. Large listings that exceed 10,000 namespaces, or recursive listings deeper than 32 levels, return an error suggesting a narrower listing. ## DROP SCHEMA and DROP NAMESPACE ```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}} DROP SCHEMA analytics.`team$features` DROP NAMESPACE IF EXISTS features IN analytics.team RESTRICT DROP NAMESPACE team CASCADE ``` 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. `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`](https://docs.lancedb.com/sql/ddl/job#show). Both spellings report operation `DROP SCHEMA`. ## Correcting invalid syntax | 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` | | `SHOW SCHEMAS IN parent` | `SHOW NAMESPACES IN parent` | ## What to read next > [card] [Database](https://docs.lancedb.com/sql/ddl/database.md) > > Attaching the database a namespace lives in. > [card] [Namespace](https://docs.lancedb.com/management/namespace.md) > > The SDK equivalent, and how a namespace fits the catalog hierarchy. > [card] [Table](https://docs.lancedb.com/sql/ddl/table.md) > > Creating tables inside a namespace. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.