feat(docs): document compact period syntax

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.

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;
 ```

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

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'
   ('(')?