mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-16 07:36:50 +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.
163 lines
6.2 KiB
Plaintext
163 lines
6.2 KiB
Plaintext
---
|
|
title: "Database"
|
|
sidebarTitle: "Database"
|
|
description: "Create, describe, list, attach, and drop databases with SQL."
|
|
icon: database
|
|
keywords: ["database", "create database", "describe database", "show databases", "drop database", "attach database", "sql"]
|
|
availability:
|
|
embedded: unavailable
|
|
enterprise: available
|
|
---
|
|
|
|
A database is the catalog's top-level container: it holds
|
|
[namespaces](/sql/ddl/namespace), which hold tables, views and other objects.
|
|
Database statements name one database, independently of the session's
|
|
current database. Database creation uses the deployment's native catalog
|
|
and storage settings.
|
|
|
|
## CREATE DATABASE {#create}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
CREATE DATABASE analytics
|
|
CREATE DATABASE IF NOT EXISTS "team/search"
|
|
```
|
|
</CodeGroup>
|
|
|
|
Creates a persistent database. Requires `CREATE DATABASE` on the system, and
|
|
ownership of the database name if it already has an owner. The caller
|
|
becomes the owner of a new name, following the same rules as the REST API.
|
|
|
|
The result has `operation`, `name`, and `status` columns. Status is
|
|
`created`, or `already_exists` with `IF NOT EXISTS`. Without that clause, an
|
|
existing database is an error. Creation never overwrites an existing
|
|
database.
|
|
|
|
<Note>
|
|
`WITH` options are unsupported on `CREATE DATABASE`. Use `ATTACH DATABASE`
|
|
[below](#attach) to register a database at an existing location. The
|
|
`system` database and reserved storage names cannot be created.
|
|
</Note>
|
|
|
|
## DESCRIBE DATABASE {#describe}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
DESCRIBE DATABASE analytics
|
|
DESC DATABASE "team/search"
|
|
```
|
|
</CodeGroup>
|
|
|
|
Requires `USAGE` on the database. Returns one row with `name` and
|
|
`properties`. Properties are the catalog's metadata encoded as a JSON
|
|
object; a database without metadata returns `{}`, and a database mid
|
|
`CASCADE` drop reports a transient property marking it as dropping. A
|
|
missing database is an error. `DESCRIBE DATABASE system` returns empty
|
|
properties and requires system `USAGE`.
|
|
|
|
## SHOW DATABASES {#show}
|
|
|
|
```sql
|
|
SHOW DATABASES LIMIT 100;
|
|
SHOW DATABASES LIMIT 100 FROM '<page-token>';
|
|
```
|
|
|
|
Returns one non-null `name` column, sorted by database name and filtered to
|
|
databases the caller has `USAGE` on, including `system` when permitted.
|
|
Databases are above namespaces, so this command does not accept `IN` or
|
|
return a `namespace_path` column.
|
|
|
|
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).
|
|
|
|
## ATTACH DATABASE {#attach}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
ATTACH DATABASE analytics WITH (location = 'analytics')
|
|
ATTACH DATABASE IF NOT EXISTS analytics WITH (location = 'analytics')
|
|
ATTACH DATABASE analytics WITH (location = 's3://customer-bucket/raw/analytics/')
|
|
ATTACH DATABASE analytics WITH (location = 'az://customer-data@customeraccount.blob.core.windows.net/raw/analytics')
|
|
```
|
|
</CodeGroup>
|
|
|
|
Registers an existing database at a path relative to the catalog's storage
|
|
root, or at an external S3, GCS or Azure location, instead of creating a
|
|
new one. `location` is the only supported option -- naming a storage
|
|
integration explicitly is refused. For an external location, the
|
|
deployment automatically binds the most specific
|
|
[storage integration](/sql/ddl/storage-integration) whose prefix covers
|
|
it; one must already exist. An Azure location must be account-qualified
|
|
(`az://container@account.blob.core.windows.net/path`); a bare
|
|
`az://container/path` is refused. `ATTACH DATABASE` requires the same
|
|
creation privileges as `CREATE DATABASE`. For an external location, it also
|
|
requires `USAGE` on the storage integration that binds it, and on that
|
|
integration's own database and namespace; the integration itself must live
|
|
in a native, root-backed database under the catalog root.
|
|
|
|
Attaching writes Enterprise's own tracking metadata into the location to
|
|
bring it under management -- it does not rewrite, move, or re-encode any
|
|
existing table's data.
|
|
|
|
<Warning>
|
|
A relative-path location never accepts an absolute path (`/tmp/db`), a
|
|
`file://` URI, a Windows path (`C:/db`), a `..` segment, an empty string,
|
|
or a doubled slash (`sub//db`). An S3 or GCS location must be a concrete
|
|
prefix, not a bare scheme (`s3://`) on its own.
|
|
</Warning>
|
|
|
|
`IF NOT EXISTS` makes the statement a no-op rather than an error when the
|
|
database is already attached.
|
|
|
|
<Note>
|
|
A quoted name reaches characters a bare identifier cannot, such as
|
|
`` ATTACH DATABASE "team/search" WITH (location = 'team-search') ``.
|
|
Removing an externally attached database with `DROP DATABASE` unregisters
|
|
the attachment and releases its storage-integration reference, without
|
|
deleting the underlying data.
|
|
</Note>
|
|
|
|
## DROP DATABASE {#drop}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
DROP DATABASE analytics
|
|
DROP DATABASE IF EXISTS analytics RESTRICT
|
|
DROP DATABASE analytics CASCADE
|
|
```
|
|
</CodeGroup>
|
|
|
|
Requires `USAGE` and `OWNERSHIP` on the database. The default, `RESTRICT`,
|
|
refuses a database that still contains objects. `CASCADE` refuses new
|
|
objects in the database, revokes every grant in it, and starts a job that
|
|
drops its contents; deployments without cascade support reject it. An
|
|
externally attached database cannot be dropped with `CASCADE`.
|
|
|
|
`RESTRICT` returns `operation`, `name`, and `status` columns: `dropped`, or
|
|
`not_found` with `IF EXISTS` for a missing database. `CASCADE` returns
|
|
`operation`, `job_id`, and `status` columns: the job's id with `dropping`,
|
|
or an empty `job_id` with `not_found`. The name stays taken until the job
|
|
finishes and the dropped storage is cleaned up. The `system` database and
|
|
federated databases cannot be dropped.
|
|
|
|
<Note>
|
|
`ALTER DATABASE` is unsupported.
|
|
</Note>
|
|
|
|
## What to read next {#next}
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Namespace" icon="folder-tree" href="/sql/ddl/namespace">
|
|
CREATE SCHEMA inside an attached database.
|
|
</Card>
|
|
<Card title="Table" icon="table" href="/sql/ddl/table">
|
|
Creating tables once a database and namespace exist.
|
|
</Card>
|
|
<Card title="Database" icon="database" href="/management/database">
|
|
The SDK equivalent, and connection settings.
|
|
</Card>
|
|
</CardGroup>
|