From 75a2558592aea3643a58188baa1268001e91f240 Mon Sep 17 00:00:00 2001 From: Andrei Pechkurov Date: Wed, 26 Nov 2025 09:58:49 +0200 Subject: [PATCH] feat(docs): document compact period syntax --- documentation/guides/mat-views.md | 18 ++ .../sql/alter-mat-view-set-refresh.md | 4 + .../reference/sql/create-mat-view.md | 38 +++- static/images/docs/diagrams/.railroad | 2 +- .../images/docs/diagrams/createMatViewDef.svg | 169 +++++++++--------- 5 files changed, 146 insertions(+), 85 deletions(-) diff --git a/documentation/guides/mat-views.md b/documentation/guides/mat-views.md index c188604cc..3a3e24f50 100644 --- a/documentation/guides/mat-views.md +++ b/documentation/guides/mat-views.md @@ -207,6 +207,24 @@ FROM trades SAMPLE BY 1d; ``` +There is also compact `PERIOD` syntax: + +```questdb-sql title="Compact syntax for period materialized views" +CREATE MATERIALIZED VIEW trades_daily_prices +REFRESH PERIOD (SAMPLE BY INTERVAL) AS +SELECT + timestamp, + symbol, + avg(price) AS avg_price +FROM trades +SAMPLE BY 1d; +``` + +The above DDL statement creates a period materialized view with single day +period, as defined by the SAMPLE BY clause. Such configuration improves +refresh performance in case of intensive real-time ingestion into the base +table since the refresh generates less transactions. + Refer to the following [documentation page](/docs/reference/sql/create-mat-view/#period-materialized-views) to learn more on period materialized views. diff --git a/documentation/reference/sql/alter-mat-view-set-refresh.md b/documentation/reference/sql/alter-mat-view-set-refresh.md index 59f5867b9..9f1423322 100644 --- a/documentation/reference/sql/alter-mat-view-set-refresh.md +++ b/documentation/reference/sql/alter-mat-view-set-refresh.md @@ -29,6 +29,10 @@ ALTER MATERIALIZED VIEW trades_hourly_prices SET REFRESH EVERY '1h'; ALTER MATERIALIZED VIEW trades_hourly_prices SET REFRESH PERIOD (LENGTH 1d DELAY 1h); ``` +```questdb-sql +ALTER MATERIALIZED VIEW trades_hourly_prices SET REFRESH PERIOD (SAMPLE BY INTERVAL); +``` + ```questdb-sql ALTER MATERIALIZED VIEW trades_hourly_prices SET REFRESH IMMEDIATE; ``` diff --git a/documentation/reference/sql/create-mat-view.md b/documentation/reference/sql/create-mat-view.md index 169c30dfe..a7820f9e5 100644 --- a/documentation/reference/sql/create-mat-view.md +++ b/documentation/reference/sql/create-mat-view.md @@ -177,7 +177,7 @@ REFRESH EVERY 10m PERIOD (LENGTH 1d TIME ZONE 'Europe/London' DELAY 2h) AS Here, the `PERIOD` refresh still takes place once a period completes, but refreshes for older rows take place each 10 minutes. -Finally, period materialized views can be configure for manual refresh: +Period materialized views can be also configured for manual refresh: ```questdb-sql title="Period materialized view with timer refresh" CREATE MATERIALIZED VIEW trades_hourly_prices @@ -190,6 +190,30 @@ The only way to refresh data on such a materialized view is to run `REFRESH` statement will refresh incrementally all recently completed periods, as well as all time intervals touched by the recent write transactions. +Finally, there is also a compact `PERIOD` syntax. It configures the view +to ignore writes into the latest, incomplete SAMPLE BY interval, e.g. +incomplete hour in our example. Ignoring the latest SAMPLE BY interval +until it ends improves materialized view refresh performance in case of +intensive real-time ingestion into the base table since the refresh generates +less transactions. + +Here is how the compact syntax looks like: + +```questdb-sql title="Compact syntax for period materialized views" +CREATE MATERIALIZED VIEW trades_hour_prices +REFRESH PERIOD (SAMPLE BY INTERVAL) AS +SELECT + timestamp, + symbol, + avg(price) AS avg_price +FROM trades +SAMPLE BY 1h +ALIGN TO CALENDAR TIME ZONE 'Europe/London'; +``` + +The above DDL statement creates a period materialized view with single day +period in the `Europe/London` time zone, as defined by the SAMPLE BY clause. + ## Initial refresh As soon as a materialized view is created an asynchronous refresh is started. In @@ -314,6 +338,18 @@ FROM trades SAMPLE BY 1h; ``` +```questdb-sql title="Creating a materialized view with compact period syntax" +CREATE MATERIALIZED VIEW trades_hourly_prices +REFRESH PERIOD (SAMPLE BY INTERVAL) AS +SELECT + timestamp, + symbol, + avg(price) AS avg_price +FROM trades +SAMPLE BY 1h +ALIGN CALENDAR TIME ZONE 'Europe/London'; +``` + ```questdb-sql title="Creating a materialized view with timer refresh each 10 minutes" CREATE MATERIALIZED VIEW trades_hourly_prices REFRESH EVERY 10m START '2025-06-18T00:00:00.000000000' AS diff --git a/static/images/docs/diagrams/.railroad b/static/images/docs/diagrams/.railroad index 5df152ddd..884bff522 100644 --- a/static/images/docs/diagrams/.railroad +++ b/static/images/docs/diagrams/.railroad @@ -334,7 +334,7 @@ createMatViewDef ('WITH BASE' baseTableName)? ( 'REFRESH' ((('IMMEDIATE' | 'MANUAL') ('DEFERRED')?) | ('EVERY' interval ('DEFERRED')? ('START' timestamp)? ('TIME' 'ZONE' timezone)?) )? - ('PERIOD' '(' 'LENGTH' length ('TIME' 'ZONE' timezone)? ('DELAY' delay)? ')')? + ('PERIOD' '(' ('LENGTH' length ('TIME' 'ZONE' timezone)? ('DELAY' delay)?) | ('SAMPLE BY INTERVAL') ')')? )? 'AS' ('(')? diff --git a/static/images/docs/diagrams/createMatViewDef.svg b/static/images/docs/diagrams/createMatViewDef.svg index 4db3b9c69..aebca2982 100644 --- a/static/images/docs/diagrams/createMatViewDef.svg +++ b/static/images/docs/diagrams/createMatViewDef.svg @@ -1,4 +1,4 @@ - + \ No newline at end of file