Update cagg material for TimescaleDB 2.7 (github#1115)

Co-authored-by: Lana Brindley <[email protected]>
Co-authored-by: Fabrízio de Royes Mello <[email protected]>

Author: 3 people

api/create_materialized_view.md

@@ -81,6 +81,7 @@ Optional `WITH` clause options:
 |-|-|-|-|
 |`timescaledb.materialized_only`|BOOLEAN|Return only materialized data when querying the continuous aggregate view|`FALSE`|
 |`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`|
 
 For more information, see the [real-time aggregates][real-time-aggregates] section.
 

timescaledb/how-to-guides/continuous-aggregates/about-continuous-aggregates.md

@@ -51,20 +51,34 @@ hasn't been aggregated yet. This gives you up-to-date results on every query. If
 you prefer not to see recent data, you can turn this setting off. For more
 information, see the section on [real-time aggregates][real-time-aggs]. 
 
-## Unsupported functions
-Continuous aggregates are supported for most aggregate functions that can be
-[parallelized by PostgreSQL][postgres-parallel-agg], including the standard
-aggregates like `SUM` and `AVG`. You can also use more complex expressions on
-top of the aggregate functions, for example `max(temperature)-min(temperature)`.
-
-However, aggregates using `ORDER BY` and `DISTINCT` cannot be used with
-continuous aggregates since they are not possible to parallelize with
-PostgreSQL. TimescaleDB does not currently support `FILTER` or `JOIN` clauses,
-or window functions in continuous aggregates. You can work around this by
-[aggregating the other parts of your query beforehand, then using the window function at query time][cagg-window-functions].
-
-To test out continuous aggregates, follow
-the [continuous aggregate tutorial][tutorial-caggs].
+## Function support
+In TimescaleDB 2.7 and above, continuous aggregates support all PostgreSQL
+aggregate functions. This includes both parallelizable aggregates, such as `SUM`
+and `AVG`, and non-parallelizable aggregates, such as `RANK`.
+
+In older versions of PostgreSQL, continuous aggregates only support
+[aggregate functions that can be parallelized by PostgreSQL][postgres-parallel-agg].
+They also don't support `FILTER` and `ORDER BY` clauses, and the `DISTINCT` keyword. You can
+work around this by aggregating the other parts of your query in the continuous
+aggregate, then
+[using the window function to query the aggregate][cagg-window-functions].
+
+The following table summarizes aggregate function support in continuous
+aggregates:
+
+|Function, clause, or feature|TimescaleDB 2.7 and above|Below TimescaleDB 2.7|
+|-|-|-|
+|Parallelizable aggregate functions|✅|✅|
+|Non-parallelizable aggregate functions|✅|❌|
+|Ordered-set aggregates|✅|❌|
+|Hypothetical-set aggregates|✅|❌|
+|`DISTINCT` in aggregate functions|✅|❌|
+|`FILTER` in aggregate functions|✅|❌|
+|`ORDER BY` in aggregate functions|✅|❌|
+
+
+If you want the old behavior in TimescaleDB 2.7 and above, set the parameter
+`timescaledb.finalized` to `false` when creating your continuous aggregate.
 
 ## Components of a continuous aggregate
 Continuous aggregates consist of:

timescaledb/overview/core-concepts/continuous-aggregates.md

@@ -80,15 +80,16 @@ SELECT bucket, avg
 ORDER BY bucket;
 ```
 
-Continuous aggregates are supported for most aggregate functions that
-can be [parallelized by PostgreSQL][postgres-parallel-agg], which
-includes the normal aggregates like `SUM` and `AVG`. However,
-aggregates using `ORDER BY` and `DISTINCT` cannot be used with
-continuous aggregates since they are not possible to parallelize by
-PostgreSQL. In addition, TimescaleDB continuous aggregates do not
-currently support the `FILTER` clause (not to be confused with
-`WHERE`) even though it is possible to parallelize but we might add
-support for this in a future version.
+<highlight type="important">
+In TimescaleDB 2.7 and above, continuous aggregates support all PostgreSQL
+aggregate functions. They also support aggregates with keywords such as
+`DISTINCT`, `ORDER BY`, and `FILTER`. Older versions of TimescaleDB only support
+aggregate functions that can be
+[parallelized by PostgreSQL](https://www.postgresql.org/docs/current/parallel-plans.html#PARALLEL-AGGREGATION).
+They don't support `DISTINCT`, `ORDER BY`, and `FILTER`. For more information,
+see the
+[how-to guide on continuous aggregates](/timescaledb/latest/how-to-guides/continuous-aggregates/about-continuous-aggregates/#unsupported-functions).
+</highlight>
 
 ## Real-time aggregation [](real-time-aggregates)
 
@@ -137,5 +138,4 @@ provides great control and flexibility!
 
 
 [postgres-materialized-views]: https://www.postgresql.org/docs/current/rules-materializedviews.html
-[postgres-parallel-agg]:https://www.postgresql.org/docs/current/parallel-plans.html#PARALLEL-AGGREGATION
 [api-alter-cagg]: /api/:currentVersion:/continuous-aggregates/alter_materialized_view/