chore(monolith): Style and formatting of the HTTP query API and system tables guide
Jason Stirnaman
parent
c5ea74b396
commit
d86e7a4d35
|
|
@ -1,11 +1,13 @@
|
|||
---
|
||||
title: HTTP SQL API and System Tables
|
||||
description: Guide for the HTTP SQL query API and the system tables in InfluxDB 3
|
||||
title: Use the HTTP API to access server information and system tables
|
||||
description: |
|
||||
Use the HTTP SQL query API to retrieve information about your database server
|
||||
and table schemas in {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_core:
|
||||
name: HTTP Query API & System Tables
|
||||
name: HTTP query API & system tables
|
||||
weight: 3
|
||||
influxdb3/core/tags: []
|
||||
influxdb3/core/tags: [query, api]
|
||||
source: /shared/v3-core-http-query-api-system-tables/_index.md
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
---
|
||||
title: HTTP SQL API and System Tables
|
||||
description: Guide for the HTTP SQL query API and the system tables in InfluxDB 3
|
||||
title: Use the HTTP API to access server information and system tables
|
||||
description: |
|
||||
Use the HTTP SQL query API to retrieve information about your database server
|
||||
and table schemas in {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: HTTP Query API & System Tables
|
||||
name: HTTP query API & system tables
|
||||
weight: 3
|
||||
influxdb3/enterprise/tags: []
|
||||
influxdb3/enterprise/tags: [query, api]
|
||||
source: /shared/v3-core-http-query-api-system-tables/_index.md
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,46 @@
|
|||
Learn how to use the HTTP API to query and access information about the database server and table schemas.
|
||||
Use the HTTP query API to access and view information about your database server and table schemas in {{% product-name %}}.
|
||||
|
||||
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.
|
||||
## Query using SQL
|
||||
|
||||
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.
|
||||
{{% product-name %}} provides the HTTP API `/api/v3/query_sql` endpoint for querying
|
||||
data, database server information, and system tables.
|
||||
|
||||
The HTTP Query API takes the following parameters:
|
||||
- `q` - The SQL query to execute
|
||||
- `db` - The database to execute the query against
|
||||
- `params` - A JSON object containing parameters to be used in the query (for parameterize SQL)
|
||||
- `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.
|
||||
> [!Note]
|
||||
> {{% product-name %}} uses separate API endpoints for SQL and InfluxQL queries.
|
||||
> Both endpoints support the same parameters.
|
||||
>
|
||||
> For more information about using InfluxQL, see [Query data with InfluxQL](/influxdb3/version/query-data/influxql/).
|
||||
|
||||
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:
|
||||
To execute a query, send a `GET` request or a `POST` request to the endpoint:
|
||||
|
||||
```shell
|
||||
curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"
|
||||
- `GET`: Pass parameters in the URL query string.
|
||||
Use for quickly exploring your data and for queries that you can easily encode in a URL.
|
||||
- `POST`: Pass parameters in a JSON object.
|
||||
Use for longer, complex
|
||||
queries, queries you can't easily URL-encode, and for better readability in
|
||||
in your code.
|
||||
|
||||
and include the following parameters:
|
||||
|
||||
- `q`: _({{< req >}})_ The SQL query to execute.
|
||||
- `db`: _({{< req >}})_ The database to execute the query against.
|
||||
- `params`: A JSON object containing parameters to be used in a _parameterized query_.
|
||||
- `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`).
|
||||
JSONL (`jsonl`) is preferred because it streams results back to the client.
|
||||
`pretty` is for human-readable output. Default is `json`.
|
||||
|
||||
### Example: show tables
|
||||
|
||||
The following example sends a `GET` request that executes a `show tables` query
|
||||
to retrieve all user-created
|
||||
tables (`"table_schema":"iox"`), system tables, and information schema tables
|
||||
for a database:
|
||||
|
||||
```bash
|
||||
curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables"
|
||||
```
|
||||
|
||||
Returns the following JSONL output
|
||||
The response body contains the following JSONL:
|
||||
|
||||
```jsonl
|
||||
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"}
|
||||
|
|
@ -41,20 +65,32 @@ Returns the following JSONL output
|
|||
{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"}
|
||||
```
|
||||
|
||||
The `iox` tables are all those created by the user of the database. The `system` tables
|
||||
are all the system tables that are used by the system to show information about
|
||||
the running of the database server. Some of these tables show stored information like
|
||||
configurations, while others keep ephemeral state in memory like the `queries` table.
|
||||
A table has one of the following `table_schema` values:
|
||||
|
||||
The `information_schema` tables are views that show information about the schema of the
|
||||
tables in the database. Here's the output of querying the information schema of the `system_swap`
|
||||
table
|
||||
- `iox`: tables created by the user of the database.
|
||||
- `system`: tables used by the system to show information about the running database server.
|
||||
Some of these tables show stored information such as configurations,
|
||||
while others, such as the `queries` table, hold ephemeral state in memory.
|
||||
- `information_schema`: views that show schema information for tables in the database.
|
||||
|
||||
```SQL
|
||||
SELECT * FROM information_schema.columns where table_schema = 'iox' AND table_name = 'system_cpu'
|
||||
### Example: view column information for a table
|
||||
|
||||
The following query sends a `POST` request that executes an SQL query to
|
||||
retrieve information about columns in the sample `system_swap` table schema:
|
||||
|
||||
_Note: when sending a query in JSON, escape the single quotes around database field names._
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/api/v3/query_sql" \
|
||||
--header "Content-Type: application/json" \
|
||||
--json '{
|
||||
"db": "cpu",
|
||||
"q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'",
|
||||
"format": "jsonl"
|
||||
}'
|
||||
```
|
||||
|
||||
And the response shows the schema of our example `system_cpu` table:
|
||||
The output is the following:
|
||||
|
||||
```jsonl
|
||||
{"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:
|
|||
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"}
|
||||
```
|
||||
|
||||
And here's query against the `queries` system table to see what queries we've recently executed:
|
||||
To view recently executed queries, query the `queries` system table:
|
||||
|
||||
```SQL
|
||||
SELECT * FROM system.queries LIMIT 2
|
||||
|
|
@ -76,4 +112,4 @@ SELECT * FROM system.queries LIMIT 2
|
|||
```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}
|
||||
```
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue