> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# refresh_continuous_aggregate()

> Manually refresh a continuous aggregate

export const HYPERTABLE = 'hypertable';

export const CAGG = 'continuous aggregate';

<Icon icon="tag" iconType="duotone" /> Since [1.3.0][tsdb-1.3.0]

Refresh all buckets of a {CAGG} in the refresh window given by
`window_start` and `window_end`.

A {CAGG} 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 {CAGG}, 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 {CAGG}'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 {CAGG} 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 {CAGG} refresh, see
[CREATE MATERIALIZED VIEW][create_materialized_view].

## Samples

Refresh the {CAGG} `conditions` between `2020-01-01` and
`2020-02-01` exclusive.

```sql theme={"dark"}
CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01');
```

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

```sql theme={"dark"}
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
$$;
```

Force the  `conditions` {CAGG} to refresh between `2020-01-01` and
`2020-02-01` exclusive, even if the data has already been refreshed.

```sql theme={"dark"}
CALL refresh_continuous_aggregate('conditions', '2020-01-01', '2020-02-01', force => TRUE);
```

## Arguments

The syntax is:

```sql theme={"dark"}
CALL refresh_continuous_aggregate(
    continuous_aggregate = '<view_name>',
    window_start = <interval>,
    window_end = <interval>,
    force = true | false,
    options = '<jsonb_options>'
);
```

| Name                   | Type                           | Default | Required | Description                                                                                                                                                                                        |
| ---------------------- | ------------------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continuous_aggregate` | REGCLASS                       | -       | ✔        | The {CAGG} 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. Supports `process_hypertable_invalidations` (boolean, default `true`).                                                                                       |

You must specify the `window_start` and `window_end` parameters differently,
depending on the type of the time column of the {HYPERTABLE}. For {HYPERTABLE}s with
`TIMESTAMP`, `TIMESTAMPTZ`, and `DATE` time columns, set the refresh window as
an `INTERVAL` type. For {HYPERTABLE}s 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>

<Warning>
  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.
</Warning>

## Returns

This function returns void.

[create_materialized_view]: /api-reference/timescaledb/continuous-aggregates/create_materialized_view

[modify-parameters]: /use-timescale/latest/configuration/customize-configuration/

[tsdb-1.3.0]: https://github.com/timescale/timescaledb/releases/tag/1.3.0