Skip to content

Commit d86e7a4

Browse files
jstirnamanjstirnaman
committed
chore(monolith): Style and formatting of the HTTP query API and system tables guide
1 parent c5ea74b commit d86e7a4

File tree

3 files changed

+72
-32
lines changed

3 files changed

+72
-32
lines changed

‎content/influxdb3/core/http-query-api-system-tables.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
---
2-
title: HTTP SQL API and System Tables
3-
description: Guide for the HTTP SQL query API and the system tables in InfluxDB 3
2+
title: Use the HTTP API to access server information and system tables
3+
description: |
4+
Use the HTTP SQL query API to retrieve information about your database server
5+
and table schemas in {{% product-name %}}.
46
menu:
57
influxdb3_core:
6-
name: HTTP Query API & System Tables
8+
name: HTTP query API & system tables
79
weight: 3
8-
influxdb3/core/tags: []
10+
influxdb3/core/tags: [query, api]
911
source: /shared/v3-core-http-query-api-system-tables/_index.md
1012
---
1113

‎content/influxdb3/enterprise/http-query-api-system-tables.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
---
2-
title: HTTP SQL API and System Tables
3-
description: Guide for the HTTP SQL query API and the system tables in InfluxDB 3
2+
title: Use the HTTP API to access server information and system tables
3+
description: |
4+
Use the HTTP SQL query API to retrieve information about your database server
5+
and table schemas in {{% product-name %}}.
46
menu:
57
influxdb3_enterprise:
6-
name: HTTP Query API & System Tables
8+
name: HTTP query API & system tables
79
weight: 3
8-
influxdb3/enterprise/tags: []
10+
influxdb3/enterprise/tags: [query, api]
911
source: /shared/v3-core-http-query-api-system-tables/_index.md
1012
---
1113

‎content/shared/v3-core-http-query-api-system-tables/_index.md

Lines changed: 60 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,46 @@
1-
Learn how to use the HTTP API to query and access information about the database server and table schemas.
1+
Use the HTTP query API to access and view information about your database server and table schemas in {{% product-name %}}.
22

3-
The HTTP API for querying is reached via either a `GET` or `POST` to the endpoint `/api/v3/query_sql`. There is also an endpoint for InfluxQL at `/api/v3/query_influxql` but this guide will focus on just the SQL endpoint.
3+
## Query using SQL
44

5-
The `POST` endpoint is there for when the query is too large to fit in a URL. The `GET` endpoint is useful for quick queries that can be easily encoded in a URL.
5+
{{% product-name %}} provides the HTTP API `/api/v3/query_sql` endpoint for querying
6+
data, database server information, and system tables.
67

7-
The HTTP Query API takes the following parameters:
8-
- `q` - The SQL query to execute
9-
- `db` - The database to execute the query against
10-
- `params` - A JSON object containing parameters to be used in the query (for parameterize SQL)
11-
- `format` - The format of the response. Can be `json`, `jsonl`, `csv`, `pretty`, or `parquet`. JSONL is the preferred format as it will stream the results back to the client. Pretty is for human-readable output.
8+
> [!Note]
9+
> {{% product-name %}} uses separate API endpoints for SQL and InfluxQL queries.
10+
> Both endpoints support the same parameters.
11+
>
12+
> For more information about using InfluxQL, see [Query data with InfluxQL](/influxdb3/version/query-data/influxql/).
1213
13-
For example, running the `show tables` query, which will show all user created tables (listed as `table_schema` of `iox`), system tables, and information schema tables. Here's the command:
14+
To execute a query, send a `GET` request or a `POST` request to the endpoint:
1415

15-
```shell
16-
curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"
16+
- `GET`: Pass parameters in the URL query string.
17+
Use for quickly exploring your data and for queries that you can easily encode in a URL.
18+
- `POST`: Pass parameters in a JSON object.
19+
Use for longer, complex
20+
queries, queries you can't easily URL-encode, and for better readability in
21+
in your code.
22+
23+
and include the following parameters:
24+
25+
- `q`: _({{< req >}})_ The SQL query to execute.
26+
- `db`: _({{< req >}})_ The database to execute the query against.
27+
- `params`: A JSON object containing parameters to be used in a _parameterized query_.
28+
- `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`).
29+
JSONL (`jsonl`) is preferred because it streams results back to the client.
30+
`pretty` is for human-readable output. Default is `json`.
31+
32+
### Example: show tables
33+
34+
The following example sends a `GET` request that executes a `show tables` query
35+
to retrieve all user-created
36+
tables (`"table_schema":"iox"`), system tables, and information schema tables
37+
for a database:
38+
39+
```bash
40+
curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"
1741
```
1842

19-
Returns the following JSONL output
43+
The response body contains the following JSONL:
2044

2145
```jsonl
2246
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"}
@@ -41,20 +65,32 @@ Returns the following JSONL output
4165
{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"}
4266
```
4367

44-
The `iox` tables are all those created by the user of the database. The `system` tables
45-
are all the system tables that are used by the system to show information about
46-
the running of the database server. Some of these tables show stored information like
47-
configurations, while others keep ephemeral state in memory like the `queries` table.
68+
A table has one of the following `table_schema` values:
4869

49-
The `information_schema` tables are views that show information about the schema of the
50-
tables in the database. Here's the output of querying the information schema of the `system_swap`
51-
table
70+
- `iox`: tables created by the user of the database.
71+
- `system`: tables used by the system to show information about the running database server.
72+
Some of these tables show stored information such as configurations,
73+
while others, such as the `queries` table, hold ephemeral state in memory.
74+
- `information_schema`: views that show schema information for tables in the database.
5275

53-
```SQL
54-
SELECT * FROM information_schema.columns where table_schema = 'iox' AND table_name = 'system_cpu'
76+
### Example: view column information for a table
77+
78+
The following query sends a `POST` request that executes an SQL query to
79+
retrieve information about columns in the sample `system_swap` table schema:
80+
81+
_Note: when sending a query in JSON, escape the single quotes around database field names._
82+
83+
```bash
84+
curl "http://localhost:8181/api/v3/query_sql" \
85+
--header "Content-Type: application/json" \
86+
--json '{
87+
"db": "cpu",
88+
"q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'",
89+
"format": "jsonl"
90+
}'
5591
```
5692

57-
And the response shows the schema of our example `system_cpu` table:
93+
The output is the following:
5894

5995
```jsonl
6096
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"}
@@ -67,7 +103,7 @@ And the response shows the schema of our example `system_cpu` table:
67103
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"}
68104
```
69105

70-
And here's query against the `queries` system table to see what queries we've recently executed:
106+
To view recently executed queries, query the `queries` system table:
71107

72108
```SQL
73109
SELECT * FROM system.queries LIMIT 2
@@ -76,4 +112,4 @@ SELECT * FROM system.queries LIMIT 2
76112
```jsonl
77113
{"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}
78114
{"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}
79-
```
115+
```

0 commit comments

Comments
 (0)