[docs] Document ORDER BY and LIMIT support in UPDATE and DELETE statements

[morrySnow]

Summary

Add documentation for the ORDER BY and LIMIT clauses in UPDATE and DELETE statements, as introduced by apache/doris#61681.

Changes

Updated 8 documentation files across dev (current) and 4.x versions, both English and Chinese:

• Syntax: Added [ORDER BY column [ASC | DESC] [NULLS FIRST | NULLS LAST] [, ...]] and [LIMIT [offset,] count] clauses to UPDATE and DELETE syntax blocks
• Parameters: Added descriptions for ORDER BY and LIMIT optional parameters
• Examples: Added usage examples demonstrating ORDER BY + LIMIT and ORDER BY + LIMIT with offset
• Version tags: Added :::tip Supported since version 4.1.0. ::: in 4.x versioned docs only

Files Modified

Version	Language	File
dev	EN	docs/.../DML/UPDATE.md
dev	EN	docs/.../DML/DELETE.md
4.x	EN	versioned_docs/version-4.x/.../DML/UPDATE.md
4.x	EN	versioned_docs/version-4.x/.../DML/DELETE.md
dev	ZH	i18n/zh-CN/.../current/.../DML/UPDATE.md
dev	ZH	i18n/zh-CN/.../current/.../DML/DELETE.md
4.x	ZH	i18n/zh-CN/.../version-4.x/.../DML/UPDATE.md
4.x	ZH	i18n/zh-CN/.../version-4.x/.../DML/DELETE.md

Related PR

• [feature](fe) Support ORDER BY and LIMIT clauses for UPDATE and DELETE commands doris#61681

[morrySnow]

run buildall

[morrySnow]

/review

[github-actions]

Code Review Summary

This PR adds documentation for ORDER BY and LIMIT support in UPDATE and DELETE statements, as introduced in Apache Doris 4.1.0. It correctly updates 8 files across dev (current) and 4.x versions, in both English and Chinese.

Critical Checkpoint Conclusions

Goal / Implementation
The goal is to document the new ORDER BY and LIMIT clause support in UPDATE and DELETE. The syntax, parameter descriptions, version tip, and examples are all present. The implementation satisfies the stated goal with two issues noted below.

Scope and Focus
Changes are appropriately targeted — only the affected DML docs are modified, with no unrelated reformatting.

Information Architecture
All 8 affected files across docs/, versioned_docs/version-4.x/, and the mirrored i18n/zh-CN/ trees are updated consistently. 3.x and older versions are intentionally not updated since the feature requires 4.1.0+, which is correct.

Version tip placement
The :::tip version note appears in the 4.x versioned docs (EN and ZH) but is absent from the dev/current docs. This is acceptable — dev docs represent the latest unreleased version and typically do not need version introduction notes. The pattern is appropriate.

Sidebar, slugs, and navigation
No pages are added, renamed, or removed. No sidebar or navigation changes are needed. ✓

Frontend / build safety
Pure documentation changes, no component or config changes. ✓

Issues Found

Issue 1 (all 8 files): DELETE examples omit WHERE clause, contradicting the required syntax

In DELETE Syntax 2, WHERE condition has no square brackets, making it required. However, both new examples (6 and 7) omit the WHERE clause:

DELETE FROM my_table ORDER BY k1 ASC LIMIT 3;
DELETE FROM my_table ORDER BY k1 ASC LIMIT 10, 5;

This creates a contradiction with the documented syntax and will confuse users. Either:

• The WHERE clause is actually optional when ORDER BY + LIMIT is used (in which case the syntax block should be updated to add brackets around WHERE condition), or
• The examples are incorrect and should include a WHERE clause.

This same issue exists in all 4 DELETE files (docs/EN, docs/ZH-current, versioned-4.x/EN, versioned-4.x/ZH).

Issue 2 (UPDATE docs, all 4 files): Code block indentation inconsistency

In UPDATE.md, existing examples 1–4 use no indentation for their numbered list items and code blocks (they are at the top level). The new examples 5 and 6 follow the same no-indentation pattern, which is consistent within UPDATE.md.

However, in DELETE.md, existing examples 1–5 use 3-space indentation for list items and code blocks. The new DELETE examples 6 and 7 correctly follow that indented pattern. No issue here — just noting it is consistent.

Issue 3 (minor): ORDER BY parameter description implies it requires LIMIT

The description "Used together with LIMIT to control which rows are affected" suggests ORDER BY requires LIMIT. But the syntax shows both as independently optional ([ORDER BY ...] and [LIMIT ...]). A user may wonder: can ORDER BY be used without LIMIT? If ORDER BY without LIMIT is allowed (e.g., for deterministic behavior), the description should say "Typically used together with LIMIT" or similar. If ORDER BY is meaningless without LIMIT, the syntax block should group them accordingly (e.g., [ORDER BY ... [LIMIT ...]]).

Recommendation

The main blocker is Issue 1 — the DELETE examples without WHERE contradict the stated required syntax. Please either add WHERE clauses to the examples or update the syntax block to mark WHERE condition as optional (with brackets) when ORDER BY/LIMIT is used.

[morrySnow]

/review

[morrySnow]

run buildall

[github-actions]

Code Review Summary — PR #3495

Goal

Document the ORDER BY and LIMIT clause support added to UPDATE and DELETE statements in Apache Doris 4.1.0. The PR updates 8 files across dev/4.x versions and EN/ZH locales.

---

Critical Checkpoint Conclusions

1. Goal vs. Implementation
The goal is clearly satisfied: syntax blocks, parameter tables, examples, and version tip callouts are all present. The structural content is accurate and well-organized.

2. Scope / Focus
Changes are appropriately scoped. No unrelated content is touched.

3. Documentation Information Architecture
All 8 expected files are updated: docs/ (EN current), versioned_docs/version-4.x/ (EN 4.x), and both i18n/zh-CN/ mirrors. No files are missing. Sidebar and config files are unaffected (no new pages, just in-place edits).

4. Link, Redirect, and Navigation References
No page moves, renames, or slug changes. No cross-links introduced. No issues.

5. Docusaurus Config / React / Styling
Not applicable — documentation-only changes.

---

Issues Found

Issue 1 (Medium) — WHERE condition is still listed under #### Required Parameters in DELETE docs after being made optional

In all four DELETE.md files (dev EN, dev ZH, 4.x EN, 4.x ZH), the syntax block now shows [WHERE condition] (optional), but the #### Required Parameters section still lists:

+ WHERE condition: Specifies a condition to use to select rows for removal

This is a direct contradiction. WHERE condition for Syntax 2 is now optional and should be moved into the #### Optional Parameters section.

Note: UPDATE.md does not have this problem — WHERE condition was already only in Required Parameters as where condition: text (which is a pre-existing minor issue), but it is not explicitly listed as a + WHERE condition: bullet there.

Issue 2 (Medium) — No safety note about omitting WHERE

Making WHERE optional in both UPDATE and DELETE Syntax 2 is a significant behavioral change: without any WHERE, ORDER BY, or LIMIT, a DELETE FROM my_table would delete all rows. The docs should include a note or warning about this risk — for example:

Note: When neither WHERE nor LIMIT is specified, the statement affects all qualifying rows. Always double-check the intended scope before omitting the WHERE clause.

This is especially important for DELETE, where the operation is irreversible.

Issue 3 (Minor) — Version tip missing from dev/current docs

The :::tip callout (ORDER BY and LIMIT ... supported since version 4.1.0) is present in the version-4.x docs (both EN and ZH) but absent from the dev/current docs. For readers browsing the latest (current) docs, there is no indication of when this feature was introduced. Consider adding a version note to the current docs as well (e.g., Supported since version 4.1.0).

Issue 4 (Minor) — ORDER BY constraint not stated: UNIQUE KEY model only

Syntax 2 (the one with ORDER BY / LIMIT) is explicitly scoped to the UNIQUE KEY model (Syntax 2: This syntax can only used on UNIQUE KEY model). However, the new ORDER BY column and LIMIT parameter descriptions do not repeat this constraint. A user who jumps directly to the Optional Parameters section may not realize that these clauses only apply to the UNIQUE KEY model. A brief note like "(Syntax 2 / UNIQUE KEY model only)" would help.

Issue 5 (Minor) — LIMIT without ORDER BY semantics unspecified

The description says ORDER BY is "typically used together with LIMIT", implying LIMIT may be used alone. However, whether LIMIT without ORDER BY is supported, and whether such a result is deterministic, is not documented. If LIMIT alone is supported, a note on ordering guarantees (or lack thereof) would prevent user confusion.

---

Positive Observations

• Syntax notation is consistent and correct ([optional] brackets, ASC | DESC, NULLS FIRST | NULLS LAST).
• Examples are self-contained and illustrate both the basic and offset-form of LIMIT.
• Chinese and English content are faithfully translated with no semantic divergence.
• Version tip callouts in 4.x docs are correctly formatted and placed.
• The :::tip for the 4.x docs is placed immediately after the parameter descriptions, which is a good location.

[morrySnow]

run buildall

[morrySnow]

/review

[github-actions]

Code Review Summary — PR #3495

Goal: Document ORDER BY and LIMIT support in UPDATE and DELETE statements, introduced in Apache Doris 4.1.0.

---

Critical Checkpoint Conclusions

1. Does the implementation satisfy the goal?
Yes, mostly. The syntax blocks, parameter descriptions, safety notes, and examples are all added correctly across all 8 files (dev + 4.x, EN + ZH). The core intent is fulfilled.

2. Is the change small, clear, and focused?
Yes. The change is tightly scoped to 4 syntax documents across 2 versions and 2 locales.

3. Does it preserve documentation information architecture correctly?
All 8 expected files (dev EN, dev ZH, 4.x EN, 4.x ZH — for both DELETE and UPDATE) are updated. No files are missing from the matrix.

4. Are links, redirects, and navigation references consistent?
No path/slug/sidebar changes. No broken links introduced. N/A for this PR.

5. Does it match existing conventions and avoid breaking behavior?
Mostly yes. However, there are two structural issues noted below:

• The :::tip version callout (indicating the feature is supported since 4.1.0) is present in the versioned_docs/version-4.x and i18n/zh-CN/version-4.x files, but missing from the docs/ (dev) and i18n/zh-CN/current/ equivalents. The dev docs should also note when this feature was introduced, so users can know the minimum version requirement. This is inconsistent across the 4 dev-stream files.
• The new examples (ORDER BY + LIMIT) do not include expected output blocks. Per the SQL function documentation standard in AGENTS.md, "Each query must be followed by its expected output in a fenced text block." This applies to all 8 files.

6. What validation covers the change?
Documentation-only change; no build/runtime test is applicable. Validation is by manual review of content and cross-file consistency. The content is factually consistent with the referenced upstream PR.

7. Other correctness, usability, accessibility, SEO, or maintainability issues?

• Accuracy concern (DELETE safety note): The new note 6 in DELETE states: "When neither WHERE nor LIMIT is specified in Syntax 2, all rows in the table will be deleted." While true, it may be slightly misleading — Syntax 2 without WHERE/LIMIT indeed deletes all rows. This is correct and an important safety warning; no change needed.
• Minor wording: In the dev EN files, the :::tip block for ORDER BY/LIMIT version info is absent. This leaves users of the dev (master) docs without clear version attribution for these new clauses, which is valuable context.

---

Issues Requiring Attention

Issue 1 (Medium): Missing :::tip version callout in dev / current docs

The 4.x versioned files correctly include:

:::tip
ORDER BY and LIMIT in DELETE/UPDATE statements are supported since version 4.1.0.
:::

But the four dev (docs/ and i18n/zh-CN/current/) files for both DELETE and UPDATE are missing this callout. Since these are the "latest" docs, users need to know the minimum version for this feature.

Affected files:

• docs/sql-manual/sql-statements/data-modification/DML/DELETE.md
• docs/sql-manual/sql-statements/data-modification/DML/UPDATE.md
• i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/data-modification/DML/DELETE.md
• i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/data-modification/DML/UPDATE.md

Issue 2 (Minor): New examples lack expected output

Per the documentation standard in AGENTS.md:

Each query must be followed by its expected output in a fenced text block.

Examples 6 and 7 in all DELETE files, and examples 5 and 6 in all UPDATE files, show DELETE FROM my_table ORDER BY k1 ASC LIMIT 3; and similar statements without any output block. For DML statements that don't produce a result set, the expected output is typically the row count affected (e.g., Query OK, 3 rows affected). At minimum, a short note or a text block showing the affected-rows response should be added for completeness.

---

Summary

The PR correctly implements the primary goal and covers all expected version/locale combinations. The two issues above are the main gaps: (1) the version tip is missing in the dev-stream docs, and (2) examples lack expected output. The content itself is accurate and the safety warning about omitting WHERE is a good addition.