-
Notifications
You must be signed in to change notification settings - Fork 465
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.
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
docs: Fix grammar of mat view WITH options #27325
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No complaints from QA side
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.
586fe17
to
35041de
Compare
CI is failing in "Lint docs" for some reason: I've now tried to temporarily remove Aru's commit that upgrades Hugo to see if that is the reason or my commit. |
"Lint docs" has now passed: https://buildkite.com/materialize/test/builds/83403#018ff300-cc6b-47b9-91bf-af9b01e0c43b |
My recollection of that PR is coming back. The Hugo upgrade brings about a change in how it computes URLs. Marta and I chatted about this and decided we probably should go for the workaround described here as the cross reference syntax isn't desirable for our docs. |
I think there was a mistake when merging the ![]() The options are then laid out in the respective configuration option table: ![]() We should also include examples for each configuration option since these diagrams are impossible to read, anyway. I'll push up a fix. Pinged @chaas because this is an issue in a lot of reference pages, and we should patch it more generally. |
Ok, this makes a lot of sense! Thank you! |
Btw. are the simplifications compared to the generic WITH option diagram from your above comment intentional? There is only |
Fixes two issues with the grammar diagram of CREATE MATERIALIZED VIEW:
WITH ()
(i.e., empty parens afterWITH
) would be possible.ASSERT NOT NULL
andRETAIN HISTORY
can come only in this order, but actuallyASSERT NOT NULL
can be specified also afterRETAIN 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, andASSERT NOT NULL
can be specified any number of times, butRETAIN HISTORY
can only be specified once. I think it's ok that we are not capturing certain restrictions in the grammar diagram, especially if they are handled by planning and not by parsing. (For example, it's also impossible to capture thatASSERT NOT NULL
can't be specified for the same column twice.)Also, the new layout seems cleaner overall, especially when I add REFRESH soon.
Note that I did not add the optional
=
forASSERT 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.
Next I'm going to work on adding REFRESH, but I'd like to get an opinion on the above before I get too deep into the REFRESH grammar.
Motivation
Fixes minor docs issues.
Tips for reviewer
Checklist
$T ⇔ Proto$T
mapping (possibly in a backwards-incompatible way), then it is tagged with aT-proto
label.