docs: Add more details to the materialized view documentation by bibith4 · Pull Request #27465 · prestodb/presto

bibith4 · 2026-03-30T09:44:25Z

Description

Updated the materialized view documentation to incorporate supporting configurations and relevant examples.

Motivation and Context

To ensure consistent understanding and usage of materialized views

Impact

Test Plan

Contributor checklist

Please make sure your submission complies with our contributing guide, in particular code style and commit standards.
PR description addresses the issue accurately and concisely. If the change is non-trivial, a GitHub Issue is referenced.
Documented new properties (with its default value), SQL syntax, functions, or other functionality.
If release notes are required, they follow the release notes guidelines.
Adequate tests were added if applicable.
CI passed.
If adding new dependencies, verified they have an OpenSSF Scorecard score of 5.0 or higher (or obtained explicit TSC approval for lower scores).

Release Notes

Please follow release notes guidelines and fill in the release notes below.

== NO RELEASE NOTE ==

Summary by Sourcery

Expand and clarify documentation around materialized views, including their creation and refresh behavior.

Documentation:

Enhance admin documentation for materialized views with additional guidance and context.
Update SQL reference pages for CREATE MATERIALIZED VIEW and REFRESH MATERIALIZED VIEW to include more details and examples.

sourcery-ai · 2026-03-30T09:44:48Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Expands and clarifies the documentation for materialized views, including admin guidance, configuration details, and SQL syntax/usage for creating and refreshing materialized views.

File-Level Changes

Change	Details	Files
Enhance the admin guide for materialized views with configuration and operational guidance.	Document additional configuration options relevant to materialized views (e.g., connector and catalog-level settings). Clarify lifecycle and management tasks such as creation, refresh strategies, and troubleshooting behavior. Add or refine narrative sections to better explain how materialized views interact with underlying tables and queries.	`presto-docs/src/main/sphinx/admin/materialized-views.rst`
Expand CREATE MATERIALIZED VIEW SQL reference with richer explanations and examples.	Clarify required and optional clauses in the CREATE MATERIALIZED VIEW syntax. Add concrete examples demonstrating common usage patterns and best practices. Explain semantics such as how the defining query is stored and how dependencies on base tables are handled.	`presto-docs/src/main/sphinx/sql/create-materialized-view.rst`
Improve REFRESH MATERIALIZED VIEW documentation with clearer behavior and example workflows.	Clarify how REFRESH MATERIALIZED VIEW behaves with respect to incremental vs full refresh, concurrency, and failure scenarios (where applicable). Provide example statements showing typical refresh usage in operational contexts. Align terminology and cross-references with the admin and CREATE MATERIALIZED VIEW documentation for consistency.	`presto-docs/src/main/sphinx/sql/refresh-materialized-view.rst`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai

Hey - I've reviewed your changes and they look great!

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

tdcmeehan · 2026-03-30T13:57:13Z

presto-docs/src/main/sphinx/admin/materialized-views.rst

+=====================+=====================+=====================+=====================+==============================+
+| USE_VIEW_QUERY      | No                  | Yes                 | No (for queries)    | Always fresh, MV ignored     |
+---------------------+---------------------+---------------------+---------------------+------------------------------+
+| USE_STITCHING       | Partial             | Yes                 | No (for queries)    | Hybrid result                |


What does hybrid result mean?

tdcmeehan · 2026-03-30T13:57:35Z

presto-docs/src/main/sphinx/admin/materialized-views.rst

    SET SESSION materialized_view_skip_storage = 'USE_STITCHING';

+
+Behavior Summary


This table doesn't seem very useful beyond the doc above, let's just remove it.

@tdcmeehan I have removed the Table. Please check

tdcmeehan · 2026-03-30T13:58:27Z

presto-docs/src/main/sphinx/sql/create-materialized-view.rst

+Create a materialized view with staleness configuration::
+
+``staleness_window - How long stale data is acceptable``
+
+``USE_VIEW_QUERY``
+
+    CREATE MATERIALIZED VIEW daily_sales
+    WITH (stale_read_behavior = 'USE_VIEW_QUERY',
+    staleness_window = '1h'
+    ) AS
+    SELECT date_trunc('day', order_date) AS day,
+    region,
+    SUM(amount) AS total_sales,
+    COUNT(*) AS order_count
+    FROM orders
+    GROUP BY date_trunc('day', order_date), region
+
+``FAIL``
+
+    CREATE MATERIALIZED VIEW daily_sales
+    WITH (stale_read_behavior = 'FAIL',
+    staleness_window = '30m'
+    ) AS
+    SELECT date_trunc('day', order_date) AS day,
+    region,
+    SUM(amount) AS total_sales,
+    COUNT(*) AS order_count
+    FROM orders
+    GROUP BY date_trunc('day', order_date), region
+
+``USE_STITCHING``
+
+    CREATE MATERIALIZED VIEW daily_sales
+    WITH (stale_read_behavior = 'USE_STITCHING',
+    staleness_window = '1h'
+    ) AS
+    SELECT date_trunc('day', order_date) AS day,
+    region,
+    SUM(amount) AS total_sales,
+    COUNT(*) AS order_count
+    FROM orders
+    GROUP BY date_trunc('day', order_date), region
+
+``No staleness window(always stale after source changes)``
+
+    CREATE MATERIALIZED VIEW daily_sales
+    WITH (stale_read_behavior = 'FAIL'
+    ) AS
+    SELECT date_trunc('day', order_date) AS day,
+    region,
+    SUM(amount) AS total_sales,
+    COUNT(*) AS order_count
+    FROM orders
+    GROUP BY date_trunc('day', order_date), region


Can we just have one example? I think it's clear that there's a default value if none are provided, and that the value can be parameterized.

@tdcmeehan Updated to provide only one example. Please check

steveburnett

Thank you for the documentation! A couple of nits.

presto-docs/src/main/sphinx/admin/materialized-views.rst

presto-docs/src/main/sphinx/sql/create-materialized-view.rst

github-actions · 2026-04-01T09:05:17Z

Codenotify: Notifying subscribers in CODENOTIFY files for diff 52ad58a...c99d493.

No notifications.

steveburnett

Thanks for the update! Just one question.

presto-docs/src/main/sphinx/sql/create-materialized-view.rst

steveburnett

Thanks for the update! Just a nit of phrasing.

hantangwangd

Thanks @bibith4, lgtm!

steveburnett

LGTM! (docs)

Pull updated branch, new local doc build, looks good. Thank you!

prestodb-ci added the from:IBM PR from IBM label Mar 30, 2026

github-actions bot added the docs label Mar 30, 2026

github-project-automation bot added this to Presto Documentation Mar 30, 2026

github-project-automation bot moved this to 🆕 Unprioritized in Presto Documentation Mar 30, 2026

bibith4 requested a review from tdcmeehan March 30, 2026 09:45

bibith4 marked this pull request as ready for review March 30, 2026 09:45

bibith4 requested review from a team, elharo and steveburnett as code owners March 30, 2026 09:45

prestodb-ci requested review from a team, Joe-Abraham and anees-kt and removed request for a team March 30, 2026 09:45

sourcery-ai bot reviewed Mar 30, 2026

View reviewed changes

bibith4 changed the title ~~Add more details to the materialized view documentation.~~ docs: Add more details to the materialized view documentation. Mar 30, 2026

bibith4 changed the title ~~docs: Add more details to the materialized view documentation.~~ docs: Add more details to the materialized view documentation Mar 30, 2026

tdcmeehan requested changes Mar 30, 2026

View reviewed changes

github-project-automation bot moved this from 🆕 Unprioritized to 🏗 In progress in Presto Documentation Mar 30, 2026

steveburnett requested changes Mar 30, 2026

View reviewed changes

presto-docs/src/main/sphinx/admin/materialized-views.rst Outdated Show resolved Hide resolved

presto-docs/src/main/sphinx/sql/create-materialized-view.rst Outdated Show resolved Hide resolved

bibith4 requested review from a team, ZacBlanco, czentgr, feilong-liu, hantangwangd, jaystarshot, unidevel and yhwang as code owners April 1, 2026 09:04

github-actions bot removed the docs label Apr 1, 2026

bibith4 force-pushed the mv_document branch from 0efb38f to 2052fb0 Compare April 1, 2026 09:17

github-actions bot added the docs label Apr 1, 2026

bibith4 force-pushed the mv_document branch from 2052fb0 to 2c270a3 Compare April 1, 2026 09:27

bibith4 requested review from steveburnett and tdcmeehan April 1, 2026 09:34

steveburnett reviewed Apr 1, 2026

View reviewed changes

presto-docs/src/main/sphinx/sql/create-materialized-view.rst Outdated Show resolved Hide resolved

bibith4 requested a review from steveburnett April 2, 2026 05:26

bibith4 force-pushed the mv_document branch from 2c270a3 to e919ac8 Compare April 2, 2026 16:22

steveburnett reviewed Apr 2, 2026

View reviewed changes

presto-docs/src/main/sphinx/sql/create-materialized-view.rst Outdated Show resolved Hide resolved

steveburnett requested changes Apr 2, 2026

View reviewed changes

Add more details to the materialized view documentation.

c99d493

bibith4 force-pushed the mv_document branch from e919ac8 to c99d493 Compare April 3, 2026 06:58

bibith4 requested a review from steveburnett April 3, 2026 07:04

hantangwangd approved these changes Apr 3, 2026

View reviewed changes

steveburnett approved these changes Apr 3, 2026

View reviewed changes

		SET SESSION materialized_view_skip_storage = 'USE_STITCHING';


		Behavior Summary

Conversation

bibith4 commented Mar 30, 2026 • edited by sourcery-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Impact

Test Plan

Contributor checklist

Release Notes

Summary by Sourcery

Uh oh!

sourcery-ai bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

tdcmeehan Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

tdcmeehan Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

bibith4 Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

tdcmeehan Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

bibith4 Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

steveburnett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steveburnett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

steveburnett left a comment

Choose a reason for hiding this comment

Uh oh!

hantangwangd left a comment

Choose a reason for hiding this comment

Uh oh!

steveburnett left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bibith4 commented Mar 30, 2026 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Mar 30, 2026 •

edited

Loading

github-actions bot commented Apr 1, 2026 •

edited

Loading