Merge pull request #5846 from influxdata/jts/query-system-data

jstirnaman · web-flow · commit 07e99a7013ff · 2025-02-20T12:15:17.000-06:00
Query system data: use `/api/v3/query_sql` to query system and schema information
diff --git a/content/influxdb3/core/admin/_index.md b/content/influxdb3/core/admin/_index.md
@@ -11,5 +11,6 @@ source: /shared/influxdb3-admin/_index.md
 ---
 
 <!--
-The content of this file is located at content/shared/influxdb3-admin/_index.md
+The content of this file is located at
+// SOURCE content/shared/influxdb3-admin/_index.md
 -->
diff --git a/content/influxdb3/core/admin/query-system-data/_index.md b/content/influxdb3/core/admin/query-system-data/_index.md
@@ -0,0 +1,23 @@
+---
+title: Query system data
+description: |
+  Query system tables to see data related
+  to the server, queries, and tables in an {{% product-name %}} instance. 
+  Use the HTTP SQL query API to retrieve information about your database server
+  and table schemas.
+menu:
+  influxdb3_core:
+    name: Query system data 
+    parent: Administer InfluxDB
+weight: 3
+influxdb3/core/tags: [query, api, system information, schemas]
+related:
+  - /influxdb3/core/query-data/sql/
+  - /influxdb3/core/query-data/execute-queries/
+source: /shared/influxdb3-admin/query-system-data/_index.md
+---
+
+<!-- 
+The content of this page is at
+// SOURCE content/shared/influxdb3-admin/query-system-data/_index.md
+-->
diff --git a/content/influxdb3/core/get-started/_index.md b/content/influxdb3/core/get-started/_index.md
@@ -9,9 +9,12 @@ menu:
   influxdb3_core:
     name: Get started
 weight: 3 
+related:
+  - /influxdb3/core/admin/query-system-data/
 source: /shared/v3-core-get-started/_index.md
 ---
 
 <!-- 
-The content of this page is at /shared/v3-core-get-started/_index.md
+The content of this page is at
+// SOURCE content/shared/v3-core-get-started/_index.md
 -->
diff --git a/content/influxdb3/core/plugins.md b/content/influxdb3/core/plugins.md
@@ -4,7 +4,7 @@ description: Use the Python processing engine to trigger and execute custom code
 menu:
   influxdb3_core:
     name: Processing Engine and Python Plugins
-weight: 2
+weight: 4
 influxdb3/core/tags: []
 source: /shared/v3-core-plugins/_index.md
 ---
diff --git a/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md b/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md
@@ -0,0 +1,29 @@
+---
+title: Use the InfluxDB v3 HTTP query API
+seotitle: Use SQL or InfluxQL and InfluxDB v3 HTTP query API
+list_title: Use the v3 query API
+description: >
+  Use SQL or InfluxQL and the InfluxDB v3 HTTP query API to query data in {{< product-name >}}.
+weight: 301
+menu:
+  influxdb3_core:
+    parent: Execute queries
+    name: Use the v3 query API
+influxdb3/core/tags: [query, influxql, sql, python]
+metadata: [InfluxQL, SQL]
+related:
+  - /influxdb3/core/api-compatibility/v1/
+list_code_example: |
+  ```sh
+  curl --get http://{{< influxdb/host >}}/api/v3/query_sql \
+    --header "Authorization: Token DATABASE_TOKEN" \
+    --data-urlencode "db=DATABASE_NAME" \
+    --data-urlencode "q=SELECT * FROM home"
+  ```
+source: /shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
+---
+
+<!--
+The content for this page is at
+// SOURCE content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
+-->
diff --git a/content/influxdb3/enterprise/admin/query-system-data/_index.md b/content/influxdb3/enterprise/admin/query-system-data/_index.md
@@ -0,0 +1,23 @@
+---
+title: Query system data
+description: |
+  Query system tables to see data related
+  to the server, queries, and tables in an {{% product-name %}} instance. 
+  Use the HTTP SQL query API to retrieve information about your database server
+  and table schemas.
+menu:
+  influxdb3_enterprise:
+    name: Query system data 
+    parent: Administer InfluxDB
+weight: 3
+influxdb3/enterprise/tags: [query, api, system information, schemas]
+related:
+  - /influxdb3/enterprise/query-data/sql/
+  - /influxdb3/enterprise/query-data/execute-queries/
+source: /shared/influxdb3-admin/query-system-data/_index.md
+---
+
+<!-- 
+The content of this page is at
+// SOURCE content/shared/influxdb3-admin/query-system-data/_index.md
+-->
diff --git a/content/influxdb3/enterprise/get-started/_index.md b/content/influxdb3/enterprise/get-started/_index.md
@@ -9,9 +9,12 @@ menu:
   influxdb3_enterprise:
     name: Get started
 weight: 3
+related:
+  - /influxdb3/enterprise/admin/query-system-data/
 source: /shared/v3-enterprise-get-started/_index.md
 ---
 
 <!-- 
-The content of this page is at /shared/v3-enterprise-get-started/_index.md
+The content of this page is at
+// SOURCE content/shared/v3-core-get-started/_index.md
 -->
diff --git a/content/influxdb3/enterprise/plugins.md b/content/influxdb3/enterprise/plugins.md
@@ -4,7 +4,7 @@ description: Use the Python processing engine to trigger and execute custom code
 menu:
   influxdb3_enterprise:
     name: Processing Engine and Python Plugins
-weight: 2
+weight: 4
 influxdb3/enterprise/tags: []
 source: /shared/v3-core-plugins/_index.md
 ---
diff --git a/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md
@@ -5,7 +5,7 @@ list_title: Use the v1 query API and InfluxQL
 description: >
   Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}}
   with InfluxQL.
-weight: 302
+weight: 303
 menu:
   influxdb3_enterprise:
     parent: Execute queries
diff --git a/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v3-api.md b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v3-api.md
@@ -0,0 +1,29 @@
+---
+title: Use the InfluxDB v3 HTTP query API
+seotitle: Use SQL or InfluxQL and InfluxDB v3 HTTP query API
+list_title: Use the v3 query API
+description: >
+  Use SQL or InfluxQL and the InfluxDB v3 HTTP query API to query data in {{< product-name >}}.
+weight: 301
+menu:
+  influxdb3_enterprise:
+    parent: Execute queries
+    name: Use the v3 query API
+influxdb3/enterprise/tags: [query, influxql, sql, python]
+metadata: [InfluxQL, SQL]
+related:
+  - /influxdb3/enterprise/api-compatibility/v1/
+list_code_example: |
+  ```sh
+  curl --get http://{{< influxdb/host >}}/api/v3/query_sql \
+    --header "Authorization: Token DATABASE_TOKEN" \
+    --data-urlencode "db=DATABASE_NAME" \
+    --data-urlencode "q=SELECT * FROM home"
+  ```
+source: /shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
+---
+
+<!--
+The content for this page is at
+// SOURCE content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
+-->
diff --git a/content/shared/influxdb3-admin/query-system-data/_index.md b/content/shared/influxdb3-admin/query-system-data/_index.md
@@ -0,0 +1,136 @@
+<!--Shortcode-->
+{{% product-name %}} stores data related to the database server, queries, and tables in _system tables_.
+You can query the system tables for information about your running server, databases, and and table schemas.
+
+## Query system tables
+
+- [Use the HTTP query API](#use-the-http-query-api)
+  - [Examples](#examples)
+    - [Show tables](#show-tables)
+    - [View column information for a table](#view-column-information-for-a-table)
+
+### Use the HTTP query API 
+
+Use the HTTP API `/api/v3/query_sql` endpoint to retrieve system information about your database server and table schemas in {{% product-name %}}.
+
+
+To execute a query, send a `GET` or `POST` request to the endpoint:
+
+- `GET`: Pass parameters in the URL query string (for simple queries)
+- `POST`: Pass parameters in a JSON object (for complex queries and readability in your code)
+
+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`.
+
+#### Examples
+
+> [!Note]
+> #### system\_ sample data
+>
+> In examples, tables with `"table_name":"system_` are user-created tables for CPU, memory, disk,
+> network, and other resource statistics collected and written
+> by the user--for example, using the `psutil` Python library or
+> [Telegraf](/telegraf/v1/get-started/) to collect
+> and write system metrics to an InfluxDB 3 database.
+
+##### 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"
+```
+
+The response body contains the following JSONL:
+
+```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"}
+```
+
+A table has one of the following `table_schema` values:
+
+- `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.
+
+#### 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 you send a query in JSON, you must escape single quotes
+that surround field names._
+
+```bash
+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"
+  }'
+```
+
+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"}
+{"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"}
+```
+
+#### Recently executed queries
+
+To view recently executed queries, query the `queries` system table:
+
+```bash
+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"
+  }'
+```
+
+The output is similar to the following:
+
+```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}
+```
diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md
diff --git a/content/shared/sql-reference/join.md b/content/shared/sql-reference/join.md
