Skip to content

Convert mz_materialized_view_refresh_strategies to a builtin mv - #39597

Merged
SangJunBak merged 4 commits into
jun/sql-701/history-retentionfrom
jun/sql-702/mv-refresh-strat
Oct 14, 2026
Merged

SangJunBak merged 4 commits into
jun/sql-701/history-retentionfrom
jun/sql-702/mv-refresh-strat

Conversation

@SangJunBak

Copy link
Copy Markdown
Contributor
  • Converts mz_materialized_view_refresh_strategies to a builtin materialized view. Read commit messages for more details
  • We also change the columns aligned_at and at from timestamptz to string values.

Motivation

Closes SQL-701

Verification

  • Diffed this relation using a customer's workload replay against main and this branch
  • A lot of the "introspection" test cases in materialized_views.slt assert mz_materialized_view_refresh_strategies already. Added a retraction test case

@SangJunBak
SangJunBak added this pull request to stack #38849 October 6, 2026 18:43
@SangJunBak
SangJunBak requested review from a team as code owners October 6, 2026 18:43
@SangJunBak
SangJunBak requested a review from leedqin October 6, 2026 18:43
@linear-code

linear-code Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

SQL-701

SQL-702

@SangJunBak
SangJunBak requested review from ggevay and removed request for a team October 6, 2026 18:44
@SangJunBak

SangJunBak commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor Author

@ggevay Added you as a reviewer since you seemed like the best to review it! I know we discussed evaluating the expression in a sql function but it gets trickier since we can also have expressions that evaluate functions (e.g. greatest(). Talked to @aljoscha offline and decided the simplest thing we could do is replace it with an expression, something borrowed from on_expression in MZ_INDEX_COLUMNS.

@SangJunBak
SangJunBak removed the request for review from leedqin October 6, 2026 18:46

@ggevay ggevay left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM. The description should say Closes SQL-702 (SQL-701 is #39473's issue).

DROP MATERIALIZED VIEW mv_retract

query I
SELECT count(*) FROM mz_internal.mz_materialized_view_refresh_strategies WHERE materialized_view_id LIKE 'u%'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

These counts only look at user views, so no PR-CI test checks the rows of the new builtin_strategies branch: catalog_server_explain.slt only pins its plan, and test/cluster's check_introspection runs only in Nightly. Dropping that branch, or losing a single builtin row, still passes this file. mz_history_retention_strategies.slt already has the same check for its relation. This version passes on the PR's CI image and fails when flipped to 1:

# Every materialized view, builtin or user, has a refresh strategy row.
query I
SELECT count(*)
FROM mz_catalog.mz_materialized_views mv
FULL OUTER JOIN mz_internal.mz_materialized_view_refresh_strategies rs ON mv.id = rs.materialized_view_id
WHERE mv.id IS NULL OR rs.materialized_view_id IS NULL
----
0


/// Rejects times that `mz_materialized_view_refresh_strategies` could not pack as a
/// `timestamptz`, whose range is far smaller than `mz_timestamp`'s.
/// Rejects times that are too large.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit: the deleted packer was why this check was added, but the bound still matters. With replica expiration on, compute rounds a dataflow's expiration up to the next refresh and logs it through mz_ore::now::to_datetime (compute_state.rs:811), which panics past chrono's range, the same range this check enforces. So it keeps REFRESH AT times out of that panic. Could the doc say so? The comment at materialized_views.slt:765 ("which is how these get packed") is stale too.

Comment on lines +538 to +539
// - aligned_at (timestamptz) -> aligned_to_expression (text)
// - at (timestamptz)-> at_expression (text)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit: aligned_at should be aligned_to (also in the description).

Suggested change
// - aligned_at (timestamptz) -> aligned_to_expression (text)
// - at (timestamptz)-> at_expression (text)
// - aligned_to (timestamptz) -> aligned_to_expression (text)
// - at (timestamptz) -> at_expression (text)

@SangJunBak
SangJunBak force-pushed the jun/sql-702/mv-refresh-strat branch from ea833b7 to 1a4d69a Compare October 9, 2026 15:29
@SangJunBak
SangJunBak force-pushed the jun/sql-702/mv-refresh-strat branch from 1a4d69a to 5330841 Compare October 9, 2026 15:34
@def-

def- commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

QA LLM Review

1. MEDIUM -- In-place upgrade from any pre-merge dev build crash-loops environmentd

src/catalog/src/builtin/mz_internal.rs:472

Retyping aligned_to/at (timestamptz) into aligned_to_expression/at_expression (text) makes this the first table-to-MV conversion whose RelationDesc cannot be evolved. The conversion keeps the table's shard, and when the source version is a dev build the 26.47.0-dev.0 replacement step never runs. Any environment last opened by a pre-merge main build therefore aborts at boot on every restart once it picks up this change, while release-to-release upgrades still work.

Details

Reproduced with docker, keeping the same /mzdata volume each time:

  • v26.47.0-dev.0--main.g8cded2ee76 (current main) to this PR's image: skipping migration: already at target version (builtin_schema_migration.rs:845), then thread 'coordinator' panicked at src/adapter/src/util.rs:268: cannot fail to evolve collections: PersistInvalidSchemaEvolve { global_id: System(551) }. In that build, s551 is mz_materialized_view_refresh_strategies. Exit code 134, every restart.
  • v26.46.0-dev.0 main to this PR's image: the dev-source branch at builtin_schema_migration.rs:828 forces Evolution for everything and ignores the replacement step at :544. Boot dies with fatal: cannot migrate builtin schemas ... incompatible schema evolution for ... mz_materialized_view_refresh_strategies.
  • v26.45.1 to this PR's image: the replacement step fires and the upgrade works.

The earlier conversions (mz_object_global_ids, mz_object_dependencies, mz_source_references, mz_replacements, mz_history_retention_strategies) all kept an evolvable desc, so they survived these paths. The underlying gap in the migration gates is already tracked in Linear SQL-663. This PR is a new, deterministic trigger for it, and it hits any deployment that runs main builds.

There are three ways out. Keep the desc evolvable, for example by leaving the old columns in place and appending the text columns as new nullable trailing columns. Land a fix for the same-version and forced dev paths before this PR. Or have the conversion allocate a fresh shard when the desc is incompatible, instead of carrying the table's mapping over.

@ggevay

ggevay commented Oct 10, 2026

Copy link
Copy Markdown
Contributor

In-place upgrade from any pre-merge dev build crash-loops environmentd

As mentioned above, this is an instance of
https://linear.app/materializeinc/issue/SQL-663/dev-to-dev-upgrades-at-the-same-version-skip-all-builtin-schema
(or https://linear.app/materializeinc/issue/SQL-652/upgrades-from-dev-versions-skip-replacement-steps-0dt-preflight-stalls). This seems hard to avoid here, so I'm leaning towards simply accepting this. Dev versions are not officially supported, obviously. It's nice when they happen to work, but it's not worth much effort to make them work. But maybe a slack msg to #team-database would be good (mentioning the error msg), so that people won't get surprised and go debugging. E.g.:

Heads-up: dev builds from before #39597 won't boot on any later dev build that includes it, since it changes two column types of mz_materialized_view_refresh_strategies. Releases are unaffected. If your staging or local environment crash-loops with cannot fail to evolve collections: PersistInvalidSchemaEvolve or cannot migrate builtin schemas from version ...: incompatible schema evolution, recreate it.

Btw. fixing the underlying issues seems not too hard (but also not urgent), see https://linear.app/materializeinc/issue/SQL-663/dev-to-dev-upgrades-at-the-same-version-skip-all-builtin-schema#comment-f76ac321

@SangJunBak
SangJunBak force-pushed the jun/sql-702/mv-refresh-strat branch from 5330841 to 8bdffff Compare October 13, 2026 17:38
For materialized views, we parse the REFRESH values from it such that we can populate `mz_materialized_view_refresh_strategies` in the future. We take the full stable ast string, meaning we don't evaluate expressions stored in the `create_sql` of a statement. This is because we would need the planner and optimizer to evaluate it, something too heavyweight for a SQL function.

The consequence of this is we can't reliably report back timestamptz values `mz_materialized_view_refresh_strategies` and return back the full expression string instead. Given we'll be deprecating this feature in the future and `mz_materialized_view_refresh_strategies`'s schema isn't stable, this is acceptable.
…a materialized view

We use parse_catalog_create_sql to get the refresh strategy information from the previous commit.
@SangJunBak
SangJunBak force-pushed the jun/sql-702/mv-refresh-strat branch from 8bdffff to 2321960 Compare October 14, 2026 08:57
@SangJunBak
SangJunBak merged commit 0037556 into main Oct 14, 2026
94 checks passed
@SangJunBak
SangJunBak deleted the jun/sql-702/mv-refresh-strat branch October 14, 2026 10:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants