diff --git a/src/current/v25.2/as-of-system-time.md b/src/current/v25.2/as-of-system-time.md
index 5a29792d96d..958830aa048 100644
--- a/src/current/v25.2/as-of-system-time.md
+++ b/src/current/v25.2/as-of-system-time.md
@@ -22,6 +22,8 @@ The `AS OF SYSTEM TIME` clause is supported in multiple SQL contexts, including
- In [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), after the parameters of the `FROM` sub-clause.
- In [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}), after the `BEGIN` keyword.
- In [`SET`]({% link {{ page.version.version }}/set-transaction.md %}), after the `SET TRANSACTION` keyword.
+- {% include_cached new-in.html version="v25.2" %} In [`CREATE MATERIALIZED VIEW`]({% link {{ page.version.version }}/create-view.md %}), after the `AS select_stmt` clause.
+- {% include_cached new-in.html version="v25.2" %} In [`REFRESH MATERIALIZED VIEW`]({% link {{ page.version.version }}/refresh.md %}), after the view name.
`AS OF SYSTEM TIME` cannot be used with:
diff --git a/src/current/v25.2/create-view.md b/src/current/v25.2/create-view.md
index 9bd76c2f8cc..a800a4a85a0 100644
--- a/src/current/v25.2/create-view.md
+++ b/src/current/v25.2/create-view.md
@@ -33,6 +33,7 @@ Parameter | Description
`view_name` | The name of the view to create, which must be unique within its database and follow these [identifier rules]({% link {{ page.version.version }}/keywords-and-identifiers.md %}#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.
`name_list` | An optional, comma-separated list of column names for the view. If specified, these names will be used in the response instead of the columns specified in `AS select_stmt`.
`AS select_stmt` | The [selection query]({% link {{ page.version.version }}/selection-queries.md %}) to execute when the view is requested.
Note that it is not currently possible to use `*` to select all columns from a referenced table or view; instead, you must specify specific columns.
+`AS OF SYSTEM TIME` | {% include_cached new-in.html version="v25.2" %} When used with `CREATE MATERIALIZED VIEW`, populates the materialized view using historical data. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
`opt_temp` | Defines the view as a session-scoped temporary view. For more information, see [Temporary Views]({% link {{ page.version.version }}/views.md %}#temporary-views).
**Support for temporary views is [in preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#temporary-objects)**.
## Example
@@ -147,6 +148,36 @@ Executing the query is as easy as `SELECT`ing from the view, as you would from a
(3 rows)
~~~
+### Create a materialized view with historical data using `AS OF SYSTEM TIME`
+
+{% include_cached new-in.html version="v25.2" %} You can create a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when populating the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+The following example creates a materialized view using the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
@@ -155,3 +186,5 @@ Executing the query is as easy as `SELECT`ing from the view, as you would from a
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
- [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.2/refresh.md b/src/current/v25.2/refresh.md
index b91bb95f039..b5a54350d29 100644
--- a/src/current/v25.2/refresh.md
+++ b/src/current/v25.2/refresh.md
@@ -28,8 +28,9 @@ The user must be the [owner]({% link {{ page.version.version }}/alter-view.md %}
`opt_concurrently` | `CONCURRENTLY` (Default behavior) This keyword has no effect. It is present for PostgreSQL compatibility. All materialized views are refreshed concurrently with other jobs.
`view_name` | The name of the materialized view to refresh.
`opt_clear_data` | `WITH DATA` (Default behavior) Refresh the stored query results.
`WITH NO DATA` Drop the query results of the materialized view from storage.
+`AS OF SYSTEM TIME` | {% include_cached new-in.html version="v25.2" %} Use historical data when refreshing the view. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
-## Example
+## Examples
The following example uses the [sample `bank` database]({% link {{ page.version.version }}/cockroach-workload.md %}#bank-workload), populated with some workload values.
@@ -120,6 +121,30 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+### Refresh a materialized view with historical data using `AS OF SYSTEM TIME`
+
+{% include_cached new-in.html version="v25.2" %} You can refresh a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when refreshing the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+Refresh a materialized view using [`follower_read_timestamp()`]({% link {{ page.version.version }}/functions-and-operators.md %}#date-and-time-functions) to use the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Materialized views]({% link {{ page.version.version }}/views.md %}#materialized-views)
@@ -127,3 +152,5 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
- [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %})
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.2/views.md b/src/current/v25.2/views.md
index 1b703728bcf..f7fe7c58d2a 100644
--- a/src/current/v25.2/views.md
+++ b/src/current/v25.2/views.md
@@ -534,6 +534,25 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+{% include_cached new-in.html version="v25.2" %} You can also create or refresh materialized views using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}).
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+For more information, see [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %}#create-a-materialized-view-with-historical-data-using-as-of-system-time) and [`REFRESH`]({% link {{ page.version.version }}/refresh.md %}#refresh-a-materialized-view-with-historical-data-using-as-of-system-time).
+
To rename the materialized view, use [`ALTER MATERIALIZED VIEW`]({% link {{ page.version.version }}/alter-view.md %}):
{% include_cached copy-clipboard.html %}
diff --git a/src/current/v25.3/as-of-system-time.md b/src/current/v25.3/as-of-system-time.md
index 5a29792d96d..675396ec306 100644
--- a/src/current/v25.3/as-of-system-time.md
+++ b/src/current/v25.3/as-of-system-time.md
@@ -22,6 +22,8 @@ The `AS OF SYSTEM TIME` clause is supported in multiple SQL contexts, including
- In [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), after the parameters of the `FROM` sub-clause.
- In [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}), after the `BEGIN` keyword.
- In [`SET`]({% link {{ page.version.version }}/set-transaction.md %}), after the `SET TRANSACTION` keyword.
+- In [`CREATE MATERIALIZED VIEW`]({% link {{ page.version.version }}/create-view.md %}), after the `AS select_stmt` clause.
+- In [`REFRESH MATERIALIZED VIEW`]({% link {{ page.version.version }}/refresh.md %}), after the view name.
`AS OF SYSTEM TIME` cannot be used with:
diff --git a/src/current/v25.3/create-view.md b/src/current/v25.3/create-view.md
index 927affb40c0..f618486dc35 100644
--- a/src/current/v25.3/create-view.md
+++ b/src/current/v25.3/create-view.md
@@ -33,6 +33,7 @@ Parameter | Description
`view_name` | The name of the view to create, which must be unique within its database and follow these [identifier rules]({% link {{ page.version.version }}/keywords-and-identifiers.md %}#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.
`name_list` | An optional, comma-separated list of column names for the view. If specified, these names will be used in the response instead of the columns specified in `AS select_stmt`.
`AS select_stmt` | The [selection query]({% link {{ page.version.version }}/selection-queries.md %}) to execute when the view is requested.
Note that it is not currently possible to use `*` to select all columns from a referenced table or view; instead, you must specify specific columns.
+`AS OF SYSTEM TIME` | When used with `CREATE MATERIALIZED VIEW`, populates the materialized view using historical data. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
`opt_temp` | Defines the view as a session-scoped temporary view. For more information, see [Temporary Views]({% link {{ page.version.version }}/views.md %}#temporary-views).
**Support for temporary views is [in preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#temporary-objects)**.
## Example
@@ -214,6 +215,36 @@ ERROR: cannot rename function "f_scalar" because other functions or views ([movr
SQLSTATE: 0A000
~~~
+### Create a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can create a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when populating the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+The following example creates a materialized view using the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
@@ -222,3 +253,5 @@ SQLSTATE: 0A000
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
- [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.3/refresh.md b/src/current/v25.3/refresh.md
index b91bb95f039..4c1cf056597 100644
--- a/src/current/v25.3/refresh.md
+++ b/src/current/v25.3/refresh.md
@@ -28,8 +28,9 @@ The user must be the [owner]({% link {{ page.version.version }}/alter-view.md %}
`opt_concurrently` | `CONCURRENTLY` (Default behavior) This keyword has no effect. It is present for PostgreSQL compatibility. All materialized views are refreshed concurrently with other jobs.
`view_name` | The name of the materialized view to refresh.
`opt_clear_data` | `WITH DATA` (Default behavior) Refresh the stored query results.
`WITH NO DATA` Drop the query results of the materialized view from storage.
+`AS OF SYSTEM TIME` | Use historical data when refreshing the view. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
-## Example
+## Examples
The following example uses the [sample `bank` database]({% link {{ page.version.version }}/cockroach-workload.md %}#bank-workload), populated with some workload values.
@@ -120,6 +121,30 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+### Refresh a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can refresh a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when refreshing the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+Refresh a materialized view using [`follower_read_timestamp()`]({% link {{ page.version.version }}/functions-and-operators.md %}#date-and-time-functions) to use the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Materialized views]({% link {{ page.version.version }}/views.md %}#materialized-views)
@@ -127,3 +152,5 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
- [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %})
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.3/views.md b/src/current/v25.3/views.md
index 1b703728bcf..6b1a667a470 100644
--- a/src/current/v25.3/views.md
+++ b/src/current/v25.3/views.md
@@ -534,6 +534,25 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+You can also create or refresh materialized views using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}).
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+For more information, see [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %}#create-a-materialized-view-with-historical-data-using-as-of-system-time) and [`REFRESH`]({% link {{ page.version.version }}/refresh.md %}#refresh-a-materialized-view-with-historical-data-using-as-of-system-time).
+
To rename the materialized view, use [`ALTER MATERIALIZED VIEW`]({% link {{ page.version.version }}/alter-view.md %}):
{% include_cached copy-clipboard.html %}
diff --git a/src/current/v25.4/as-of-system-time.md b/src/current/v25.4/as-of-system-time.md
index 5a29792d96d..675396ec306 100644
--- a/src/current/v25.4/as-of-system-time.md
+++ b/src/current/v25.4/as-of-system-time.md
@@ -22,6 +22,8 @@ The `AS OF SYSTEM TIME` clause is supported in multiple SQL contexts, including
- In [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), after the parameters of the `FROM` sub-clause.
- In [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}), after the `BEGIN` keyword.
- In [`SET`]({% link {{ page.version.version }}/set-transaction.md %}), after the `SET TRANSACTION` keyword.
+- In [`CREATE MATERIALIZED VIEW`]({% link {{ page.version.version }}/create-view.md %}), after the `AS select_stmt` clause.
+- In [`REFRESH MATERIALIZED VIEW`]({% link {{ page.version.version }}/refresh.md %}), after the view name.
`AS OF SYSTEM TIME` cannot be used with:
diff --git a/src/current/v25.4/create-view.md b/src/current/v25.4/create-view.md
index 7041825f6fa..826ce5d05e1 100644
--- a/src/current/v25.4/create-view.md
+++ b/src/current/v25.4/create-view.md
@@ -33,6 +33,7 @@ Parameter | Description
`view_name` | The name of the view to create, which must be unique within its database and follow these [identifier rules]({% link {{ page.version.version }}/keywords-and-identifiers.md %}#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.
`name_list` | An optional, comma-separated list of column names for the view. If specified, these names will be used in the response instead of the columns specified in `AS select_stmt`.
`AS select_stmt` | The [selection query]({% link {{ page.version.version }}/selection-queries.md %}) to execute when the view is requested.
Note that it is not currently possible to use `*` to select all columns from a referenced table or view; instead, you must specify specific columns.
+`AS OF SYSTEM TIME` | When used with `CREATE MATERIALIZED VIEW`, populates the materialized view using historical data. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
`opt_temp` | Defines the view as a session-scoped temporary view. For more information, see [Temporary Views]({% link {{ page.version.version }}/views.md %}#temporary-views).
**Support for temporary views is [in preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#temporary-objects)**.
## Example
@@ -214,6 +215,36 @@ ERROR: cannot rename function "f_scalar" because other functions or views ([movr
SQLSTATE: 0A000
~~~
+### Create a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can create a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when populating the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+The following example creates a materialized view using the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
@@ -222,3 +253,5 @@ SQLSTATE: 0A000
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
- [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.4/refresh.md b/src/current/v25.4/refresh.md
index b91bb95f039..4c1cf056597 100644
--- a/src/current/v25.4/refresh.md
+++ b/src/current/v25.4/refresh.md
@@ -28,8 +28,9 @@ The user must be the [owner]({% link {{ page.version.version }}/alter-view.md %}
`opt_concurrently` | `CONCURRENTLY` (Default behavior) This keyword has no effect. It is present for PostgreSQL compatibility. All materialized views are refreshed concurrently with other jobs.
`view_name` | The name of the materialized view to refresh.
`opt_clear_data` | `WITH DATA` (Default behavior) Refresh the stored query results.
`WITH NO DATA` Drop the query results of the materialized view from storage.
+`AS OF SYSTEM TIME` | Use historical data when refreshing the view. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
-## Example
+## Examples
The following example uses the [sample `bank` database]({% link {{ page.version.version }}/cockroach-workload.md %}#bank-workload), populated with some workload values.
@@ -120,6 +121,30 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+### Refresh a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can refresh a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when refreshing the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+Refresh a materialized view using [`follower_read_timestamp()`]({% link {{ page.version.version }}/functions-and-operators.md %}#date-and-time-functions) to use the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Materialized views]({% link {{ page.version.version }}/views.md %}#materialized-views)
@@ -127,3 +152,5 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
- [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %})
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v25.4/views.md b/src/current/v25.4/views.md
index 88d8310926b..7aaea1c54a9 100644
--- a/src/current/v25.4/views.md
+++ b/src/current/v25.4/views.md
@@ -534,6 +534,25 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+You can also create or refresh materialized views using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}).
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+For more information, see [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %}#create-a-materialized-view-with-historical-data-using-as-of-system-time) and [`REFRESH`]({% link {{ page.version.version }}/refresh.md %}#refresh-a-materialized-view-with-historical-data-using-as-of-system-time).
+
To rename the materialized view, use [`ALTER MATERIALIZED VIEW`]({% link {{ page.version.version }}/alter-view.md %}):
{% include_cached copy-clipboard.html %}
diff --git a/src/current/v26.1/as-of-system-time.md b/src/current/v26.1/as-of-system-time.md
index 5a29792d96d..675396ec306 100644
--- a/src/current/v26.1/as-of-system-time.md
+++ b/src/current/v26.1/as-of-system-time.md
@@ -22,6 +22,8 @@ The `AS OF SYSTEM TIME` clause is supported in multiple SQL contexts, including
- In [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), after the parameters of the `FROM` sub-clause.
- In [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}), after the `BEGIN` keyword.
- In [`SET`]({% link {{ page.version.version }}/set-transaction.md %}), after the `SET TRANSACTION` keyword.
+- In [`CREATE MATERIALIZED VIEW`]({% link {{ page.version.version }}/create-view.md %}), after the `AS select_stmt` clause.
+- In [`REFRESH MATERIALIZED VIEW`]({% link {{ page.version.version }}/refresh.md %}), after the view name.
`AS OF SYSTEM TIME` cannot be used with:
diff --git a/src/current/v26.1/create-view.md b/src/current/v26.1/create-view.md
index 7041825f6fa..826ce5d05e1 100644
--- a/src/current/v26.1/create-view.md
+++ b/src/current/v26.1/create-view.md
@@ -33,6 +33,7 @@ Parameter | Description
`view_name` | The name of the view to create, which must be unique within its database and follow these [identifier rules]({% link {{ page.version.version }}/keywords-and-identifiers.md %}#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.
`name_list` | An optional, comma-separated list of column names for the view. If specified, these names will be used in the response instead of the columns specified in `AS select_stmt`.
`AS select_stmt` | The [selection query]({% link {{ page.version.version }}/selection-queries.md %}) to execute when the view is requested.
Note that it is not currently possible to use `*` to select all columns from a referenced table or view; instead, you must specify specific columns.
+`AS OF SYSTEM TIME` | When used with `CREATE MATERIALIZED VIEW`, populates the materialized view using historical data. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
`opt_temp` | Defines the view as a session-scoped temporary view. For more information, see [Temporary Views]({% link {{ page.version.version }}/views.md %}#temporary-views).
**Support for temporary views is [in preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#temporary-objects)**.
## Example
@@ -214,6 +215,36 @@ ERROR: cannot rename function "f_scalar" because other functions or views ([movr
SQLSTATE: 0A000
~~~
+### Create a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can create a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when populating the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+The following example creates a materialized view using the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
@@ -222,3 +253,5 @@ SQLSTATE: 0A000
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
- [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v26.1/refresh.md b/src/current/v26.1/refresh.md
index b91bb95f039..4c1cf056597 100644
--- a/src/current/v26.1/refresh.md
+++ b/src/current/v26.1/refresh.md
@@ -28,8 +28,9 @@ The user must be the [owner]({% link {{ page.version.version }}/alter-view.md %}
`opt_concurrently` | `CONCURRENTLY` (Default behavior) This keyword has no effect. It is present for PostgreSQL compatibility. All materialized views are refreshed concurrently with other jobs.
`view_name` | The name of the materialized view to refresh.
`opt_clear_data` | `WITH DATA` (Default behavior) Refresh the stored query results.
`WITH NO DATA` Drop the query results of the materialized view from storage.
+`AS OF SYSTEM TIME` | Use historical data when refreshing the view. The timestamp must be within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds). This can reduce [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}). For more information, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
-## Example
+## Examples
The following example uses the [sample `bank` database]({% link {{ page.version.version }}/cockroach-workload.md %}#bank-workload), populated with some workload values.
@@ -120,6 +121,30 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+### Refresh a materialized view with historical data using `AS OF SYSTEM TIME`
+
+You can refresh a materialized view using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by performing a [follower read]({% link {{ page.version.version }}/follower-reads.md %}) when refreshing the view.
+
+{{site.data.alerts.callout_info}}
+Historical data is available only within the [garbage collection window]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds).
+{{site.data.alerts.end}}
+
+Refresh a materialized view using [`follower_read_timestamp()`]({% link {{ page.version.version }}/functions-and-operators.md %}#date-and-time-functions) to use the most recent data that is available for [follower reads]({% link {{ page.version.version }}/follower-reads.md %}):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+You can also specify an explicit timestamp:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME '-10s';
+~~~
+
## See also
- [Materialized views]({% link {{ page.version.version }}/views.md %}#materialized-views)
@@ -127,3 +152,5 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
- [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %})
- [`ALTER VIEW`]({% link {{ page.version.version }}/alter-view.md %})
- [`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Follower Reads]({% link {{ page.version.version }}/follower-reads.md %})
diff --git a/src/current/v26.1/views.md b/src/current/v26.1/views.md
index 88d8310926b..7aaea1c54a9 100644
--- a/src/current/v26.1/views.md
+++ b/src/current/v26.1/views.md
@@ -534,6 +534,25 @@ To update the materialized view's results, use a [`REFRESH`]({% link {{ page.ver
(0 rows)
~~~
+You can also create or refresh materialized views using historical data with the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause. This is useful for reducing [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) by leveraging [follower reads]({% link {{ page.version.version }}/follower-reads.md %}).
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> CREATE MATERIALIZED VIEW overdrawn_accounts
+ AS SELECT id, balance
+ FROM bank
+ WHERE balance < 0
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> REFRESH MATERIALIZED VIEW overdrawn_accounts
+ AS OF SYSTEM TIME follower_read_timestamp();
+~~~
+
+For more information, see [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %}#create-a-materialized-view-with-historical-data-using-as-of-system-time) and [`REFRESH`]({% link {{ page.version.version }}/refresh.md %}#refresh-a-materialized-view-with-historical-data-using-as-of-system-time).
+
To rename the materialized view, use [`ALTER MATERIALIZED VIEW`]({% link {{ page.version.version }}/alter-view.md %}):
{% include_cached copy-clipboard.html %}