Skip to content

docs: document streaming EXPLAIN ANALYZE HTTP API #2730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
discord9 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document streaming EXPLAIN ANALYZE HTTP API #2730

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/reference/http-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,80 @@ Various query APIs for sending query to GreptimeDB.

For more information on the SQL API, refer to the [HTTP API documentation](/user-guide/protocols/http.md#post-sql-statements) in the user guide.

### Streaming EXPLAIN ANALYZE API

- **Path**: `/v1/sql/analyze/stream`
- **Methods**: `POST`
- **Description**: Streams live `EXPLAIN ANALYZE VERBOSE` metrics of a running query as Server-Sent Events (SSE).

This experimental endpoint is gated by the `http.experimental_enable_explain_analyze_stream` configuration option (defaults to `true`). When the option is disabled, the endpoint is not registered and returns `404 Not Found`.

The endpoint is POST-only and responds with `Content-Type: text/event-stream`. Since browser `EventSource` only supports GET requests, it cannot be used with this endpoint.

#### Request parameters

Parameters can be passed either as query string parameters or as form fields in the POST body:

| Parameter | Required | Description |
| --- | --- | --- |
| `sql` | Yes | The `EXPLAIN ANALYZE VERBOSE` statement to execute. |
| `db` | No | The database to run the statement against. |
| `snapshot_interval_ms` | No | Interval between `metrics` snapshots in milliseconds. Defaults to `5000`; values are clamped to the `[1000, 60000]` range. |

Example:

```bash
curl -N -X POST 'http://127.0.0.1:4000/v1/sql/analyze/stream' \
-H 'Accept: text/event-stream' \
-F 'sql=EXPLAIN ANALYZE VERBOSE SELECT * FROM monitor'

@fengjiachun fengjiachun Aug 10, 2026

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 example uses curl -F, which sends multipart/form-data, but this handler extracts Axum Form<SqlQuery>, which accepts application/x-www-form-urlencoded. Because the unsupported media type is ignored and no query-string sql is supplied, this command reaches sql parameter is required instead of opening an SSE stream. Please use --data-urlencode 'sql=EXPLAIN ANALYZE VERBOSE SELECT * FROM monitor' and update all four copies so the documented example works.

```

#### Statement restrictions

The endpoint only accepts a single `EXPLAIN ANALYZE VERBOSE` statement. `EXPLAIN ANALYZE VERBOSE FORMAT JSON` is accepted as well; the `FORMAT` clause is optional and only `JSON` is supported. Any other request is rejected with a regular JSON error response (not SSE), including:

- Non-explain statements, such as `SELECT ...`
- `EXPLAIN` or `EXPLAIN ANALYZE` without `VERBOSE`
- `EXPLAIN ANALYZE VERBOSE` with a non-JSON format, such as `FORMAT TEXT` or `FORMAT GRAPHVIZ`
- Multiple statements separated by semicolons

#### 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.

All payloads share these fields:

| Field | Type | Description |
| --- | --- | --- |
| `seq` | integer | Monotonically increasing sequence number of the event. |
| `state` | string | The event type: `metrics`, `final`, `canceled`, or `error`. |
| `partial` | boolean | `true` for `metrics` events, `false` for terminal events. |
| `elapsed_ms` | integer | Elapsed time in milliseconds since the request started. |
| `metrics` | array | The current `EXPLAIN ANALYZE VERBOSE` metrics snapshot: an array of `stage` / `node` / `plan` entries. Present in `metrics` and `final` events. |
| `output` | object | The final query result in GreptimeDB JSON format. Only present in `final` events. |
| `reason` | string | The reason for the failure or cancellation. Only present in `error` and `canceled` events. |
| `code` | integer | The GreptimeDB status code. Only present in `error` and `canceled` events. |

The server emits four event types:

- `metrics` — emitted periodically while the query runs. Each event carries a **complete best-effort snapshot** of the metrics collected so far, not a delta of the changes since the previous event. The snapshot is best-effort: metric values may change while it is being collected. Snapshots are coalesced with an adaptive interval: once a snapshot payload reaches 1 MiB, the interval is raised to at least 10 seconds; at 10 MiB, to at least 30 seconds. Snapshots are throttled but never truncated.
- `final` — terminal. Emitted when the query finishes. It carries the final metrics snapshot and the query result in the `output` field.
- `canceled` — terminal. Emitted when the query is canceled before finishing. It carries the cancellation reason and the GreptimeDB status code `1005` (`Cancelled`).
- `error` — terminal. Emitted when the query fails. It carries the error reason and the GreptimeDB status code.

Example of a `metrics` event:

```text
event: metrics
data: {"seq":3,"state":"metrics","partial":true,"elapsed_ms":15234,"metrics":[{"stage":0,"node":0,"plan":{"name":"MergeScanExec","param":"peers=[...]","output_rows":0,"elapsed_compute":0,"metrics":{...},"children":[...]}}]}
```

#### Client disconnect and lifecycle

If the client disconnects before a terminal event, it simply stops receiving events: the SSE stream is dropped and the underlying query is best-effort canceled. A disconnected client never receives a `canceled` event.

The stream has no resume, reconnect, or detached-execution lifecycle: the connection stays open from the request until the terminal event, and events are delivered only to the connected client.

### PromQL API

- **Path**: `/v1/promql`
Expand Down
74 changes: 74 additions & 0 deletions i18n/zh/docusaurus-plugin-content-docs/current/reference/http-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,80 @@ curl -X POST 'http://127.0.0.1:4000/debug/prof/mem/gdump' -d 'activate=true'

有关 SQL API 的更多信息，请参阅用户指南中的 [HTTP API 文档](/user-guide/protocols/http.md#post-sql-statements)。

### 流式 EXPLAIN ANALYZE API

- **路径**: `/v1/sql/analyze/stream`
- **方法**: `POST`
- **描述**: 以 Server-Sent Events (SSE) 的形式流式返回运行中查询的 `EXPLAIN ANALYZE VERBOSE` 指标。

这是一个实验性端点，由 `http.experimental_enable_explain_analyze_stream` 配置项控制（默认为 `true`）。当该配置项被禁用时，端点不会被注册，请求将返回 `404 Not Found`。

该端点仅支持 POST，响应 `Content-Type` 为 `text/event-stream`。由于浏览器的 `EventSource` 只支持 GET 请求，因此无法使用该端点。

#### 请求参数

参数可以通过查询字符串或 POST 请求体中的表单字段传递：

| 参数 | 必填 | 描述 |
| --- | --- | --- |
| `sql` | 是 | 要执行的 `EXPLAIN ANALYZE VERBOSE` 语句。 |
| `db` | 否 | 执行语句所在的数据库。 |
| `snapshot_interval_ms` | 否 | `metrics` 快照的发送间隔（毫秒）。默认为 `5000`，取值会被限制在 `[1000, 60000]` 范围内。 |

示例：

```bash
curl -N -X POST 'http://127.0.0.1:4000/v1/sql/analyze/stream' \
-H 'Accept: text/event-stream' \
-F 'sql=EXPLAIN ANALYZE VERBOSE SELECT * FROM monitor'
```

#### 语句限制

该端点仅接受单条 `EXPLAIN ANALYZE VERBOSE` 语句，也接受 `EXPLAIN ANALYZE VERBOSE FORMAT JSON`；`FORMAT` 子句可选，且仅支持 `JSON`。其他请求都会被拒绝，并返回常规的 JSON 错误响应（而非 SSE），包括：

- 非 explain 语句，如 `SELECT ...`
- 不带 `VERBOSE` 的 `EXPLAIN` 或 `EXPLAIN ANALYZE`
- 使用非 JSON 格式的 `EXPLAIN ANALYZE VERBOSE`，如 `FORMAT TEXT` 或 `FORMAT GRAPHVIZ`
- 以分号分隔的多条语句

#### SSE 事件

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

所有负载都包含以下字段：

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `seq` | 整数 | 事件的单调递增序号。 |
| `state` | 字符串 | 事件类型：`metrics`、`final`、`canceled` 或 `error`。 |
| `partial` | 布尔值 | `metrics` 事件为 `true`，终止事件为 `false`。 |
| `elapsed_ms` | 整数 | 自请求开始以来的耗时（毫秒）。 |
| `metrics` | 数组 | 当前的 `EXPLAIN ANALYZE VERBOSE` 指标快照：由 `stage` / `node` / `plan` 条目组成的数组。仅出现在 `metrics` 和 `final` 事件中。 |
| `output` | 对象 | 以 GreptimeDB JSON 格式返回的最终查询结果。仅出现在 `final` 事件中。 |
| `reason` | 字符串 | 失败或取消的原因。仅出现在 `error` 和 `canceled` 事件中。 |
| `code` | 整数 | GreptimeDB 状态码。仅出现在 `error` 和 `canceled` 事件中。 |

服务器会发出四种事件类型：

- `metrics` — 查询运行期间周期性发送。每个事件携带截至目前已收集指标的**完整 best-effort 快照**，而不是自上一个事件以来的增量（delta）。快照是 best-effort 的：在收集过程中指标值可能会变化。快照会以自适应间隔进行合并（coalescing）：一旦单个快照负载达到 1 MiB，间隔将提升至至少 10 秒；达到 10 MiB 时，提升至至少 30 秒。快照会被限流但绝不会被截断。
- `final` — 终止事件。查询完成时发送，携带最终指标快照以及 `output` 字段中的查询结果。
- `canceled` — 终止事件。查询在完成前被取消时发送，携带取消原因和 GreptimeDB 状态码 `1005`（`Cancelled`）。
- `error` — 终止事件。查询失败时发送，携带错误原因和 GreptimeDB 状态码。

`metrics` 事件示例：

```text
event: metrics
data: {"seq":3,"state":"metrics","partial":true,"elapsed_ms":15234,"metrics":[{"stage":0,"node":0,"plan":{"name":"MergeScanExec","param":"peers=[...]","output_rows":0,"elapsed_compute":0,"metrics":{...},"children":[...]}}]}
```

#### 客户端断开与生命周期

如果客户端在终止事件之前断开连接，它将不再收到任何事件：SSE 流会被丢弃，底层查询会被 best-effort 取消。断开的客户端永远不会收到 `canceled` 事件。

该流没有 resume、reconnect 或 detached 执行的生命周期：连接会从请求开始保持到终止事件发生，事件只发送给已连接的客户端。

### PromQL API

- **路径**: `/v1/promql`
Expand Down
74 changes: 74 additions & 0 deletions i18n/zh/docusaurus-plugin-content-docs/version-1.2/reference/http-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,80 @@ curl -X POST 'http://127.0.0.1:4000/debug/prof/mem/gdump' -d 'activate=true'

有关 SQL API 的更多信息，请参阅用户指南中的 [HTTP API 文档](/user-guide/protocols/http.md#post-sql-statements)。

### 流式 EXPLAIN ANALYZE API

- **路径**: `/v1/sql/analyze/stream`
- **方法**: `POST`
- **描述**: 以 Server-Sent Events (SSE) 的形式流式返回运行中查询的 `EXPLAIN ANALYZE VERBOSE` 指标。

这是一个实验性端点，由 `http.experimental_enable_explain_analyze_stream` 配置项控制（默认为 `true`）。当该配置项被禁用时，端点不会被注册，请求将返回 `404 Not Found`。

该端点仅支持 POST，响应 `Content-Type` 为 `text/event-stream`。由于浏览器的 `EventSource` 只支持 GET 请求，因此无法使用该端点。

#### 请求参数

参数可以通过查询字符串或 POST 请求体中的表单字段传递：

| 参数 | 必填 | 描述 |
| --- | --- | --- |
| `sql` | 是 | 要执行的 `EXPLAIN ANALYZE VERBOSE` 语句。 |
| `db` | 否 | 执行语句所在的数据库。 |
| `snapshot_interval_ms` | 否 | `metrics` 快照的发送间隔（毫秒）。默认为 `5000`，取值会被限制在 `[1000, 60000]` 范围内。 |

示例：

```bash
curl -N -X POST 'http://127.0.0.1:4000/v1/sql/analyze/stream' \
-H 'Accept: text/event-stream' \
-F 'sql=EXPLAIN ANALYZE VERBOSE SELECT * FROM monitor'
```

#### 语句限制

该端点仅接受单条 `EXPLAIN ANALYZE VERBOSE` 语句，也接受 `EXPLAIN ANALYZE VERBOSE FORMAT JSON`；`FORMAT` 子句可选，且仅支持 `JSON`。其他请求都会被拒绝，并返回常规的 JSON 错误响应（而非 SSE），包括：

- 非 explain 语句，如 `SELECT ...`
- 不带 `VERBOSE` 的 `EXPLAIN` 或 `EXPLAIN ANALYZE`
- 使用非 JSON 格式的 `EXPLAIN ANALYZE VERBOSE`，如 `FORMAT TEXT` 或 `FORMAT GRAPHVIZ`
- 以分号分隔的多条语句

#### SSE 事件

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

所有负载都包含以下字段：

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `seq` | 整数 | 事件的单调递增序号。 |
| `state` | 字符串 | 事件类型：`metrics`、`final`、`canceled` 或 `error`。 |
| `partial` | 布尔值 | `metrics` 事件为 `true`，终止事件为 `false`。 |
| `elapsed_ms` | 整数 | 自请求开始以来的耗时（毫秒）。 |
| `metrics` | 数组 | 当前的 `EXPLAIN ANALYZE VERBOSE` 指标快照：由 `stage` / `node` / `plan` 条目组成的数组。仅出现在 `metrics` 和 `final` 事件中。 |
| `output` | 对象 | 以 GreptimeDB JSON 格式返回的最终查询结果。仅出现在 `final` 事件中。 |
| `reason` | 字符串 | 失败或取消的原因。仅出现在 `error` 和 `canceled` 事件中。 |
| `code` | 整数 | GreptimeDB 状态码。仅出现在 `error` 和 `canceled` 事件中。 |

服务器会发出四种事件类型：

- `metrics` — 查询运行期间周期性发送。每个事件携带截至目前已收集指标的**完整 best-effort 快照**，而不是自上一个事件以来的增量（delta）。快照是 best-effort 的：在收集过程中指标值可能会变化。快照会以自适应间隔进行合并（coalescing）：一旦单个快照负载达到 1 MiB，间隔将提升至至少 10 秒；达到 10 MiB 时，提升至至少 30 秒。快照会被限流但绝不会被截断。
- `final` — 终止事件。查询完成时发送，携带最终指标快照以及 `output` 字段中的查询结果。
- `canceled` — 终止事件。查询在完成前被取消时发送，携带取消原因和 GreptimeDB 状态码 `1005`（`Cancelled`）。
- `error` — 终止事件。查询失败时发送，携带错误原因和 GreptimeDB 状态码。

`metrics` 事件示例：

```text
event: metrics
data: {"seq":3,"state":"metrics","partial":true,"elapsed_ms":15234,"metrics":[{"stage":0,"node":0,"plan":{"name":"MergeScanExec","param":"peers=[...]","output_rows":0,"elapsed_compute":0,"metrics":{...},"children":[...]}}]}
```

#### 客户端断开与生命周期

如果客户端在终止事件之前断开连接，它将不再收到任何事件：SSE 流会被丢弃，底层查询会被 best-effort 取消。断开的客户端永远不会收到 `canceled` 事件。

该流没有 resume、reconnect 或 detached 执行的生命周期：连接会从请求开始保持到终止事件发生，事件只发送给已连接的客户端。

### PromQL API

- **路径**: `/v1/promql`
Expand Down
74 changes: 74 additions & 0 deletions versioned_docs/version-1.2/reference/http-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,80 @@ Various query APIs for sending query to GreptimeDB.

For more information on the SQL API, refer to the [HTTP API documentation](/user-guide/protocols/http.md#post-sql-statements) in the user guide.

### Streaming EXPLAIN ANALYZE API

- **Path**: `/v1/sql/analyze/stream`
- **Methods**: `POST`
- **Description**: Streams live `EXPLAIN ANALYZE VERBOSE` metrics of a running query as Server-Sent Events (SSE).

This experimental endpoint is gated by the `http.experimental_enable_explain_analyze_stream` configuration option (defaults to `true`). When the option is disabled, the endpoint is not registered and returns `404 Not Found`.

The endpoint is POST-only and responds with `Content-Type: text/event-stream`. Since browser `EventSource` only supports GET requests, it cannot be used with this endpoint.

#### Request parameters

Parameters can be passed either as query string parameters or as form fields in the POST body:

| Parameter | Required | Description |
| --- | --- | --- |
| `sql` | Yes | The `EXPLAIN ANALYZE VERBOSE` statement to execute. |
| `db` | No | The database to run the statement against. |
| `snapshot_interval_ms` | No | Interval between `metrics` snapshots in milliseconds. Defaults to `5000`; values are clamped to the `[1000, 60000]` range. |

Example:

```bash
curl -N -X POST 'http://127.0.0.1:4000/v1/sql/analyze/stream' \
-H 'Accept: text/event-stream' \
-F 'sql=EXPLAIN ANALYZE VERBOSE SELECT * FROM monitor'
```

#### Statement restrictions

The endpoint only accepts a single `EXPLAIN ANALYZE VERBOSE` statement. `EXPLAIN ANALYZE VERBOSE FORMAT JSON` is accepted as well; the `FORMAT` clause is optional and only `JSON` is supported. Any other request is rejected with a regular JSON error response (not SSE), including:

- Non-explain statements, such as `SELECT ...`
- `EXPLAIN` or `EXPLAIN ANALYZE` without `VERBOSE`
- `EXPLAIN ANALYZE VERBOSE` with a non-JSON format, such as `FORMAT TEXT` or `FORMAT GRAPHVIZ`
- Multiple statements separated by semicolons

#### 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.

All payloads share these fields:

| Field | Type | Description |
| --- | --- | --- |
| `seq` | integer | Monotonically increasing sequence number of the event. |
| `state` | string | The event type: `metrics`, `final`, `canceled`, or `error`. |
| `partial` | boolean | `true` for `metrics` events, `false` for terminal events. |
| `elapsed_ms` | integer | Elapsed time in milliseconds since the request started. |
| `metrics` | array | The current `EXPLAIN ANALYZE VERBOSE` metrics snapshot: an array of `stage` / `node` / `plan` entries. Present in `metrics` and `final` events. |
| `output` | object | The final query result in GreptimeDB JSON format. Only present in `final` events. |
| `reason` | string | The reason for the failure or cancellation. Only present in `error` and `canceled` events. |
| `code` | integer | The GreptimeDB status code. Only present in `error` and `canceled` events. |

The server emits four event types:

- `metrics` — emitted periodically while the query runs. Each event carries a **complete best-effort snapshot** of the metrics collected so far, not a delta of the changes since the previous event. The snapshot is best-effort: metric values may change while it is being collected. Snapshots are coalesced with an adaptive interval: once a snapshot payload reaches 1 MiB, the interval is raised to at least 10 seconds; at 10 MiB, to at least 30 seconds. Snapshots are throttled but never truncated.
- `final` — terminal. Emitted when the query finishes. It carries the final metrics snapshot and the query result in the `output` field.
- `canceled` — terminal. Emitted when the query is canceled before finishing. It carries the cancellation reason and the GreptimeDB status code `1005` (`Cancelled`).
- `error` — terminal. Emitted when the query fails. It carries the error reason and the GreptimeDB status code.

Example of a `metrics` event:

```text
event: metrics
data: {"seq":3,"state":"metrics","partial":true,"elapsed_ms":15234,"metrics":[{"stage":0,"node":0,"plan":{"name":"MergeScanExec","param":"peers=[...]","output_rows":0,"elapsed_compute":0,"metrics":{...},"children":[...]}}]}
```

#### Client disconnect and lifecycle

If the client disconnects before a terminal event, it simply stops receiving events: the SSE stream is dropped and the underlying query is best-effort canceled. A disconnected client never receives a `canceled` event.

The stream has no resume, reconnect, or detached-execution lifecycle: the connection stays open from the request until the terminal event, and events are delivered only to the connected client.

### PromQL API

- **Path**: `/v1/promql`
Expand Down
Loading