From e635f66a6000685e178e487f01d846c01dd4cb2d Mon Sep 17 00:00:00 2001 From: Lorenzo Mangani Date: Mon, 18 Sep 2023 23:04:07 +0200 Subject: [PATCH] Create sql.md Signed-off-by: Lorenzo Mangani --- docs/sql.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/sql.md diff --git a/docs/sql.md b/docs/sql.md new file mode 100644 index 0000000..06b9af6 --- /dev/null +++ b/docs/sql.md @@ -0,0 +1,151 @@ +# InfluxDB SQL Repl Tips and Tricks + +InfluxDB IOx contains a built in SQL client you can use to interact with the server using SQL. + +## Quick Start + +```shell +influxdb_iox --host http://localhost:8082 sql + +Connected to IOx Server at http://localhost:8082 +Ready for commands. (Hint: try 'help;') +> + +``` + +## Remote Mode +In this mode queries are run on the remote server in the context of a namespace. To use this mode, specify a namespace and then run queries as normal + +``` +> show namespaces; ++--------------+-----------------------------------+ +| namespace_id | name | ++--------------+-----------------------------------+ +| 1 | internal_test | +| 2 | 33a8e04942966029_8dce392f44992579 | +| 3 | 810c5937734635d8_dbce66e3a6cbe757 | ++--------------+-----------------------------------+ +``` + +Then run the `USE ` command + +``` +> use 810c5937734635d8_dbce66e3a6cbe757; +You are now in remote mode, querying namespace 810c5937734635d8_dbce66e3a6cbe757 +810c5937734635d8_dbce66e3a6cbe757> +``` + +Now, all queries will be run against the specified namespace (`810c5937734635d8_dbce66e3a6cbe757`) in this example +``` +810c5937734635d8_dbce66e3a6cbe757> show tables; ++---------------+--------------------+-------------+------------+ +| table_catalog | table_schema | table_name | table_type | ++---------------+--------------------+-------------+------------+ +| public | iox | cpu | BASE TABLE | +| public | iox | disk | BASE TABLE | +| public | iox | diskio | BASE TABLE | +| public | iox | mem | BASE TABLE | +| public | iox | net | BASE TABLE | +| public | iox | processes | BASE TABLE | +| public | iox | swap | BASE TABLE | +| public | iox | system | BASE TABLE | +| public | system | queries | BASE TABLE | +| public | information_schema | tables | VIEW | +| public | information_schema | views | VIEW | +| public | information_schema | columns | VIEW | +| public | information_schema | df_settings | VIEW | ++---------------+--------------------+-------------+------------+ +Returned 13 rows in 101.973855ms +810c5937734635d8_dbce66e3a6cbe757> select count(*) from cpu; ++-----------------+ +| COUNT(UInt8(1)) | ++-----------------+ +| 66980 | ++-----------------+ +Returned 1 row in 74.022768ms +810c5937734635d8_dbce66e3a6cbe757> +``` + + +# Query Cookbook + +This section contains some common and useful queries against IOx system tables + + +## Explore Schema + + +The `SHOW TABLES` command will show all tables available to you. + +``` +my_db> show tables; ++---------------+--------------------+-------------+------------+ +| table_catalog | table_schema | table_name | table_type | ++---------------+--------------------+-------------+------------+ +| public | iox | query_count | BASE TABLE | +| public | information_schema | tables | VIEW | +| public | information_schema | columns | VIEW | ++---------------+--------------------+-------------+------------+ + +Query execution complete in 45.06072ms +``` +tables in the `iox` schema are those that you have loaded (`query_count`) in this example. Tables which allow you to interrogate IOx's internals are in the `system` schema. The `information_schema` schema contains SQL standard views for accessing table and column metadata. + + +The `SHOW COLUMNS FROM ` command will show the columns in a table + +``` +my_db> show columns from query_count; ++---------------+--------------+-------------+-------------+-----------------------------+-------------+ +| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | ++---------------+--------------+-------------+-------------+-----------------------------+-------------+ +| public | iox | query_count | avg | Int64 | YES | +| public | iox | query_count | time | Timestamp(Nanosecond, None) | NO | ++---------------+--------------+-------------+-------------+-----------------------------+-------------+ + +Query execution complete in 62.77733ms +``` + +A classic trick to explore a table's schema is to select from it with a limit. For example: + +``` +my_db> select * from query_count limit 2; ++-----+---------------------+ +| avg | time | ++-----+---------------------+ +| 461 | 2021-04-28 16:51:00 | +| 402 | 2021-04-28 17:51:00 | ++-----+---------------------+ + +Query execution complete in 39.046225ms +``` + +# Debug Features +Certain features are hidden behind a "debug mode". This mode opt-in and is enabled when the `iox-debug` HTTP header / gRPC metadata +field is set to `1`. In this case, certain operations are possible that are helpful to IOx developers but that may +confuse end users. Features that are debug features are marked as such. + +**IMPORTANT: Debug features MUST NOT contain security-critical information. It is assumed that every user (even our end +users) can always enable the debug features!** + + +# SQL Reference + +Since IOx uses Apache Arrow's +[DataFusion](https://github.com/apache/arrow-datafusion) query engine, IOx SQL is mostly the same as DataFusion. + +In this section, IOx specific SQL tables, commands, and extensions are documented. + + +## System Tables + +In addition to the SQL standard `information_schema`, IOx contains several *system tables* that provide access to IOx +specific information. The information in each system table is scoped to that particular namespace. Cross namespace +queries are not possible due to the design of IOx's security model. + +### `system.queries` +**This is a debug feature.** + +`system.queries` contains information about queries run against this IOx instance. The query log is process local and +NOT shared across instances within the same deployment. While the log size is limited per instance, the view on this log +is scoped to the requesting namespace (i.e. queries are NOT leaked across namespaces.).