Commit 1b91fd4
docs: Complete the scoped freshness CCDF query (#38378)
### Motivation
On [How to monitor
freshness](https://materialize.com/docs/transform-data/monitor-freshness/#summarize-freshness-with-a-ccdf),
the last code block in the "Summarize freshness with a CCDF" section is
incomplete. It shows only the middle of the statement (the object-name
placeholder below is spelled `MV_NAME` here, and appears in the page as
that name wrapped in angle brackets):
```mzsql
FROM mz_internal.mz_wallclock_global_lag_recent_history wl
JOIN mz_catalog.mz_objects o ON wl.object_id = o.id
WHERE o.name = 'MV_NAME'
AND wl.lag IS NOT NULL
AND wl.lag > INTERVAL '0'
```
It starts mid-statement at `FROM`, drops the `SELECT extract(epoch FROM
wl.lag) AS lag_seconds` line that the `FROM` belongs to, and has no
enclosing `WITH lags AS (`, no `thresholds` CTE, and no outer
aggregation. Running it verbatim fails:
```
ERROR: Unexpected keyword FROM at the beginning of a statement
LINE 1: FROM mz_internal.mz_wallclock_global_lag_recent_history wl
^
```
A reader has to reassemble the statement by hand from the aggregate
query further up the page. Every other code block on this page is a
complete, runnable statement, so this one is the odd one out.
### Description
Show the whole statement in the block, so it can be copied and run
directly, and reword the lead-in sentence so it describes the query that
follows rather than reading as a patch instruction ("add a join ... to
the `lags` CTE" becomes "join `mz_catalog.mz_objects` in the `lags` CTE
and filter on the object name").
The SQL is unchanged from what the fragment implied: the `lags` CTE
gains the join to `mz_catalog.mz_objects` and the object-name filter,
and the rest of the query matches the aggregate version above it.
`mz_wallclock_global_lag_recent_history.object_id` is documented as
corresponding to `mz_objects.id`, so the join key is correct. The
placeholder in the page is left exactly as it was.
### Verification
Manual, against a local `environmentd` built from this branch with a
materialized view producing wallclock lag history.
- The block as it appears on the published page fails with `ERROR:
Unexpected keyword FROM at the beginning of a statement` (exit 3).
- The block extracted programmatically from the edited markdown runs
clean and returns the three-row shape the surrounding prose describes:
```
lag_threshold_seconds | fraction_of_time_at_or_above
-----------------------+------------------------------
1 | 1
10 | 0
100 | 0
(3 rows)
```
- Re-ran the page's other two `mzsql` blocks (the per-object lag history
query and the aggregate CCDF) to confirm they were already complete and
still run clean.
Docs-only change, so no automated tests were added or modified.
### Release notes
No release note. This is a documentation-only fix with no user-visible
product change.
Co-authored-by: Claude <noreply@anthropic.com>1 parent f9be4ed commit 1b91fd4
1 file changed
Lines changed: 18 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
128 | 128 | | |
129 | 129 | | |
130 | 130 | | |
131 | | - | |
132 | | - | |
| 131 | + | |
| 132 | + | |
133 | 133 | | |
134 | 134 | | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
135 | 139 | | |
136 | 140 | | |
137 | 141 | | |
138 | 142 | | |
139 | 143 | | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
140 | 156 | | |
141 | 157 | | |
142 | 158 | | |
| |||
0 commit comments