---
title: "Create a materialized view"
sidebarTitle: "Create Materialized View"
description: "Store the result of a query as a table, ready to query, index and search."
icon: table
keywords: ["materialized view", "create_materialized_view"]
availability:
embedded: unavailable
enterprise: available
---
A materialized view stores the result of a query as a table. Use it to keep a
filtered or transformed dataset that you can query, index and search
repeatedly, instead of recomputing the query every time you read it.
In SQL this is [`CREATE MATERIALIZED VIEW`](/sql/ddl/materialized-view#create).
## Create a view {#create}
A materialized view is defined by a SQL query, so it is created with one.
From Python, pass the defining query to `create_materialized_view` on an
[Enterprise connection](/basics/catalog#enterprise):
```python Python icon="python"
view = db.create_materialized_view(
"frames_captioned",
query="""
SELECT frame_id, video_id, ts, caption
FROM frames
WHERE selected = true
""",
)
```
```sql SQL icon="database"
CREATE MATERIALIZED VIEW frames_captioned AS
SELECT frame_id, video_id, ts, caption
FROM frames
WHERE selected = true
```
`create_materialized_view` waits for creation and initial population, then
returns the view handle. Use `create_materialized_view_async` to submit a job
and wait for it separately. Both methods accept `query=` on synchronous and
asynchronous connections. `query` cannot be combined with `source`, `select`,
`where`, or `limit`; put those clauses in the query itself.
The query defines the view: here, the `frames` table's `frame_id`,
`video_id`, `ts` and `caption` columns, filtered to the frames selected for
captioning. There is no separate, more limited form for defining one --
joins and [Functions](#functions) in the select list work the same way any
other `SELECT` does, within the query shapes your deployment's LanceDB
Enterprise version and configuration accept; see the
[SQL reference](/sql/ddl/materialized-view#create).
Creating the view computes its rows, so it is ready to read immediately.
[`db.open_materialized_view`](/management/materialized-view#manage) gets a
handle back for reading, refreshing or inspecting it from Python; the view
itself is also an ordinary table, queryable by name like any other.
Your administrator manages stable row IDs and other source-table
requirements for materialized views on the server; confirm support for your
source table's shape before creating a view over it.
## Selecting a Function's output {#functions}
Enterprise
A `SELECT` expression is SQL text, so it can call a registered
[Function](/curation/create-function) the same way a computed column's
expression can. Continuing the
[`caption` Function](/curation/create-function#chain) registered in Create a
Function, against a `frames` table that already has a `jpeg` column:
```python Python icon="python"
db.execute_query("""
CREATE MATERIALIZED VIEW frames_captioned AS
SELECT frame_id, jpeg, caption(jpeg) AS caption
FROM frames
WHERE selected = true
""").read_all()
```
```sql SQL icon="database"
CREATE MATERIALIZED VIEW frames_captioned AS
SELECT frame_id, jpeg, caption(jpeg) AS caption
FROM frames
WHERE selected = true
```
A query that joins tables works the same way, with no separate syntax for
it. Continuing the join and chained Functions from
[Create a Function](/curation/create-function#chain), producing `jpeg` from
a separate `videos` table and captioning it in the same statement:
```python Python icon="python"
db.execute_query("""
CREATE MATERIALIZED VIEW frames_captioned
WITH (auto_refresh_enabled = false, auto_refresh_interval_seconds = 5)
AS
SELECT
f.frame_id,
extract_frame(v.video, f.ts) AS jpeg,
caption(extract_frame(v.video, f.ts)) AS caption
FROM videos v
JOIN frames f ON v.id = f.video_id
WHERE f.selected = true
""").read_all()
```
```sql SQL icon="database"
CREATE MATERIALIZED VIEW frames_captioned
WITH (auto_refresh_enabled = false, auto_refresh_interval_seconds = 5)
AS
SELECT
f.frame_id,
extract_frame(v.video, f.ts) AS jpeg,
caption(extract_frame(v.video, f.ts)) AS caption
FROM videos v
JOIN frames f ON v.id = f.video_id
WHERE f.selected = true
```
See [Joins](/curation/join) for the join itself, and
[Auto Refresh](/enterprise/auto-refresh) for what `WITH` sets here.
## Automatic refresh at creation {#auto-refresh}
Set `auto_refresh_enabled` and `auto_refresh_interval_seconds` in the `WITH`
clause to schedule refreshes instead of calling
[`refresh`](/feature-engineering/refresh-materialized-view) yourself:
```python Python icon="python"
db.execute_query("""
CREATE MATERIALIZED VIEW frames_captioned
WITH (auto_refresh_enabled = true, auto_refresh_interval_seconds = 300)
AS
SELECT frame_id, video_id, ts, caption
FROM frames
WHERE selected = true
""").read_all()
```
```sql SQL icon="database"
CREATE MATERIALIZED VIEW frames_captioned
WITH (auto_refresh_enabled = true, auto_refresh_interval_seconds = 300)
AS
SELECT frame_id, video_id, ts, caption
FROM frames
WHERE selected = true
```
Omit `auto_refresh_enabled` to let the server decide whether to enable it,
and omit `auto_refresh_interval_seconds` to let the server decide the
pacing. See [Auto Refresh](/enterprise/auto-refresh) for how scheduling
behaves once the view exists.
## Working with the view {#working-with-the-view}
`view.table` is the underlying table, for querying, indexing, or search.
`view.definition` has a single field, `query` -- the recorded query, in the
canonical spelling the server stores. Use it to inspect the query without
inferring it from the rows. Both are properties; on an async view, the
definition is read with `await view.definition()`.
Creation, refresh and drop also have async, job-returning SDK methods; see
[Materialized view](/management/materialized-view#manage).
## Related guides {#next}
Bring the view up to date with its source.
Inspect the table history and read a particular version.