Skip to content

Commit

Permalink
docs: Fix grammar of mat view WITH options
Browse files Browse the repository at this point in the history
Fixes two issues:
- It looked as if `WITH ()` would be possible.
- It looked as if `ASSERT NOT NULL` and `RETAIN HISTORY` can come
  only in this order, but actually `ASSERT NOT NULL` can be specified
  also after `RETAIN HISTORY` (even both before and after).

Note that the new diagram is also not perfect, because now it looks as
if `RETAIN HISTORY` could be specified more than once. I think we have
to accept this, because it seems impossible to exactly specify using
BNF that these options can be specified in any order, and `ASSERT NOT
NULL` can be specified any number of times, but `RETAIN HISTORY` can
only be specified once.

Also, the new layout seems cleaner overall, especially when I add
REFRESH soon.

Note that I did not add the optional `=` for `ASSERT NOT NULL`. Started
a discussion on this here:
https://materializeinc.slack.com/archives/C063H5S7NKE/p1716888019218749

Plus the commit removes a stale PrPr notice fragment for
ASSERT NOT NULL.
  • Loading branch information
ggevay committed May 28, 2024
1 parent 4214f4b commit ac45722
Show file tree
Hide file tree
Showing 4 changed files with 79 additions and 61 deletions.
6 changes: 5 additions & 1 deletion doc/user/content/sql/create-materialized-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ resources used for view maintenance from the resources used for query serving.

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

### `with_option`

{{< diagram "with-option-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,7 +35,7 @@ _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).
**(** **ASSERT NOT NULL** _col_ident_... **)** | 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`.

## Details
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 6 additions & 3 deletions doc/user/sql-grammar/sql-grammar.bnf
Original file line number Diff line number Diff line change
Expand Up @@ -622,7 +622,10 @@ 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' '(' with_option ( ',' with_option )* ')')?
with_option_materialized_view ::=
(
( 'ASSERT NOT NULL' col_ident )
| ( 'RETAIN HISTORY' '='? 'FOR' retention_period )
)
with_options_retain_history ::= ('WITH' '(' ('RETAIN HISTORY' '='? 'FOR' retention_period) ')')

0 comments on commit ac45722

Please sign in to comment.