Document incremental refresh_continuous_aggregate() options (2.28.0)

[atovpeko]

Describe your changes

Documents the incremental, batched manual refresh added in TimescaleDB 2.28.0 (timescale/timescaledb#9903), on the refresh_continuous_aggregate() reference page.

• Documents the options JSONB keys buckets_per_batch, max_batches_per_execution, and refresh_newest_first, with defaults, in a new Options section.
• Notes the new default behavior: manual refreshes now batch by default (buckets_per_batch is 10), matching refresh policies, and explains how to restore single-transaction behavior (buckets_per_batch set to 0).
• Replaces the manual DO-loop incremental sample, now superseded by native batching, with a native incremental example.
• Removes the stale process_hypertable_invalidations option, which was removed from the engine in 2.27.0 (Remove dead process_hypertable_invalidations policy code timescaledb#9596) and is now silently ignored.

Affected pages

• /reference/timescaledb/continuous-aggregates/refresh_continuous_aggregate

Related Issues

Issue: https://linear.app/tigerdata/issue/EDU-136

Checklist before requesting a review

• - This is ready for review. If not, raise as a draft PR
• - I have reviewed my changes.
• - I have confirmed the content is technically accurate.
• - I have tested any code that is added or updated on the latest available version.
• - I have confirmed the content is free of typos or grammar errors.
• - I have verified all images and videos are clear and match production (or dev for unreleased features).
• - This references a feature that is public. If not, add a note and we can schedule the merge for after the feature release.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiger-data-docs	Ready	Preview, Comment	Jun 12, 2026 9:47am

[github-actions]

⚠️ Checklist Incomplete

Please complete all checklist items in the PR description before requesting review.

Unchecked items:

• This references a feature that is public

Tip: If an item isn't relevant to your PR, mark it as checked and add "n/a" next to it.

[melihmutlu]

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]

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]

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]

Updated