Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #6093 from influxdata/6080-add-auth-to-examples 

chore(mono): Core and Enterprise: add auth to Get Started examples (p…
pull/6094/head^2
Jason Stirnaman 2025-05-27 15:02:27 -05:00 committed by GitHub
parent 3260897049 cbd62a8f87
commit e5ee6bfabe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 579 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

359
content/shared/v3-core-get-started/_index.md
View File

@ -134,10 +134,9 @@ source ~/.zshrc
#### Start InfluxDB
To start your InfluxDB instance, use the `influxdb3 serve` command
and provide the following:
To start your InfluxDB instance, use the `influxdb3 serve` command and provide the following:
- `--object-store`: Specifies the type of Object store to use.
`--object-store`: Specifies the type of object store to use.
InfluxDB supports the following: local file system (`file`), `memory`,
S3 (and compatible services like Ceph or Minio) (`s3`),
Google Cloud Storage (`google`), and Azure Blob Storage (`azure`).
@ -148,6 +147,8 @@ and provide the following:
This forms the final part of the storage path: `<CONFIGURED_PATH>/<NODE_ID>`.
In a multi-node setup, this ID is used to reference specific nodes.
The following examples show how to start {{% product-name %}} with different object store configurations.
> [!Note]
> #### Diskless architecture
>
@ -155,15 +156,13 @@ and provide the following:
> storage alone, eliminating the need for locally attached disks.
> {{% product-name %}} can also work with only local disk storage when needed.
The following examples show how to start InfluxDB 3 with different object store configurations:
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--object-store memory
```
##### Filesystem object store
Store data in a specified directory on the local filesystem.
This is the default object store type.
Replace the following with your values:
```bash
# Filesystem object store
@ -174,15 +173,11 @@ influxdb3 serve \
--data-dir ~/.influxdb3
```
To run the [Docker image](/influxdb3/core/install/#docker-image) and persist data to the filesystem, mount a volume for the Object store-for example, pass the following options:
To run the [Docker image](/influxdb3/version/install/#docker-image) and persist data to the filesystem, mount a volume for the object store-for example, pass the following options:
- `-v /path/on/host:/path/in/container`: Mounts a directory from your filesystem to the container
- `--object-store file --data-dir /path/in/container`: Uses the mount for server storage
> [!Note]
>
> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections.
> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/).
<!--pytest.mark.skip-->
```bash
@ -197,13 +192,24 @@ docker run -it \
--data-dir /path/in/container
```
> [!Note]
>
> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections.
> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/).
##### S3 object store
Store data in an S3-compatible object store.
This is useful for production deployments that require high availability and durability.
Provide your bucket name and credentials to access the S3 object store.
```bash
# S3 object store (default is the us-east-1 region)
# Specify the Object store type and associated options
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--object-store s3 \
--bucket BUCKET \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY
```
@ -215,14 +221,27 @@ influxdb3 serve \
influxdb3 serve \
--node-id host01 \
--object-store s3 \
--bucket BUCKET \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key-id AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY \
--aws-endpoint ENDPOINT \
--aws-allow-http
```
For more information about server options, use the CLI help:
#### Memory object store
Store data in RAM without persisting it on shutdown.
It's useful for rapid testing and development.
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--object-store memory
```
For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/serve/):
```bash
influxdb3 serve --help
@ -232,7 +251,7 @@ influxdb3 serve --help
After you have [started the server](#start-influxdb), you can create and manage tokens using the `influxdb3` CLI or the HTTP API.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
With authentication enabled, you must provide a token to access server actions.
With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
An {{% product-name %}} instance can have one _admin token_, which grants access to all CLI actions and API endpoints.
When you create a token, InfluxDB 3 returns a token string in plain text
@ -282,8 +301,54 @@ Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}
{{< /code-tabs-wrapper >}}
The command returns a token string that you can use to authenticate CLI commands and API requests.
Store your token in a secure location, as you cannot retrieve it from the database later.
For more information, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
For more information about tokens, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
#### Use tokens to authorize CLI commands and API requests
With authentication enabled (the default), {{% product-name %}} requires a
token for all `influxdb3` CLI commands and HTTP API requests.
In the following examples, replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}} with your {{% token-link "admin" %}} string.
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#cli-use-a-token)
[HTTP API](#api-use-a-token)
{{% /tabs %}}
{{% tab-content %}}
For `influxdb3` to use your token automatically, assign it your
token to the `INFLUXDB3_AUTH_TOKEN` environment variable:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Set the environment variable for future CLI commands
export INFLUXDB3_AUTH_TOKEN=AUTH_TOKEN
```
{{% /code-placeholders %}}
Or to authenticate a single `influxdb3` CLI command and override `$INFLUXDB3_AUTH_TOKEN`, include the `--token` option:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Use the --token option for a single command
influxdb3 show databases --token AUTH_TOKEN
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
To authenticate HTTP API requests, include `Bearer <TOKEN>` in the `Authorization` header value:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Include the token in the Authorization HTTP request header
curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Data model
@ -373,24 +438,18 @@ Use the `influxdb3 write` command to write data to a database.
In the code samples, replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: The name of the [database](/influxdb3/version/admin/databases/) to write to.
{{% show-in "core" %}}
- {{% code-placeholder-key %}}`TOKEN`{{% /code-placeholder-key %}}: A [token](/influxdb3/version/admin/tokens/) for your {{% product-name %}} server.
{{% /show-in %}}
{{% show-in "enterprise" %}}
- {{% code-placeholder-key %}}`TOKEN`{{% /code-placeholder-key %}}: A [token](/influxdb3/version/admin/tokens/)
with permission to write to the specified database.
{{% /show-in %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to.
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}}
##### Write data via stdin
Pass data as quoted line protocol via standard input (stdin)--for example:
{{% code-placeholders "DATABASE_NAME|TOKEN" %}}
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 write \
--database DATABASE_NAME \
--token TOKEN \
--token AUTH_TOKEN \
--precision ns \
--accept-partial \
'cpu,host=Alpha,region=us-west,application=webserver val=1i,usage_percent=20.5,status="OK"
@ -408,17 +467,21 @@ Pass the `--file` option to write line protocol you have saved to a file--for ex
[sample line protocol](#write-data-in-line-protocol-syntax) to a file named `server_data`
and then enter the following command:
{{% code-placeholders "DATABASE_NAME|TOKEN" %}}
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 write \
--database DATABASE_NAME \
--token TOKEN \
--token AUTH_TOKEN \
--precision ns \
--accept-partial \
--file server_data
--file path/to/server_data
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to.
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}}
### Write data using the HTTP API
{{% product-name %}} provides three write API endpoints that respond to HTTP `POST` requests.
@ -450,7 +513,7 @@ and supports the following parameters:
- `?precision=<PRECISION>`: Specify the precision of the timestamp. The default is nanosecond precision.
- request body: The line protocol data to write.
For more information about the parameters, see [Write data](/influxdb3/core/write-data/).
For more information about the parameters, see [Write data](/influxdb3/version/write-data/).
##### Example: write data using the /api/v3 HTTP API
@ -463,6 +526,7 @@ With `accept_partial=true` (default):
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw 'home,room=Sunroom temp=96
home,room=Sunroom temp="hi"'
```
@ -493,6 +557,7 @@ With `accept_partial=false`:
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw 'home,room=Sunroom temp=96
home,room=Sunroom temp="hi"'
```
@ -546,17 +611,17 @@ The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility
#### Write responses
By default, InfluxDB acknowledges writes after flushing the WAL file to the Object store (occurring every second).
By default, InfluxDB acknowledges writes after flushing the WAL file to the object store (occurring every second).
For high write throughput, you can send multiple concurrent write requests.
#### Use no_sync for immediate write responses
To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes.
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the Object store.
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the object store.
Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability.
- Default behavior (`no_sync=false`): Waits for data to be written to the Object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
- Default behavior (`no_sync=false`): Waits for data to be written to the object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence.
##### Immediate write using the HTTP API
@ -565,30 +630,27 @@ The `no_sync` parameter controls when writes are acknowledged--for example:
```bash
curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw "home,room=Sunroom temp=96"
```
##### Immediate write using the influxdb3 CLI
The `no_sync` CLI option controls when writes are acknowledged--for example:
```bash
influxdb3 write \
--bucket mydb \
--org my_org \
--token my-token \
--no-sync
```
### Create a database or table
To create a database without writing data, use the `create` subcommand--for example:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 create database mydb
influxdb3 create database DATABASE_NAME \
--token AUTH_TOKEN
```
{{% /code-placeholders %}}
To learn more about a subcommand, use the `-h, --help` flag:
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server
To learn more about a subcommand, use the `-h, --help` flag or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/create/):
```bash
influxdb3 create -h
@ -596,7 +658,7 @@ influxdb3 create -h
### Query data
InfluxDB 3 now supports native SQL for querying, in addition to InfluxQL, an
InfluxDB 3 supports native SQL for querying, in addition to InfluxQL, an
SQL-like language customized for time series queries.
{{< product-name >}} limits
@ -662,12 +724,20 @@ $ influxdb3 query --database servers "SELECT DISTINCT usage_percent, time FROM c
To query using InfluxQL, enter the `influxdb3 query` subcommand and specify `influxql` in the language option--for example:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 query \
--database servers \
--database DATABASE_NAME \
--token <AUTH_TOKEN> \
--language influxql \
"SELECT DISTINCT usage_percent FROM cpu WHERE time >= now() - 1d"
```
{{% /code-placeholders %}}
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
@ -683,18 +753,35 @@ Use the `format` parameter to specify the response format: `pretty`, `jsonl`, `p
The following example sends an HTTP `GET` request with a URL-encoded SQL query:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5"
curl -G "http://{{< influxdb/host >}}/api/v3/query_sql" \
--header 'Authorization: Bearer AUTH_TOKEN' \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=select * from cpu limit 5"
```
{{% /code-placeholders %}}
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 %}}
##### Example: Query passing JSON parameters
The following example sends an HTTP `POST` request with parameters in a JSON payload:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
curl http://{{< influxdb/host >}}/api/v3/query_sql \
--data '{"db": "server", "q": "select * from cpu limit 5"}'
--data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}'
```
{{% /code-placeholders %}}
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
@ -709,24 +796,35 @@ pip install influxdb3-python
From here, you can connect to your database with the client library using just the **host** and **database name:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```python
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
token='AUTH_TOKEN',
host='http://{{< influxdb/host >}}',
database='servers'
database='DATABASE_NAME'
)
```
{{% /code-placeholders %}}
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 %}}
The following example shows how to query using SQL, and then
use PyArrow to explore the schema and process results:
use PyArrow to explore the schema and process results.
To authorize the query, the example retrieves the {{% token-link "database" %}}
from the `INFLUXDB3_AUTH_TOKEN` environment variable.
```python
from influxdb_client_3 import InfluxDBClient3
import os
client = InfluxDBClient3(
token=os.environ.get('INFLUXDB3_AUTH_TOKEN'),
host='http://{{< influxdb/host >}}',
database='servers'
)
@ -776,12 +874,22 @@ visualization of your time series data.
{{% product-name %}} supports a **last-n values cache** which stores the last N values in a series or column hierarchy in memory. This gives the database the ability to answer these kinds of queries in under 10 milliseconds.
You can use the `influxdb3` CLI to [create a last value cache](/influxdb3/version/reference/cli/influxdb3/create/last_cache/).
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 create last_cache \
-d <DATABASE_NAME> \
-t <TABLE> \
[CACHE_NAME]
--token AUTH_TOKEN
--database DATABASE_NAME \
--table TABLE_NAME \
CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the last values cache in
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache
Consider the following `cpu` sample table:
@ -797,6 +905,7 @@ The following command creates a last value cache named `cpuCache`:
```bash
influxdb3 create last_cache \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
--table cpu \
--key-columns host,application \
@ -808,10 +917,11 @@ _You can create a last values cache per time series, but be mindful of high card
#### Query a last values cache
To use the LVC, call it using the `last_cache()` function in your query--for example:
To query data from the LVC, use the [`last_cache()`](influxdb3/version/reference/sql/functions/cache/#last_cache) function in your query--for example:
```bash
influxdb3 query \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
"SELECT * FROM last_cache('cpu', 'cpuCache') WHERE host = 'Bravo';"
```
@ -819,32 +929,53 @@ influxdb3 query \
> [!Note]
> #### Only works with SQL
>
> The Last values cache only works with SQL, not InfluxQL; SQL is the default language.
> The last values cache only works with SQL, not InfluxQL; SQL is the default language.
#### Delete a Last values cache
#### Delete a last values cache
Use the `influxdb3` CLI to [delete a last values cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/)
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 delete last_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--cache-name <CACHE_NAME>
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--cache-name CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the last values cache from
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the last values cache from
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the last values cache to delete
### Distinct values cache
Similar to the Last values cache, the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns. This is useful for fast metadata lookups, which can return in under 30 milliseconds. Many of the options are similar to the last value cache.
Similar to the [last values cache](#last-values-cache), the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns.
This is useful for fast metadata lookups, which can return in under 30 milliseconds.
Many of the options are similar to the last value cache.
You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/).
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 create distinct_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--columns <COLUMNS> \
[CACHE_NAME]
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--columns COLUMNS \
CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the distinct values cache in
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache
Consider the following `cpu` sample table:
@ -860,6 +991,7 @@ The following command creates a distinct values cache named `cpuDistinctCache`:
```bash
influxdb3 create distinct_cache \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
--table cpu \
--columns host,application \
@ -868,10 +1000,11 @@ influxdb3 create distinct_cache \
#### Query a distinct values cache
To use the distinct values cache, call it using the `distinct_cache()` function in your query--for example:
To query data from the distinct values cache, use the [`distinct_cache()`](/influxdb3/version/reference/sql/functions/cache/#distinct_cache) function in your query--for example:
```bash
influxdb3 query \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
"SELECT * FROM distinct_cache('cpu', 'cpuDistinctCache')"
```
@ -885,19 +1018,28 @@ influxdb3 query \
Use the `influxdb3` CLI to [delete a distinct values cache](/influxdb3/version/reference/cli/influxdb3/delete/distinct_cache/)
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 delete distinct_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--cache-name <CACHE_NAME>
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--cache-name CACHE_NAME
```
{{% /code-placeholders %}}
### Python plugins and the Processing engine
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the distinct values cache from
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the distinct values cache from
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the distinct values cache to delete
The InfluxDB 3 Processing engine is an embedded Python VM for running code inside the database to process and transform data.
### Python plugins and the processing engine
To activate the Processing engine, pass the `--plugin-dir <PLUGIN_DIR>` option when starting the {{% product-name %}} server.
`PLUGIN_DIR` is your filesystem location for storing [plugin](#plugin) files for the Processing engine to run.
The InfluxDB 3 processing engine is an embedded Python VM for running code inside the database to process and transform data.
To activate the processing engine, pass the `--plugin-dir <PLUGIN_DIR>` option when starting the {{% product-name %}} server.
`PLUGIN_DIR` is your filesystem location for storing [plugin](#plugin) files for the processing engine to run.
#### Plugin
@ -1011,13 +1153,24 @@ To test a plugin, do the following:
- `--lp` or `--file`: The line protocol to test
- Optional: `--input-arguments`: A comma-delimited list of `<KEY>=<VALUE>` arguments for your plugin code
```bash
influxdb3 test wal_plugin \
--lp <INPUT_LINE_PROTOCOL> \
--input-arguments "arg1=foo,arg2=bar" \
--database <DATABASE_NAME> \
<PLUGIN_FILENAME>
```
{{% 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
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% 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 `<KEY>=<VALUE>` arguments for your plugin code--for example, `arg1=hello,arg2=world`
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against
- {{% 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.
@ -1042,7 +1195,8 @@ trigger:
# Test a plugin
influxdb3 test wal_plugin \
--lp "my_measure,tag1=asdf f1=1.0 123" \
--database mydb \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors \
--input-arguments "arg1=hello,arg2=world" \
test.py
```
@ -1050,7 +1204,8 @@ influxdb3 test wal_plugin \
```bash
# Create a trigger that runs the plugin
influxdb3 create trigger \
-d mydb \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors \
--plugin test_plugin \
--trigger-spec "table:foo" \
--trigger-arguments "arg1=hello,arg2=world" \
@ -1060,8 +1215,28 @@ influxdb3 create 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:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME" %}}
```bash
influxdb3 enable trigger --database mydb trigger1
influxdb3 enable trigger \
--token AUTH_TOKEN \
--database DATABASE_NAME \
TRIGGER_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to enable the trigger in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: the name of the trigger to enable
For example, to enable the trigger named `trigger1` in the `sensors` database:
```bash
influxdb3 enable trigger \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors
trigger1
```
For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/).

424
content/shared/v3-enterprise-get-started/_index.md
View File

@ -133,21 +133,20 @@ source ~/.zshrc
#### Start InfluxDB
To start your InfluxDB instance, use the `influxdb3 serve` command
and provide the following:
To start your InfluxDB instance, use the `influxdb3 serve` command and provide the following:
- `--object-store`: Specifies the type of Object store to use.
- `--object-store`: Specifies the type of object store to use.
InfluxDB supports the following: local file system (`file`), `memory`,
S3 (and compatible services like Ceph or Minio) (`s3`),
Google Cloud Storage (`google`), and Azure Blob Storage (`azure`).
The default is `file`.
Depending on the object store type, you may need to provide additional options
for your object store configuration.
- `--cluster-id`: A string identifier that determines part of the storage path hierarchy. All nodes within the same cluster share this identifier. The storage path follows the pattern `<CONFIGURED_PATH>/<CLUSTER_ID>/<NODE_ID>`. In a multi-node setup, this ID is used to reference the entire cluster.
- `--node-id`: A string identifier that distinguishes individual server instances within the cluster. This forms the final part of the storage path: `<CONFIGURED_PATH>/<CLUSTER_ID>/<NODE_ID>`. In a multi-node setup, this ID is used to reference specific nodes.
- `--cluster-id`: A string identifier that determines part of the storage path hierarchy. All nodes within the same cluster share this identifier. The storage path follows the pattern `<CONFIGURED_PATH>/<CLUSTER_ID>/<NODE_ID>`. In a multi-node setup, this ID is used to reference the entire cluster.
> [!Note]
> The combined path structure `<CONFIGURED_PATH>/<CLUSTER_ID>/<NODE_ID>` ensures proper organization of data in your object store, allowing for clean separation between clusters and individual nodes.
The following examples show how to start {{% product-name %}} with different object store configurations.
> [!Note]
> #### Diskless architecture
@ -156,16 +155,15 @@ and provide the following:
> storage alone, eliminating the need for locally attached disks.
> {{% product-name %}} can also work with only local disk storage when needed.
The following examples show how to start InfluxDB 3 with different object store configurations:
> [!Note]
> The combined path structure `<CONFIGURED_PATH>/<CLUSTER_ID>/<NODE_ID>` ensures proper organization of data in your object store, allowing for clean separation between clusters and individual nodes.
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store memory
```
##### Filesystem object store
Store data in a specified directory on the local filesystem.
This is the default object store type.
Replace the following with your values:
```bash
# Filesystem object store
@ -177,15 +175,12 @@ influxdb3 serve \
--data-dir ~/.influxdb3
```
To run the [Docker image](/influxdb3/enterprise/install/#docker-image) and persist data to the filesystem, mount a volume for the Object store-for example, pass the following options:
To run the [Docker image](/influxdb3/version/install/#docker-image) and persist data to the filesystem, mount a volume for the object store-for example, pass the following options:
- `-v /path/on/host:/path/in/container`: Mounts a directory from your filesystem to the container
- `--object-store file --data-dir /path/in/container`: Uses the mount for server storage
> [!Note]
>
> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections.
> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/).
<!--pytest.mark.skip-->
```bash
@ -201,15 +196,28 @@ docker run -it \
--data-dir /path/in/container
```
> [!Note]
>
> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections.
> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/).
##### S3 object store
Store data in an S3-compatible object store.
This is useful for production deployments that require high availability and durability.
Provide your bucket name and credentials to access the S3 object store.
```bash
# S3 object store (default is the us-east-1 region)
# Specify the Object store type and associated options
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store s3 \
--bucket BUCKET \
--aws-access-key-id AWS_ACCESS_KEY_ID \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY
```
@ -221,14 +229,28 @@ influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store s3 \
--bucket BUCKET \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key-id AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY \
--aws-endpoint ENDPOINT \
--aws-allow-http
```
For more information about server options, use the CLI help:
#### Memory object store
Store data in RAM without persisting it on shutdown.
It's useful for rapid testing and development.
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store memory
```
For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/serve/):
```bash
influxdb3 serve --help
@ -236,7 +258,7 @@ influxdb3 serve --help
#### Licensing
When first starting a new instance, InfluxDB prompts you to select a license type.
When first starting a new instance, {{% product-name %}} prompts you to select a license type.
InfluxDB 3 Enterprise licenses authorize the use of the InfluxDB 3 Enterprise software and apply to a single cluster. Licenses are primarily based on the number of CPUs InfluxDB can use, but there are other limitations depending on the license type. The following InfluxDB 3 Enterprise license types are available:
@ -250,7 +272,7 @@ You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage
After you have [started the server](#start-influxdb), you can create and manage tokens using the `influxdb3` CLI or the HTTP API.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
With authentication enabled, you must provide a token to access server actions.
With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
{{% product-name %}} supports the following types of tokens:
- **admin token**: Grants access to all CLI actions and API endpoints. A server can have one admin token.
@ -312,11 +334,12 @@ Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}
{{< /code-tabs-wrapper >}}
The command returns a token string that you can use to authenticate CLI commands and API requests.
Store your token in a secure location, as you cannot retrieve it from the database later.
For more information about tokens, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
After you have created an admin token, you can use it to create database tokens and system tokens.
For more information, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
#### Create a database token
To create a database token, use the `influxdb3 create token` subcommand and pass the following:
@ -394,21 +417,59 @@ For more information, see how to [Manage resource tokens](/influxdb3/version/adm
#### Use tokens to authorize CLI commands and API requests
- To authenticate `influxdb3` CLI commands, use the `--token` option or assign your
token to the `INFLUXDB3_AUTH_TOKEN` environment variable for `influxdb3` to use it automatically.
- To authenticate HTTP API requests, include `Bearer <TOKEN>` in the `Authorization` header value--for example:
#### Use tokens to authorize CLI commands and API requests
{{% code-placeholders "SYSTEM_TOKEN" %}}
With authentication enabled (the default), {{% product-name %}} requires a
token for all `influxdb3` CLI commands and HTTP API requests.
```bash
curl "http://{{< influxdb/host >}}/health" \
--header "Authorization: Bearer SYSTEM_TOKEN"
```
In the following examples, replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}} with your {{% token-link "admin" %}} string.
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#cli-use-a-token)
[HTTP API](#api-use-a-token)
{{% /tabs %}}
{{% tab-content %}}
For `influxdb3` to use your token automatically, assign it your
token to the `INFLUXDB3_AUTH_TOKEN` environment variable:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Set the environment variable for future CLI commands
export INFLUXDB3_AUTH_TOKEN=AUTH_TOKEN
```
{{% /code-placeholders %}}
Replace the following:
Or to authenticate a single `influxdb3` CLI command and override `$INFLUXDB3_AUTH_TOKEN`, include the `--token` option:
In your command, replace {{% code-placeholder-key %}}`SYSTEM_TOKEN`{{% /code-placeholder-key %}}: System token that grants access to system endpoints (`/health`, `/metrics`, etc.)
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Use the --token option for a single command
influxdb3 show databases --token AUTH_TOKEN
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
To authenticate HTTP API requests, include `Bearer <TOKEN>` in the `Authorization` header value:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Include the token in the Authorization HTTP request header
curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
{{% code-placeholders "SYSTEM_TOKEN" %}}
```bash
curl "http://{{< influxdb/host >}}/health" \
--header "Authorization: Bearer SYSTEM_TOKEN"
```
{{% /code-placeholders %}}
Replace {{% code-placeholder-key %}}`SYSTEM_TOKEN`{{% /code-placeholder-key %}} with the system token string that grants access to system endpoints (`/health`, `/metrics`)
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Data model
@ -504,11 +565,11 @@ In the code samples, replace the following placeholders with your values:
Pass data as quoted line protocol via standard input (stdin)--for example:
{{% code-placeholders "DATABASE_NAME|TOKEN" %}}
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 write \
--database DATABASE_NAME \
--token TOKEN \
--token AUTH_TOKEN \
--precision ns \
--accept-partial \
'cpu,host=Alpha,region=us-west,application=webserver val=1i,usage_percent=20.5,status="OK"
@ -526,17 +587,21 @@ Pass the `--file` option to write line protocol you have saved to a file--for ex
[sample line protocol](#write-data-in-line-protocol-syntax) to a file named `server_data`
and then enter the following command:
{{% code-placeholders "DATABASE_NAME|TOKEN" %}}
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 write \
--database DATABASE_NAME \
--token TOKEN \
--token AUTH_TOKEN \
--precision ns \
--accept-partial \
--file server_data
--file path/to/server_data
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to.
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}}
### Write data using the HTTP API
{{% product-name %}} provides three write API endpoints that respond to HTTP `POST` requests.
@ -568,7 +633,7 @@ and supports the following parameters:
- `?precision=<PRECISION>`: Specify the precision of the timestamp. The default is nanosecond precision.
- request body: The line protocol data to write.
For more information about the parameters, see [Write data](/influxdb3/core/write-data/).
For more information about the parameters, see [Write data](/influxdb3/version/write-data/).
##### Example: write data using the /api/v3 HTTP API
@ -581,6 +646,7 @@ With `accept_partial=true` (default):
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw 'home,room=Sunroom temp=96
home,room=Sunroom temp="hi"'
```
@ -611,6 +677,7 @@ With `accept_partial=false`:
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw 'home,room=Sunroom temp=96
home,room=Sunroom temp="hi"'
```
@ -664,17 +731,17 @@ The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility
#### Write responses
By default, InfluxDB acknowledges writes after flushing the WAL file to the Object store (occurring every second).
By default, InfluxDB acknowledges writes after flushing the WAL file to the object store (occurring every second).
For high write throughput, you can send multiple concurrent write requests.
#### Use no_sync for immediate write responses
To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes.
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the Object store.
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the object store.
Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability.
- Default behavior (`no_sync=false`): Waits for data to be written to the Object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
- Default behavior (`no_sync=false`): Waits for data to be written to the object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence.
##### Immediate write using the HTTP API
@ -683,30 +750,27 @@ The `no_sync` parameter controls when writes are acknowledged--for example:
```bash
curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
--data-raw "home,room=Sunroom temp=96"
```
##### Immediate write using the influxdb3 CLI
The `no_sync` CLI option controls when writes are acknowledged--for example:
```bash
influxdb3 write \
--bucket mydb \
--org my_org \
--token my-token \
--no-sync
```
### Create a database or table
To create a database without writing data, use the `create` subcommand--for example:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 create database mydb
influxdb3 create database DATABASE_NAME \
--token AUTH_TOKEN
```
{{% /code-placeholders %}}
To learn more about a subcommand, use the `-h, --help` flag:
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server
To learn more about a subcommand, use the `-h, --help` flag or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/create/):
```bash
influxdb3 create -h
@ -774,12 +838,20 @@ $ influxdb3 query --database servers "SELECT DISTINCT usage_percent, time FROM c
To query using InfluxQL, enter the `influxdb3 query` subcommand and specify `influxql` in the language option--for example:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 query \
--database servers \
--database DATABASE_NAME \
--token <AUTH_TOKEN> \
--language influxql \
"SELECT DISTINCT usage_percent FROM cpu WHERE time >= now() - 1d"
```
{{% /code-placeholders %}}
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
@ -795,18 +867,35 @@ Use the `format` parameter to specify the response format: `pretty`, `jsonl`, `p
The following example sends an HTTP `GET` request with a URL-encoded SQL query:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
curl -v "http://{{< influxdb/host >}}/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5"
curl -G "http://{{< influxdb/host >}}/api/v3/query_sql" \
--header 'Authorization: Bearer AUTH_TOKEN' \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=select * from cpu limit 5"
```
{{% /code-placeholders %}}
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 %}}
##### Example: Query passing JSON parameters
The following example sends an HTTP `POST` request with parameters in a JSON payload:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```bash
curl http://{{< influxdb/host >}}/api/v3/query_sql \
--data '{"db": "server", "q": "select * from cpu limit 5"}'
--data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}'
```
{{% /code-placeholders %}}
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
@ -821,24 +910,35 @@ pip install influxdb3-python
From here, you can connect to your database with the client library using just the **host** and **database name:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```python
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
token='AUTH_TOKEN',
host='http://{{< influxdb/host >}}',
database='servers'
database='DATABASE_NAME'
)
```
{{% /code-placeholders %}}
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 %}}
The following example shows how to query using SQL, and then
use PyArrow to explore the schema and process results:
use PyArrow to explore the schema and process results.
To authorize the query, the example retrieves the {{% token-link "database" %}}
from the `INFLUXDB3_AUTH_TOKEN` environment variable.
```python
from influxdb_client_3 import InfluxDBClient3
import os
client = InfluxDBClient3(
token=os.environ.get('INFLUXDB3_AUTH_TOKEN'),
host='http://{{< influxdb/host >}}',
database='servers'
)
@ -883,18 +983,27 @@ Set your expected database connection details on the Settings page.
From there, you can query data, browser your database schema, and do basic
visualization of your time series data.
### Last values cache
{{% product-name %}} supports a **last-n values cache** which stores the last N values in a series or column hierarchy in memory. This gives the database the ability to answer these kinds of queries in under 10 milliseconds.
You can use the `influxdb3` CLI to create a last value cache.
You can use the `influxdb3` CLI to [create a last value cache](/influxdb3/version/reference/cli/influxdb3/create/last_cache/).
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 create last_cache \
-d <DATABASE_NAME> \
-t <TABLE> \
[CACHE_NAME]
--token AUTH_TOKEN
--database DATABASE_NAME \
--table TABLE_NAME \
CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the last values cache in
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache
Consider the following `cpu` sample table:
@ -910,6 +1019,7 @@ The following command creates a last value cache named `cpuCache`:
```bash
influxdb3 create last_cache \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
--table cpu \
--key-columns host,application \
@ -921,10 +1031,11 @@ _You can create a last values cache per time series, but be mindful of high card
#### Query a last values cache
To use the LVC, call it using the `last_cache()` function in your query--for example:
To query data from the LVC, use the [`last_cache()`](influxdb3/version/reference/sql/functions/cache/#last_cache) function in your query--for example:
```bash
influxdb3 query \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
"SELECT * FROM last_cache('cpu', 'cpuCache') WHERE host = 'Bravo';"
```
@ -932,32 +1043,53 @@ influxdb3 query \
> [!Note]
> #### Only works with SQL
>
> The Last values cache only works with SQL, not InfluxQL; SQL is the default language.
> The last values cache only works with SQL, not InfluxQL; SQL is the default language.
#### Delete a Last values cache
#### Delete a last values cache
Use the `influxdb3` CLI to [delete a last values cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/)
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 delete last_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--cache-name <CACHE_NAME>
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--cache-name CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the last values cache from
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the last values cache from
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the last values cache to delete
### Distinct values cache
Similar to the Last values cache, the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns. This is useful for fast metadata lookups, which can return in under 30 milliseconds. Many of the options are similar to the last value cache.
Similar to the [last values cache](#last-values-cache), the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns.
This is useful for fast metadata lookups, which can return in under 30 milliseconds.
Many of the options are similar to the last value cache.
You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/).
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 create distinct_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--columns <COLUMNS> \
[CACHE_NAME]
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--columns COLUMNS \
CACHE_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the distinct values cache in
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache
Consider the following `cpu` sample table:
@ -973,6 +1105,7 @@ The following command creates a distinct values cache named `cpuDistinctCache`:
```bash
influxdb3 create distinct_cache \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
--table cpu \
--columns host,application \
@ -985,6 +1118,7 @@ To use the distinct values cache, call it using the `distinct_cache()` function
```bash
influxdb3 query \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database servers \
"SELECT * FROM distinct_cache('cpu', 'cpuDistinctCache')"
```
@ -998,19 +1132,28 @@ influxdb3 query \
Use the `influxdb3` CLI to [delete a distinct values cache](/influxdb3/version/reference/cli/influxdb3/delete/distinct_cache/)
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}}
```bash
influxdb3 delete distinct_cache \
--database <DATABASE_NAME> \
--table <TABLE> \
--cache-name <CACHE_NAME>
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE \
--cache-name CACHE_NAME
```
{{% /code-placeholders %}}
### Python plugins and the Processing engine
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the distinct values cache from
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the distinct values cache from
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the distinct values cache to delete
The InfluxDB 3 Processing engine is an embedded Python VM for running code inside the database to process and transform data.
### Python plugins and the processing engine
To activate the Processing engine, pass the `--plugin-dir <PLUGIN_DIR>` option when starting the {{% product-name %}} server.
`PLUGIN_DIR` is your filesystem location for storing [plugin](#plugin) files for the Processing engine to run.
The InfluxDB 3 processing engine is an embedded Python VM for running code inside the database to process and transform data.
To activate the processing engine, pass the `--plugin-dir <PLUGIN_DIR>` option when starting the {{% product-name %}} server.
`PLUGIN_DIR` is your filesystem location for storing [plugin](#plugin) files for the processing engine to run.
#### Plugin
@ -1027,7 +1170,7 @@ InfluxDB 3 provides the following types of triggers, each with specific trigger-
- **On WAL flush**: Sends a batch of written data (for a specific table or all tables) to a plugin (by default, every second).
- **On Schedule**: Executes a plugin on a user-configured schedule (using a crontab or a duration); useful for data collection and deadman monitoring.
- **On Request**: Binds a plugin to a custom HTTP API endpoint at `/api/v3/engine/<ENDPOINT>`.
- **On Request**: Binds a plugin to a custom HTTP API endpoint at `/api/v3/engine/<ENDPOINT_PATH>`.
The plugin receives the HTTP request headers and content, and can then parse, process, and send the data into the database or to third-party services.
### Test, create, and trigger plugin code
@ -1124,13 +1267,24 @@ To test a plugin, do the following:
- `--lp` or `--file`: The line protocol to test
- Optional: `--input-arguments`: A comma-delimited list of `<KEY>=<VALUE>` arguments for your plugin code
```bash
influxdb3 test wal_plugin \
--lp <INPUT_LINE_PROTOCOL> \
--input-arguments "arg1=foo,arg2=bar" \
--database <DATABASE_NAME> \
<PLUGIN_FILENAME>
```
{{% 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
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% 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 `<KEY>=<VALUE>` arguments for your plugin code--for example, `arg1=hello,arg2=world`
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against
- {{% 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.
@ -1155,7 +1309,8 @@ trigger:
# Test a plugin
influxdb3 test wal_plugin \
--lp "my_measure,tag1=asdf f1=1.0 123" \
--database mydb \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors \
--input-arguments "arg1=hello,arg2=world" \
test.py
```
@ -1163,7 +1318,8 @@ influxdb3 test wal_plugin \
```bash
# Create a trigger that runs the plugin
influxdb3 create trigger \
-d mydb \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors \
--plugin test_plugin \
--trigger-spec "table:foo" \
--trigger-arguments "arg1=hello,arg2=world" \
@ -1173,8 +1329,28 @@ influxdb3 create 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:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME" %}}
```bash
influxdb3 enable trigger --database mydb trigger1
influxdb3 enable trigger \
--token AUTH_TOKEN \
--database DATABASE_NAME \
TRIGGER_NAME
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to enable the trigger in
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: the name of the trigger to enable
For example, to enable the trigger named `trigger1` in the `sensors` database:
```bash
influxdb3 enable trigger \
--token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \
--database sensors
trigger1
```
For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/).
@ -1225,6 +1401,7 @@ influxdb3 serve \
--http-bind {{< influxdb/host >}} \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
```bash
## NODE 2
@ -1241,8 +1418,8 @@ influxdb3 serve \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind localhost:8282 \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
--aws-access-key-id AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY
```
After the nodes have started, querying either node returns data for both nodes, and _NODE 1_ runs compaction.
@ -1442,28 +1619,43 @@ You can use the default port `8181` for any write or query, without changing any
>
> When running multiple local instances for testing or separate nodes in production, specifying the host ensures writes and queries are routed to the correct instance.
{{% code-placeholders "(http://localhost:8585)|AUTH_TOKEN|DATABASE_NAME|QUERY" %}}
```bash
# Example variables on a query
# Example querying a specific host
# HTTP-bound Port: 8585
influxdb3 query http://localhost:8585 --database <DATABASE> "<QUERY>"
influxdb3 query \
--host http://localhost:8585
--token AUTH_TOKEN \
--database DATABASE_NAME "QUERY"
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`http://localhost:8585`{{% /code-placeholder-key %}}: the host and port of the node 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 %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query
- {{% code-placeholder-key %}}`QUERY`{{% /code-placeholder-key %}}: the SQL or InfluxQL query to run against the database
### File index settings
To accelerate performance on specific queries, you can define non-primary keys to index on, which helps improve performance for single-series queries.
This feature is only available in Enterprise and is not available in Core.
This feature is only available in {{% product-name %}} and is not available in Core.
#### Create a file index
{{% code-placeholders "AUTH_TOKEN|DATABASE|TABLE|COLUMNS" %}}
```bash
# Example variables on a query
# HTTP-bound Port: 8585
influxdb3 create file_index \
--host http://localhost:8585 \
--database <DATABASE> \
--table <TABLE> \
<COLUMNS>
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE_NAME \
COLUMNS
```
#### Delete a file index
@ -1471,6 +1663,14 @@ influxdb3 create file_index \
```bash
influxdb3 delete file_index \
--host http://localhost:8585 \
--database <DATABASE> \
--table <TABLE> \
--database DATABASE_NAME \
--table TABLE_NAME \
```
{{% /code-placeholders %}}
Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the file index in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the file index in
- {{% code-placeholder-key %}}`COLUMNS`{{% /code-placeholder-key %}}: a comma-separated list of columns to index on, for example, `host,application`