docs: shorten the batching mode title and rework the flownode diagrams - #2814
Merged
Conversation
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.
Deploying greptime-docs with
|
| 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 |
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.
discord9
reviewed
Sep 3, 2026
discord9
reviewed
Sep 3, 2026
discord9
reviewed
Sep 3, 2026
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
approved these changes
Sep 3, 2026
discord9
left a comment
Contributor
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Rename the Flownode batching mode page to Batching Mode. The old heading
Flownode Batching Mode Developer Guidealso drove the sidebar label, which wastoo long for the flownode section. Cross-references in
dataflow.mdandoverview.mdfollow the new name.Replace
batching_mode_arch.pngwith an inline mermaid diagram, matching theplugin added in #2801 and the existing usage in
enterprise/iceberg.md. Therendered 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:
BatchingEngineandDatabaseas decision diamonds. Neither is a decision.Notifyedge implied that a source-table write drives the task. docs: correct outdated Nightly contributor guide content #2784corrected this: marking a window dirty does not wake the task, which runs on its
evaluation schedule or adaptive polling cadence.
Databaseis vague. The task encodes anINSERT INTO sink SELECTplan and sendsit through
FrontendClient, so the node is nowFrontend.source-table read edge.
static/batching_mode_arch.pngis kept rather than deleted, in case the URL isreferenced outside this repository.
Flow mode selection
dataflow.mdlisted the mode-selection rules without their precedence, so a readercould conclude that an aggregating Flow on a source table with
ttl = 'instant'runsin batching mode.
determine_flow_typechecks the source tables first: a missingsource table needs
defer_on_missing_sourceand yields a pending batching Flow, aninstant-TTL source forces streaming, and only then are TQL and
Aggregate/Distinctconsidered. 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_sourcedoes not exist in v1.0.2, wherean instant-TTL source returns streaming directly from the source-table loop.
Scope
Verification
DOC_LANG=en pnpm check:linksDOC_LANG=zh pnpm check:linksgit diff --checklocales: the H1 is
Batching Mode/批处理模式, and each page emits exactly onearia-roledescription="flowchart"SVG.and that the v1.0 flow-selection diagram omits the
defer_on_missing_sourcebranch.main:gen_insert_plan_unlockedbuilds aLogicalPlan::Dml(WriteOp::Insert)over the sink table,encode_insert_plan_requestwraps it as
api::v1::InsertIntoPlan, and it is sent throughFrontendClient, soFrontend performs both the source scan and the sink write.
package.jsonchange.Checklist
are needed: the entry is the doc id, and its label comes from the H1.