Skip to content

docs: shorten the batching mode title and rework the flownode diagrams - #2814

Merged
killme2008 merged 3 commits into
mainfrom
docs/shorten-batching-mode-title
Sep 3, 2026
Merged

docs: shorten the batching mode title and rework the flownode diagrams#2814
killme2008 merged 3 commits into
mainfrom
docs/shorten-batching-mode-title

Conversation

@killme2008

@killme2008 killme2008 commented Sep 2, 2026

Copy link
Copy Markdown
Member

What changed

Rename the Flownode batching mode page to Batching Mode. The old heading
Flownode Batching Mode Developer Guide also drove the sidebar label, which was
too long for the flownode section. Cross-references in dataflow.md and
overview.md follow the new name.

Replace batching_mode_arch.png with an inline mermaid diagram, matching the
plugin added in #2801 and the existing usage in enterprise/iceberg.md. The
rendered diagram goes from 633x1582 to 387x608, and mermaid picks up the site's
configured light and dark themes instead of shipping a light-only raster.

The old image also had errors, which the new diagram fixes:

  • It drew BatchingEngine and Database as decision diamonds. Neither is a decision.
  • Its Notify edge implied that a source-table write drives the task. docs: correct outdated Nightly contributor guide content #2784
    corrected this: marking a window dirty does not wake the task, which runs on its
    evaluation schedule or adaptive polling cadence.
  • Database is vague. The task encodes an INSERT INTO sink SELECT plan and sends
    it through FrontendClient, so the node is now Frontend.
  • Frontend scans the source table while executing that plan. The old image had no
    source-table read edge.

static/batching_mode_arch.png is kept rather than deleted, in case the URL is
referenced outside this repository.

Flow mode selection

dataflow.md listed the mode-selection rules without their precedence, so a reader
could conclude that an aggregating Flow on a source table with ttl = 'instant' runs
in batching mode. determine_flow_type checks the source tables first: a missing
source table needs defer_on_missing_source and yields a pending batching Flow, an
instant-TTL source forces streaming, and only then are TQL and Aggregate/Distinct
considered. The paragraph is replaced with a flowchart in that order, plus an explicit
sentence about the instant-TTL consequence.

v1.0 gets a shorter diagram. defer_on_missing_source does not exist in v1.0.2, where
an instant-TTL source returns streaming directly from the source-table loop.

Scope

  • Documentation versions: Nightly, 1.2, 1.1, 1.0
  • Languages: English, Chinese

Verification

  • DOC_LANG=en pnpm check:links
  • DOC_LANG=zh pnpm check:links
  • git diff --check
  • Rendered every built page in headless Chrome for all four versions and both
    locales: the H1 is Batching Mode / 批处理模式, and each page emits exactly one
    aria-roledescription="flowchart" SVG.
  • Verified the mermaid blocks are byte-identical across the versions that share them,
    and that the v1.0 flow-selection diagram omits the defer_on_missing_source branch.
  • Verified the diagram against GreptimeDB main: gen_insert_plan_unlocked builds a
    LogicalPlan::Dml(WriteOp::Insert) over the sink table, encode_insert_plan_request
    wraps it as api::v1::InsertIntoPlan, and it is sent through FrontendClient, so
    Frontend performs both the source scan and the sink write.
  • No lockfile or package.json change.

Checklist

  • I verified the content against the applicable GreptimeDB version.
  • I updated the relevant documentation versions and languages, or explained why not.
  • I checked changed links and anchors.
  • I updated navigation when the document structure changed. No sidebar file changes
    are needed: the entry is the doc id, and its label comes from the H1.

Rename the page to Batching Mode. The old heading also drove the sidebar
label, which was too long for the flownode section. Cross-references in
dataflow.md and overview.md follow the new name.

Replace batching_mode_arch.png with an inline mermaid diagram, matching the
plugin added in #2801 and the usage in enterprise/iceberg.md. The rendered
diagram goes from 633x1582 to 387x608, and mermaid picks up the site's light
and dark themes.

The old image also had errors. It drew BatchingEngine and Database as
decision diamonds, and its Notify edge implied that a source-table write
drives the task, which #2784 corrected: marking a window dirty does not wake
the task. The new diagram names Frontend rather than Database, because the
task encodes an INSERT INTO sink SELECT plan and sends it through
FrontendClient, and adds the source-table scan that Frontend performs while
executing that plan.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 2, 2026

Copy link
Copy Markdown

Deploying greptime-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 5748d9a
Status: ✅  Deploy successful!
Preview URL: https://409bffdd.greptime-docs.pages.dev
Branch Preview URL: https://docs-shorten-batching-mode-t.greptime-docs.pages.dev

View logs

The prose listed the rules without their precedence, so a reader could
conclude that an aggregating Flow on a source table with ttl = 'instant'
runs in batching mode. determine_flow_type checks the source tables first:
a missing source table needs defer_on_missing_source and yields a pending
batching Flow, an instant-TTL source forces streaming, and only then are
TQL and Aggregate/Distinct considered.

Replace the paragraph with a flowchart in that order, and state the
instant-TTL consequence explicitly.

v1.0 gets a shorter diagram: defer_on_missing_source does not exist in
v1.0.2, where an instant-TTL source returns streaming directly from the
source-table loop.
@killme2008 killme2008 changed the title docs: shorten the batching mode title and redraw its diagram docs: shorten the batching mode title and rework the flownode diagrams Sep 3, 2026
Comment thread docs/contributor-guide/flownode/batching_mode.md Outdated
Comment thread versioned_docs/version-1.0/contributor-guide/flownode/dataflow.md Outdated
Comment thread docs/contributor-guide/flownode/batching_mode.md
gen_query_with_time_window has two paths. Windowed SQL is pruned by
dirty-window time predicates; TQL and evaluation-interval SQL whose plan
cannot be safely pruned run an unfiltered full snapshot, where the dirty
set is only a scheduling signal. The diagram showed only the first, and
the prose omitted TQL entirely.

Give the diagram two labelled edges into Frontend, and rewrite the prose
to name both callers. Diagram height is unchanged at 608px.

v1.0 keeps its own wording: there TQL always runs the full query, while
no-window SQL clears the dirty set first and skips the evaluation when
nothing is dirty.

@discord9 discord9 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.

The reported Flow execution-path and v1.0 behavior issues are fixed. I also verified that the renamed H1s do not generate Docusaurus fragment IDs, so no AnchorAlias is needed. The release-specific EN/ZH content is aligned, and all checks pass.

@killme2008
killme2008 merged commit d87a062 into main Sep 3, 2026
7 checks passed
@killme2008
killme2008 deleted the docs/shorten-batching-mode-title branch September 3, 2026 14:45
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