Files
lancedb/docs/web/sql/ddl/view.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

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>