mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-13 14:16:54 +00:00
Jack Ye
ac7930fa77
Stacked on #4675. Remote view create, describe, list, and drop now execute SQL. CREATE returns the stored definition, resolution defaults, and Arrow schema from the same execution; DESCRIBE VIEW returns that metadata and SHOW VIEWS supports scoped pagination. `drop_view_async()` returns a `job_type="query"` handle whose single `job.id` is the SQL query UUID. Waiting drains the query result once and caches completion; `describe_query(job.id)` works on the submitting connection. Completion means catalog removal, with physical cleanup continuing separately. Query handles have no registry history and cannot be reopened through `open_job()`.
116 lines
3.9 KiB
Plaintext
116 lines
3.9 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}
|
|
|
|
```sql
|
|
CREATE VIEW "recent_matches" AS
|
|
SELECT t1.floats
|
|
FROM "documents" AS t1
|
|
INNER JOIN "categories" AS t2 ON t1.ints = t2.ints
|
|
```
|
|
|
|
The statement returns one UTF-8 `definition` column containing JSON with the
|
|
view name, namespace, original query, default database and namespace, and its
|
|
Arrow schema resolved at creation time. `DESCRIBE VIEW "recent_matches"`
|
|
returns the same metadata shape. Anything the
|
|
[dialect](/sql/functions) supports can define one: joins, predicates,
|
|
aggregates, window functions.
|
|
|
|
## Reading one {#reading}
|
|
|
|
A view is queried like a table:
|
|
|
|
```sql
|
|
SELECT * FROM "recent_matches" WHERE floats > 0.5
|
|
```
|
|
|
|
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}
|
|
|
|
```sql
|
|
DROP VIEW "recent_matches"
|
|
```
|
|
|
|
Removes the saved query. Unlike dropping a table, no data is removed: there
|
|
was none to begin with.
|
|
|
|
## Listing {#listing}
|
|
|
|
```sql
|
|
SHOW VIEWS
|
|
SHOW VIEWS IN "analytics" WHERE name > 'previous_view' LIMIT 100
|
|
```
|
|
|
|
`SHOW VIEWS` returns ascending `name` values and a nullable `location` column.
|
|
Locations are populated only when the deployment exposes catalog locations.
|
|
The `name` cursor is scoped to the selected namespace.
|
|
|
|
Object commands retain their small results in shared storage even when general
|
|
query-result copying is disabled, so asynchronous polling can use any query node.
|
|
|
|
Views and tables share a namespace, and both are things you can query. The
|
|
catalog distinguishes them:
|
|
|
|
| | |
|
|
| --- | --- |
|
|
| view names | the views in the database |
|
|
| table names | the tables |
|
|
| relation names | everything queryable (both) |
|
|
|
|
Use the relation listing when the question is "what can I select from," and the
|
|
separate listings when the distinction matters: before dropping, for
|
|
instance, since dropping a view removes only the saved query while dropping a
|
|
table removes data.
|
|
|
|
## 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>
|