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