diff --git a/api/continuous-aggregates/create_materialized_view.md b/api/continuous-aggregates/create_materialized_view.md index bab3e10d98..5018fc8c33 100644 --- a/api/continuous-aggregates/create_materialized_view.md +++ b/api/continuous-aggregates/create_materialized_view.md @@ -12,10 +12,9 @@ products: [cloud, self_hosted, mst] import Since2220 from "versionContent/_partials/_since_2_22_0.mdx"; -# CREATE MATERIALIZED VIEW (Continuous Aggregate) Community +# CREATE MATERIALIZED VIEW (continuous aggregate) Community -The `CREATE MATERIALIZED VIEW` statement is used to create continuous -aggregates. To learn more, see the +The `CREATE MATERIALIZED VIEW` statement is used to create $CAGGs. To learn more, see the [continuous aggregate how-to guides][cagg-how-tos]. The syntax is: @@ -39,30 +38,46 @@ GROUP BY time_bucket( , ), [HAVING ...] ``` -The continuous aggregate view defaults to `WITH DATA`. This means that when the +The $CAGG view defaults to `WITH DATA`. This means that when the view is created, it refreshes using all the current data in the underlying -hypertable or continuous aggregate. This occurs once when the view is created. +$HYPERTABLE or $CAGG. This occurs once when the view is created. If you want the view to be refreshed regularly, you can use a refresh policy. If you do not want the view to update when it is first created, use the `WITH NO DATA` parameter. For more information, see [`refresh_continuous_aggregate`][refresh-cagg]. -Continuous aggregates have some limitations of what types of queries they can +$CAGG_CAPs have some limitations of what types of queries they can support. For more information, see the [continuous aggregates section][cagg-how-tos]. -$TIMESCALE_DB v2.17.1 and greater dramatically decrease the amount -of data written on a continuous aggregate in the presence of a small number of changes, -reduce the i/o cost of refreshing a continuous aggregate, and generate fewer Write-Ahead -Logs (WAL), set the`timescaledb.enable_merge_on_cagg_refresh` -configuration parameter to `TRUE`. This enables continuous aggregate -refresh to use merge instead of deleting old materialized data and re-inserting. +In $TIMESCALE_DB v2.17.0 and greater (with $PG 15+), you can dramatically decrease the amount +of data written on a $CAGG in the presence of a small number of changes, +reduce the I/O cost of refreshing a $CAGG, and generate fewer Write-Ahead +Logs (WAL) by enabling the `timescaledb.enable_merge_on_cagg_refresh` +[GUC parameter][gucs]. This enables $CAGG +refresh to use MERGE instead of deleting old materialized data and re-inserting. +This is a session-level parameter that only works for finalized $CAGGs +that don't have compression enabled. It is disabled by default. -For more settings for continuous aggregates, see [timescaledb_information.continuous_aggregates][info-views]. +To enable this parameter for your session: + +```sql +SET timescaledb.enable_merge_on_cagg_refresh = ON; +``` + +To enable it at the database level: + +```sql +ALTER DATABASE your_database SET timescaledb.enable_merge_on_cagg_refresh = ON; +``` + +For more information about GUC parameters, see the [configuration documentation][gucs]. + +For more settings for $CAGGs, see [timescaledb_information.continuous_aggregates][info-views]. ## Samples -Create a daily continuous aggregate view: +Create a daily $CAGG view: ```sql CREATE MATERIALIZED VIEW continuous_aggregate_daily( timec, minl, sumt, sumh ) @@ -72,7 +87,7 @@ WITH (timescaledb.continuous) AS GROUP BY time_bucket('1day', timec) ``` -Add a thirty day continuous aggregate on top of the same raw hypertable: +Add a thirty day $CAGG on top of the same raw $HYPERTABLE: ```sql CREATE MATERIALIZED VIEW continuous_aggregate_thirty_day( timec, minl, sumt, sumh ) @@ -82,7 +97,7 @@ WITH (timescaledb.continuous) AS GROUP BY time_bucket('30day', timec); ``` -Add an hourly continuous aggregate on top of the same raw hypertable: +Add an hourly $CAGG on top of the same raw $HYPERTABLE: ```sql CREATE MATERIALIZED VIEW continuous_aggregate_hourly( timec, minl, sumt, sumh ) @@ -96,26 +111,26 @@ WITH (timescaledb.continuous) AS |Name|Type|Description| |-|-|-| -|``|TEXT|Name (optionally schema-qualified) of continuous aggregate view to create| +|``|TEXT|Name (optionally schema-qualified) of $CAGG view to create| |``|TEXT|Optional list of names to be used for columns of the view. If not given, the column names are calculated from the query| -|`WITH` clause|TEXT|Specifies options for the continuous aggregate view| +|`WITH` clause|TEXT|Specifies options for the $CAGG view| |``|TEXT|A `SELECT` query that uses the specified syntax| Required `WITH` clause options: |Name|Type|Description| |-|-|-| -|`timescaledb.continuous`|BOOLEAN|If `timescaledb.continuous` is not specified, this is a regular PostgresSQL materialized view| +|`timescaledb.continuous`|BOOLEAN|If `timescaledb.continuous` is not specified, this is a regular $PG materialized view| Optional `WITH` clause options: |Name|Type| Description |Default value| |-|-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-| -|`timescaledb.chunk_interval`|INTERVAL| Set the chunk interval. The default value is 10x the original hypertable. | -|`timescaledb.create_group_indexes`|BOOLEAN| Create indexes on the continuous aggregate for columns in its `GROUP BY` clause. Indexes are in the form `(, time_bucket)` |`TRUE`| -|`timescaledb.finalized`|BOOLEAN| In TimescaleDB 2.7 and above, use the new version of continuous aggregates, which stores finalized results for aggregate functions. Supports all aggregate functions, including ones that use `FILTER`, `ORDER BY`, and `DISTINCT` clauses. |`TRUE`| -|`timescaledb.materialized_only`|BOOLEAN| Return only materialized data when querying the continuous aggregate view |`TRUE`| -| `timescaledb.invalidate_using` | TEXT | Set to `wal` to read changes from the WAL using logical decoding, then update the materialization invalidations for continuous aggregates using this information. This reduces the I/O and CPU needed to manage the hypertable invalidation log. Set to `trigger` to collect invalidations whenever there are inserts, updates, or deletes to a hypertable. This default behaviour uses more resources than `wal`. | `trigger` | +|`timescaledb.chunk_interval`|INTERVAL| Set the chunk interval. The default value is 10x the original $HYPERTABLE. | +|`timescaledb.create_group_indexes`|BOOLEAN| Create indexes on the $CAGG for columns in its `GROUP BY` clause. Indexes are in the form `(, time_bucket)` |`TRUE`| +|`timescaledb.finalized`|BOOLEAN| In $TIMESCALE_DB 2.7 and above, use the new version of $CAGGs, which stores finalized results for aggregate functions. Supports all aggregate functions, including ones that use `FILTER`, `ORDER BY`, and `DISTINCT` clauses. |`TRUE`| +|`timescaledb.materialized_only`|BOOLEAN| Return only materialized data when querying the $CAGG view |`TRUE`| +| `timescaledb.invalidate_using` | TEXT | Set to `wal` to read changes from the WAL using logical decoding, then update the materialization invalidations for $CAGGs using this information. This reduces the I/O and CPU needed to manage the $HYPERTABLE invalidation log. Set to `trigger` to collect invalidations whenever there are inserts, updates, or deletes to a $HYPERTABLE. This default behaviour uses more resources than `wal`. | `trigger` | For more information, see the [real-time aggregates][real-time-aggregates] section. @@ -125,3 +140,4 @@ For more information, see the [real-time aggregates][real-time-aggregates] secti [real-time-aggregates]: /use-timescale/:currentVersion:/continuous-aggregates/real-time-aggregates/ [refresh-cagg]: /api/:currentVersion:/continuous-aggregates/refresh_continuous_aggregate/ [info-views]: /api/:currentVersion:/informational-views/continuous_aggregates/ +[gucs]: /api/:currentVersion:/configuration/gucs/