Document AS OF SYSTEM TIME for materialized views

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:
 

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.<br><br>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).<br><br>**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 %})

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. <br>`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,10 +121,36 @@ 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)
 - [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %})
 - [`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 %})

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 %}

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:
 

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.<br><br>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).<br><br>**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 %})

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. <br>`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,10 +121,36 @@ 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)
 - [`CREATE VIEW`]({% link {{ page.version.version }}/create-view.md %})
 - [`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 %})

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 %}

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: