Skip to content

Document MV GRACE PERIOD clause #15810

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

Closed
findepi wants to merge 4 commits into from
Closed

Document MV GRACE PERIOD clause #15810

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d62ab47
Document MV GRACE PERIOD clause
findepi Jan 23, 2023
b975033
Update docs/src/main/sphinx/sql/create-materialized-view.rst
findepi Jan 24, 2023
c265175
Update docs/src/main/sphinx/sql/create-materialized-view.rst
findepi Jan 24, 2023
630baf3
Update docs/src/main/sphinx/sql/create-materialized-view.rst
findepi Jan 24, 2023
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
12 changes: 8 additions & 4 deletions docs/src/main/sphinx/sql/create-materialized-view.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Synopsis

CREATE [ OR REPLACE ] MATERIALIZED VIEW
[ IF NOT EXISTS ] view_name
[ GRACE PERIOD interval ]
[ COMMENT string ]
[ WITH properties ]
AS query
Expand All @@ -29,16 +30,19 @@ materialized views, as compared to each time of accessing the view. Multiple
reads of view data over time, or by multiple users, all trigger repeated
processing. This is avoided for materialized views.

When the underlying data changes, the materialized view becomes out of sync with
the source tables. Update the data in the materialized view with the
:doc:`refresh-materialized-view` statement.

The optional ``OR REPLACE`` clause causes the materialized view to be replaced
if it already exists rather than raising an error.

The optional ``IF NOT EXISTS`` clause causes the materialized view only to be
created or replaced if it does not exist yet.

The optional ``GRACE PERIOD`` clause specifies how long the query materialization
is used for querying. If the time elapsed since last materialized view refresh
is greater than the grace period, the materialized view acts as a normal view and
the materialized data is not used. If not specified, the grace period defaults to
infinity. See :doc:`refresh-materialized-view` for more about refreshing
Copy link
Member

@mosabua mosabua Jan 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re "defaults to infinity". We should clarify what that means in practice. Something like that:

As a result a materialized by default therefore without the specified grace period always uses the materialized data from the last refresh and never falls back to act like a view and retrieve the current data from the source tables.

Copy link
Member Author

@findepi findepi Jan 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for pointing this out.
You worded it very precisely. I am afraid some users may not understand. The sentence feels pretty long. Would it be possible to reword it or split?

Ideally, can you please make it a suggestion, or somehow else indicate which piece of text you would want to have replaced with the new sentence(s)?

Copy link
Member

@mosabua mosabua Jan 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah .. I was struggling putting something together.

How about this? After "inifinity." insert this:

The default behavior therefore is that the queries accessing the materialized view always access the data from the most recent refresh and the materialized view storage tables. The query processing never falls back to process the materialized view access like a view and retrieve the current data from the source tables. This only occurs if a grace period is specified.

I know this is long but I feel like this is the only way to truly explain what is and is not happening. Maybe @colebow can chime in and refine my wording some more.

Copy link
Member

@mosabua mosabua Jan 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@findepi did you forget to pull the above suggestion in?

materialized views.

The optional ``COMMENT`` clause causes a ``string`` comment to be stored with
the metadata about the materialized view. The comment is displayed with the
:doc:`show-create-materialized-view` statement and is available in the table
Expand Down