HTTP API

GreptimeDB 提供了 HTTP API 用于与数据库进行交互。

Headers

鉴权

GreptimeDB 支持 HTTP API 中内置的 Basic 鉴权机制。要设置鉴权，请按照以下步骤操作：

  1. 使用 <username:password> 格式和 Base64 算法对用户名和密码进行编码。
  2. 使用 Authorization : Basic <base64-encoded-credentials> 格式将编码后的凭据附加到 HTTP 请求头中。

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

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

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

HTTP API - 图1注意

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

时区

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

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

1. curl -X POST \
2. -H 'X-Greptime-Timezone: +1:00' \
3. -H 'Content-Type: application/x-www-form-urlencoded' \
4. -d 'sql=SHOW VARIABLES time_zone;' \
5. http://localhost:4000/v1/sql

结果为：

1. {
2. "output": [
3. {
4. "records": {
5. "schema": {
6. "column_schemas": [
7. {
8. "name": "TIME_ZONE",
9. "data_type": "String"
10. }
11. ]
12. },
13. "rows": [
14. [
15. "+01:00"
16. ]
17. ]
18. }
19. }
20. ],
21. "execution_time_ms": 27
22. }

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

POST SQL 语句

你可以使用 GreptimeDB 的 HTTP API 发送 SQL 语句与数据库进行交互。 例如，要将数据插入到 monitor 表中，可以使用以下命令：

1. curl -X POST \
2. -H 'Authorization: Basic {{authorization if exists}}' \
3. -H 'Content-Type: application/x-www-form-urlencoded' \
4. -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)' \
5. http://localhost:4000/v1/sql?db=public
  • API endpoint 为 /v1/sql。
  • 鉴权 header 可选。有关更多信息，请参考鉴权部分。
  • SQL 语句应包含在请求的 body 中作为 sql 的参数。
  • URL 中的 db 参数可选，用于指定要使用的数据库。默认值为 public。

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

1. curl -X POST \
2. -H 'Authorization: Basic {{authorization if exists}}' \
3. -H 'Content-Type: application/x-www-form-urlencoded' \
4. -d "sql=SELECT * FROM monitor" \
5. http://localhost:4000/v1/sql?db=public

响应 JSON 格式的数据：

1. {
2. "output": [
3. {
4. "records": {
5. "schema": {
6. "column_schemas": [
7. {
8. "name": "host",
9. "data_type": "String"
10. },
11. {
12. "name": "ts",
13. "data_type": "TimestampMillisecond"
14. },
15. {
16. "name": "cpu",
17. "data_type": "Float64"
18. },
19. {
20. "name": "memory",
21. "data_type": "Float64"
22. }
23. ]
24. },
25. "rows": [
26. [
27. "127.0.0.1",
28. 1720728000000,
29. 0.5,
30. 0.1
31. ]
32. ],
33. "total_rows": 1
34. }
35. }
36. ],
37. "execution_time_ms": 7
38. }

结果包含以下字段：

  • output：执行结果。
  • records：查询结果。
    • schema：结果的 schema，包括每个列的 schema。
    • rows：查询结果的行数据，每行是一个数组，包含 schema 中对应列的值。
  • execution_time_ms：该语句的执行时间，以毫秒为单位。

POST PromQL 查询

GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询，即在当前的 API 路径 /v1 的后方拼接 /promql，如下示例：

1. curl -X GET \
2. -H 'Authorization: Basic {{authorization if exists}}' \
3. -G \
4. --data-urlencode 'db=public' \
5. --data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
6. --data-urlencode 'start=1667446797' \
7. --data-urlencode 'end=1667446799' \
8. --data-urlencode 'step=1s' \
9. http://localhost:4000/v1/promql

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

  • db=<database>：在使用 GreptimeDB 进行鉴权操作时必填。
  • query=<string>：必填。Prometheus 表达式查询字符串。
  • start=<rfc3339 | unix_timestamp>：必填。开始时间戳，包含在内。它用于设置 TIME INDEX 列中的时间范围。
  • end=<rfc3339 | unix_timestamp>：必填。结束时间戳，包含在内。它用于设置 TIME INDEX 列中的时间范围。
  • step=<duration | float>：必填。查询步长，可以使用持续时间格式或秒数的浮点数。

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

  • 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 接口相同。

1. {
2. "code": 0,
3. "output": [
4. {
5. "records": {
6. "schema": {
7. "column_schemas": [
8. {
9. "name": "ts",
10. "data_type": "TimestampMillisecond"
11. },
12. {
13. "name": "AVG(system_metrics.cpu_util)",
14. "data_type": "Float64"
15. },
16. {
17. "name": "AVG(system_metrics.memory_util)",
18. "data_type": "Float64"
19. },
20. {
21. "name": "AVG(system_metrics.disk_util)",
22. "data_type": "Float64"
23. }
24. ]
25. },
26. "rows": [
27. [
28. 1667446798000,
29. 80.1,
30. 70.3,
31. 90
32. ],
33. [
34. 1667446799000,
35. 80.1,
36. 70.3,
37. 90
38. ]
39. ]
40. }
41. }
42. ],
43. "execution_time_ms": 5
44. }