Skip to content

Commit 5611da7

Browse files
sandersonjstirnaman
sanderson
authored and
jstirnaman
committed
WIP monolith get started, enterprise multi-node, file index docs
1 parent 776a209 commit 5611da7

File tree

2 files changed

+270
-25
lines changed

2 files changed

+270
-25
lines changed

‎content/shared/influxdb3-get-started/processing-engine.md

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -90,11 +90,11 @@ def process_writes(influxdb3_local, table_batches, args=None):
9090

9191
# here we're using arguments provided at the time the trigger was set up
9292
# to feed into paramters that we'll put into a query
93-
query_params = {"host": "foo"}
93+
query_params = {"room": "Kitchen"}
9494
# here's an example of executing a parameterized query. Only SQL is supported.
9595
# It will query the database that the trigger is attached to by default. We'll
9696
# soon have support for querying other DBs.
97-
query_result = influxdb3_local.query("SELECT * FROM cpu where host = '$host'", query_params)
97+
query_result = influxdb3_local.query("SELECT * FROM home where room = '$host'", query_params)
9898
# the result is a list of Dict that have the column name as key and value as
9999
# value. If you run the WAL test plugin with your plugin against a DB that
100100
# you've written data into, you'll be able to see some results
@@ -142,57 +142,57 @@ def process_writes(influxdb3_local, table_batches, args=None):
142142
influxdb3_local.info("done")
143143
```
144144

145-
##### Test a plugin on the server
145+
## Test a plugin on the server
146146

147-
Test your InfluxDB 3 plugin safely without affecting written data. During a plugin test:
147+
Use the [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/)
148+
CLI command to test your processing engine plugin safely without
149+
affecting actual data. During a plugin test:
148150

149151
- A query executed by the plugin queries against the server you send the request to.
150152
- Writes aren't sent to the server but are returned to you.
151153

152-
To test a plugin, do the following:
154+
To test a plugin:
153155

154-
1. Create a _plugin directory_--for example, `/path/to/.influxdb/plugins`
155-
2. [Start the InfluxDB server](#start-influxdb) and include the `--plugin-dir <PATH>` option.
156-
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.
157-
4. To run the test, enter the following command with the following options:
156+
1. Save the [example plugin code](#example-python-plugin-for-wal-rows) to a
157+
plugin file inside of the plugin directory. If you haven't yet written data
158+
to the table in the example, comment out the lines where it queries.
159+
2. To run the test, enter the following command with the following options:
158160

159161
- `--lp` or `--file`: The line protocol to test
160162
- Optional: `--input-arguments`: A comma-delimited list of `<KEY>=<VALUE>` arguments for your plugin code
161163

162164
{{% code-placeholders "INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME" %}}
163165
```bash
164166
influxdb3 test wal_plugin \
165-
--lp INPUT_LINE_PROTOCOL \
166-
--input-arguments INPUT_ARGS \
167-
--database DATABASE_NAME \
168-
--token AUTH_TOKEN \
169-
PLUGIN_FILENAME
167+
--database DATABASE_NAME \
168+
--token AUTH_TOKEN \
169+
--lp INPUT_LINE_PROTOCOL \
170+
--input-arguments INPUT_ARGS \
171+
PLUGIN_FILENAME
170172
```
171173
{{% /code-placeholders %}}
172174

173-
Replace the following placeholders with your values:
175+
Replace the following:
174176

175177
- {{% code-placeholder-key %}}`INPUT_LINE_PROTOCOL`{{% /code-placeholder-key %}}: the line protocol to test
176178
- Optional: {{% code-placeholder-key %}}`INPUT_ARGS`{{% /code-placeholder-key %}}: a comma-delimited list of `<KEY>=<VALUE>` arguments for your plugin code--for example, `arg1=hello,arg2=world`
177179
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against
178180
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server
179181
- {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: the name of the plugin file to test
180182

181-
The command runs the plugin code with the test data, yields the data to the plugin code, and then responds with the plugin result.
182-
You can quickly see how the plugin behaves, what data it would have written to the database, and any errors.
183+
The command runs the plugin code with the test data, yields the data to the
184+
plugin code, and then responds with the plugin result.
185+
You can quickly see how the plugin behaves, what data it would have written to
186+
the database, and any errors.
183187
You can then edit your Python code in the plugins directory, and rerun the test.
184188
The server reloads the file for every request to the `test` API.
185189

186-
For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) or run `influxdb3 test wal_plugin -h`.
187-
188190
With the plugin code inside the server plugin directory, and a successful test,
189191
you're ready to create a trigger for your server to run the plugin.
190192

191193
##### Example: Test and run a plugin
192194

193-
The following example shows how to test a plugin, and then create the plugin and
194-
trigger:
195-
195+
<!-- pytest.mark.skip -->
196196
```bash
197197
# Test a plugin
198198
# Requires:
@@ -207,6 +207,16 @@ influxdb3 test wal_plugin \
207207
test.py
208208
```
209209

210+
For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/)
211+
or run `influxdb3 test wal_plugin -h`.
212+
213+
## Create a trigger
214+
215+
With the plugin code inside the server plugin directory, and a successful test,
216+
you're ready to create a trigger to run the plugin. Use the
217+
[`influxdb3 create trigger` command](/influxdb3/version/reference/cli/influxdb3/create/trigger/)
218+
to create a trigger.
219+
210220
```bash
211221
# Create a trigger that runs the plugin
212222
influxdb3 create trigger \
@@ -218,6 +228,8 @@ influxdb3 create trigger \
218228
trigger1
219229
```
220230

231+
## Enable the trigger
232+
221233
After you have created a plugin and trigger, enter the following command to
222234
enable the trigger and have it run the plugin as you write data:
223235

‎content/shared/influxdb3-get-started/query.md

Lines changed: 236 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,26 @@ For more information about the 72-hour limitation, see the
1313
> [!Note]
1414
> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3.
1515
16-
The quickest way to get started querying is to use the `influxdb3` CLI (which uses the Flight SQL API over HTTP2).
16+
<!-- TOC -->
17+
18+
- [Query data with the influxdb3 CLI](#query-data-with-the-influxdb3-cli)
19+
- [Example queries](#example-queries)
20+
- [Other tools for executing queries](#other-tools-for-executing-queries)
21+
- [SQL vs InfluxQL](#sql-vs-influxql)
22+
- [SQL](#sql)
23+
- [InfluxQL](#influxql)
24+
- [Optimize queries](#optimize-queries)
25+
- [Last values cache](#last-values-cache)
26+
- [Distinct values cache](#distinct-values-cache)
27+
{{% show-in "enterprise" %}}- [File indexes](#file-indexes){{% /show-in %}}
28+
29+
<!-- /TOC -->
30+
31+
## Query data with the influxdb3 CLI
32+
33+
To get started querying data in {{% product-name %}}, use the
34+
[`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/)
35+
and provide the following:
1736

1837
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.
1938

@@ -83,7 +102,217 @@ Replace the following placeholders with your values:
83102
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query
84103
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}
85104

86-
### Query using the API
105+
To query from a specific time range, use the `WHERE` clause to designate the
106+
boundaries of your time range.
107+
108+
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
109+
110+
{{< code-tabs-wrapper >}}
111+
{{% code-tabs %}}
112+
[SQL](#)
113+
[InfluxQL](#)
114+
{{% /code-tabs %}}
115+
{{% code-tab-content %}}
116+
117+
<!-- pytest.mark.skip -->
118+
```bash
119+
influxdb3 query \
120+
--database DATABASE_NAME \
121+
"SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time"
122+
```
123+
{{% /code-tab-content %}}
124+
{{% code-tab-content %}}
125+
<!-- pytest.mark.skip -->
126+
```bash
127+
influxdb3 query \
128+
--database DATABASE_NAME \
129+
--language influxql \
130+
"SELECT * FROM home WHERE time >= now() - 7d"
131+
```
132+
{{% /code-tab-content %}}
133+
{{< /code-tabs-wrapper >}}
134+
135+
{{% /code-placeholders %}}
136+
137+
### Example queries
138+
139+
{{< expand-wrapper >}}
140+
{{% expand "List tables in a database" %}}
141+
142+
{{< code-tabs-wrapper >}}
143+
{{% code-tabs %}}
144+
[SQL](#)
145+
[InfluxQL](#)
146+
{{% /code-tabs %}}
147+
{{% code-tab-content %}}
148+
```sql
149+
SHOW TABLES
150+
```
151+
{{% /code-tab-content %}}
152+
{{% code-tab-content %}}
153+
```sql
154+
SHOW MEASUREMENTS
155+
```
156+
{{% /code-tab-content %}}
157+
{{< /code-tabs-wrapper >}}
158+
159+
{{% /expand %}}
160+
{{% expand "Return the average temperature of all rooms" %}}
161+
162+
{{< code-tabs-wrapper >}}
163+
{{% code-tabs %}}
164+
[SQL](#)
165+
[InfluxQL](#)
166+
{{% /code-tabs %}}
167+
{{% code-tab-content %}}
168+
```sql
169+
SELECT avg(temp) AS avg_temp FROM home
170+
```
171+
{{% /code-tab-content %}}
172+
{{% code-tab-content %}}
173+
```sql
174+
SELECT MEAN(temp) AS avg_temp FROM home
175+
```
176+
{{% /code-tab-content %}}
177+
{{< /code-tabs-wrapper >}}
178+
179+
{{% /expand %}}
180+
{{% expand "Return the average temperature of the kitchen" %}}
181+
182+
{{< code-tabs-wrapper >}}
183+
{{% code-tabs %}}
184+
[SQL](#)
185+
[InfluxQL](#)
186+
{{% /code-tabs %}}
187+
{{% code-tab-content %}}
188+
```sql
189+
SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen'
190+
```
191+
{{% /code-tab-content %}}
192+
{{% code-tab-content %}}
193+
```sql
194+
SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen'
195+
```
196+
{{% /code-tab-content %}}
197+
{{< /code-tabs-wrapper >}}
198+
199+
{{% /expand %}}
200+
{{% expand "Query data from an absolute time range" %}}
201+
202+
{{% influxdb/custom-timestamps %}}
203+
204+
{{< code-tabs-wrapper >}}
205+
{{% code-tabs %}}
206+
[SQL](#)
207+
[InfluxQL](#)
208+
{{% /code-tabs %}}
209+
{{% code-tab-content %}}
210+
```sql
211+
SELECT
212+
*
213+
FROM
214+
home
215+
WHERE
216+
time >= '2022-01-01T12:00:00Z'
217+
AND time <= '2022-01-01T18:00:00Z'
218+
```
219+
{{% /code-tab-content %}}
220+
{{% code-tab-content %}}
221+
```sql
222+
SELECT
223+
*
224+
FROM
225+
home
226+
WHERE
227+
time >= '2022-01-01T12:00:00Z'
228+
AND time <= '2022-01-01T18:00:00Z'
229+
```
230+
{{% /code-tab-content %}}
231+
{{< /code-tabs-wrapper >}}
232+
233+
{{% /influxdb/custom-timestamps %}}
234+
235+
{{% /expand %}}
236+
{{% expand "Query data from a relative time range" %}}
237+
238+
{{< code-tabs-wrapper >}}
239+
{{% code-tabs %}}
240+
[SQL](#)
241+
[InfluxQL](#)
242+
{{% /code-tabs %}}
243+
{{% code-tab-content %}}
244+
```sql
245+
SELECT
246+
*
247+
FROM
248+
home
249+
WHERE
250+
time >= now() - INTERVAL '7 days'
251+
```
252+
{{% /code-tab-content %}}
253+
{{% code-tab-content %}}
254+
```sql
255+
SELECT
256+
*
257+
FROM
258+
home
259+
WHERE
260+
time >= now() - 7d
261+
```
262+
{{% /code-tab-content %}}
263+
{{< /code-tabs-wrapper >}}
264+
265+
{{% /expand %}}
266+
{{% expand "Calculate average humidity in 3-hour windows per room" %}}
267+
268+
{{< code-tabs-wrapper >}}
269+
{{% code-tabs %}}
270+
[SQL](#)
271+
[InfluxQL](#)
272+
{{% /code-tabs %}}
273+
{{% code-tab-content %}}
274+
```sql
275+
SELECT
276+
date_bin(INTERVAL '3 hours', time) AS time,
277+
room,
278+
avg(hum) AS avg_hum
279+
FROM
280+
home
281+
GROUP BY
282+
1,
283+
room
284+
ORDER BY
285+
room,
286+
1
287+
```
288+
{{% /code-tab-content %}}
289+
{{% code-tab-content %}}
290+
```sql
291+
SELECT
292+
MEAN(hum) AS avg_hum
293+
FROM
294+
home
295+
WHERE
296+
time >= '2022-01-01T08:00:00Z'
297+
AND time <= '2022-01-01T20:00:00Z'
298+
GROUP BY
299+
time(3h),
300+
room
301+
```
302+
{{% /code-tab-content %}}
303+
{{< /code-tabs-wrapper >}}
304+
305+
{{% /expand %}}
306+
{{< /expand-wrapper >}}
307+
308+
## Other tools for executing queries
309+
310+
Other tools are available for querying data in {{% product-name %}}, including
311+
the following:
312+
313+
{{< expand-wrapper >}}
314+
{{% expand "Query using the API" %}}
315+
#### Query using the API
87316

88317
InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API.
89318
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:
127356
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query
128357
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}
129358

130-
### Query using the Python client
359+
{{% /expand %}}
360+
361+
{{% expand "Query using the Python client" %}}
362+
363+
#### Query using the Python client
131364

132365
Use the InfluxDB 3 Python library to interact with the database and integrate with your application.
133366
We recommend installing the required packages in a Python virtual environment for your specific project.

0 commit comments

Comments
 (0)