mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-15 00:02:26 +00:00
Brendan Clement
bbadf0dbea
The SDK now sends CREATE MATERIALIZED VIEW and REFRESH MATERIALIZED VIEW to a db:// deployment as SQL, and refuses source_version on a remote refresh. Current Sophon source accepts both statements, with CASCADE and WITH (full = true), but only on deployments that enable materialized views, and whether a refresh rebuilds the view or reconciles changes depends on configuration. The pages said there is no CREATE MATERIALIZED VIEW statement, that refreshes are incremental by default and that CASCADE is not implemented. The refresh, management and SQL reference pages now describe what the SDK sends, say that materialized views are experimental and must be enabled on a deployment, and leave refresh behaviour, CASCADE and the job type to the deployment's version and configuration. The SQL and management summaries list CREATE MATERIALIZED VIEW. No deployment was exercised.
95 lines
3.5 KiB
Plaintext
95 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", {
|
|
source: "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 experimental 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>
|