Files
lancedb/docs/web/sql/ddl/view.mdx
T
Jack Ye b061c3627c feat(python): support exist_ok when creating views (#4984)
Add `exist_ok=False` to synchronous and asynchronous Python view
creation. Passing `True` sends `CREATE VIEW IF NOT EXISTS` and returns
the existing view's stored query and schema unchanged; the default
continues to fail on an existing name.

```python
view = db.create_view("recent_orders", query, exist_ok=True)
view = await async_db.create_view("recent_orders", query, exist_ok=True)
```

Requires a SQL server supporting `CREATE VIEW IF NOT EXISTS`. Rust gains
an awaitable builder with `.exist_ok(true)`. Existing
`.create_view(...).await` calls continue to work; callers requiring
`Future` must convert the builder, and custom `Database` implementations
must accept the new `exist_ok` argument. Includes Python round-trip
coverage and Rust coverage for direct/deferred results and metadata
preservation.
2026-11-14 10:35:52 +08:00

135 lines
4.5 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
SHOW VIEWS IN "analytics" WHERE name > 'previous_view' LIMIT 100
```
`SHOW VIEWS` returns ascending `name` values. 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>