版本：1.2

HTTP API

GreptimeDB 提供了 HTTP API 用于与数据库进行交互。如需查看完整的 API 端点列表，请查看 HTTP Endpoints。

Base URL

API 的 Base URL 是 http(s)://<host>:<port>/。

对于在本地机器上运行的 GreptimeDB 实例，Base URL 是 http://localhost:4000/，默认端口配置为 4000。你可以在配置文件中更改服务的 host 和 port。
对于 GreptimeCloud，Base URL 是 https://<host>/。你可以在 GreptimeCloud 控制台的 "Connection Information" 中找到 host。

在以下内容中，我们使用 http://<API-host>/ 作为 Base URL 来演示 API。

通用 Headers

鉴权

假设你已经正确设置了数据库鉴权， GreptimeDB 支持 HTTP API 中内置的 Basic 鉴权机制。要设置鉴权，请按照以下步骤操作：

使用 <username:password> 格式和 Base64 算法对用户名和密码进行编码。
将编码后的凭据附加到下列 HTTP 请求头之一中:

Authorization : Basic <base64-encoded-credentials>
x-greptime-auth : Basic <base64-encoded-credentials>

以下是一个示例。如果要使用用户名 greptime_user 和密码 greptime_pwd 连接到 GreptimeDB，请使用以下命令：

curl -X POST \
-H 'Authorization: Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'sql=show tables' \
http://localhost:4000/v1/sql

在此示例中，Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q= 表示 greptime_user:greptime_pwd 的 Base64 编码值。请确保用自己配置的用户名和密码替换它，并使用 Base64 进行编码。

注意

InfluxDB 使用自己的鉴权格式，请参阅 InfluxDB 获取详细信息。

请求超时设置

GreptimeDB 支持在 HTTP 请求中使用 X-Greptime-Timeout 请求头，用于指定数据库服务器中运行的请求超时时间。

例如，以下请求为查询设置了 120s 的超时时间：

curl -X POST \
-H 'Authorization: Basic <base64-encoded-credentials>' \
-H 'X-Greptime-Timeout: 120s' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'sql=show tables' \
http://localhost:4000/v1/sql

Hints

GreptimeDB 支持在 HTTP 请求中使用 x-greptime-hints 请求头来传递影响请求行为的键值对。这些 hints 主要用于在数据写入时自动建表的场景下设置表选项。

x-greptime-hints 格式为逗号分隔的 key=value 对：

x-greptime-hints: key1=value1, key2=value2

你也可以使用 x-greptime-hint-<key> 为每个请求头传递一个 hint：

x-greptime-hint-key1: value1
x-greptime-hint-key2: value2

支持的 hints：

Hint	类型	默认值	说明
`auto_create_table`	Boolean	`true`	插入数据时，如果表不存在是否自动创建。
`ttl`	时间字符串	无	设置表的数据过期时间，例如 `7d`、`24h`。过期数据将被自动清理。
`append_mode`	Boolean	`false`	启用表的 append-only 模式，该模式禁用按主键去重，支持重复行。对于 InfluxDB 行协议写入，显式设置 `append_mode=true` hint 时，会使用 `append_mode = 'true'` 和 `merge_mode = 'last_row'` 创建表。
`merge_mode`	String	无	设置表的 merge 模式，例如 `last_non_null`、`last_row`。对于通过 InfluxDB 行协议自动创建的表，该 hint 优先于 `influxdb.default_merge_mode` 配置；该配置默认值为 `last_non_null`。启用 `append_mode` 时，仅允许使用 `last_row`。
`physical_table`	String	无	指定 metric 引擎的物理表名。
`query.enable_remote_dynamic_filter_pushdown`	Boolean	`true`	为 SQL 查询启用远程动态过滤下推。设置为 `false` 可为当前请求关闭 Frontend 到 Datanode 的动态过滤传播。请参阅远程动态过滤下推。
`skip_wal`	Boolean	`false`	跳过表的 WAL（Write-Ahead Log）写入。
`sst_format`	String	无	设置表的 SST（Sorted String Table）文件格式。可选值：`flat`、`primary_key`。
`trace_table_partitions`	Int	None	自定义 Trace 表的默认分区数（16）。设置为 `0` 或 `1` 时禁用分区。

例如，以下请求为自动创建的表设置 TTL 和 append 模式：

curl -X POST \
-H 'Authorization: Basic <base64-encoded-credentials>' \
-H 'x-greptime-hints: ttl=7d, append_mode=true' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'sql=INSERT INTO my_table VALUES (...)' \
http://localhost:4000/v1/sql

Admin APIs

注意

这些 API 在 GreptimeCloud 中无法使用。

请参考 Admin APIs 接口文档以获取更多信息。

POST SQL 语句

要通过 HTTP API 向 GreptimeDB 服务器提交 SQL 语句，请使用以下格式：

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'X-Greptime-Timeout: <timeout>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'sql=<SQL-statement>' \
  'http://<API-host>/v1/sql'

Headers

Authorization
X-Greptime-Timeout
Content-Type: application/x-www-form-urlencoded.
X-Greptime-Timezone: 当前 SQL 查询的时区。可选。请参阅时区。

Query string parameters

db: 数据库名称。可选。如果未提供，将使用默认数据库 public。
format: 输出格式。可选。默认为 greptimedb_v1 的 JSON 格式。除了默认的 JSON 格式外，HTTP API 还允许你通过提供 format 查询参数来自定义输出格式，值如下：
- influxdb_v1: influxdb 查询 API 兼容格式。附加参数：
  - epoch: [ns,u,µ,ms,s,m,h]，返回指定精度的时间戳
- csv: 以逗号分隔值格式输出
- csvWithNames: 以逗号分隔值格式输出，包含列名标题
- csvWithNamesAndTypes: 以逗号分隔值格式输出，包含列名和数据类型标题
- arrow: Arrow IPC 格式。此接口输出流式格式。附加参数：
  - compression: zstd 或 lz4，默认：无压缩
- table: 控制台输出的 ASCII 表格格式
- null: 简洁的纯文本输出，仅显示行数和执行时间，用于评估查询性能。

Body

sql: SQL 语句。必填。

响应

响应是一个 JSON 对象，包含以下字段：

output: SQL 执行结果，请参阅下面的示例以了解详细信息。
execution_time_ms: 语句的执行时间（毫秒）。

示例

`INSERT` 语句

例如，要向数据库 public 的 monitor 表中插入数据，请使用以下命令：

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'sql=INSERT INTO monitor VALUES ("127.0.0.1", 1667446797450, 0.1, 0.4), ("127.0.0.2", 1667446798450, 0.2, 0.3), ("127.0.0.1", 1667446798450, 0.5, 0.2)' \
  http://localhost:4000/v1/sql?db=public

Response 包含受影响的行数：

{"output":[{"affectedrows":3}],"execution_time_ms":11}

`SELECT` 语句

你还可以使用 HTTP API 执行其他 SQL 语句。例如，从 monitor 表中查询数据：

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=SELECT * FROM monitor" \
  http://localhost:4000/v1/sql?db=public

Response 包含 JSON 格式的查询数据：

{
  "output": [
    {
      "records": {
        "schema": {
          "column_schemas": [
            {
              "name": "host",
              "data_type": "String"
            },
            {
              "name": "ts",
              "data_type": "TimestampMillisecond"
            },
            {
              "name": "cpu",
              "data_type": "Float64"
            },
            {
              "name": "memory",
              "data_type": "Float64"
            }
          ]
        },
        "rows": [
          [
            "127.0.0.1",
            1720728000000,
            0.5,
            0.1
          ]
        ],
        "total_rows": 1
      }
    }
  ],
  "execution_time_ms": 7
}

Response 包含以下字段：

output: 执行结果。
- records: 查询结果。
  - schema: 结果的 schema，包括每列的 schema。
  - rows: 查询结果的行，每行是一个包含 schema 中对应列值的数组。
execution_time_ms: 语句的执行时间（毫秒）。

时区

GreptimeDB 支持 HTTP 请求中的 X-Greptime-Timezone header。它用于为当前 SQL 查询指定时区。

例如，以下请求使用时区 +1:00 进行查询：

curl -X POST \
-H 'Authorization: Basic <base64-encoded-credentials>' \
-H 'X-Greptime-Timezone: +1:00' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'sql=SHOW VARIABLES time_zone;' \
http://localhost:4000/v1/sql

查询后的结果为：

{
  "output": [
    {
      "records": {
        "schema": {
          "column_schemas": [
            {
              "name": "TIME_ZONE",
              "data_type": "String"
            }
          ]
        },
        "rows": [
          [
            "+01:00"
          ]
        ]
      }
    }
  ],
  "execution_time_ms": 27
}

有关时区如何影响数据的写入和查询，请参考写入数据和查询数据部分中的 SQL 文档。

使用 `table` 格式输出查询数据

你可以在查询字符串参数中使用 table 格式，以 ASCII 表格格式获取输出。

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -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    │
└─────────────┴───────────────┴─────┴────────┘

使用 `csvWithNames` 格式输出查询数据

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=SELECT * FROM monitor" \
  http://localhost:4000/v1/sql?db=public&format=csvWithNames

输出：

host,ts,cpu,memory
0.0.1,1667446797450,0.1,0.4
0.0.1,1667446798450,0.5,0.2
0.0.2,1667446798450,0.2,0.3

将 format 改为 csvWithNamesAndTypes：

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=SELECT * FROM monitor" \
  http://localhost:4000/v1/sql?db=public&format=csvWithNamesAndTypes

输出：

host,ts,cpu,memory
String,TimestampMillisecond,Float64,Float64
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

使用 `influxdb_v1` 格式输出查询数据

你可以在查询字符串参数中使用 influxdb_v1 格式，以 InfluxDB 查询 API 兼容格式获取输出。

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=SELECT * FROM monitor" \
  http://localhost:4000/v1/sql?db=public&format=influxdb_v1&epoch=ms

{
  "results": [
    {
      "statement_id": 0,
      "series": [
        {
          "name": "",
          "columns": [
            "host",
            "ts",
            "cpu",
            "memory"
          ],
          "values": [
            ["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]
          ]
        }
      ]
    }
  ],
  "execution_time_ms": 2
}

使用 GreptimeDB 的 SQL 方言格式化 SQL

使用 /v1/sql/format 接口，可以把 SQL 语句改写成 GreptimeDB SQL 方言的规范形式。该接口用 GreptimeDB 的解析器解析输入，再把语句序列化回文本，统一关键字大小写和空白，并在末尾补上分号。它不会重新缩进或换行，每条语句都在一行内返回。适用于在存储或比对 SQL 前做统一规范化。从 v0.17 起支持。

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=select 1 as x" \
  http://localhost:4000/v1/sql/format

响应中包含格式化后的 SQL 字符串：

{
  "formatted": "SELECT 1 AS x;"
}

也可以用 GET 通过查询参数传入 SQL：

curl -X GET \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  'http://localhost:4000/v1/sql/format?sql=select%201%20as%20x'

POST 请求必须设置 Content-Type: application/x-www-form-urlencoded，否则请求会在到达该接口前被拒绝。查询字符串和表单体中都提供 SQL 时，以查询参数为准。

如果输入包含多条语句，formatted 会把它们用换行符连接后一并返回：

{
  "formatted": "SELECT 1 AS x;\nSELECT 2 AS y;"
}

若缺少 sql 参数，接口返回 HTTP 状态码 400，错误码为 1004，错误信息为 sql parameter is required.。若 SQL 无法解析，则返回解析器的报错。

使用 GreptimeDB 的 SQL 方言解析 SQL

为了解析和理解使用 GreptimeDB SQL 方言编写的查询（例如在仪表盘等工具里，为了更好的用户体验，提前解析 SQL 获取表名等），您可以使用 /v1/sql/parse 接口来获取 SQL 查询的结构化结果：

curl -X POST \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "sql=SELECT * FROM monitor" \
  http://localhost:4000/v1/sql/parse

[
  {
    "Query": {
      "inner": {
        "with": null,
        "body": {
          "Select": {
            "select_token": {
              "token": {
                "Word": {
                  "value": "SELECT",
                  "quote_style": null,
                  "keyword": "SELECT"
                }
              },
              "span": {
                "start": {
                  "line": 1,
                  "column": 1
                },
                "end": {
                  "line": 1,
                  "column": 7
                }
              }
            },
            "optimizer_hint": null,
            "distinct": null,
            "select_modifiers": null,
            "top": null,
            "top_before_distinct": false,
            "projection": [
              {
                "Wildcard": {
                  "wildcard_token": {
                    "token": "Mul",
                    "span": {
                      "start": {
                        "line": 1,
                        "column": 8
                      },
                      "end": {
                        "line": 1,
                        "column": 9
                      }
                    }
                  },
                  "opt_ilike": null,
                  "opt_exclude": null,
                  "opt_except": null,
                  "opt_replace": null,
                  "opt_rename": null
                }
              }
            ],
            "exclude": null,
            "into": null,
            "from": [
              {
                "relation": {
                  "Table": {
                    "name": [
                      {
                        "Identifier": {
                          "value": "monitor",
                          "quote_style": null,
                          "span": {
                            "start": {
                              "line": 1,
                              "column": 15
                            },
                            "end": {
                              "line": 1,
                              "column": 22
                            }
                          }
                        }
                      }
                    ],
                    "alias": null,
                    "args": null,
                    "with_hints": [],
                    "version": null,
                    "with_ordinality": false,
                    "partitions": [],
                    "json_path": null,
                    "sample": null,
                    "index_hints": []
                  }
                },
                "joins": []
              }
            ],
            "lateral_views": [],
            "prewhere": null,
            "selection": null,
            "connect_by": [],
            "group_by": {
              "Expressions": [
                [],
                []
              ]
            },
            "cluster_by": [],
            "distribute_by": [],
            "sort_by": [],
            "having": null,
            "named_window": [],
            "qualify": null,
            "window_before_qualify": false,
            "value_table_mode": null,
            "flavor": "Standard"
          }
        },
        "order_by": null,
        "limit_clause": null,
        "fetch": null,
        "locks": [],
        "for_clause": null,
        "settings": null,
        "format_clause": null,
        "pipe_operators": []
      },
      "hybrid_cte": null
    }
  }
]

POST PromQL 查询

API 返回 Prometheus 查询结果格式

GreptimeDB 兼容 Prometheus 查询语言 (PromQL)，可以用于查询 GreptimeDB 中的数据。有关所有兼容的 API，请参阅 Prometheus 查询语言文档。

API 返回 GreptimeDB JSON 格式

GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询，即在当前的 API 路径 /v1 的后方拼接 /promql。该接口的返回值是 GreptimeDB 的 JSON 格式，而不是 Prometheus 的格式。如下示例：

curl -X GET \
  -H 'Authorization: Basic <base64-encoded-credentials>' \
  -G \
  --data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
  --data-urlencode 'start=1667446797' \
  --data-urlencode 'end=1667446799' \
  --data-urlencode 'step=1s' \
  'http://localhost:4000/v1/promql?db=public'

接口中的参数和 Prometheus' HTTP API 的 range_query 接口相似：

db=<database>：在使用 GreptimeDB 进行鉴权操作时必填，如果使用的是 public 数据库则可以忽略该参数。注意这个参数需要被设置在 query param 中，或者通过 --header 'x-greptime-db-name: <database name>' 设置在 HTTP 请求头中。
query=<string>：必填。Prometheus 表达式查询字符串。
start=<rfc3339 | unix_timestamp>：必填。开始时间戳，包含在内。它用于设置 TIME INDEX 列中的时间范围。
end=<rfc3339 | unix_timestamp>：必填。结束时间戳，包含在内。它用于设置 TIME INDEX 列中的时间范围。
step=<duration | float>：必填。查询步长，可以使用持续时间格式或秒数的浮点数。
format: 输出格式。可选。默认为 greptimedb_v1 的 JSON 格式。除了默认的 JSON 格式外，HTTP API 还允许你通过提供 format 查询参数来自定义输出格式，值如下：
- influxdb_v1: influxdb 查询 API 兼容格式。附加参数：
  - epoch: [ns,u,µ,ms,s,m,h]，返回指定精度的时间戳
- csv: 以逗号分隔值格式输出
- csvWithNames: 以逗号分隔值格式输出，包含列名标题
- csvWithNamesAndTypes: 以逗号分隔值格式输出，包含列名和数据类型标题
- arrow: Arrow IPC 格式。附加参数：
  - compression: zstd 或 lz4，默认：无压缩
- table: 控制台输出的 ASCII 表格格式
- null: 简洁的纯文本输出，仅显示行数和执行时间，用于评估查询性能。

以下是每种参数的类型的示例：

rfc3339
- 2015-07-01T20:11:00Z (default to seconds resolution)
- 2015-07-01T20:11:00.781Z (with milliseconds resolution)
- 2015-07-02T04:11:00+08:00 (with timezone offset)
unix timestamp
- 1435781460 (default to seconds resolution)
- 1435781460.781 (with milliseconds resolution)
duration
- 1h (1 hour)
- 5d1m (5 days and 1 minute)
- 2 (2 seconds)
- 2s (also 2 seconds)

结果格式与 Post SQL 语句中描述的 /sql 接口相同。

{
  "output": [
    {
      "records": {
        "schema": {
          "column_schemas": [
            {
              "name": "ts",
              "data_type": "TimestampMillisecond"
            },
            {
              "name": "AVG(system_metrics.cpu_util)",
              "data_type": "Float64"
            },
            {
              "name": "AVG(system_metrics.memory_util)",
              "data_type": "Float64"
            },
            {
              "name": "AVG(system_metrics.disk_util)",
              "data_type": "Float64"
            }
          ]
        },
        "rows": [
          [
            1667446798000,
            80.1,
            70.3,
            90
          ],
          [
            1667446799000,
            80.1,
            70.3,
            90
          ]
        ]
      }
    }
  ],
  "execution_time_ms": 5
}

Post Influxdb line protocol 数据

InfluxDB line protocol V2
InfluxDB line protocol V1

curl -X POST \
  -H 'Authorization: token <username:password>' \
  -d '<influxdb-line-protocol-data>' \
  'http://<API-host>/v1/influxdb/api/v2/write?bucket=<db-name>&precision=<time-precision>'

curl -X POST \
  -d '<influxdb-line-protocol-data>' \
  'http://<API-host>/v1/influxdb/write?u=<username>&p=<password>&precision=<time-precision>'

Headers

Authorization: 与其他 API 不同，InfluxDB 行协议 API 使用 InfluxDB 鉴权格式。对于 V2 协议，Authorization 是 token <username:password>。

Query string parameters

u: 用户名。可选。它是 V1 的鉴权用户名。
p: 密码。可选。它是 V1 的鉴权密码。
bucket: InfluxDB line protocol V2 写入使用的数据库名称。可选。默认值是 public。
db: 数据库名称。这是 InfluxDB line protocol V1 写入的标准参数。V2 API 也接受 db 作为 GreptimeDB 的兼容别名，但 V2 推荐使用 bucket。可选。默认值是 public。
precision: 定义请求体中提供的时间戳的精度。请参考用户指南中的 InfluxDB 行协议文档。

Body

InfluxDB 行协议数据点。请参考 InfluxDB 行协议文档。

示例

请参考用户指南中的 InfluxDB 行协议。

管理 Pipeline 的 API

在将日志写入 GreptimeDB 时，你可以使用 HTTP API 来管理 Pipeline。请参考管理 Pipeline 文档。

HTTP API

Base URL​

通用 Headers​

鉴权​

请求超时设置​

Hints​

Admin APIs​

POST SQL 语句​

Headers​

Query string parameters​

Body​

响应​

示例​

INSERT 语句​

SELECT 语句​

时区​

使用 table 格式输出查询数据​

使用 csvWithNames 格式输出查询数据​

使用 influxdb_v1 格式输出查询数据​

使用 GreptimeDB 的 SQL 方言格式化 SQL​

使用 GreptimeDB 的 SQL 方言解析 SQL​

POST PromQL 查询​

API 返回 Prometheus 查询结果格式​

API 返回 GreptimeDB JSON 格式​

Post Influxdb line protocol 数据​

Headers​

Query string parameters​

Body​

示例​

管理 Pipeline 的 API​

Base URL

通用 Headers

鉴权

请求超时设置

Hints

Admin APIs

POST SQL 语句

Headers

Query string parameters

Body

响应

示例

`INSERT` 语句

`SELECT` 语句

时区

使用 `table` 格式输出查询数据

使用 `csvWithNames` 格式输出查询数据

使用 `influxdb_v1` 格式输出查询数据

使用 GreptimeDB 的 SQL 方言格式化 SQL

使用 GreptimeDB 的 SQL 方言解析 SQL

POST PromQL 查询

API 返回 Prometheus 查询结果格式

API 返回 GreptimeDB JSON 格式

Post Influxdb line protocol 数据

Headers

Query string parameters

Body

示例

管理 Pipeline 的 API