questdb · nwoolmer · Mar 28, 2025 · Mar 28, 2025
diff --git a/documentation/concept/mat-views.md b/documentation/concept/mat-views.md
@@ -12,8 +12,9 @@ Materialized View support is in **beta**.
 
 It may not be fit for production use.
 
-To enable **beta** materialized views, set `cairo.mat.view.enabled=true` in `server.conf`, or export the equivalent
-environment variable: `QDB_CAIRO_MAT_VIEW_ENABLED=true`.
+To enable **beta** materialized views, set `cairo.mat.view.enabled=true` in
+`server.conf`, or export the equivalent environment variable:
+`QDB_CAIRO_MAT_VIEW_ENABLED=true`.
 
 Please let us know if you run into issues.
 
@@ -25,7 +26,6 @@ Either:
 
 :::
 
-
 A materialized view is a database object that stores the pre-computed results of
 a query. Unlike regular views, which compute their results at query time,
 materialized views persist their data to disk, making them particularly
@@ -39,6 +39,7 @@ efficient for expensive aggregate queries that are run frequently.
   - [How to create a materialized view](/blog/how-to-create-a-materialized-view/):
     A full walkthrough of simple and advanced materialized views
 -->
+
 - **SQL Commands**
 
   - [`CREATE MATERIALIZED VIEW`](/docs/reference/sql/create-mat-view/): Create a
@@ -85,11 +86,13 @@ process works as follows:
 3. This data is extracted and used to recompute the materialised view.
 
 This refresh happens asynchronously, minimising any impact on write performance.
-The refresh state of the materialized view is tracked using transaction numbers. The
-transaction numbers can be compared with the base table, for monitoring the 'refresh lag'.
+The refresh state of the materialized view is tracked using transaction numbers.
+The transaction numbers can be compared with the base table, for monitoring the
+'refresh lag'.
 
 For example, if a base table receives new rows for `2025-02-18`, only that day's
-relevant time slices are recomputed, rather than reprocessing all historical data.
+relevant time slices are recomputed, rather than reprocessing all historical
+data.
 
 You can monitor refresh status using the `materialized_views()` system function:
 
@@ -106,10 +109,9 @@ FROM materialized_views();
 Here is an example output:
 
 | view_name   | last_refresh_timestamp | view_status | base_table_txn | applied_base_table_txn |
-|-------------| ---------------------- | ----------- | -------------- | ---------------------- |
+| ----------- | ---------------------- | ----------- | -------------- | ---------------------- |
 | trades_view | null                   | valid       | 102            | 102                    |
 
-
 When `base_table_txn` matches `applied_base_table_txn`, the materialized view is
 fully up-to-date.
 
@@ -127,7 +129,7 @@ FROM materialized_views();
 ```
 
 | view_name     | base_table_name | view_status | invalidation_reason                          |
-|---------------|-----------------| ----------- | -------------------------------------------- |
+| ------------- | --------------- | ----------- | -------------------------------------------- |
 | trades_view   | trades          | valid       | null                                         |
 | exchange_view | exchange        | invalid     | [-105] table does not exist [table=exchange] |
 
@@ -137,12 +139,14 @@ To restore an invalid view, and refresh its data from scratch, use:
 REFRESH MATERIALIZED VIEW view_name FULL;
 ```
 
-This command deletes existing data in the materialized view, and re-runs its query.
+This command deletes existing data in the materialized view, and re-runs its
+query.
 
-Once the view is repopulated, the view is marked as 'valid' so that it can be incrementally refreshed.
+Once the view is repopulated, the view is marked as 'valid' so that it can be
+incrementally refreshed.
 
-For large base tables, a full refresh may take a significant amount of time.
-You can cancel the refresh using the
+For large base tables, a full refresh may take a significant amount of time. You
+can cancel the refresh using the
 [`CANCEL QUERY`](/docs/reference/sql/cancel-query/) SQL.
 
 For the conditions which can invalidate a materialized view, see the
@@ -158,8 +162,9 @@ source.
   table using `WITH BASE`.
 
 The view is automatically refreshed when the base table is changed. Therefore,
-you should make sure the table that you wish to drive the view is defined correctly.
-If you use the wrong base table, then the view may not be refreshed at the times you expect.
+you should make sure the table that you wish to drive the view is defined
+correctly. If you use the wrong base table, then the view may not be refreshed
+at the times you expect.
 
 ## Technical requirements
 
@@ -169,32 +174,35 @@ To create a materialized view, your query:
 
 - Must use either `SAMPLE BY` or `GROUP BY` with a designated timestamp column
   key.
-- Must not contain `FROM-TO`, `FILL`, and `ALIGN TO FIRST OBSERVATION` clauses in
-  `SAMPLE BY` queries
+- Must not contain `FROM-TO`, `FILL`, and `ALIGN TO FIRST OBSERVATION` clauses
+  in `SAMPLE BY` queries
 - Must use join conditions that are compatible with incremental refreshing.
+- When the base table has [deduplication](/docs/concept/deduplication/) enabled,
+  the non-aggregate columns selected by the materialized view query must be a
+  subset of the `DEDUP` keys from the base table.
 
 We intend to loosen some of these restrictions in future.
 
 ### View invalidation
 
 The view's structure is tightly coupled with its base table.
 
-The main cause of invalidation for a materialised view, is when the table schema or underlying data
-is modified.
-
-These changes include dropping columns, dropping partitions and renaming the table.
-
-Data deletion or modification, for example, using `TRUNCATE` or `UPDATE`, may also cause invalidation.
+The main cause of invalidation for a materialised view, is when the table schema
+or underlying data is modified.
 
-Also, a materialized view must use the same `DEDUP` keys as the base table.
+These changes include dropping columns, dropping partitions and renaming the
+table.
 
+Data deletion or modification, for example, using `TRUNCATE` or `UPDATE`, may
+also cause invalidation.
 
 ## Replicated views (Enterprise only)
 
 Replication of the base table is independent of materialized view maintenance.
 
-If you promote a replica to a new primary instance, this may trigger a full materialized view refresh
-in the case where the replica did not already have a fully up-to-date materialized view.
+If you promote a replica to a new primary instance, this may trigger a full
+materialized view refresh in the case where the replica did not already have a
+fully up-to-date materialized view.
 
 ## Resource management
 
@@ -208,9 +216,11 @@ Materialized Views are compatible with the usual resource management systems:
 ### Materialized view with TTL
 
 Materialized Views take extra storage and resources to maintain. If your
-`SAMPLE BY` unit is small (seconds, milliseconds), this could be a significant amount of data.
+`SAMPLE BY` unit is small (seconds, milliseconds), this could be a significant
+amount of data.
 
-Therefore, you can decide on a retention policy for the data, and set it using `TTL`:
+Therefore, you can decide on a retention policy for the data, and set it using
+`TTL`:
 
 ```questdb-sql title="Create a materialized view with a TTL policy"
 CREATE MATERIALIZED VIEW trades_hourly_prices AS (
@@ -223,5 +233,5 @@ CREATE MATERIALIZED VIEW trades_hourly_prices AS (
 ) PARTITION BY WEEK TTL 8 WEEKS;
 ```
 
-In this example, the view stores hourly summaries of the pricing data, in weekly partitions,
-keeping the prior 8 partitions.
+In this example, the view stores hourly summaries of the pricing data, in weekly
+partitions, keeping the prior 8 partitions.
diff --git a/documentation/reference/sql/create-mat-view.md b/documentation/reference/sql/create-mat-view.md
@@ -11,8 +11,9 @@ Materialized View support is in **beta**.
 
 It may not be fit for production use.
 
-To enable **beta** materialized views, set `cairo.mat.view.enabled=true` in `server.conf`, or export the equivalent
-environment variable: `QDB_CAIRO_MAT_VIEW_ENABLED=true`.
+To enable **beta** materialized views, set `cairo.mat.view.enabled=true` in
+`server.conf`, or export the equivalent environment variable:
+`QDB_CAIRO_MAT_VIEW_ENABLED=true`.
 
 Please let us know if you run into issues.
 
@@ -48,7 +49,6 @@ The following example demonstrate creating materialized views from basic
 statements, and introduces feature such as
 [partitioning](/glossary/database-partitioning/).
 
-
 ## Creating a view
 
 Our examples use the following base table:
@@ -131,10 +131,11 @@ been created.
 
 ## Time To Live (TTL)
 
-A retention policy can be set on the materialized view, bounding how much data is stored.
+A retention policy can be set on the materialized view, bounding how much data
+is stored.
 
-Simply specify a time-to-live (TTL) using the `TTL` clause, placing it right after
-`PARTITION BY <unit>`.
+Simply specify a time-to-live (TTL) using the `TTL` clause, placing it right
+after `PARTITION BY <unit>`.
 
 Follow the `TTL` keyword with a number and a time unit, one of:
 
@@ -149,7 +150,8 @@ information on the behavior of this feature.
 
 :::note
 
-The time-to-live (TTL) for the materialized view can differ from the base table, depending on your needs.
+The time-to-live (TTL) for the materialized view can differ from the base table,
+depending on your needs.
 
 :::
 
@@ -191,11 +193,11 @@ Materialized view names follow the
 ## OWNED BY (Enterprise)
 
 When a user creates a new materialized view, they are automatically assigned all
-materialized view level permissions with the `GRANT` option for that view.
-This behaviour can can be overridden using `OWNED BY`.
+materialized view level permissions with the `GRANT` option for that view. This
+behaviour can can be overridden using `OWNED BY`.
 
-If the `OWNED BY` clause is used, the permissions instead go to the
-user, group, or service account named in that clause.
+If the `OWNED BY` clause is used, the permissions instead go to the user, group,
+or service account named in that clause.
 
 The `OWNED BY` clause cannot be omitted if the materialized view is created by
 an external user, as permissions cannot be granted to them.
@@ -212,3 +214,10 @@ CREATE MATERIALIZED VIEW trades_hourly_prices AS (
 ) PARTITION BY DAY
 OWNED BY analysts;
 ```
+
+## Query constraints
+
+There is a list of requirements for the queries that are used in materialized
+views. Refer to this
+[documentation section](/docs/concept/mat-views/#technical-requirements) to
+learn them.