Skip to content

Update for enable_merge_on_cagg_refresh #4587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: latest
Choose a base branch
from
+40 −24
Open

Update for enable_merge_on_cagg_refresh #4587

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d174efe
update for GUC parameter
atovpeko Nov 21, 2025
f3df755
variables
atovpeko Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 40 additions & 24 deletions api/continuous-aggregates/create_materialized_view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,9 @@ products: [cloud, self_hosted, mst]

import Since2220 from "versionContent/_partials/_since_2_22_0.mdx";

# CREATE MATERIALIZED VIEW (Continuous Aggregate) <Tag type="community">Community</Tag>
# CREATE MATERIALIZED VIEW (continuous aggregate) <Tag type="community">Community</Tag>

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:
Expand All @@ -39,30 +38,46 @@ GROUP BY time_bucket( <const_value>, <partition_col_of_hypertable> ),
[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 )
Expand All @@ -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 )
Expand All @@ -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 )
Expand All @@ -96,26 +111,26 @@ WITH (timescaledb.continuous) AS

|Name|Type|Description|
|-|-|-|
|`<view_name>`|TEXT|Name (optionally schema-qualified) of continuous aggregate view to create|
|`<view_name>`|TEXT|Name (optionally schema-qualified) of $CAGG view to create|
|`<column_name>`|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|
|`<select_query>`|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 `(<GROUP_BY_COLUMN>, 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 | <Since2220 />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 `(<GROUP_BY_COLUMN>, 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 | <Since2220 />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.

Expand All @@ -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/