Skip to content

[fix](doc) median.md: add missing setup in EN; align Example 2 SQL with its result#3787

Merged
morningman merged 2 commits into
apache:masterfrom
boluor:fix/median-md-setup-and-example2
May 28, 2026
Merged

[fix](doc) median.md: add missing setup in EN; align Example 2 SQL with its result#3787
morningman merged 2 commits into
apache:masterfrom
boluor:fix/median-md-setup-and-example2

Conversation

@boluor

@boluor boluor commented May 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Two fixes to sql-manual/sql-functions/aggregate-functions/median.md, both found by running every example on a real Doris 4.1.1 cluster.

Fix 1 — EN page is missing the setup block

The EN page jumps straight to SELECT … FROM log_statis … without first creating the table or inserting fixture rows, so every example fails with Table [log_statis] does not exist if a reader copy-pastes them. The ZH version already has the setup block. This PR brings the EN page in line — same CREATE TABLE + INSERT content, no other changes.

Fix 2 — Example 2 SQL doesn't match its result block (EN + ZH)

The second example on both pages had:

  • SQL block: SELECT median(scan_rows) FROM log_statis GROUP BY datetime;
  • Result block: first line was the literal select median(scan_rows) from log_statis where scan_rows is null; (a captured command echo from mysql CLI), followed by a single NULL row.

So the result is actually the output of WHERE scan_rows IS NULL, not GROUP BY datetime — the SQL block was pasted from a different query by mistake.

Aligned the SQL block to match the result (the WHERE form). Two reasons that direction over the other:

  1. The result body (single NULL row) is what WHERE scan_rows IS NULL returns; the GROUP BY datetime form returns two median rows on the fixture data.
  2. Demonstrates the Description's note that median returns NULL when the group has no valid data.

A reader can now copy-paste Example 2 and reproduce the documented output.

Verification on Apache Doris 4.1.1

With the setup block applied:

-- Example 1
SELECT datetime, median(scan_rows) FROM log_statis GROUP BY datetime;
-- → (2025-08-25 10:00 → 50.0), (2025-08-25 11:00 → 30.0)   ✓

-- Example 2 (after this fix)
SELECT median(scan_rows) FROM log_statis WHERE scan_rows IS NULL;
-- → NULL   ✓

Changes

  • versioned_docs/version-4.x/sql-manual/sql-functions/aggregate-functions/median.md — add setup block (+16); fix Example 2 SQL (1 line)
  • i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/aggregate-functions/median.md — fix Example 2 SQL (1 line)

Total: 2 files, +17 / -1 lines, split into 2 logically-distinct commits for review.

Detection

Discovered by running median.md examples on a single-BE Apache Doris 4.1.1 cluster as part of a broader docs-vs-implementation verification effort. The same effort already produced doris-website#3781 (merged) and doris-website#3786 (open).

boluor added 2 commits May 26, 2026 02:32
The EN page jumps straight to `SELECT … FROM log_statis …` without first
creating the table or inserting the fixture rows, so every example fails
with `Table [log_statis] does not exist` when a reader copy-pastes them.

The ZH version of the same page already contains the setup block. This
PR just brings the EN page in line with it — same CREATE TABLE + INSERT,
no other changes.

Verified on Apache Doris 4.1.1: with the setup block applied, the
existing Example 1 SELECT produces exactly the result shown in the doc
(median = 50 for the 10:00 group, median = 30 for the 11:00 group).

Note: Example 2 on this page has a separate inconsistency between its
SQL block (`SELECT median(scan_rows) FROM log_statis GROUP BY datetime`)
and its expected-output block (which appears to be the output of
`WHERE scan_rows IS NULL` instead). That looks like a paste mix-up but
could be intentional in either direction, so this PR leaves it untouched
— it deserves a separate discussion with the original author.
The second example on both EN and ZH pages had:

- SQL block:  `SELECT median(scan_rows) FROM log_statis GROUP BY datetime;`
- result block first line:  `select median(scan_rows) from log_statis where scan_rows is null;`
- result body:  a single NULL row

The result was the captured output of the `WHERE scan_rows IS NULL`
query (including the leading command echo from mysql CLI), so the SQL
block above it must have been pasted from a different query by mistake.

Two ways to fix this; the WHERE version is the one the result block
actually demonstrates and it matches the Description's note that
median returns NULL when the group has no valid data. Aligning the SQL
to the result also lets a reader copy-paste the example and reproduce
the documented NULL.

Verified on Apache Doris 4.1.1:
- SELECT median(scan_rows) FROM log_statis WHERE scan_rows IS NULL  →  NULL ✓
@morningman morningman merged commit ae3beda into apache:master May 28, 2026
3 checks passed
@boluor boluor deleted the fix/median-md-setup-and-example2 branch May 30, 2026 08: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.

2 participants