GreptimeTeam / GreptimeTeam/docs

Document the streaming EXPLAIN ANALYZE HTTP API

Open
#2,719 0 comments 0 reactions 1 assignee Claimed by @discord9 View on GitHub
Dominant language
TypeScript
Stars
52
Forks
54
Avg merge
1d 14h
Merged PRs (30d)
65

Description

## Context

GreptimeDB v1.2 introduces a streaming SQL analysis endpoint:

- Upstream: https://github.com/GreptimeTeam/greptimedb/pull/8380
- Endpoint: `POST /v1/sql/analyze/stream`
- Transport: Server-Sent Events (SSE)

The current docs only expose the related configuration and do not document the API contract.

## Documentation work

Add HTTP API/reference documentation covering:

- A request example using one `EXPLAIN ANALYZE VERBOSE` statement.
- Accepted format constraints and rejection of non-explain or multi-statement requests.
- SSE event types: `metrics`, `final`, `canceled`, and `error`.
- Metrics as complete, best-effort snapshots rather than deltas, including snapshot coalescing.
- Terminal event behavior and client disconnect cancellation.
- No resume, reconnect, or detached-query lifecycle.
- The v1.2 default for the related configuration, verified against the v1.2 source/tag.

## Scope

Update both English and Chinese documentation in:

- Nightly
- v1.2

## Completion criteria

- [ ] The endpoint has a complete request and event-stream example.
- [ ] Lifecycle, cancellation, and snapshot semantics are explicit.
- [ ] Version-sensitive defaults are verified against v1.2.
- [ ] English and Chinese content is aligned.
- [ ] Affected locale builds pass.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.