diff --git a/content/shared/influxdb3-get-started/processing-engine.md b/content/shared/influxdb3-get-started/processing-engine.md index a301cfc64..16c244134 100644 --- a/content/shared/influxdb3-get-started/processing-engine.md +++ b/content/shared/influxdb3-get-started/processing-engine.md @@ -90,11 +90,11 @@ def process_writes(influxdb3_local, table_batches, args=None): # here we're using arguments provided at the time the trigger was set up # to feed into paramters that we'll put into a query - query_params = {"host": "foo"} + query_params = {"room": "Kitchen"} # here's an example of executing a parameterized query. Only SQL is supported. # It will query the database that the trigger is attached to by default. We'll # soon have support for querying other DBs. - query_result = influxdb3_local.query("SELECT * FROM cpu where host = '$host'", query_params) + query_result = influxdb3_local.query("SELECT * FROM home where room = '$host'", query_params) # the result is a list of Dict that have the column name as key and value as # value. If you run the WAL test plugin with your plugin against a DB that # you've written data into, you'll be able to see some results @@ -142,19 +142,21 @@ def process_writes(influxdb3_local, table_batches, args=None): influxdb3_local.info("done") ``` -##### Test a plugin on the server +## Test a plugin on the server -Test your InfluxDB 3 plugin safely without affecting written data. During a plugin test: +Use the [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) +CLI command to test your processing engine plugin safely without +affecting actual data. During a plugin test: - A query executed by the plugin queries against the server you send the request to. - Writes aren't sent to the server but are returned to you. -To test a plugin, do the following: +To test a plugin: -1. Create a _plugin directory_--for example, `/path/to/.influxdb/plugins` -2. [Start the InfluxDB server](#start-influxdb) and include the `--plugin-dir ` option. -3. Save the [example plugin code](#example-python-plugin-for-wal-rows) to a plugin file inside of the plugin directory. If you haven't yet written data to the table in the example, comment out the lines where it queries. -4. To run the test, enter the following command with the following options: +1. Save the [example plugin code](#example-python-plugin-for-wal-rows) to a + plugin file inside of the plugin directory. If you haven't yet written data + to the table in the example, comment out the lines where it queries. +2. To run the test, enter the following command with the following options: - `--lp` or `--file`: The line protocol to test - Optional: `--input-arguments`: A comma-delimited list of `=` arguments for your plugin code @@ -162,15 +164,15 @@ To test a plugin, do the following: {{% code-placeholders "INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME" %}} ```bash influxdb3 test wal_plugin \ ---lp INPUT_LINE_PROTOCOL \ ---input-arguments INPUT_ARGS \ ---database DATABASE_NAME \ ---token AUTH_TOKEN \ -PLUGIN_FILENAME + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --lp INPUT_LINE_PROTOCOL \ + --input-arguments INPUT_ARGS \ + PLUGIN_FILENAME ``` {{% /code-placeholders %}} -Replace the following placeholders with your values: +Replace the following: - {{% code-placeholder-key %}}`INPUT_LINE_PROTOCOL`{{% /code-placeholder-key %}}: the line protocol to test - Optional: {{% code-placeholder-key %}}`INPUT_ARGS`{{% /code-placeholder-key %}}: a comma-delimited list of `=` arguments for your plugin code--for example, `arg1=hello,arg2=world` @@ -178,21 +180,19 @@ Replace the following placeholders with your values: - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server - {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: the name of the plugin file to test -The command runs the plugin code with the test data, yields the data to the plugin code, and then responds with the plugin result. -You can quickly see how the plugin behaves, what data it would have written to the database, and any errors. +The command runs the plugin code with the test data, yields the data to the +plugin code, and then responds with the plugin result. +You can quickly see how the plugin behaves, what data it would have written to +the database, and any errors. You can then edit your Python code in the plugins directory, and rerun the test. The server reloads the file for every request to the `test` API. -For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) or run `influxdb3 test wal_plugin -h`. - With the plugin code inside the server plugin directory, and a successful test, you're ready to create a trigger for your server to run the plugin. ##### Example: Test and run a plugin -The following example shows how to test a plugin, and then create the plugin and -trigger: - + ```bash # Test a plugin # Requires: @@ -207,6 +207,16 @@ influxdb3 test wal_plugin \ test.py ``` +For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) +or run `influxdb3 test wal_plugin -h`. + +## Create a trigger + +With the plugin code inside the server plugin directory, and a successful test, +you're ready to create a trigger to run the plugin. Use the +[`influxdb3 create trigger` command](/influxdb3/version/reference/cli/influxdb3/create/trigger/) +to create a trigger. + ```bash # Create a trigger that runs the plugin influxdb3 create trigger \ @@ -218,6 +228,8 @@ influxdb3 create trigger \ trigger1 ``` +## Enable the trigger + After you have created a plugin and trigger, enter the following command to enable the trigger and have it run the plugin as you write data: diff --git a/content/shared/influxdb3-get-started/query.md b/content/shared/influxdb3-get-started/query.md index 6c1c48a3b..3c2861d50 100644 --- a/content/shared/influxdb3-get-started/query.md +++ b/content/shared/influxdb3-get-started/query.md @@ -13,7 +13,26 @@ For more information about the 72-hour limitation, see the > [!Note] > Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3. -The quickest way to get started querying is to use the `influxdb3` CLI (which uses the Flight SQL API over HTTP2). + + +- [Query data with the influxdb3 CLI](#query-data-with-the-influxdb3-cli) + - [Example queries](#example-queries) +- [Other tools for executing queries](#other-tools-for-executing-queries) +- [SQL vs InfluxQL](#sql-vs-influxql) + - [SQL](#sql) + - [InfluxQL](#influxql) +- [Optimize queries](#optimize-queries) + - [Last values cache](#last-values-cache) + - [Distinct values cache](#distinct-values-cache) + {{% show-in "enterprise" %}}- [File indexes](#file-indexes){{% /show-in %}} + + + +## Query data with the influxdb3 CLI + +To get started querying data in {{% product-name %}}, use the +[`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) +and provide the following: The `query` subcommand includes options to help ensure that the right database is queried with the correct permissions. Only the `--database` option is required, but depending on your specific setup, you may need to pass other options, such as host, port, and token. @@ -83,7 +102,217 @@ Replace the following placeholders with your values: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}} -### Query using the API +To query from a specific time range, use the `WHERE` clause to designate the +boundaries of your time range. + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +influxdb3 query \ + --database DATABASE_NAME \ + "SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +influxdb3 query \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT * FROM home WHERE time >= now() - 7d" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +### Example queries + +{{< expand-wrapper >}} +{{% expand "List tables in a database" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SHOW TABLES +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SHOW MEASUREMENTS +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Return the average temperature of all rooms" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT avg(temp) AS avg_temp FROM home +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT MEAN(temp) AS avg_temp FROM home +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Return the average temperature of the kitchen" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Query data from an absolute time range" %}} + +{{% influxdb/custom-timestamps %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T12:00:00Z' + AND time <= '2022-01-01T18:00:00Z' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T12:00:00Z' + AND time <= '2022-01-01T18:00:00Z' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "Query data from a relative time range" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= now() - INTERVAL '7 days' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= now() - 7d +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Calculate average humidity in 3-hour windows per room" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + date_bin(INTERVAL '3 hours', time) AS time, + room, + avg(hum) AS avg_hum +FROM + home +GROUP BY + 1, + room +ORDER BY + room, + 1 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + MEAN(hum) AS avg_hum +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + time(3h), + room +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Other tools for executing queries + +Other tools are available for querying data in {{% product-name %}}, including +the following: + +{{< expand-wrapper >}} +{{% expand "Query using the API" %}} +#### Query using the API InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API. To query your database using the HTTP API, send a request to the `/api/v3/query_sql` or `/api/v3/query_influxql` endpoints. @@ -127,7 +356,11 @@ Replace the following placeholders with your values: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}} -### Query using the Python client +{{% /expand %}} + +{{% expand "Query using the Python client" %}} + +#### Query using the Python client Use the InfluxDB 3 Python library to interact with the database and integrate with your application. We recommend installing the required packages in a Python virtual environment for your specific project.