文档文档

InfluxDB 3 Core

使用 InfluxDB v3 HTTP 查询 API

  • InfluxQL
  • SQL

使用 InfluxDB 3 HTTP 查询 API 查询 InfluxDB 3 Core 中的数据。 该 API 提供了 GET 和 POST 端点，用于使用 SQL 或 InfluxQL 查询数据和系统信息。

使用 gRPC 或 HTTP 查询

InfluxDB 3 支持 HTTP 和 Flight (gRPC) 查询 API。 有关使用 Flight 的更多信息，请参阅 InfluxDB 3 (influxdb3-) 客户端库。

以下示例使用 cURL 向 InfluxDB 3 HTTP API 发送 HTTP 请求，但您可以使用任何 HTTP 客户端。

使用 SQL 和 HTTP API 查询

将 /api/v3/query_sql 端点与 GET 或 POST 请求方法一起使用。

  • GET：在 URL 查询字符串中传递参数（用于简单查询）
  • POST：在 JSON 对象中传递参数（用于复杂查询和代码可读性）

包括以下参数

  • q: (必需) 要执行的 SQL 查询。
  • db: (必需) 要对其执行查询的数据库。
  • params: 包含要在参数化查询中使用的参数的 JSON 对象。
  • format: 响应的格式 (json, jsonl, csv, pretty, 或 parquet)。 JSONL (jsonl) 是首选格式，因为它将结果流式传输回客户端。 pretty 用于人类可读的输出。 默认值为 json。

示例：查询传递 URL 编码的参数

以下示例发送一个 HTTP GET 请求，其中包含 URL 编码的 SQL 查询

curl -v "http://localhost:8181/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5"

示例：查询传递 JSON 参数

以下示例发送一个 HTTP POST 请求，其中参数在 JSON 有效负载中

curl http://localhost:8181/api/v3/query_sql \
  --data '{"db": "server", "q": "select * from cpu limit 5"}'

查询系统信息

使用 HTTP API /api/v3/query_sql 端点检索有关 InfluxDB 3 Core 中数据库服务器和表模式的系统信息。

示例

system_ 示例数据

在示例中，带有 "table_name":"system_ 的表是用户创建的表，用于 CPU、内存、磁盘、网络和其他资源统计信息，这些信息由用户收集和写入——例如，使用 psutil Python 库或 Telegraf 收集系统指标并将其写入 InfluxDB 3 数据库。

显示表

以下示例发送一个 GET 请求，该请求执行 show tables 查询以检索数据库的所有用户创建的表 ("table_schema":"iox")、系统表和信息模式表

curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"

响应正文包含以下 JSONL

{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"}

表具有以下 table_schema 值之一

  • iox：数据库用户创建的表。
  • system：系统使用的表，用于显示有关正在运行的数据库服务器的信息。 其中一些表显示存储的信息（例如配置），而另一些表（例如 queries 表）则在内存中保存临时状态。
  • information_schema：显示数据库中表的模式信息的视图。

查看表的列信息

以下查询发送一个 POST 请求，该请求执行 SQL 查询以检索有关示例 system_swap 表模式中列的信息

注意：当您在 JSON 中发送查询时，必须转义包围字段名称的单引号。

curl "http://localhost:8181/api/v3/query_sql" \
  --header "Content-Type: application/json" \
  --json '{
    "db": "mydb",
    "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'",
    "format": "jsonl"
  }'

输出类似于以下内容

{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"percent","ordinal_position":2,"is_nullable":"YES","data_type":"Float64","numeric_precision":24,"numeric_precision_radix":2}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"}

最近执行的查询

要查看最近执行的查询，请查询 queries 系统表

curl "http://localhost:8181/api/v3/query_sql" \
  --header "Content-Type: application/json" \
  --json '{
    "db": "mydb",
    "q": "SELECT * FROM system.queries LIMIT 2",
    "format": "jsonl"
  }'

输出类似于以下内容

{"id":"cdd63409-1822-4e65-8e3a-d274d553dbb3","phase":"success","issue_time":"2025-01-20T17:01:40.690067","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.032689S","permit_duration":"PT0.000202S","execute_duration":"PT0.000223S","end2end_duration":"PT0.033115S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false}
{"id":"47f8d312-5e75-4db2-837a-6fcf94c09927","phase":"success","issue_time":"2025-01-20T17:02:32.627782","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.000583S","permit_duration":"PT0.000015S","execute_duration":"PT0.000063S","end2end_duration":"PT0.000662S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false}

使用 InfluxQL 和 HTTP API 查询

将 /api/v3/query_influxql 端点与 GET 或 POST 请求方法一起使用。

  • GET：在 URL 查询字符串中传递参数（用于简单查询）
  • POST：在 JSON 对象中传递参数（用于复杂查询和代码可读性）

包括以下参数

  • q: (必需) 要执行的 InfluxQL 查询。
  • db: (必需) 要对其执行查询的数据库。
  • params: 包含要在参数化查询中使用的参数的 JSON 对象。
  • format: 响应的格式 (json, jsonl, csv, pretty, 或 parquet)。 JSONL (jsonl) 是首选格式，因为它将结果流式传输回客户端。 pretty 用于人类可读的输出。 默认值为 json。

示例：查询传递 URL 编码的参数

以下示例发送一个 HTTP GET 请求，其中包含 URL 编码的 InfluxQL 查询

curl -v "http://localhost:8181/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5"

示例：查询传递 JSON 参数

以下示例发送一个 HTTP POST 请求，其中参数在 JSON 有效负载中

curl http://localhost:8181/api/v3/query_influxql \
  --data '{"db": "server", "q": "select * from cpu limit 5"}'
    query influxql sql python

    此页内容是否有帮助？

    感谢您的反馈！

    © 2025 InfluxData, Inc.

    您的 InfluxDB 3 Core URL 是什么？

    自定义您的 InfluxDB 3 Core URL，我们将为您更新代码示例。

    默认
    自定义

    有关更多信息，请参阅 InfluxDB Cloud 区域 或 InfluxDB OSS URLs。

    感谢您的反馈！

    请告诉我们如何改进

    谢谢！

    不用了，谢谢

    Flux 的未来

    Flux 即将进入维护模式。 您可以继续像现在一样使用它，而无需对您的代码进行任何更改。

    阅读更多

    现已全面上市

    InfluxDB 3 Core 和 Enterprise

    快速启动。 更快扩展。

    获取更新

    InfluxDB 3 Core 是一个开源、高速、近实时的数据引擎，可实时收集和处理数据，并将其持久化到本地磁盘或对象存储。 InfluxDB 3 Enterprise 构建在 Core 的基础上，增加了高可用性、读取副本、增强的安全性以及数据压缩，以实现更快的查询和优化的存储。 InfluxDB 3 Enterprise 的免费层级可供非商业家庭或业余爱好者使用。

    有关更多信息，请查看