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.
128 lines
4.6 KiB
Plaintext
128 lines
4.6 KiB
Plaintext
---
|
|
title: "View"
|
|
sidebarTitle: "View"
|
|
description: "Create, describe, list, and drop saved queries with SQL."
|
|
icon: eye
|
|
keywords: ["create view", "drop view", "sql", "catalog"]
|
|
availability:
|
|
embedded: unavailable
|
|
enterprise: available
|
|
---
|
|
|
|
A view stores a **query**, not rows. Reading it runs the query against current
|
|
data, so a view is never stale, and never faster than the query it wraps. It
|
|
is the counterpart to a [materialized view](/sql/ddl/materialized-view), which
|
|
stores rows and is brought up to date by a refresh; both are
|
|
[catalog objects](/basics/catalog) defined by a query, differing only in when
|
|
that query runs.
|
|
|
|
The SDK methods `create_view`, `describe_view`, `list_views`, and `drop_view`
|
|
submit SQL through the connection's Flight endpoint. `drop_view_async` returns
|
|
a job of type `query` whose single `id` is the SQL query UUID. Waiting confirms
|
|
catalog removal; physical cleanup can continue afterward.
|
|
|
|
## CREATE VIEW {#create}
|
|
|
|
{/* Draft for the view exist_ok release.
|
|
|
|
`CREATE VIEW IF NOT EXISTS` creates a missing view and returns an existing
|
|
view's stored query and schema unchanged. Without `IF NOT EXISTS`, an existing
|
|
name is an error. In Python, use `db.create_view(name, query, exist_ok=True)`;
|
|
in Rust, use `db.create_view(name, query, &namespace).exist_ok(true).await?`.
|
|
Returning an existing view requires `SELECT` on that view.
|
|
|
|
*/}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
CREATE VIEW "recent_matches" AS
|
|
SELECT t1.floats
|
|
FROM "documents" AS t1
|
|
INNER JOIN "categories" AS t2 ON t1.ints = t2.ints
|
|
```
|
|
</CodeGroup>
|
|
|
|
The statement returns one row with UTF-8 `name`, `query`, and `schema` columns.
|
|
`query` contains the stored query, including any declared column aliases, and
|
|
`schema` contains its Arrow schema as JSON. The schema metadata keys
|
|
`lancedb::view::default_db` and `lancedb::view::default_namespace` identify the
|
|
defining database and namespace. The root namespace is `public`; nested
|
|
namespace components are separated by `$`.
|
|
|
|
`DESCRIBE VIEW "recent_matches"` returns the same metadata shape. Anything the
|
|
[dialect](/sql/dql/functions) supports can define one: joins, predicates,
|
|
aggregates, window functions.
|
|
|
|
## Reading one {#reading}
|
|
|
|
A view is queried like a table:
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
SELECT * FROM "recent_matches" WHERE floats > 0.5
|
|
```
|
|
</CodeGroup>
|
|
|
|
Predicates applied to the view compose with the query inside it rather than
|
|
filtering its output afterwards, so a selective filter does not pay for rows
|
|
the view would have produced and then discarded.
|
|
|
|
## DROP VIEW {#drop}
|
|
|
|
<CodeGroup>
|
|
```sql SQL icon="database"
|
|
DROP VIEW "recent_matches"
|
|
```
|
|
</CodeGroup>
|
|
|
|
Removes the saved query. Unlike dropping a table, no data is removed: there
|
|
was none to begin with.
|
|
|
|
## Listing {#listing}
|
|
|
|
```sql
|
|
SHOW VIEWS IN analytics.`team$ml` LIMIT 100;
|
|
SHOW VIEWS IN analytics.`team$ml` LIMIT 100 FROM '<page-token>';
|
|
```
|
|
|
|
Returns two non-null string columns: `namespace_path`, a compact JSON array
|
|
of parent namespace components (`[]` for root), and `name`, the unqualified
|
|
object name. Omitting `IN` lists all authorized namespaces in the current database;
|
|
`IN team$ml` selects that exact path without a database qualifier; `IN public` selects
|
|
the current database's root. Listings require the relevant database and
|
|
namespace `USAGE` privileges.
|
|
|
|
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).
|
|
|
|
## Choosing between a view and a materialized view {#choosing}
|
|
|
|
| | View | Materialized view |
|
|
| --- | --- | --- |
|
|
| Stores | the query | the rows |
|
|
| Freshness | always current | as of the last refresh |
|
|
| Read cost | the full query, every read | a table scan |
|
|
| Write cost | none | a refresh |
|
|
|
|
Reach for a **view** when the query is cheap, or when reading stale rows would
|
|
be wrong. Reach for a **materialized view** when the query is expensive and the
|
|
data changes less often than it is read.
|
|
|
|
The privileges are separate too: `CREATE_VIEW` and `CREATE_MATERIALIZED_VIEW`
|
|
are distinct grants on a namespace, so the ability to create one does not imply
|
|
the other. See [Authorization](/governance/authorization).
|
|
|
|
## What to read next {#next}
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Materialized View" icon="table" href="/sql/ddl/materialized-view">
|
|
The stored-rows counterpart.
|
|
</Card>
|
|
<Card title="Management" icon="folder-tree" href="/management">
|
|
Where views fit among the other catalog objects.
|
|
</Card>
|
|
</CardGroup>
|