|
| 1 | +This guide shows some of the capabilities of the HTTP API API for querying and accessing useful information from system tables. |
| 2 | + |
| 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. |
| 4 | + |
| 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. |
| 6 | + |
| 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. |
| 12 | + |
| 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 | + |
| 15 | +```shell |
| 16 | +curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" |
| 17 | +``` |
| 18 | + |
| 19 | +Returns the following JSONL output |
| 20 | + |
| 21 | +```jsonl |
| 22 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"} |
| 23 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"} |
| 24 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"} |
| 25 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"} |
| 26 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"} |
| 27 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"} |
| 28 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"} |
| 29 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"} |
| 30 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"} |
| 31 | +{"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"} |
| 32 | +{"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"} |
| 33 | +{"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"} |
| 34 | +{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"} |
| 35 | +{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"} |
| 36 | +{"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"} |
| 37 | +{"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"} |
| 38 | +{"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"} |
| 39 | +{"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"} |
| 40 | +{"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"} |
| 41 | +{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"} |
| 42 | +``` |
| 43 | + |
| 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. |
| 48 | + |
| 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 |
| 52 | + |
| 53 | +```SQL |
| 54 | +SELECT * FROM information_schema.columns where table_schema = 'iox' AND table_name = 'system_cpu' |
| 55 | +``` |
| 56 | + |
| 57 | +And the response shows the schema of our example `system_cpu` table: |
| 58 | + |
| 59 | +```jsonl |
| 60 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"} |
| 61 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"} |
| 62 | +{"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} |
| 63 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"} |
| 64 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"} |
| 65 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"} |
| 66 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"} |
| 67 | +{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"} |
| 68 | +``` |
| 69 | + |
| 70 | +And here's query against the `queries` system table to see what queries we've recently executed: |
| 71 | + |
| 72 | +```SQL |
| 73 | +SELECT * FROM system.queries LIMIT 2 |
| 74 | +``` |
| 75 | + |
| 76 | +```jsonl |
| 77 | +{"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} |
| 78 | +{"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 | +``` |
0 commit comments