Skip to content

Document incremental refresh_continuous_aggregate() options (2.28.0) #315

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

Merged
atovpeko merged 3 commits into from
Jun 12, 2026
Merged

Document incremental refresh_continuous_aggregate() options (2.28.0) #315

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e632083
Document incremental refresh_continuous_aggregate() options
atovpeko Jun 11, 2026
2435b85
Clarify default incremental refresh and how to disable it
atovpeko Jun 12, 2026
378dcbf
Remove double space in Force sample description
atovpeko Jun 12, 2026
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
69 changes: 48 additions & 21 deletions ...cs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,35 +40,41 @@
## Samples

Refresh the {C.CAGG} `conditions` between `2020-01-01` and
`2020-02-01` exclusive.
`2020-02-01` exclusive. This call uses the default settings shown in
[Options](#options). Since {C.TIMESCALE_DB} 2.28.0, those defaults perform an
incremental refresh in batches of 10 buckets (`buckets_per_batch`):

```sql
CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01');

@melihmutlu melihmutlu Jun 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is also an incremental refresh as buckets_per_batch is 10 by default. It may be better to state that to prevent confusion.

@melihmutlu melihmutlu Jun 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can also show how to disable the incremental refresh instead

CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01', options => '{"buckets_per_batch": 0}'::jsonb);

@gayyappan gayyappan Jun 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest keeping both versions. I think we should keep this version so that it is clear that no changes are needed to existing calls.
i.e. keep
call refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01');
Perhaps state that this uses default settings (as shown in the table).

and add a blurb that if num_buckets=0, then the refresh is not split into batches.

@atovpeko atovpeko Jun 12, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

```

Alternatively, incrementally refresh the {C.CAGG} `conditions`
between `2020-01-01` and `2020-02-01` exclusive, working in `12h` intervals:
Incrementally refresh the {C.CAGG} `conditions` between `2020-01-01` and

Check notice on line 51 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L51 

[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 51, "column": 30}}}, "severity": "INFO"}
`2020-02-01` exclusive, in batches of 5 buckets at a time, from newest data to
oldest. This breaks a large refresh into smaller transactions, so locks are held
for shorter periods and results become visible as each batch completes:

```sql
DO
$$
DECLARE
refresh_interval INTERVAL = '12h'::INTERVAL;
start_timestamp TIMESTAMPTZ = '2020-01-01T00:00:00Z';
end_timestamp TIMESTAMPTZ = start_timestamp + refresh_interval;
BEGIN
WHILE start_timestamp < '2020-02-01T00:00:00Z' LOOP
CALL refresh_continuous_aggregate('conditions', start_timestamp, end_timestamp);
COMMIT;
RAISE NOTICE 'finished with timestamp %', end_timestamp;
start_timestamp = end_timestamp;
end_timestamp = end_timestamp + refresh_interval;
END LOOP;
END
$$;
CALL refresh_continuous_aggregate(
'conditions',
'2020-01-01',
'2020-02-01',
options => '{"buckets_per_batch": 5, "refresh_newest_first": true}'::jsonb
);
```

Disable incremental refresh and refresh the entire window in a single atomic
pass by setting `buckets_per_batch` to `0`:

```sql
CALL refresh_continuous_aggregate(
'conditions',
'2020-01-01',
'2020-02-01',
options => '{"buckets_per_batch": 0}'::jsonb
);
```

Force the `conditions` {C.CAGG} to refresh between `2020-01-01` and
Force the `conditions` {C.CAGG} to refresh between `2020-01-01` and

Check notice on line 77 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L77 

[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 77, "column": 27}}}, "severity": "INFO"}
`2020-02-01` exclusive, even if the data has already been refreshed.

```sql
Expand All @@ -95,7 +101,7 @@
| `window_start` | INTERVAL, TIMESTAMPTZ, INTEGER | - | ✔ | Start of the window to refresh, has to be before `window_end`. |
| `window_end` | INTERVAL, TIMESTAMPTZ, INTEGER | - | ✔ | End of the window to refresh, has to be after `window_start`. |
| `force` | BOOLEAN | `FALSE` | - | Force refresh every bucket in the time range between `window_start` and `window_end`, even when the bucket has already been refreshed. This can be very expensive when a lot of data is refreshed. |
| `options` | JSONB | `NULL` | - | JSONB object with additional options. Supports `process_hypertable_invalidations` (boolean, default `true`). |
| `options` | JSONB | `NULL` | - | JSONB object with additional options. See [Options](#options). |

Check notice on line 104 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L104 

[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 104, "column": 15}}}, "severity": "INFO"}

Check notice on line 104 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L104 

[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 104, "column": 36}}}, "severity": "INFO"}

You must specify the `window_start` and `window_end` parameters differently,
depending on the type of the time column of the {C.HYPERTABLE}. For {C.HYPERTABLE}s with
Expand All @@ -118,6 +124,27 @@
changes that only occurred in the secondary table used in the JOIN.
</Callout>

## Options

<SinceRelease version="2.28.0" product="tsdb" />

The `options` argument is a JSONB object that accepts the following keys:

Check notice on line 131 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L131 

[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'JSONB', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 131, "column": 29}}}, "severity": "INFO"}

| Key | Type | Default | Description |
|-|-|-|-|
| `buckets_per_batch` | INTEGER | `10` | Number of buckets to refresh per batch. This value is multiplied by the {C.CAGG} bucket width to determine the size of each batch range. Set to `0` to refresh the whole window in a single atomic pass. Values less than `0` are not allowed. |

Check notice on line 135 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L135 

[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 135, "column": 117}}}, "severity": "INFO"}
| `max_batches_per_execution` | INTEGER | `0` | Maximum number of batches to process in this call. Default `0` means no limit. Values less than `0` are not allowed. |
| `refresh_newest_first` | BOOLEAN | `true` | Control the order of incremental refreshes. Set to `true` to refresh from the newest data to the oldest, or `false` for oldest to newest. |

<Callout variant="note">
Since {C.TIMESCALE_DB} 2.28.0, `refresh_continuous_aggregate()` processes the
refresh window incrementally in batches by default (`buckets_per_batch` is
`10`), matching the behavior of {C.CAGG} refresh policies. Each batch runs in

Check notice on line 142 in src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx#L142 

[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.
Raw output 
{"message": "[Google.Acronyms] Spell out 'CAGG', if it's unfamiliar to the audience.", "location": {"path": "src/content/docs/reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate.mdx", "range": {"start": {"line": 142, "column": 38}}}, "severity": "INFO"}
its own transaction, so locks are released between batches and results become
visible as each batch completes. To refresh the entire window in a single
atomic pass instead, set `buckets_per_batch` to `0`.
</Callout>

## Returns

<ReturnsVoid />
Loading