mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-14 15:52:26 +00:00
Brendan Clement
0e9dc14d01
The deployment notes called materialized views experimental. Nothing published says so; the word came from one comment in Sophon's create handler. What Sophon's source does establish is that a deployment serves materialized views only with derived_compute_enabled, which is off by default, so the pages now say that instead.
94 lines
3.5 KiB
Plaintext
94 lines
3.5 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
|
|
computes its stored rows again from 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; any table can be one, with no special
|
|
storage option. `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; 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">
|
|
What a refresh recomputes, and what it writes.
|
|
</Card>
|
|
<Card title="Views" icon="eye" href="/management/view">
|
|
The non-materialized counterpart, defined in SQL.
|
|
</Card>
|
|
</CardGroup>
|