diff --git a/docs/user-guide/protocols/http.md b/docs/user-guide/protocols/http.md index 22418d723..edb664627 100644 --- a/docs/user-guide/protocols/http.md +++ b/docs/user-guide/protocols/http.md @@ -151,6 +151,44 @@ The response contains the following fields: - `rows`: The rows of the query result, where each row is an array containing the corresponding values of the columns in the schema. - `execution_time_ms`: The execution time of the statement in milliseconds. +### Alternative formats + +In addition to the default JSON format, the HTTP API also allows you to +customize output format by providing the `format` query parameter with following +values: + +- `influxdb_v1`: [influxdb query + API](https://docs.influxdata.com/influxdb/v1/tools/api/#query-http-endpoint) + compatible format. Additional parameters: + - `epoch`: `[ns,u,µ,ms,s,m,h]`, returns epoch timestamps with the specified + precision +- `csv`: output in comma separated values +- `arrow`: [Arrow IPC + format](https://arrow.apache.org/docs/python/feather.html). Additional + parameters: + - `compression`: `zstd` or `lz4`, default: no compression +- `table`: ASCII table format for console output + +Call the SQL API with `table` format as an example: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=table +``` + +Output + +``` +┌─host────────┬─ts────────────┬─cpu─┬─memory─┐ +│ "127.0.0.1" │ 1667446797450 │ 0.1 │ 0.4 │ +│ "127.0.0.1" │ 1667446798450 │ 0.5 │ 0.2 │ +│ "127.0.0.2" │ 1667446798450 │ 0.2 │ 0.3 │ +└─────────────┴───────────────┴─────┴────────┘ +``` + ## POST PromQL Queries GreptimeDB also exposes an custom HTTP API for querying with PromQL, and returning diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/protocols/http.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/protocols/http.md index bea55d2ff..9578cd895 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/protocols/http.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/protocols/http.md @@ -152,6 +152,43 @@ curl -X POST \ - `rows`:查询结果的行数据,每行是一个数组,包含 schema 中对应列的值。 - `execution_time_ms`:该语句的执行时间,以毫秒为单位。 +### 其他输出格式 + + +除了默认的 JSON 格式外,通过指定 `format` 参数,HTTP API 还支持自定义以下输出格 +式: + +- `influxdb_v1`: [influxdb 查询接 + 口](https://docs.influxdata.com/influxdb/v1/tools/api/#query-http-endpoint)兼 + 容格式,支持额外参数: + - `epoch`: `[ns,u,µ,ms,s,m,h]`, 控制输出时间戳精度 +- `csv`: CSV 格式 +- `arrow`: [Arrow IPC 格式](https://arrow.apache.org/docs/python/feather.html). + 支持额外的参数: + - `compression`: `zstd` or `lz4`, 默认不设置压缩 +- `table`: 用于终端数据的 ASCII 表格格式 + +以输出 `table` 格式为例: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=table +``` + +结果: + +``` +┌─host────────┬─ts────────────┬─cpu─┬─memory─┐ +│ "127.0.0.1" │ 1667446797450 │ 0.1 │ 0.4 │ +│ "127.0.0.1" │ 1667446798450 │ 0.5 │ 0.2 │ +│ "127.0.0.2" │ 1667446798450 │ 0.2 │ 0.3 │ +└─────────────┴───────────────┴─────┴────────┘ +``` + + ## POST PromQL 查询 GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询,即在当前的 API 路径 `/v1` 的后方拼接 `/promql`,如下示例: