Skip to content

docs: Complete the scoped freshness CCDF query - #38378

Merged
maheshwarip merged 1 commit into
mainfrom
claude/materialize-freshness-code-block-tcf8dx
Aug 21, 2026
Merged

docs: Complete the scoped freshness CCDF query#38378
maheshwarip merged 1 commit into
mainfrom
claude/materialize-freshness-code-block-tcf8dx

Conversation

@maheshwarip

@maheshwarip maheshwarip commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Motivation

On How to monitor freshness, 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):

    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.

The "Summarize freshness with a CCDF" section showed the per-object
variant as a bare fragment starting at `FROM`, with no `SELECT`, no
enclosing `lags` CTE, and no outer aggregation. Pasting it into psql
fails with "Unexpected keyword FROM at the beginning of a statement",
so a reader had to reassemble the statement by hand from the aggregate
query above it.

Show the whole statement instead, matching every other code block on the
page, and reword the lead-in so it describes the query rather than
reading as a patch instruction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H48CHtCVFAmZ3L6JHJeTWB
@maheshwarip
maheshwarip requested a review from a team as a code owner August 20, 2026 21:00
@maheshwarip
maheshwarip enabled auto-merge (squash) August 21, 2026 14:12
@maheshwarip

Copy link
Copy Markdown
Contributor Author

@sjwiesman could I get a quick 👍🏾 on this one?

@maheshwarip
maheshwarip merged commit 1b91fd4 into main Aug 21, 2026
12 checks passed
@maheshwarip
maheshwarip deleted the claude/materialize-freshness-code-block-tcf8dx branch August 21, 2026 17:56
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