--- title: refresh_continuous_aggregate() | Tiger Data Docs description: Manually refresh a continuous aggregate --- Since [1.3.0](https://github.com/timescale/timescaledb/releases/tag/1.3.0) Refresh all buckets of a continuous aggregate in the refresh window given by `window_start` and `window_end`. A continuous aggregate materializes aggregates in time buckets. For example, min, max, average over 1 day worth of data, and is determined by the `time_bucket` interval. Therefore, when refreshing the continuous aggregate, only buckets that completely fit within the refresh window are refreshed. In other words, it is not possible to compute the aggregate over, for an incomplete bucket. Therefore, any buckets that do not fit within the given refresh window are excluded. The function expects the window parameter values to have a time type that is compatible with the continuous aggregate's time bucket expression, for example, if the time bucket is specified in `TIMESTAMP WITH TIME ZONE`, then the start and end time should be a date or timestamp type. Note that a continuous aggregate using the `TIMESTAMP WITH TIME ZONE` type aligns with the UTC time zone, so, if `window_start` and `window_end` is specified in the local time zone, any time zone shift relative UTC needs to be accounted for when refreshing to align with bucket boundaries. To improve performance for continuous aggregate refresh, see [CREATE MATERIALIZED VIEW](/reference/timescaledb/continuous-aggregates/create_materialized_view/index.md). ## Samples Refresh the continuous aggregate `conditions` between `2020-01-01` and `2020-02-01` exclusive. This call uses the default settings shown in [Options](#options). Since TimescaleDB 2.28.0, those defaults perform an incremental refresh in batches of 10 buckets (`buckets_per_batch`): ``` CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01'); ``` Incrementally refresh the continuous aggregate `conditions` between `2020-01-01` and `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: ``` 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`: ``` CALL refresh_continuous_aggregate( 'conditions', '2020-01-01', '2020-02-01', options => '{"buckets_per_batch": 0}'::jsonb ); ``` Force the `conditions` continuous aggregate to refresh between `2020-01-01` and `2020-02-01` exclusive, even if the data has already been refreshed. ``` CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01', force => TRUE); ``` ## Arguments The syntax is: ``` CALL refresh_continuous_aggregate( continuous_aggregate = '', window_start = , window_end = , force = true | false, options = '' ); ``` | Name | Type | Default | Required | Description | | ---------------------- | ------------------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `continuous_aggregate` | REGCLASS | - | ✔ | The continuous aggregate to refresh. | | `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. See [Options](#options). | You must specify the `window_start` and `window_end` parameters differently, depending on the type of the time column of the hypertable. For hypertables with `TIMESTAMP`, `TIMESTAMPTZ`, and `DATE` time columns, set the refresh window as an `INTERVAL` type. For hypertables with integer-based timestamps, set the refresh window as an `INTEGER` type. Note A `NULL` value for `window_start` is equivalent to the lowest changed element in the raw hypertable of the CAgg. A `NULL` value for `window_end` is equivalent to the largest changed element in raw hypertable of the CAgg. As changed element tracking is performed after the initial CAgg refresh, running CAgg refresh without `window_start` and `window_end` covers the entire time range. Note Note that it's not guaranteed that all buckets will be updated: refreshes will not take place when buckets are materialized with no data changes or with changes that only occurred in the secondary table used in the JOIN. ## Options Since [2.28.0](https://github.com/timescale/timescaledb/releases/tag/2.28.0) The `options` argument is a JSONB object that accepts the following keys: | Key | Type | Default | Description | | --------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buckets_per_batch` | INTEGER | `10` | Number of buckets to refresh per batch. This value is multiplied by the continuous aggregate 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. | | `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. | Note Since TimescaleDB 2.28.0, `refresh_continuous_aggregate()` processes the refresh window incrementally in batches by default (`buckets_per_batch` is `10`), matching the behavior of continuous aggregate refresh policies. Each batch runs in 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`. ## Returns This function returns void.