diff --git a/docs/getting-started/installation/overview.md b/docs/getting-started/installation/overview.md index 76b993aa7..6b8e6ae3c 100644 --- a/docs/getting-started/installation/overview.md +++ b/docs/getting-started/installation/overview.md @@ -7,7 +7,7 @@ Follow these instructions to install GreptimeDB: - [GreptimeDB Standalone](greptimedb-standalone.md) runs as a standalone system in a single process. - [GreptimeDB Cluster](greptimedb-cluster.md) runs as a distributed, clustered time series database. -## Check database status +## Check database health After starting GreptimeDB, you can check its status to ensure it is running. diff --git a/docs/reference/sql/http-api.md b/docs/reference/sql/http-api.md deleted file mode 100644 index a1a16d2f7..000000000 --- a/docs/reference/sql/http-api.md +++ /dev/null @@ -1,40 +0,0 @@ -# HTTP API - -To submit a SQL query to the GreptimeDB server via HTTP API, use the following format: - -```shell -curl -X POST \ - -H 'Authorization: Basic {{authentication}}' \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - -d 'sql={{SQL-statement}}' \ -http://{{API-host}}/v1/sql?db={{db-name}} -``` - -## Method - -Use the POST method to submit the SQL statement to the server. - -## Header - -- `Authorization`: The credential. Required if you are using GreptimeDB with authentication enabled. Please refer to [authentication](/user-guide/protocols/http.md#authentication). -- `Content-Type`: `application/x-www-form-urlencoded`. -- `X-Greptime-Timezone`: The time zone for the current SQL query. Optional. Please refer to [time zone](/user-guide/protocols/http.md#time-zone). - -## Query params - -- `db`: The database name. Required if you are using GreptimeDB with authentication enabled. Otherwise, it can be omitted if you are using the default `public` database. - -## Body - -- `sql`: The SQL statement. Required. - -## Response - -The response is a JSON object. - -- `code`: the result integer code. Zero means success, otherwise failure. -- `output`: the SQL executed result, including schema and rows. - -## Example - -Please refer to [POST SQL Statements](/user-guide/protocols/http.md) in the user guide. diff --git a/docs/reference/sql/overview.md b/docs/reference/sql/overview.md index 35f3bcef3..f7c552f0b 100644 --- a/docs/reference/sql/overview.md +++ b/docs/reference/sql/overview.md @@ -1,7 +1,6 @@ # Overview * [Data Types](./data-types) -* [HTTP API](./http-api) * [INSERT](./insert.md) * [CAST](./cast.md) * [COPY](./copy.md) diff --git a/docs/user-guide/administration/manage-data/basic-table-operations.md b/docs/user-guide/administration/manage-data/basic-table-operations.md index dcf039184..5677e262d 100644 --- a/docs/user-guide/administration/manage-data/basic-table-operations.md +++ b/docs/user-guide/administration/manage-data/basic-table-operations.md @@ -347,7 +347,7 @@ http://localhost:4000/v1/sql?db=public { "code": 0, "output": [{ "affectedrows": 1 }], "execution_time_ms": 10 } ``` -For more information about SQL HTTP request, please refer to [API document](/reference/sql/http-api.md). +For more information about SQL HTTP request, please refer to [API document](/user-guide/protocols/http.md#post-sql-statements). ## Time zone diff --git a/docs/user-guide/protocols/http.md b/docs/user-guide/protocols/http.md index 353d783ef..a75a7ffce 100644 --- a/docs/user-guide/protocols/http.md +++ b/docs/user-guide/protocols/http.md @@ -2,7 +2,21 @@ GreptimeDB provides HTTP APIs for interacting with the database. -## Headers +## Base URL + +The base URL of API is `http(s)://:/`. + +- For the GreptimeDB instance running on the local machine, + with default port configuration `4000`, + the base URL is `http://localhost:4000/`. + You can change the server host and port in the [configuration](/user-guide/deployments/configuration#protocol-options) file. + +- For GreptimeCloud, the base URL is `https:///`. + You can find the host in 'Connection Information' at the GreptimeCloud console. + +In the following sections, we use `http://{{API-host}}/` as the base URL to demonstrate the API usage. + +## Common headers ### Authentication @@ -27,69 +41,149 @@ In this example, `Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=` represents the Base64-en InfluxDB uses its own authentication format, see [InfluxDB](./influxdb-line-protocol.md) for details. ::: -### Time zone +### Timeout -GreptimeDB supports the `X-Greptime-Timezone` header in HTTP requests. -It is used to specify the timezone for the current SQL query. +GreptimeDB supports the `X-Greptime-Timeout` header in HTTP requests. +It is used to specify the timeout for the request running in the database server. -For example, the following request uses the time zone `+1:00` for the query: +For example, the following request set `120s` timeout for the request: ```bash curl -X POST \ --H 'X-Greptime-Timezone: +1:00' \ +-H 'X-Greptime-Timeout: 120s' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --d 'sql=SHOW VARIABLES time_zone;' \ +-d 'sql=show tables' \ http://localhost:4000/v1/sql ``` -After the query, the result will be: +## Admin APIs + +:::tip NOTE +These endpoint cannot be used in GreptimeCloud. +::: + +### Check database health + +You can use the `/health` endpoint to check the health of the GreptimeDB server. +For more information, +please refer to [Check Database Health](/getting-started/installation/overview.md#check-database-health). + +### Check Database Status + +You can use the `/status` endpoint to check the status of the GreptimeDB server. + +```shell +curl http://{{API-host}}/status +``` + +For example: + +```shell +curl http://localhost:4000/status +``` + + +The output contains the database version and source code information, +which will be similar to the following: ```json { - "output": [ - { - "records": { - "schema": { - "column_schemas": [ - { - "name": "TIME_ZONE", - "data_type": "String" - } - ] - }, - "rows": [ - [ - "+01:00" - ] - ] - } - } - ], - "execution_time_ms": 27 + "source_time": "2024-11-08T06:34:49Z", + "commit": "0e0c4faf0d784f25fed8f26e7000f1f869c88587", + "branch": "main", + "rustc_version": "rustc 1.84.0-nightly (e92993dbb 2024-10-18)", + "hostname": "local", + "version": "0.9.5" } ``` -For information on how the time zone affects data inserts and queries, please refer to the SQL documents in the [Ingest Data](../ingest-data/for-iot/sql.md#time-zone) and [Query Data](../query-data/sql.md#time-zone) sections. +### Get GreptimeDB server configuration -### TIMEOUT +You can use the `/config` endpoint to get the [TOML configuration](/user-guide/deployments/configuration.md#configuration-file-options) of the GreptimeDB server. -GreptimeDB supports the `X-Greptime-Timeout` header in HTTP requests. -It is used to specify the timeout for the current SQL query. +```shell +curl http://{{API-host}}/config +``` -For example, the following request set `120s` timeout for the query: +For example: -```bash -curl -X POST \ --H 'X-Greptime-Timeout: 120s' \ --H 'Content-Type: application/x-www-form-urlencoded' \ --d 'sql=show tables' \ -http://localhost:4000/v1/sql +```shell +curl http://localhost:4000/config +``` + +The output contains the configuration information of the GreptimeDB server. + +```toml +mode = "standalone" +enable_telemetry = true +user_provider = "static_user_provider:file:user" +init_regions_in_background = false +init_regions_parallelism = 16 + +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MiB" +is_strict_mode = false + +# ... ``` ## POST SQL statements -You can use the GreptimeDB HTTP API to post SQL statements and interact with the database. -For example, to insert data into the `monitor` table, use the following command: +To submit a SQL query to the GreptimeDB server via HTTP API, use the following format: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authentication}}' \ + -H 'X-Greptime-Timeout: {{time precision}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql={{SQL-statement}}' \ +http://{{API-host}}/v1/sql +``` + +### Headers + +- [`Authorization`](#authentication) +- [`X-Greptime-Timeout`](#timeout) +- `Content-Type`: `application/x-www-form-urlencoded`. +- `X-Greptime-Timezone`: The time zone for the current SQL query. Optional. Please refer to [time zone](#time-zone). + +### Query string parameters + +- `db`: The database name. Optional. If not provided, the default database `public` will be used. +- `format`: The output format. Optional. + 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 + +### Body + +- `sql`: The SQL statement. Required. + +### Response + +The response is a JSON object containing the following fields: + +- `output`: The SQL executed result. Please refer to the examples blow to see the details. +- `execution_time_ms`: The execution time of the statement in milliseconds. + +### Examples + +#### `INSERT` statement + +For example, to insert data into the `monitor` table of database `public`, use the following command: ```shell curl -X POST \ @@ -99,10 +193,13 @@ curl -X POST \ http://localhost:4000/v1/sql?db=public ``` -- The API endpoint is `/v1/sql`. -- The authentication header is optional. For more information, refer to the [Authentication](#authentication) section. -- The SQL statement should be included in the body of the request as `sql` parameter. -- The `db` parameter in the URL is optional and specifies the database to use. The default value is `public`. +The response will contain the number of affected rows: + +```shell +{"output":[{"affectedrows":3}],"execution_time_ms":11} +``` + +#### `SELECT` statement You can also use the HTTP API to execute other SQL statements. For example, to retrieve data from the `monitor` table: @@ -166,25 +263,53 @@ 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 +#### Time zone -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: +GreptimeDB supports the `X-Greptime-Timezone` header in HTTP requests. +It is used to specify the timezone for the current SQL query. + +For example, the following request uses the time zone `+1:00` for the query: + +```bash +curl -X POST \ +-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 +``` + +After the query, the result will be: + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "TIME_ZONE", + "data_type": "String" + } + ] + }, + "rows": [ + [ + "+01:00" + ] + ] + } + } + ], + "execution_time_ms": 27 +} +``` -- `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 +For information on how the time zone affects data inserts and queries, please refer to the SQL documents in the [Ingest Data](../ingest-data/for-iot/sql.md#time-zone) and [Query Data](../query-data/sql.md#time-zone) sections. + +#### Query data with `table` format output -Call the SQL API with `table` format as an example: +You can use the `table` format in the query string parameters to get the output in ASCII table format. ```shell curl -X POST \ @@ -204,11 +329,61 @@ Output └─────────────┴───────────────┴─────┴────────┘ ``` -## POST PromQL Queries +#### Query data with `influxdb_v1` format output + +You can use the `influxdb_v1` format in the query string parameters to get the output in InfluxDB query API compatible format. + +```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=influxdb_v1&epoch=ms +``` + +```json +{ + "results": [ + { + "statement_id": 0, + "series": [ + { + "name": "", + "columns": [ + "host", + "cpu", + "memory", + "ts" + ], + "values": [ + [ + ["127.0.0.1", 0.1, 0.4, 1667446797450], + ["127.0.0.1", 0.5, 0.2, 1667446798450], + ["127.0.0.2", 0.2, 0.3, 1667446798450] + ] + ] + } + ] + } + ], + "execution_time_ms": 2 +} +``` + +## POST PromQL queries + +### The API returns Prometheus query result format + +GreptimeDB compatible with Prometheus query language (PromQL) and can be used to query data in GreptimeDB. +For all the compatible APIs, please refer to the [Prometheus Query Language](/user-guide/query-data/promql#prometheus-http-api) documentation. + +### The API returns GreptimeDB JSON format GreptimeDB also exposes an custom HTTP API for querying with PromQL, and returning GreptimeDB's data frame output. You can find it on `/promql` path under the -current stable API version `/v1`. For example: +current stable API version `/v1`. +The return value of this API is in GreptimeDB's JSON format, not Prometheus's format. +For example: ```shell curl -X GET \ @@ -293,3 +468,56 @@ The result format is the same as `/sql` interface described in [Post SQL stateme "execution_time_ms": 5 } ``` + +## Post Influxdb line protocol data + + + + + +```shell +curl -X POST \ + -H 'Authorization: token :' \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v2/write?precision={{time-precision}} +``` + + + + + +```shell +curl -X POST \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v1/write?u={{username}}&p={{password}}&precision={{time-precision}} +``` + + + + +### Headers + +- `Authorization`: **Unlike other APIs**, the InfluxDB line protocol APIs use the InfluxDB authentication format. For V2, it is `token :`. + +### Query string parameters + +- `u`: The username. Optional. It is the authentication username for V1. +- `p`: The password. Optional. It is the authentication password for V1. +- `db`: The database name. Optional. The default value is `public`. +- `precision`: Defines the precision of the timestamp provided in the request body. Please refer to [InfluxDB Line Protocol](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) in the user guide. + +### Body + +The InfluxDB line protocol data points. Please refer to the [InfluxDB Line Protocol](https://docs.influxdata.com/influxdb/v1/write_protocols/line_protocol_tutorial/#syntax) document. + +### Examples + +Please refer to [InfluxDB Line Protocol](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) in the user guide. + +## API for managing Pipelines + +When writing logs to GreptimeDB, +you can use HTTP APIs to manage the pipelines. +For detailed information, +please refer to the [Manage Pipelines](/user-guide/logs/manage-pipelines.md) documentation. + diff --git a/docs/user-guide/query-data/promql.md b/docs/user-guide/query-data/promql.md index 94b69c7f7..5ec41f6ae 100644 --- a/docs/user-guide/query-data/promql.md +++ b/docs/user-guide/query-data/promql.md @@ -26,6 +26,60 @@ of these API. You can use additional query parameter `db` to specify GreptimeDB database name. +For example, the following query will return the CPU usage of the `process_cpu_seconds_total` metric in the `public` database: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + --data-urlencode 'query=irate(process_cpu_seconds_total[1h])' \ + --data-urlencode 'start=2024-11-24T00:00:00Z' \ + --data-urlencode 'end=2024-11-25T00:00:00Z' \ + --data-urlencode 'step=1h' \ + --data-urlencode 'db=public' \ + http://localhost:4000/v1/prometheus/api/v1/query_range +``` +If authentication is enabled in GreptimeDB, the authentication header is required. Refer to the [authentication documentation](/user-guide/protocols/http.md#authentication) for more details. + +The query string parameters for the API are identical to those of the original [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries), with the exception of the additional `db` parameter, which specifies the GreptimeDB database name. + +The output format is compatible with the Prometheus API: + +```json +{ + "status": "success", + "data": { + "resultType": "matrix", + "result": [ + { + "metric": { + "job": "node", + "instance": "node_exporter:9100", + "__name__": "process_cpu_seconds_total" + }, + "values": [ + [ + 1732618800, + "0.0022222222222222734" + ], + [ + 1732622400, + "0.0009999999999999788" + ], + [ + 1732626000, + "0.0029999999999997585" + ], + [ + 1732629600, + "0.002222222222222175" + ] + ] + } + ] + } +} +``` + ## SQL GreptimeDB also extends SQL grammar to support PromQL. You can start with the `TQL` (Time-series Query Language) keyword to write parameters and queries. The grammar looks like this: diff --git a/docs/user-guide/query-data/sql.md b/docs/user-guide/query-data/sql.md index b862638d9..91993b9b9 100644 --- a/docs/user-guide/query-data/sql.md +++ b/docs/user-guide/query-data/sql.md @@ -479,4 +479,4 @@ The result is shown below: } ``` -For more information about SQL HTTP request, please refer to [API document](/reference/sql/http-api.md). +For more information about SQL HTTP request, please refer to [API document](/user-guide/protocols/http.md#post-sql-statements). diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation/overview.md index e4db6cf59..430f34ce5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation/overview.md @@ -7,7 +7,7 @@ - [GreptimeDB 单机模式](greptimedb-standalone.md) - [GreptimeDB 分布式集群](greptimedb-cluster.md) -## 检查数据库状态 +## 检查数据库健康状态 启动 GreptimeDB 后,你可以检查其状态以确保其正常运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/http-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/http-api.md deleted file mode 100644 index 70b64d10d..000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/http-api.md +++ /dev/null @@ -1,40 +0,0 @@ -# HTTP API - -要通过 HTTP API 向 GreptimeDB 服务器提交 SQL 查询,请使用以下格式: - -```shell -curl -X POST \ - -H 'Authorization: Basic {{authentication}}' \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - -d 'sql={{SQL-statement}}' \ -http://{{API-host}}/v1/sql?db={{db-name}} -``` - -## Method - -请使用 POST 方法 - -## Header - -- `Authorization`: 身份凭证。如果你使用启用了身份验证的 GreptimeDB,则此项为必需。 请参考[鉴权](/user-guide/protocols/http.md#authentication)。 -- `Content-Type`: `application/x-www-form-urlencoded`。 -- `X-Greptime-Timezone`: 当前 SQL 语句使用的时区,可选。请参考[时区](/user-guide/protocols/http.md#时区). - -## Query 参数 - -- `db`: 数据库名称。如果你使用启用了需要身份验证的 GreptimeDB,则此项必需。如果使用默认的 `public` 数据库就可以省略这一项。 - -## Body - -- `sql`: SQL 语句,必需。 - -## Response - -请求的响应是一个 JSON 对象。 - -- `code`: 结果状态码,0 代表成功,其他代表失败。 -- `output`: SQL 的执行结果,包括 Schema 和数据。 - -## 示例 - -请参考用户指南中的 [POST SQL 语句](/user-guide/protocols/http.md#post-sql-语句)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/overview.md index 4a67622ab..8d5fa9fc7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/overview.md @@ -1,7 +1,6 @@ # 概述 * [数据类型](./data-types) -* [HTTP API](./http-api) * [INSERT](./insert.md) * [CAST](./cast.md) * [COPY](./copy.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/administration/manage-data/basic-table-operations.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/administration/manage-data/basic-table-operations.md index ce19f7790..ac36a5b7d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/administration/manage-data/basic-table-operations.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/administration/manage-data/basic-table-operations.md @@ -344,7 +344,7 @@ http://localhost:4000/v1/sql?db=public { "code": 0, "output": [{ "affectedrows": 1 }], "execution_time_ms": 10 } ``` -关于 SQL HTTP 请求的更多信息,请参考 [API 文档](/reference/sql/http-api.md)。 +关于 SQL HTTP 请求的更多信息,请参考 [API 文档](/user-guide/protocols/http.md#post-sql-语句)。 ## 时区 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 4c6c63f38..5cb7f0ab5 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 @@ -2,7 +2,16 @@ GreptimeDB 提供了 HTTP API 用于与数据库进行交互。 -## Headers +## Base URL + +API Base URL 是 `http(s)://:/`。 + +- 对于在本地机器上运行的 GreptimeDB 实例,Base URL 是 `http://localhost:4000/`,默认端口配置为 `4000`。你可以在[配置文件](/user-guide/deployments/configuration#protocol-options)中更改服务的 host 和 port。 +- 对于 GreptimeCloud,Base URL 是 `https:///`。你可以在 GreptimeCloud 控制台的 "Connection Information" 中找到 host。 + +在以下内容中,我们使用 `http://{{API-host}}/` 作为 Base URL 来演示 API。 + +## 通用 Headers ### 鉴权 @@ -73,7 +82,7 @@ http://localhost:4000/v1/sql ### 请求超时设置 -GreptimeDB 支持在 HTTP 请求中使用 `X-Greptime-Timeout` 请求头,用于指定当前 SQL 查询的超时时间。 +GreptimeDB 支持在 HTTP 请求中使用 `X-Greptime-Timeout` 请求头,用于指定数据库服务器中运行的请求超时时间。 例如,以下请求为查询设置了 `120s` 的超时时间: @@ -85,10 +94,127 @@ curl -X POST \ http://localhost:4000/v1/sql ``` +## Admin APIs + +:::tip 注意 +这些 API 在 GreptimeCloud 中无法使用。 +::: + +### 检查数据库健康状态 + +你可以使用 `/health` 端点检查 GreptimeDB 服务器的健康状况。 +有关更多信息,请参阅[检查数据库健康状态](/getting-started/installation/overview#检查数据库健康状态)。 + +### 检查数据库状态 + +你可以使用 `/status` 端点检查 GreptimeDB 服务器的状态。 + +```shell +curl http://{{API-host}}/status +``` + +例如: + +```shell +curl http://localhost:4000/status +``` + +输出包含数据库版本和源代码信息,类似如下: + +```json +{ + "source_time": "2024-11-08T06:34:49Z", + "commit": "0e0c4faf0d784f25fed8f26e7000f1f869c88587", + "branch": "main", + "rustc_version": "rustc 1.84.0-nightly (e92993dbb 2024-10-18)", + "hostname": "local", + "version": "0.9.5" +} +``` + +### 获取 GreptimeDB 服务器配置 + +你可以使用 `/config` 端点获取 GreptimeDB 服务器的 [TOML 配置](/user-guide/deployments/configuration.md#configuration-file-options)。 + +```shell +curl http://{{API-host}}/config +``` + +例如: + +```shell +curl http://localhost:4000/config +``` + +输出包含 GreptimeDB 服务器的配置信息。 + +```toml +mode = "standalone" +enable_telemetry = true +user_provider = "static_user_provider:file:user" +init_regions_in_background = false +init_regions_parallelism = 16 + +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MiB" +is_strict_mode = false + +# ... +``` + ## POST SQL 语句 -你可以使用 GreptimeDB 的 HTTP API 发送 SQL 语句与数据库进行交互。 -例如,要将数据插入到 `monitor` 表中,可以使用以下命令: +要通过 HTTP API 向 GreptimeDB 服务器提交 SQL 语句,请使用以下格式: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authentication}}' \ + -H 'X-Greptime-Timeout: {{time precision}}' \ + -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`: 输出格式。可选。 + 除了默认的 JSON 格式外,HTTP API 还允许你通过提供 `format` 查询参数来自定义输出格式,值如下: + - `influxdb_v1`: [influxdb 查询 + API](https://docs.influxdata.com/influxdb/v1/tools/api/#query-http-endpoint) + 兼容格式。附加参数: + - `epoch`: `[ns,u,µ,ms,s,m,h]`,返回指定精度的时间戳 + - `csv`: 逗号分隔值输出 + - `arrow`: [Arrow IPC + 格式](https://arrow.apache.org/docs/python/feather.html)。附加参数: + - `compression`: `zstd` 或 `lz4`,默认:无压缩 + - `table`: 控制台输出的 ASCII 表格格式 + +### Body + +- `sql`: SQL 语句。必填。 + +### 响应 + +响应是一个 JSON 对象,包含以下字段: + +- `output`: SQL 执行结果,请参阅下面的示例以了解详细信息。 +- `execution_time_ms`: 语句的执行时间(毫秒)。 + +### 示例 + +#### `INSERT` 语句 + +例如,要向数据库 `public` 的 `monitor` 表中插入数据,请使用以下命令: ```shell curl -X POST \ @@ -98,13 +224,15 @@ curl -X POST \ http://localhost:4000/v1/sql?db=public ``` -- API endpoint 为 `/v1/sql`。 -- 鉴权 header 可选。有关更多信息,请参考[鉴权](#鉴权)部分。 -- SQL 语句应包含在请求的 body 中作为 `sql` 的参数。 -- URL 中的 `db` 参数可选,用于指定要使用的数据库。默认值为 `public`。 +Response 包含受影响的行数: + +```shell +{"output":[{"affectedrows":3}],"execution_time_ms":11} +``` -你还可以使用 HTTP API 执行其他 SQL 语句。 -例如,从 `monitor` 表中搜索数据: +#### `SELECT` 语句 + +你还可以使用 HTTP API 执行其他 SQL 语句。例如,从 `monitor` 表中查询数据: ```shell curl -X POST \ @@ -114,7 +242,7 @@ curl -X POST \ http://localhost:4000/v1/sql?db=public ``` -响应 JSON 格式的数据: +Response 包含 JSON 格式的查询数据: ```json { @@ -157,32 +285,61 @@ curl -X POST \ } ``` +Response 包含以下字段: -结果包含以下字段: +- `output`: 执行结果。 + - `records`: 查询结果。 + - `schema`: 结果的 schema,包括每列的 schema。 + - `rows`: 查询结果的行,每行是一个包含 schema 中对应列值的数组。 +- `execution_time_ms`: 语句的执行时间(毫秒)。 -- `output`:执行结果。 - - `records`:查询结果。 - - `schema`:结果的 schema,包括每个列的 schema。 - - `rows`:查询结果的行数据,每行是一个数组,包含 schema 中对应列的值。 -- `execution_time_ms`:该语句的执行时间,以毫秒为单位。 +#### 时区 -### 其他输出格式 +GreptimeDB 支持 HTTP 请求中的 `X-Greptime-Timezone` header。 +它用于为当前 SQL 查询指定时区。 +例如,以下请求使用时区 `+1:00` 进行查询: -除了默认的 JSON 格式外,通过指定 `format` 参数,HTTP API 还支持自定义以下输出格 -式: +```bash +curl -X POST \ +-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 +``` -- `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` 格式为例: +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "TIME_ZONE", + "data_type": "String" + } + ] + }, + "rows": [ + [ + "+01:00" + ] + ] + } + } + ], + "execution_time_ms": 27 +} +``` + +有关时区如何影响数据的写入和查询,请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md#time-zone)和[查询数据](/user-guide/query-data/sql.md#时区)部分中的 SQL 文档。 + +#### 使用 `table` 格式输出查询数据 + +你可以在查询字符串参数中使用 `table` 格式,以 ASCII 表格格式获取输出。 ```shell curl -X POST \ @@ -192,7 +349,7 @@ curl -X POST \ http://localhost:4000/v1/sql?db=public&format=table ``` -结果: +输出 ``` ┌─host────────┬─ts────────────┬─cpu─┬─memory─┐ @@ -202,10 +359,59 @@ curl -X POST \ └─────────────┴───────────────┴─────┴────────┘ ``` +#### 使用 `influxdb_v1` 格式输出查询数据 + +你可以在查询字符串参数中使用 `influxdb_v1` 格式,以 InfluxDB 查询 API 兼容格式获取输出。 + +```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=influxdb_v1&epoch=ms +``` + +```json +{ + "results": [ + { + "statement_id": 0, + "series": [ + { + "name": "", + "columns": [ + "host", + "cpu", + "memory", + "ts" + ], + "values": [ + [ + ["127.0.0.1", 0.1, 0.4, 1667446797450], + ["127.0.0.1", 0.5, 0.2, 1667446798450], + ["127.0.0.2", 0.2, 0.3, 1667446798450] + ] + ] + } + ] + } + ], + "execution_time_ms": 2 +} +``` ## POST PromQL 查询 -GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询,即在当前的 API 路径 `/v1` 的后方拼接 `/promql`,如下示例: +### API 返回 Prometheus 查询结果格式 + +GreptimeDB 兼容 Prometheus 查询语言 (PromQL),可以用于查询 GreptimeDB 中的数据。 +有关所有兼容的 API,请参阅 [Prometheus 查询语言](/user-guide/query-data/promql#prometheus-http-api) 文档。 + +### API 返回 GreptimeDB JSON 格式 + +GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询,即在当前的 API 路径 `/v1` 的后方拼接 `/promql`。 +该接口的返回值是 GreptimeDB 的 JSON 格式,而不是 Prometheus 的格式。 +如下示例: ```shell curl -X GET \ @@ -290,3 +496,53 @@ curl -X GET \ "execution_time_ms": 5 } ``` + +## Post Influxdb line protocol 数据 + + + + + +```shell +curl -X POST \ + -H 'Authorization: token :' \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v2/write?precision={{time-precision}} +``` + + + + + +```shell +curl -X POST \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v1/write?u={{username}}&p={{password}}&precision={{time-precision}} +``` + + + + +### Headers + +- `Authorization`: **与其他 API 不同**,InfluxDB 行协议 API 使用 InfluxDB 鉴权格式。对于 V2 协议,Authorization 是 `token :`。 + +### Query string parameters + +- `u`: 用户名。可选。它是 V1 的鉴权用户名。 +- `p`: 密码。可选。它是 V1 的鉴权密码。 +- `db`: 数据库名称。可选。默认值是 `public`。 +- `precision`: 定义请求体中提供的时间戳的精度。请参考用户指南中的 [InfluxDB 行协议](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md)文档。 + +### Body + +InfluxDB 行协议数据点。请参考 [InfluxDB 行协议](https://docs.influxdata.com/influxdb/v1/write_protocols/line_protocol_tutorial/#syntax) 文档。 + +### 示例 + +请参考用户指南中的 [InfluxDB 行协议](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md)。 + +## 管理 Pipeline 的 API + +在将日志写入 GreptimeDB 时,你可以使用 HTTP API 来管理 Pipeline。 +请参考 [管理 Pipeline](/user-guide/logs/manage-pipelines.md) 文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/promql.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/promql.md index 97a866326..1adf2247e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/promql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/promql.md @@ -25,6 +25,60 @@ GreptimeDB 实现了兼容 Prometheus 的一系列 API ,通过 `/v1/prometheus 你可以通过设置 HTTP 请求的 `db` 参数来指定 GreptimeDB 中的数据库名。 +例如,以下查询将返回 `public` 数据库中 `process_cpu_seconds_total` 指标的 CPU 使用率: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + --data-urlencode 'query=irate(process_cpu_seconds_total[1h])' \ + --data-urlencode 'start=2024-11-24T00:00:00Z' \ + --data-urlencode 'end=2024-11-25T00:00:00Z' \ + --data-urlencode 'step=1h' \ + --data-urlencode 'db=public' \ + http://localhost:4000/v1/prometheus/api/v1/query_range +``` + +如果你使用启用了身份验证的 GreptimeDB,则需要 Authorization header,请参阅[鉴权](/user-guide/protocols/http.md#鉴权)。 +该 API 的查询字符串参数与原始 [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) 的查询字符串参数相同,但额外的 `db` 参数除外,该参数指定了 GreptimeDB 数据库名称。 + +输出格式与 Prometheus API 完全兼容: + +```json +{ + "status": "success", + "data": { + "resultType": "matrix", + "result": [ + { + "metric": { + "job": "node", + "instance": "node_exporter:9100", + "__name__": "process_cpu_seconds_total" + }, + "values": [ + [ + 1732618800, + "0.0022222222222222734" + ], + [ + 1732622400, + "0.0009999999999999788" + ], + [ + 1732626000, + "0.0029999999999997585" + ], + [ + 1732629600, + "0.002222222222222175" + ] + ] + } + ] + } +} +``` + ## SQL GreptimeDB 还扩展了 SQL 语法以支持 PromQL。可以用 `TQL`(Time-series Query Language)为关键字开始写入参数和进行查询。该语法如下: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/sql.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/sql.md index bc31455f2..112185d90 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/sql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/sql.md @@ -458,4 +458,4 @@ http://localhost:4000/v1/sql?db=public } ``` -请参考 [API 文档](/reference/sql/http-api.md)获取更详细的 HTTP 请求的内容。 +请参考 [API 文档](/user-guide/protocols/http.md#post-sql-语句)获取更详细的 HTTP 请求的内容。 diff --git a/sidebars.ts b/sidebars.ts index 8a368427d..9ad43478a 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -375,7 +375,6 @@ const sidebars: SidebarsConfig = { items: [ 'reference/sql/overview', 'reference/sql/data-types', - 'reference/sql/http-api', 'reference/sql/insert', 'reference/sql/case', 'reference/sql/cast',