Skip to content

[docs] Restructure primary-key table documentation and diagrams - #9718

Merged
JingsongLi merged 2 commits into
apache:masterfrom
JingsongLi:codex/restructure-primary-key-docs
Sep 10, 2026
Merged

[docs] Restructure primary-key table documentation and diagrams#9718
JingsongLi merged 2 commits into
apache:masterfrom
JingsongLi:codex/restructure-primary-key-docs

Conversation

@JingsongLi

Copy link
Copy Markdown
Contributor

Purpose

The primary-key table guides mix conceptual introductions, configuration details, and long examples, making it difficult to choose a table layout or follow update behavior. Reorganize the existing pages into a reading path covering data layout, updates and changelogs, compaction and querying, and advanced features.

  • Add decision tables and concrete SQL examples, and clarify ordering, partial-update NULL and retraction behavior, aggregation, changelog production, deletion vectors, and index coverage against the current implementation.
  • Replace bitmap references in these guides with editable SVG diagrams and add diagrams for sequence groups, index coverage, and BLOB lifecycle (10 SVGs in total).
  • Fold lengthy reference examples, remove duplicated explanations, preserve page URLs and relevant legacy anchors, and repair the Concepts footer link.

Tests

  • COREPACK_ENABLE_AUTO_PIN=0 yarn build: production documentation build and REST OpenAPI validation pass on the updated upstream baseline.
  • Browser checks: all 15 primary-key pages, 177 internal links, SVG loading, legacy anchors, SQL tabs, and expandable examples pass.
  • Mobile layout checks at 390 px: overview, sequence/row-kind, and partial-update pages have no page-wide horizontal overflow.
  • All 10 SVGs pass XML, viewBox, title, and description checks; rendered diagrams were visually inspected.
  • git diff --check passes.

SQL examples were checked against the implementation; they were not executed in Flink. This PR changes documentation and static assets only.

@leaves12138 leaves12138 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 5b898f3. One configuration-semantics correction is needed before approval; see the inline comment about the effective default in gentle lookup compaction.

Independent validation passed:

  • Production documentation build and REST OpenAPI validation.
  • All 175 unique internal body links/anchors across the 15 changed documentation pages.
  • Preservation of all 15 primary-key sidebar document IDs.
  • Browser checks of all 15 pages: image loading, SQL tabs, expandable examples, 390 px mobile width, and no JavaScript page errors.
  • All 10 SVGs: XML metadata, rendered text bounds, and visual inspection.

The semantic review used the implementation and existing test assertions at this head. SQL examples and Java/engine tests were not executed.

Comment thread docs/docs/primary-key-table/compaction.md Outdated

@leaves12138 leaves12138 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Re-reviewed at 5c5f2d1.

The previous finding is fixed: gentle lookup compaction now correctly documents the effective default of twice the sorted-run compaction trigger (10 with defaults), the minimum applied to an explicit interval, and which selection attempts are counted. I also checked the new force-lookup, radical/gentle, and non-lookup compaction.force-up-level-0 explanations against the implementation.

The only change since my previous review is this compaction guide update. No additional findings.

Revalidation on the updated head:

  • Production documentation build and REST OpenAPI validation pass with a fresh dependency installation.
  • All 175 unique internal body links/anchors across the 15 primary-key pages resolve; sidebar document IDs and SVG metadata checks pass.
  • The updated compaction page passes browser rendering, image loading, mobile-width, and JavaScript-error checks.

SQL examples and Java/engine tests were not executed; this remains a documentation-only change.

@JingsongLi
JingsongLi merged commit 61e9165 into apache:master Sep 10, 2026
2 checks passed
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