docs: document streaming EXPLAIN ANALYZE HTTP API by discord9 · Pull Request #2730 · GreptimeTeam/docs

discord9 · 2026-08-10T10:17:58Z

What changed

Document the POST /v1/sql/analyze/stream (SSE) endpoint contract added in v1.2 (upstream GreptimeDB #8380): request parameters, EXPLAIN ANALYZE VERBOSE statement restrictions, the metrics/final/canceled/error SSE events and payload fields, snapshot semantics (complete best-effort snapshot with adaptive coalescing), client-disconnect cancellation, and the no resume/reconnect lifecycle.

Closes #2719.

Scope

Documentation versions: Nightly, 1.2
Languages: English, Chinese

Verification

Contract verified against GreptimeDB v1.2 source (src/servers/src/http/handler.rs SSE event generation; endpoint registration in src/servers/src/http.rs; config default http.experimental_enable_explain_analyze_stream = true, snapshot_interval_ms default 5000 clamped to [1000, 60000]).
EN/ZH and Nightly/v1.2 copies are line-aligned.
markdownlint config in repo disables all rules; manual structural checks passed. Docusaurus build not run (no node runtime available).

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.

Add the POST /v1/sql/analyze/stream (SSE) endpoint contract to the HTTP endpoint reference: request parameters, EXPLAIN ANALYZE VERBOSE statement restrictions, the metrics/final/canceled/error SSE events and payload fields, snapshot semantics (complete best-effort snapshot, adaptive coalescing), client-disconnect behavior, and the no resume/reconnect lifecycle. Synchronized to EN/ZH Nightly and v1.2. Signed-off-by: discord9 <discord9@163.com>

Signed-off-by: discord9 <discord9@163.com>

killme2008

Checked the contract against main (nightly) and the v1.2.0 tag. The version split is right: nightly dropped the config gate and gained TQL, 1.2 has the gate and SQL-only — the pages match. Interval/clamp constants, the adaptive 1 MiB/10 MiB thresholds, the stage/node/plan shape, 1005, the skip_serializing_if behaviour of output/reason/code, and the nightly-only "slow clients may skip snapshots" note all check out.

Two things are wrong and worth fixing before merge (both repeated across all four files); inline.

Two optional follow-ups:

Nightly only: "compact execution topology" overstates what verbose=false does. It only switches the per-node param string between DisplayFormatType::Default and Verbose (one_line() in src/common/recordbatch/src/adapter.rs). Node count, tree shape and the metric set are identical, and the stage-1 sub-stage metrics are unaffected by the flag. "compact" reads as "fewer nodes".
Out of scope for this PR, but directly contradicts the new nightly page: docs/user-guide/deployments-administration/configuration.md still lists experimental_enable_explain_analyze_stream (example TOML and the options table). GreptimeDB #8966 removed the option from HttpOptions on main; only a test_http_options_legacy_analyze_stream_config_is_ignored test remains.

killme2008 · 2026-09-11T12:32:22Z

+
+#### SSE events
+
+Each event is sent as an `event:` line followed by a `data:` line containing a JSON payload, and events are separated by blank lines. A keep-alive comment line is sent every 15 seconds while the stream is open.


axum's KeepAlive is an idle timeout, not a fixed tick — the timer is reset on every emitted event (KeepAliveStream::poll_next in axum-0.8/src/response/sse.rs). With the default 5000 ms snapshot interval a keep-alive comment is never sent at all. As written, a client would size its read timeout around a 15s heartbeat that does not exist.

Suggest: "A keep-alive comment line is sent after 15 seconds without any event."

killme2008 · 2026-09-11T12:32:22Z

+| `partial` | boolean | `true` for `metrics` events, `false` for terminal events. |
+| `elapsed_ms` | integer | Elapsed time in milliseconds since the request started. |
+| `metrics` | array | When available, a `stage` / `node` / `plan` snapshot. It can appear in `metrics`, `final`, `canceled`, and `error` events. Periodic `metrics` events contain compact execution topology and runtime metrics; terminal events include verbose plan details. |
+| `output` | object | The final query result in GreptimeDB JSON format. Only present in `final` events. |


output is the result of the EXPLAIN ANALYZE statement itself — the stage/node/plan records plus the total-rows row assembled in create_output_batch (src/query/src/analyze.rs) — identical to what /v1/sql returns for EXPLAIN ANALYZE VERBOSE FORMAT JSON. It does not contain the rows of the query being analyzed.

"The final query result" reads like the SELECT * FROM monitor rows, so a client written against this description will parse for something that never arrives. Worth stating explicitly.

killme2008 · 2026-09-11T12:32:22Z

+
+#### SSE 事件
+
+每个事件由 `event:` 行和包含 JSON 负载的 `data:` 行组成，事件之间以空行分隔。流打开期间，服务器每 15 秒发送一行 keep-alive 注释。


同 docs/reference/http-endpoints.md:259：keep-alive 是 idle timeout，不是固定 15 秒一次。

killme2008 · 2026-09-11T12:32:23Z

+| `partial` | 布尔值 | `metrics` 事件为 `true`，终止事件为 `false`。 |
+| `elapsed_ms` | 整数 | 自请求开始以来的耗时（毫秒）。 |
+| `metrics` | 数组 | 可用时，包含 `stage` / `node` / `plan` 快照。可以出现在 `metrics`、`final`、`canceled` 和 `error` 事件中。周期性 `metrics` 事件包含紧凑执行拓扑和运行时指标；终止事件包含详细计划。 |
+| `output` | 对象 | 以 GreptimeDB JSON 格式返回的最终查询结果。仅出现在 `final` 事件中。 |


同 docs/reference/http-endpoints.md:270：output 是 EXPLAIN ANALYZE 语句自身的结果表，不是被分析查询的数据行。

killme2008 · 2026-09-11T12:32:23Z

+
+#### SSE events
+
+Each event is sent as an `event:` line followed by a `data:` line containing a JSON payload, and events are separated by blank lines. A keep-alive comment line is sent every 15 seconds while the stream is open.


Same as docs/reference/http-endpoints.md:259 — the v1.2 handler uses the same KeepAlive::new().interval(Duration::from_secs(15)), so the idle-timeout wording applies here too.

killme2008 · 2026-09-11T12:32:23Z

+| `partial` | boolean | `true` for `metrics` events, `false` for terminal events. |
+| `elapsed_ms` | integer | Elapsed time in milliseconds since the request started. |
+| `metrics` | array | When available, the current `EXPLAIN ANALYZE VERBOSE` metrics snapshot: an array of `stage` / `node` / `plan` entries. It can appear in `metrics`, `final`, `canceled`, and `error` events. |
+| `output` | object | The final query result in GreptimeDB JSON format. Only present in `final` events. |


Same as docs/reference/http-endpoints.md:270.

killme2008 · 2026-09-11T12:32:23Z

+
+#### SSE 事件
+
+每个事件由 `event:` 行和包含 JSON 负载的 `data:` 行组成，事件之间以空行分隔。流打开期间，服务器每 15 秒发送一行 keep-alive 注释。


同 docs/reference/http-endpoints.md:259。

killme2008 · 2026-09-11T12:32:23Z

+| `partial` | 布尔值 | `metrics` 事件为 `true`，终止事件为 `false`。 |
+| `elapsed_ms` | 整数 | 自请求开始以来的耗时（毫秒）。 |
+| `metrics` | 数组 | 可用时，当前的 `EXPLAIN ANALYZE VERBOSE` 指标快照：由 `stage` / `node` / `plan` 条目组成的数组。可以出现在 `metrics`、`final`、`canceled` 和 `error` 事件中。 |
+| `output` | 对象 | 以 GreptimeDB JSON 格式返回的最终查询结果。仅出现在 `final` 事件中。 |


同 docs/reference/http-endpoints.md:270。

discord9 requested review from fengjiachun and killme2008 as code owners August 10, 2026 10:17

fengjiachun reviewed Aug 10, 2026

View reviewed changes

Comment thread docs/reference/http-endpoints.md Outdated

docs: resolve streaming analyze review and merge main

70c4f17

Signed-off-by: discord9 <discord9@163.com>

killme2008 reviewed Sep 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: document streaming EXPLAIN ANALYZE HTTP API - #2730

docs: document streaming EXPLAIN ANALYZE HTTP API#2730
discord9 wants to merge 2 commits into
GreptimeTeam:mainfrom
discord9:docs/streaming-explain-analyze-2719

discord9 commented Aug 10, 2026

Uh oh!

Uh oh!

killme2008 left a comment

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

killme2008 Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		#### SSE events

		Each event is sent as an `event:` line followed by a `data:` line containing a JSON payload, and events are separated by blank lines. A keep-alive comment line is sent every 15 seconds while the stream is open.


		#### SSE 事件

		每个事件由 `event:` 行和包含 JSON 负载的 `data:` 行组成，事件之间以空行分隔。流打开期间，服务器每 15 秒发送一行 keep-alive 注释。

Uh oh!

Conversation

discord9 commented Aug 10, 2026

What changed

Scope

Verification

Checklist

Uh oh!

Uh oh!

killme2008 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants