Altermv tutorial#34854
Conversation
| things like querying materialized views from different clusters, indexed vs. | ||
| non-indexed, and so on." | ||
|
|
||
| {{< if-released "v26.10" >}} |
There was a problem hiding this comment.
| FROM highest_bid_per_auction | ||
| WHERE end_time < mz_now(); | ||
| ``` | ||
| {{% include-example file="examples/create_materialized_view" example="example-create-materialized-view" %}} |
There was a problem hiding this comment.
I replaced this with the example from quickstart (with the modification of creating a view -> creating a materialized view).
|
|
||
| ## Details | ||
|
|
||
| ### Replacing a materialized view |
There was a problem hiding this comment.
| - name: "syntax-apply-replacement" | ||
| code: | | ||
| ALTER MATERIALIZED VIEW <name> APPLY REPLACEMENT <replacement_name>; | ||
| ALTER MATERIALIZED VIEW <name> APPLY REPLACEMENT <replacement_view>; |
There was a problem hiding this comment.
changed to view ... in case people thought we were renaming.
There was a problem hiding this comment.
how would you feel about us making it replacement_materialized_view to make this more clear?
| the target materialized view. See [`CREATE REPLACEMENT MATERIALIZED VIEW | ||
| <replacement_view>...FOR <name>...`](/sql/create-materialized-view). | ||
|
|
||
| - name: "example-apply-replacement" |
There was a problem hiding this comment.
| Materialize supports a two-step process for replacing materialized views | ||
| in-place, i.e., without recreating downstream objects: | ||
|
|
||
| 1. **Create a replacement**: Use `CREATE REPLACEMENT MATERIALIZED VIEW` to |
There was a problem hiding this comment.
since there's the guide being written, I condensed this.
https://preview.materialize.com/materialize/34854/sql/create-materialized-view/#use-case
| #### Restrictions | ||
| #### Query performance of replacement views | ||
|
|
||
| - The replacement must have the same schema as the target materialized view: |
There was a problem hiding this comment.
I incorporated this not quite as a restriction ... but more on how to run the command
| --- | ||
| You cannot run `ALTER MATERIALIZED VIEW ... APPLY REPLACEMENT` command within a | ||
| transaction block. Instead, the `ALTER MATERIALIZED VIEW ... APPLY REPLACEMENT` | ||
| command must be run outside of an explicit transaction. |
There was a problem hiding this comment.
Oh ... actually, given that we only allow:
- read-only transactions (for SELECT only txn or SUBSCRIBE-based txns)
- insert-only transactions
We might not actually need this .. because the list of things we don't allow in a transaction block is everything but the aforementioned bullet points.
| ``` | ||
|
|
||
| If the target view is behind, it is recommended to drop the replacement | ||
| view instead of having it run for an extended period, buffering |
There was a problem hiding this comment.
Q: Is this something people can gauge by how far behind the target is? or is it just people check again after some time and see that it is still behind?
Q: Can people reduce the likelihood of the target being behind by applying the replacement view soon after it hydrates?
There was a problem hiding this comment.
Is this something people can gauge by how far behind the target is? or is it just people check again after some time and see that it is still behind?
Kind of. The write frontier is a timestamp and can be interpreted as the time up to which the target MV has processed its outputs. You can subtract that time from the current time to get the "wallclock lag", or look it up in the wallclock lag relations directly. But if the MV is stuck, it doesn't really tell you how long you have to wait (might be forever). Better to look at the frontier several times and check if the write frontier is catching up (i.e. it advances by more than one second per second).
Can people reduce the likelihood of the target being behind by applying the replacement view soon after it hydrates?
I don't think so. That would imply that the replacement running somehow makes the target unhealthy. They are independent dataflows, so the only way the replacement could influence the target is when they run on the same cluster and the running replacement pushes the cluster over the edge. But if that's the case, then hydrating the replacement (which is generally more compute intensive than steady state) would have already overloaded the cluster and would have made the target fall behind, so you wouldn't have been able to apply the replacement immediately after hydration either.
| If the replacement view is ahead of the target view, both the command and | ||
| the replacement view wait for the target view to catch up. During this | ||
| wait, the replacement view buffers any changes it receives from its | ||
| inputs, which, depending on the amount to buffer, could cause the cluster |
There was a problem hiding this comment.
Q: If someone runs the command before checking and it hangs, should we tell people to break out of it?
There was a problem hiding this comment.
- I would personally add this in a guidelines section below the bullet points. Adding a note here feels confusing as a reader - but feel free to discard the opinion.
FWIW here's how I would re-write this if we were to move it lower:
To successfully replace a materialized view, the original and the replacement materialized view need to both be up to date. If the original is lagging behind, the ALTER MATERIALIZED VIEW ... APPLY REPLACEMENT command will pause until the original has caught up. If it takes too long for the original to catch up, the cluster might run out of memory. It is recommended to first check whether the original materialized view is up to date with the replacement. If the ALTER MATERIALIZED VIEW ... APPLY REPLACEMENT command does not execute successfully, we recommend canceling it to prevent out of memory errors.
doc/user/content/headless/replacement-views/replacement-view-index-restrictions.md
Outdated
Show resolved
Hide resolved
| Before applying the replacement view: | ||
|
|
||
| - Verify that the replacement view is hydrated to replace without downtime. | ||
| - Verify that the target materialized view results are not behind the |
There was a problem hiding this comment.
Nit: I'd use the word original rather than target here. And I'd frame this as : verify that the original and replacement materialized views are up to date.
There was a problem hiding this comment.
Went with original.
As for the framing ... for now, went with the not behind ... because everything else was more talking about one catching up to another.
There was a problem hiding this comment.
Ah ... just seeing your reframing. Will incorporate.
|
|
||
| The replacement view hydrates in the background. | ||
|
|
||
| #### Apply the replacement |
There was a problem hiding this comment.
I like re-using the content! But re-using it does make this section feel like it has been accidentally copy pasted
There was a problem hiding this comment.
Heh ... reused the wrong shared content :D
|
@kay-kim once Jan replies, feel free to incorporate whichever changes you feel strongly about and then feel free to merge this into my branch so we get unblocked |
This reverts commit 2d89321.
|
Will revert the fake release of v26.10 and merge. |
3 participants
Wanted to get a pulse on the changes before tweaking the guide a bit.
For ease of review, added a patch to fake the release of v26.10 (2d89321) which will be reverted before merging [hence, converted to draft]