mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-15 00:02:26 +00:00
Brendan Clement
8cc8acd30c
The limits page still listed REFRESH MATERIALIZED VIEW ... CASCADE as parsed but not implemented, while the refresh page says it depends on the deployment's version. The row now says the same and links there. The refresh page told deployment users to create a view's source with new_table_enable_stable_row_ids. A db:// connection never sends that option: RemoteOptions keeps only the Azure account name, and a remote create_table sends only its mode and data. The page now says stable row ids are set up on the deployment, which depending on its version may give new tables them, refuse a view created through SQL over a source without them, or convert the source when a view is created through its REST API, and to check with its administrator. The architecture, limits, table and database pages no longer say stable row ids can never be enabled after creation, which that REST conversion contradicts; they say the SDK can only give them to a table it creates. The local heading now names the removed stable-row-id requirement instead of promising that any table can be a source, and notes the write-ahead-log checks that remain.
96 lines
3.7 KiB
Plaintext
96 lines
3.7 KiB
Plaintext
---
|
|
title: "Materialized view"
|
|
sidebarTitle: "Materialized View"
|
|
description: "Create, open, list and drop a table whose contents are defined by a query."
|
|
icon: table
|
|
keywords: ["materialized view", "create_materialized_view", "catalog", "ddl"]
|
|
---
|
|
|
|
A materialized view is a table whose contents are defined by a query over
|
|
another table. The query is recorded in the view's schema, and a refresh
|
|
brings its stored rows up to date with the source.
|
|
|
|
The result is an ordinary table -- queryable, indexable, searchable, and present
|
|
in `table_names()`. Nothing about reading it is special.
|
|
|
|
This page covers creating and managing one. Keeping it current is
|
|
[Refresh a materialized view](/feature-engineering/materialized-views).
|
|
|
|
<Note>
|
|
In SQL, see [`REFRESH MATERIALIZED VIEW`](/sql/dml/refresh#refresh-materialized-view) and [`SHOW MATERIALIZED VIEWS`](/sql/ddl/materialized-view#show).
|
|
</Note>
|
|
|
|
## Creating one {#create}
|
|
|
|
<CodeGroup>
|
|
```python Python icon="python"
|
|
view = db.create_materialized_view(
|
|
"recent_docs",
|
|
source="documents",
|
|
select=["id", "title", "embedding"],
|
|
where="created_at > '2026-01-01'",
|
|
)
|
|
```
|
|
|
|
```typescript TypeScript icon="square-js"
|
|
const view = await db.createMaterializedView("recent_docs", "documents", {
|
|
select: ["id", "title", "embedding"],
|
|
where: "created_at > '2026-01-01'",
|
|
});
|
|
```
|
|
</CodeGroup>
|
|
|
|
`source` names the table it derives from. A local source does not need stable
|
|
row ids or any other storage option; a deployment may require stable row ids
|
|
(see [Against a deployment](#deployment)). `select`, `where` and `limit` record
|
|
the query -- there is no separate definition step.
|
|
|
|
## Opening, listing and dropping {#manage}
|
|
|
|
| | Python | TypeScript | SQL |
|
|
| --- | --- | --- | --- |
|
|
| create | `create_materialized_view` | `createMaterializedView` | `CREATE MATERIALIZED VIEW` |
|
|
| open | `open_materialized_view` | `openMaterializedView` | -- |
|
|
| list | `list_materialized_views` | `listMaterializedViews` | `SHOW MATERIALIZED VIEWS` |
|
|
| refresh | `refresh` | `refresh` | `REFRESH MATERIALIZED VIEW` |
|
|
| drop | `drop_table` | `dropTable` | `DROP TABLE` |
|
|
|
|
<Note>
|
|
`list_materialized_views` finds views by reading every table's schema, so it
|
|
costs one open per table. `SHOW MATERIALIZED VIEWS` asks the server instead and
|
|
is cheaper on a catalog with many tables.
|
|
</Note>
|
|
|
|
A view is dropped with `drop_table`, because a materialized view **is** a table.
|
|
That also means dropping one removes stored rows -- unlike dropping a
|
|
[view](/management/view), which removes only a saved query.
|
|
|
|
## Working with the view {#working}
|
|
|
|
`view.table` is the underlying table, for querying, indexing, or search.
|
|
`view.definition` is the recorded query -- select list, predicate, limit
|
|
-- which is how you check what a view contains without inferring it from the
|
|
rows. Both are properties; on an async view, the definition is read with
|
|
`await view.definition()`.
|
|
|
|
## Against a deployment {#deployment}
|
|
|
|
<Badge color="red">Enterprise</Badge> `create_materialized_view` works on a
|
|
`db://` connection as well as a local one. There the SDK creates and refreshes
|
|
the view through SQL, and the work runs on the cluster rather than in your
|
|
process. Materialized views are off by default on a deployment and have to be
|
|
enabled there, and a deployment may require a view's source to have stable row
|
|
ids; see
|
|
[Against a deployment](/feature-engineering/materialized-views#availability).
|
|
|
|
## What to read next {#next}
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Refresh a materialized view" icon="arrows-rotate" href="/feature-engineering/materialized-views">
|
|
How a refresh works, and what it writes.
|
|
</Card>
|
|
<Card title="Views" icon="eye" href="/management/view">
|
|
The non-materialized counterpart, defined in SQL.
|
|
</Card>
|
|
</CardGroup>
|