Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Fix grammar of mat view WITH options #27325

Merged
merged 2 commits into from
Jun 18, 2024
Merged

docs: Fix grammar of mat view WITH options #27325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
35041de
docs: Fix grammar of mat view WITH options
ggevay May 28, 2024
96d48c3
Restructure
morsapaes Jun 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions doc/user/content/sql/create-materialized-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,6 @@ resources used for view maintenance from the resources used for query serving.

{{< diagram "create-materialized-view.svg" >}}

### `with_options`

{{< diagram "with-options-materialized-view.svg" >}}

Field | Use
------|-----
**OR REPLACE** | If a materialized view exists with the same name, replace it with the view defined in this statement. You cannot replace views that other views or sinks depend on, nor can you replace a non-view object with a view.
Expand All @@ -31,8 +27,13 @@ _view&lowbar;name_ | A name for the materialized view.
**(** _col_ident_... **)** | Rename the `SELECT` statement's columns to the list of identifiers, both of which must be the same length. Note that this is required for statements that return multiple columns with the same identifier.
_cluster&lowbar;name_ | The cluster to maintain this materialized view. If not specified, defaults to the active cluster.
_select&lowbar;stmt_ | The [`SELECT` statement](../select) whose results you want to maintain incrementally updated.
**(** **ASSERT NOT NULL** _col_ident_... **)** | This option has known performance or stability issues and is under active development.* A list of columns for which to create [non-null assertions](#non-null-assertions).
_retention_period_ | ***Private preview.** This option has known performance or stability issues and is under active development.* Duration for which Materialize retains historical data for performing [time travel queries](/transform-data/patterns/time-travel-queries). Accepts positive [interval](https://materialize.com/docs/sql/types/interval/) values (e.g. `'1hr'`). Default: `1s`.

### `WITH` options

| Field | Value | Description |
| ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ASSERT NOT NULL** _col_ident_ | `text` | The column identifier for which to create a [non-null assertion](#non-null-assertions). To specify multiple columns, repeat the option multiple times. |
| **RETAIN HISTORY FOR** _retention_period_ | `interval` | ***Private preview.** This option has known performance or stability issues and is under active development.* Duration for which Materialize retains historical data for performing [time travel queries](/transform-data/patterns/time-travel-queries). Accepts positive [interval](/sql/types/interval/) values (e.g. `'1hr'`). Default: `1s`. |

## Details

Expand Down Expand Up @@ -86,6 +87,9 @@ clause is used erroneously, and a `NULL` value is in fact produced in
a column for which `ASSERT NOT NULL` was specified, querying the
materialized view will produce an error until the offending row is deleted.

[//]: # "TODO(morsapaes) Add section linking to refresh strategies docs
in #27521."

## Examples

### Creating a materialized view
Expand Down Expand Up @@ -116,6 +120,8 @@ SELECT
FROM users FULL OUTER JOIN orders ON users.id = orders.user_id
```

[//]: # "TODO(morsapaes) Add example for setting a refresh strategy in #27521."

[//]: # "TODO(morsapaes) Add more elaborate examples with \timing that show
things like querying materialized views from different clusters, indexed vs.
non-indexed, and so on."
Expand Down
120 changes: 60 additions & 60 deletions doc/user/layouts/partials/sql-grammar/create-materialized-view.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
78 changes: 0 additions & 78 deletions doc/user/layouts/partials/sql-grammar/with-options-materialized-view.svg
View file
Open in desktop

This file was deleted.

13 changes: 2 additions & 11 deletions doc/user/sql-grammar/sql-grammar.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,15 +150,10 @@ create_index ::=
)
with_options?
create_materialized_view ::=
'CREATE' 'MATERIALIZED VIEW' 'IF NOT EXISTS'?
'CREATE' 'OR REPLACE'? 'MATERIALIZED VIEW' 'IF NOT EXISTS'?
view_name ( '(' col_ident ( ',' col_ident )* ')' )?
('IN CLUSTER' cluster_name)?
with_options?
'AS' select_stmt |
'CREATE' 'OR REPLACE' 'MATERIALIZED VIEW'
view_name ( '(' col_ident ( ',' col_ident )* ')' )?
('IN CLUSTER' cluster_name)?
with_options?
('WITH' with_options)?
'AS' select_stmt
create_role ::=
'CREATE' 'ROLE' role_name ('WITH'? 'INHERIT')?
Expand Down Expand Up @@ -624,8 +619,4 @@ with_options_aws ::= 'WITH' '('

with_options_aws_static ::=
'access_key_id' '=' val ',' 'secret_access_key' '=' val ( ',' 'token' '=' val )?
with_options_materialized_view ::=
('WITH' '(' ( 'ASSERT NOT NULL' col_ident ( ',' 'ASSERT NOT NULL' col_ident )* )?
( 'RETAIN HISTORY' '='? 'FOR' retention_period )?
')')
with_options_retain_history ::= ('WITH' '(' ('RETAIN HISTORY' '='? 'FOR' retention_period) ')')