diff --git a/documentation/concept/mat-views.md b/documentation/concept/mat-views.md index 40fd5215e..8d4488a6e 100644 --- a/documentation/concept/mat-views.md +++ b/documentation/concept/mat-views.md @@ -74,15 +74,14 @@ To create a materialize view, surround your `SAMPLE BY` or time-based `GROUP BY` query with a [`CREATE MATERIALIZED VIEW`](/docs/reference/sql/create-mat-view) statement. ```questdb-sql title="trades_notional_1m ddl" -CREATE MATERIALIZED VIEW 'trades_notional_1m' AS ( - SELECT - timestamp, - symbol, - side, - sum(price * amount) AS notional - FROM trades - SAMPLE BY 1m -) PARTITION BY DAY; +CREATE MATERIALIZED VIEW 'trades_notional_1m' AS +SELECT + timestamp, + symbol, + side, + sum(price * amount) AS notional +FROM trades +SAMPLE BY 1m; ``` Querying a materialized view can be up to hundreds of times faster than diff --git a/documentation/guides/mat-views.md b/documentation/guides/mat-views.md index edb41f241..0522f70d4 100644 --- a/documentation/guides/mat-views.md +++ b/documentation/guides/mat-views.md @@ -104,7 +104,7 @@ If you are unfamiliar with the OHLC concept, please see our ::: -```questdb-sql title="trades_OHLC_15m ddl" +```questdb-sql title="trades_OHLC_15m DDL" CREATE MATERIALIZED VIEW 'trades_OHLC_15m' WITH BASE 'trades' REFRESH INCREMENTAL AS ( @@ -137,12 +137,20 @@ In this example: - Therefore, the materialized view will contain a summary of _all_ the base `trades` table's data. -:::tip +Many parts of the above DDL statement are optional and can be ommited: -This particular example can also be written via the -[compact syntax](#compact-syntax). - -::: +```questdb-sql title="trades_OHLC_15m compact DDL" +CREATE MATERIALIZED VIEW 'trades_OHLC_15m' AS +SELECT + timestamp, symbol, + first(price) AS open, + max(price) as high, + min(price) as low, + last(price) AS close, + sum(amount) AS volume +FROM trades +SAMPLE BY 15m; +``` #### The view name @@ -227,15 +235,15 @@ which omits the parentheses. ```questdb-sql title="trades_OHLC_15m compact syntax" CREATE MATERIALIZED VIEW trades_OHLC_15m AS - SELECT - timestamp, symbol, - first(price) AS open, - max(price) as high, - min(price) as low, - last(price) AS close, - sum(amount) AS volume - FROM trades - SAMPLE BY 15m; +SELECT + timestamp, symbol, + first(price) AS open, + max(price) as high, + min(price) as low, + last(price) AS close, + sum(amount) AS volume +FROM trades +SAMPLE BY 15m; ``` ## Querying materialized views @@ -508,17 +516,16 @@ This result set comprises just `14595` rows, instead of ~767 million. That's Here it is as a materialized view: ```questdb-sql title="LATEST ON materialized view" -CREATE MATERIALIZED VIEW 'trades_latest_1d' WITH BASE 'trades' REFRESH INCREMENTAL AS ( - SELECT - timestamp, - symbol, - side, - last(price) AS price, - last(amount) AS amount, - last(timestamp) as latest - FROM trades - SAMPLE BY 1d -) PARTITION BY DAY; +CREATE MATERIALIZED VIEW 'trades_latest_1d' AS +SELECT + timestamp, + symbol, + side, + last(price) AS price, + last(amount) AS amount, + last(timestamp) as latest +FROM trades +SAMPLE BY 1d; ``` You can try this view out on our demo: diff --git a/documentation/reference/sql/create-mat-view.md b/documentation/reference/sql/create-mat-view.md index b62951fdf..7692cafc8 100644 --- a/documentation/reference/sql/create-mat-view.md +++ b/documentation/reference/sql/create-mat-view.md @@ -7,9 +7,11 @@ description: :::info -Materialized View support is now generally available (GA) and ready for production use. +Materialized View support is now generally available (GA) and ready for +production use. -If you are using versions earlier than `8.3.1`, we suggest you upgrade at your earliest convenience. +If you are using versions earlier than `8.3.1`, we suggest you upgrade at your +earliest convenience. ::: @@ -24,16 +26,19 @@ the [introduction](/docs/concept/mat-views/) and ## Syntax -To create a materialized view, manually enter the parameters and settings: +The `CREATE MATERIALIZED VIEW` statement comes in two flavors: compact and full +syntax. The compact syntax can be used when the default parameters are +sufficient. -![Flow chart showing the syntax of the CREATE MATERIALIZED VIEW keyword](/images/docs/diagrams/createMatViewDef.svg) +![Flow chart showing the syntax of the compact CREATE MATERIALIZED VIEW syntax](/images/docs/diagrams/createMatViewCompactDef.svg) -:::tip +For more on the semantics of the compact syntax, see the +[materialized view guide](/docs/guides/mat-views/#compact-syntax). -For simple materialized views, you can alternatively use the -[compact syntax](#compact-syntax). +To create a materialized view with full syntax, you need to enter the following +parameters and settings: -::: +![Flow chart showing the syntax of the CREATE MATERIALIZED VIEW keyword](/images/docs/diagrams/createMatViewDef.svg) ## Metadata @@ -63,14 +68,13 @@ Now we can create a materialized view holding aggregated data from the base table: ```questdb-sql title="Hourly materialized view" -CREATE MATERIALIZED VIEW trades_hourly_prices AS ( - SELECT - timestamp, - symbol, - avg(price) AS avg_price - FROM trades - SAMPLE BY 1h -) PARTITION BY HOUR; +CREATE MATERIALIZED VIEW trades_hourly_prices AS +SELECT + timestamp, + symbol, + avg(price) AS avg_price +FROM trades +SAMPLE BY 1h; ``` Now, we've created a materialized view that will be automatically refreshed each @@ -96,17 +100,15 @@ one of them as the base table. ```questdb-sql title="Hourly materialized view with LT JOIN" CREATE MATERIALIZED VIEW trades_ext_hourly_prices -WITH BASE trades -AS ( - SELECT - t.timestamp, - t.symbol, - avg(t.price) AS avg_price, - avg(e.price) AS avg_ext_price - FROM trades t - LT JOIN ext_trades e ON (symbol) - SAMPLE BY 1d -) PARTITION BY WEEK; +WITH BASE trades AS +SELECT + t.timestamp, + t.symbol, + avg(t.price) AS avg_price, + avg(e.price) AS avg_ext_price +FROM trades t +LT JOIN ext_trades e ON (symbol) +SAMPLE BY 1d; ``` ## Partitioning @@ -156,7 +158,7 @@ depending on your needs. ### Examples -```questdb-sql title="Creating a materialized view with TTL" +```questdb-sql title="Creating a materialized view with PARTITION BY and TTL" CREATE MATERIALIZED VIEW trades_hourly_prices AS ( SELECT timestamp, @@ -174,14 +176,13 @@ An optional `IF NOT EXISTS` clause may be added directly after the created only if a view with the desired view name does not already exist. ```questdb-sql -CREATE MATERIALIZED VIEW IF NOT EXISTS trades_weekly_prices AS ( - SELECT - timestamp, - symbol, - avg(price) AS avg_price - FROM trades - SAMPLE BY 7d -) PARTITION BY YEAR; +CREATE MATERIALIZED VIEW IF NOT EXISTS trades_weekly_prices AS +SELECT + timestamp, + symbol, + avg(price) AS avg_price +FROM trades +SAMPLE BY 7d; ``` ## Materialized view names @@ -214,26 +215,6 @@ CREATE MATERIALIZED VIEW trades_hourly_prices AS ( OWNED BY analysts; ``` -## Compact syntax - -The `CREATE MATERIALIZED VIEW` statement also supports a compact syntax which -can be used when the default parameters are sufficient. - -![Flow chart showing the syntax of the compact CREATE MATERIALIZED VIEW syntax](/images/docs/diagrams/createMatViewCompactDef.svg) - -```questdb-sql -CREATE MATERIALIZED VIEW trades_hourly_prices AS -SELECT - timestamp, - symbol, - avg(price) AS avg_price -FROM trades -SAMPLE BY 1h; -``` - -For more on the semantics of the compact syntax, see the -[materialized view guide](/docs/guides/mat-views/#compact-syntax). - ## SYMBOL column capacity By default, SYMBOL column capacities in a materialized view are set to the same diff --git a/documentation/reference/sql/refresh-mat-view.md b/documentation/reference/sql/refresh-mat-view.md index e23a13a9e..e82e52092 100644 --- a/documentation/reference/sql/refresh-mat-view.md +++ b/documentation/reference/sql/refresh-mat-view.md @@ -28,13 +28,13 @@ incremental refresh of the materialized view. Usually, incremental refresh is automatic, so this command is useful only in niche situations when incremental refresh is not working as expected, but the view is still valid. -When the `INTERVAL` keyword is specified, this command refreshes the data in the -specified time interval only. This command is useful for a valid materialized +When the `RANGE` keyword is specified, this command refreshes the data in the +specified time range only. This command is useful for a valid materialized view with configured [`REFRESH LIMIT`](/docs/reference/sql/alter-mat-view-set-refresh-limit/). That's because inserted base table rows with timestamps older than the refresh limit -are ignored by incremental refresh, so interval refresh may be used to -recalculate materialized view on older rows. Interval refresh does not affect +are ignored by incremental refresh, so range refresh may be used to +recalculate materialized view on older rows. Range refresh does not affect incremental refresh, e.g. it does not update the last base table transaction used by incremental refresh. @@ -53,7 +53,7 @@ REFRESH MATERIALIZED VIEW trades_1h INCREMENTAL; ``` ```questdb-sql -REFRESH MATERIALIZED VIEW trades_1h INTERVAL FROM '2025-05-05T01:00:00.000000Z' TO '2025-05-05T02:00:00.000000Z'; +REFRESH MATERIALIZED VIEW trades_1h RANGE FROM '2025-05-05T01:00:00.000000Z' TO '2025-05-05T02:00:00.000000Z'; ``` ## See also