Skip to content

Commit 081be27

Browse files
jstirnamanjstirnaman
committed
feat(mono): Query using the HTTP API
- Adds Execute queries guide for SQL and InfluxQL query endpoints. - Fixes.
1 parent 7ce4497 commit 081be27

File tree

5 files changed

+262
-2
lines changed

5 files changed

+262
-2
lines changed

‎content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Use the InfluxDB v3 HTTP query API to query data
3+
seotitle: Use SQL or InfluxQL and InfluxDB v3 HTTP query API
4+
list_title: Use the v3 query API
5+
description: >
6+
Use SQL or InfluxQL and the InfluxDB v3 HTTP query API to query data in {{< product-name >}}.
7+
weight: 301
8+
menu:
9+
influxdb3_core:
10+
parent: Execute queries
11+
name: Use the v3 query API
12+
influxdb3/core/tags: [query, influxql, sql, python]
13+
metadata: [InfluxQL, SQL]
14+
related:
15+
- /influxdb3/core/api-compatibility/v1/
16+
aliases:
17+
- /influxdb3/core/query-data/influxql/execute-queries/influxdb-v1-api/
18+
list_code_example: |
19+
```sh
20+
curl --get http://{{< influxdb/host >}}/api/v3/query_sql \
21+
--header "Authorization: Token DATABASE_TOKEN" \
22+
--data-urlencode "db=DATABASE_NAME" \
23+
--data-urlencode "q=SELECT * FROM home"
24+
```
25+
source: /shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
26+
---
27+
28+
<!--
29+
The content for this page is at
30+
// SOURCE content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
31+
-->

‎content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ list_title: Use the v1 query API and InfluxQL
55
description: >
66
Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}}
77
with InfluxQL.
8-
weight: 302
8+
weight: 303
99
menu:
1010
influxdb3_enterprise:
1111
parent: Execute queries

‎content/influxdb3/enterprise/query-data/execute-queries/influxdb-v3-api.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Use the InfluxDB v3 HTTP query API to query data
3+
seotitle: Use SQL or InfluxQL and InfluxDB v3 HTTP query API
4+
list_title: Use the v3 query API
5+
description: >
6+
Use SQL or InfluxQL and the InfluxDB v3 HTTP query API to query data in {{< product-name >}}.
7+
weight: 301
8+
menu:
9+
influxdb3_enterprise:
10+
parent: Execute queries
11+
name: Use the v3 query API
12+
influxdb3/enterprise/tags: [query, influxql, sql, python]
13+
metadata: [InfluxQL, SQL]
14+
related:
15+
- /influxdb3/enterprise/api-compatibility/v1/
16+
aliases:
17+
- /influxdb3/enterprise/query-data/influxql/execute-queries/influxdb-v1-api/
18+
list_code_example: |
19+
```sh
20+
curl --get http://{{< influxdb/host >}}/api/v3/query_sql \
21+
--header "Authorization: Token DATABASE_TOKEN" \
22+
--data-urlencode "db=DATABASE_NAME" \
23+
--data-urlencode "q=SELECT * FROM home"
24+
```
25+
source: /shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
26+
---
27+
28+
<!--
29+
The content for this page is at
30+
// SOURCE content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
31+
-->

‎content/shared/influxdb3-admin/query-system-data/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ You can query the system tables for information about your running server, datab
1111

1212
### Use the HTTP query API
1313

14-
Use the HTTP API `/api/v3/query_sql` endpoint to retrieve and system information about your database server and table schemas in {{% product-name %}}.
14+
Use the HTTP API `/api/v3/query_sql` endpoint to retrieve system information about your database server and table schemas in {{% product-name %}}.
1515

1616
> [!Note]
1717
> {{% product-name %}} uses separate API endpoints for SQL and InfluxQL queries.

‎content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
2+
Use the InfluxDB 3 HTTP query API to query data in {{< product-name >}}.
3+
The API provides `GET` and `POST` endpoints for querying data and system information using SQL or InfluxQL.
4+
5+
> [!Note]
6+
> #### Query using gRPC or HTTP
7+
>
8+
> InfluxDB 3 supports HTTP and Flight (gRPC) query APIs.
9+
> For more information about using Flight, see the [InfluxDB 3 (`influxdb3-`) client libraries](https://github.com/InfluxCommunity/).
10+
11+
The examples below use **cURL** to send HTTP requests to the InfluxDB 3 HTTP API,
12+
but you can use any HTTP client.
13+
14+
- [Query using SQL and the HTTP API](#query-using-sql-and-the-http-api)
15+
- [Query using InfluxQL and the HTTP API](#query-using-influxql-and-the-http-api)
16+
17+
## Query using SQL and the HTTP API
18+
19+
Use the `/api/v3/query_sql` endpoint with the `GET` or `POST` request methods.
20+
21+
- `GET`: Pass parameters in the URL query string (for simple queries)
22+
- `POST`: Pass parameters in a JSON object (for complex queries and readability in your code)
23+
24+
Include the following parameters:
25+
26+
- `q`: _({{< req >}})_ The **SQL** query to execute.
27+
- `db`: _({{< req >}})_ The database to execute the query against.
28+
- `params`: A JSON object containing parameters to be used in a _parameterized query_.
29+
- `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`).
30+
JSONL (`jsonl`) is preferred because it streams results back to the client.
31+
`pretty` is for human-readable output. Default is `json`.
32+
33+
### Example: Query passing URL-encoded parameters
34+
35+
The following example sends an HTTP `GET` request with a URL-encoded SQL query:
36+
37+
```bash
38+
curl -v "http://{{< influxdb/host >}}/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5"
39+
```
40+
41+
### Example: Query passing JSON parameters
42+
43+
The following example sends an HTTP `POST` request with parameters in a JSON payload:
44+
45+
```bash
46+
curl http://{{< influxdb/host >}}/api/v3/query_sql \
47+
--data '{"db": "server", "q": "select * from cpu limit 5"}'
48+
```
49+
50+
### Query system information
51+
52+
Use the HTTP API `/api/v3/query_sql` endpoint to retrieve system information about your database server and table schemas in {{% product-name %}}.
53+
54+
> [!Note]
55+
> {{% product-name %}} uses separate API endpoints for SQL and InfluxQL queries.
56+
> Both endpoints support the same parameters.
57+
>
58+
> For more information about using InfluxQL, see [Query data with InfluxQL](/influxdb3/version/query-data/influxql/).
59+
60+
#### Examples
61+
62+
> [!Note]
63+
> #### system_ sample data
64+
>
65+
> In examples, tables with `"table_name":"system_` are user-created tables for CPU, memory, disk,
66+
> network, and other resource statistics collected and written
67+
> by the user--for example, using the `psutil` Python library or
68+
> [Telegraf](https://docs.influxdata.com/telegraf/v1/get-started/) to collect
69+
> and write system metrics to an InfluxDB 3 database.
70+
71+
##### Show tables
72+
73+
The following example sends a `GET` request that executes a `show tables` query
74+
to retrieve all user-created
75+
tables (`"table_schema":"iox"`), system tables, and information schema tables
76+
for a database:
77+
78+
```bash
79+
curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"
80+
```
81+
82+
The response body contains the following JSONL:
83+
84+
```jsonl
85+
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"}
86+
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"}
87+
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"}
88+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"}
89+
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"}
90+
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"}
91+
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"}
92+
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"}
93+
{"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"}
94+
{"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"}
95+
{"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"}
96+
{"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"}
97+
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"}
98+
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"}
99+
{"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"}
100+
{"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"}
101+
{"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"}
102+
{"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"}
103+
{"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"}
104+
{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"}
105+
```
106+
107+
A table has one of the following `table_schema` values:
108+
109+
- `iox`: tables created by the user of the database.
110+
- `system`: tables used by the system to show information about the running database server.
111+
Some of these tables show stored information such as configurations,
112+
while others, such as the `queries` table, hold ephemeral state in memory.
113+
- `information_schema`: views that show schema information for tables in the database.
114+
115+
#### View column information for a table
116+
117+
The following query sends a `POST` request that executes an SQL query to
118+
retrieve information about columns in the sample `system_swap` table schema:
119+
120+
_Note: when you send a query in JSON, you must escape single quotes
121+
that surround field names._
122+
123+
```bash
124+
curl "http://localhost:8181/api/v3/query_sql" \
125+
--header "Content-Type: application/json" \
126+
--json '{
127+
"db": "mydb",
128+
"q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'",
129+
"format": "jsonl"
130+
}'
131+
```
132+
133+
The output is the following:
134+
135+
```jsonl
136+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"}
137+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"}
138+
{"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}
139+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"}
140+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"}
141+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"}
142+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"}
143+
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"}
144+
```
145+
146+
#### Recently executed queries
147+
148+
To view recently executed queries, query the `queries` system table:
149+
150+
```bash
151+
curl "http://localhost:8181/api/v3/query_sql" \
152+
--header "Content-Type: application/json" \
153+
--json '{
154+
"db": "mydb",
155+
"q": "SELECT * FROM system.queries LIMIT 2",
156+
"format": "jsonl"
157+
}'
158+
```
159+
160+
The output is the following:
161+
162+
```jsonl
163+
{"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}
164+
{"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}
165+
```
166+
167+
## Query using InfluxQL and the HTTP API
168+
169+
Use the `/api/v3/query_influxql` endpoint with the `GET` or `POST` request methods.
170+
171+
- `GET`: Pass parameters in the URL query string (for simple queries)
172+
- `POST`: Pass parameters in a JSON object (for complex queries and readability in your code)
173+
174+
Include the following parameters:
175+
176+
- `q`: _({{< req >}})_ The **InfluxQL** query to execute.
177+
- `db`: _({{< req >}})_ The database to execute the query against.
178+
- `params`: A JSON object containing parameters to be used in a _parameterized query_.
179+
- `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`).
180+
JSONL (`jsonl`) is preferred because it streams results back to the client.
181+
`pretty` is for human-readable output. Default is `json`.
182+
183+
### Example: Query passing URL-encoded parameters
184+
185+
The following example sends an HTTP `GET` request with a URL-encoded InfluxQL query:
186+
187+
```bash
188+
curl -v "http://{{< influxdb/host >}}/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5"
189+
```
190+
191+
### Example: Query passing JSON parameters
192+
193+
The following example sends an HTTP `POST` request with parameters in a JSON payload:
194+
195+
```bash
196+
curl http://{{< influxdb/host >}}/api/v3/query_influxql \
197+
--data '{"db": "server", "q": "select * from cpu limit 5"}'
198+
```

0 commit comments

Comments
 (0)