chore(mono): Unify Core and Enterprise get-started pages

- Unify into a common page using show-in and other shortcodes
- Misc. fixes and cleanup
fix-mono-get-started
Jason Stirnaman 2025-05-29 15:21:15 -05:00
parent d563dc9116
commit af7a6ff51e
2 changed files with 794 additions and 76 deletions

View File

@ -11,7 +11,13 @@ Common use cases include:
InfluxDB is optimized for scenarios where near real-time data monitoring is essential and queries need to return quickly to support user experiences such as dashboards and interactive user interfaces. InfluxDB is optimized for scenarios where near real-time data monitoring is essential and queries need to return quickly to support user experiences such as dashboards and interactive user interfaces.
{{% show-in "enterprise" %}}
{{% product-name %}} is built on InfluxDB 3 Core, the InfluxDB 3 open source release.
{{% /show-in %}}
{{% show-in "core" %}}
{{% product-name %}} is the InfluxDB 3 open source release. {{% product-name %}} is the InfluxDB 3 open source release.
{{% /show-in %}}
Core's feature highlights include: Core's feature highlights include:
* Diskless architecture with object storage support (or local disk with no dependencies) * Diskless architecture with object storage support (or local disk with no dependencies)
@ -29,11 +35,18 @@ The Enterprise version adds the following features to Core:
* Row-level delete support (coming soon) * Row-level delete support (coming soon)
* Integrated admin UI (coming soon) * Integrated admin UI (coming soon)
{{% show-in "core" %}}
For more information, see how to [get started with Enterprise](/influxdb3/enterprise/get-started/). For more information, see how to [get started with Enterprise](/influxdb3/enterprise/get-started/).
{{% /show-in %}}
### What's in this guide ### What's in this guide
{{% show-in "enterprise" %}}
This guide covers Enterprise as well as InfluxDB 3 Core, including the following topics:
{{% /show-in %}}
{{% show-in "core" %}}
This guide covers InfluxDB 3 Core (the open source release), including the following topics: This guide covers InfluxDB 3 Core (the open source release), including the following topics:
{{% /show-in %}}
- [Install and startup](#install-and-startup) - [Install and startup](#install-and-startup)
- [Authentication and authorization](#authentication-and-authorization) - [Authentication and authorization](#authentication-and-authorization)
@ -44,6 +57,9 @@ This guide covers InfluxDB 3 Core (the open source release), including the follo
- [Last values cache](#last-values-cache) - [Last values cache](#last-values-cache)
- [Distinct values cache](#distinct-values-cache) - [Distinct values cache](#distinct-values-cache)
- [Python plugins and the processing engine](#python-plugins-and-the-processing-engine) - [Python plugins and the processing engine](#python-plugins-and-the-processing-engine)
{{% show-in "enterprise" %}}
- [Multi-server setups](#multi-server-setup)
{{% /show-in %}}
> [!Tip] > [!Tip]
> #### Find support for {{% product-name %}} > #### Find support for {{% product-name %}}
@ -55,6 +71,7 @@ This guide covers InfluxDB 3 Core (the open source release), including the follo
{{% product-name %}} runs on **Linux**, **macOS**, and **Windows**. {{% product-name %}} runs on **Linux**, **macOS**, and **Windows**.
{{% show-in "enterprise" %}}
{{% tabs-wrapper %}} {{% tabs-wrapper %}}
{{% tabs %}} {{% tabs %}}
[Linux or macOS](#linux-or-macos) [Linux or macOS](#linux-or-macos)
@ -68,10 +85,10 @@ To get started quickly, download and run the install script--for example, using
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```bash ```bash
curl -O https://www.influxdata.com/d/install_influxdb3.sh \ curl -O https://www.influxdata.com/d/install_influxdb3.sh \
&& sh install_influxdb3.sh && sh install_influxdb3.sh enterprise
``` ```
Or, download and install [build artifacts](/influxdb3/core/install/#download-influxdb-3-core-binaries): Or, download and install [build artifacts](/influxdb3/enterprise/install/#download-influxdb-3-enterprise-binaries):
- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz) - [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz)
@ -98,6 +115,63 @@ Download and install the {{% product-name %}} [Windows (AMD64, x86_64) binary](h
{{% tab-content %}} {{% tab-content %}}
<!--------------- BEGIN DOCKER --------------> <!--------------- BEGIN DOCKER -------------->
The [`influxdb:3-enterprise` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-enterprise)
is available for x86_64 (AMD64) and ARM64 architectures.
Pull the image:
<!--pytest.mark.skip-->
```bash
docker pull influxdb:3-enterprise
```
<!--------------- END DOCKER -------------->
{{% /tab-content %}}
{{% /tabs-wrapper %}}
{{% /show-in %}}
{{% show-in "core" %}}
{{% tabs-wrapper %}}
{{% tabs %}}
[Linux or macOS](#linux-or-macos)
[Windows](#windows)
[Docker](#docker)
{{% /tabs %}}
{{% tab-content %}}
<!--------------- BEGIN LINUX AND MACOS -------------->
To get started quickly, download and run the install script--for example, using [curl](https://curl.se/download.html):
<!--pytest.mark.skip-->
```bash
curl -O https://www.influxdata.com/d/install_influxdb3.sh \
&& sh install_influxdb3.sh
```
Or, download and install [build artifacts](/influxdb3/core/install/#download-influxdb-3-core-binaries):
- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz.sha256)
- [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz.sha256)
- [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz.sha256)
> [!Note]
> macOS Intel builds are coming soon.
<!--------------- END LINUX AND MACOS -------------->
{{% /tab-content %}}
{{% tab-content %}}
<!--------------- BEGIN WINDOWS -------------->
Download and install the {{% product-name %}} [Windows (AMD64, x86_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256)
<!--------------- END WINDOWS -------------->
{{% /tab-content %}}
{{% tab-content %}}
<!--------------- BEGIN DOCKER -------------->
The [`influxdb:3-core` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-core) The [`influxdb:3-core` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-core)
is available for x86_64 (AMD64) and ARM64 architectures. is available for x86_64 (AMD64) and ARM64 architectures.
@ -108,18 +182,10 @@ Pull the image:
docker pull influxdb:3-core docker pull influxdb:3-core
``` ```
##### InfluxDB 3 Explorer -- Query Interface (Beta)
You can download the new InfluxDB 3 Explorer query interface using Docker.
Explorer is currently in beta. Pull the image:
```bash
docker pull quay.io/influxdb/influxdb3-explorer:latest
```
<!--------------- END DOCKER --------------> <!--------------- END DOCKER -------------->
{{% /tab-content %}} {{% /tab-content %}}
{{% /tabs-wrapper %}} {{% /tabs-wrapper %}}
{{% /show-in %}}
_Build artifacts and images update with every merge into the {{% product-name %}} `main` branch._ _Build artifacts and images update with every merge into the {{% product-name %}} `main` branch._
@ -138,20 +204,38 @@ If your system doesn't locate `influxdb3`, then `source` the configuration file
source ~/.zshrc source ~/.zshrc
``` ```
> [!Tip]
> #### Run the InfluxDB 3 Explorer query interface (beta)
>
> InfluxDB 3 Explorer (currently in beta) is the user interface component of the InfluxDB 3 platform.
> It provides visual management of databases and tokens and an easy way to query your time series data.
>
> Use Docker to download and run InfluxDB 3 Explorer:
>
> ```bash
> docker pull quay.io/influxdb/influxdb3-explorer:latest
> ```
#### Start InfluxDB #### 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`, InfluxDB supports the following: local file system (`file`), `memory`,
S3 (and compatible services like Ceph or Minio) (`s3`), S3 (and compatible services like Ceph or Minio) (`s3`),
Google Cloud Storage (`google`), and Azure Blob Storage (`azure`). Google Cloud Storage (`google`), and Azure Blob Storage (`azure`).
The default is `file`. The default is `file`.
Depending on the object store type, you may need to provide additional options Depending on the object store type, you may need to provide additional options
for your object store configuration. for your object store configuration.
{{% show-in "enterprise" %}}
- `--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.
{{% /show-in %}}
{{% show-in "core" %}}
- `--node-id`: A string identifier that distinguishes individual server instances within the 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>/<NODE_ID>`. 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. In a multi-node setup, this ID is used to reference specific nodes.
{{% /show-in %}}
The following examples show how to start {{% product-name %}} with different object store configurations. The following examples show how to start {{% product-name %}} with different object store configurations.
@ -162,6 +246,11 @@ The following examples show how to start {{% product-name %}} with different obj
> storage alone, eliminating the need for locally attached disks. > storage alone, eliminating the need for locally attached disks.
> {{% product-name %}} can also work with only local disk storage when needed. > {{% product-name %}} can also work with only local disk storage when needed.
{{% show-in "enterprise" %}}
> [!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.
{{% /show-in %}}
##### Filesystem object store ##### Filesystem object store
Store data in a specified directory on the local filesystem. Store data in a specified directory on the local filesystem.
@ -169,6 +258,18 @@ This is the default object store type.
Replace the following with your values: Replace the following with your values:
{{% show-in "enterprise" %}}
```bash
# Filesystem object store
# Provide the filesystem directory
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store file \
--data-dir ~/.influxdb3
```
{{% /show-in %}}
{{% show-in "core" %}}
```bash ```bash
# Filesystem object store # Filesystem object store
# Provide the filesystem directory # Provide the filesystem directory
@ -177,12 +278,30 @@ influxdb3 serve \
--object-store file \ --object-store file \
--data-dir ~/.influxdb3 --data-dir ~/.influxdb3
``` ```
{{% /show-in %}}
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: 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 - `-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 - `--object-store file --data-dir /path/in/container`: Uses the mount for server storage
{{% show-in "enterprise" %}}
<!--pytest.mark.skip-->
```bash
# Filesystem object store with Docker
# Create a mount
# Provide the mount path
docker run -it \
-v /path/on/host:/path/in/container \
influxdb:3-enterprise influxdb3 serve \
--node-id my_host \
--cluster-id my_cluster \
--object-store file \
--data-dir /path/in/container
```
{{% /show-in %}}
{{% show-in "core" %}}
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```bash ```bash
# Filesystem object store with Docker # Filesystem object store with Docker
@ -195,6 +314,7 @@ docker run -it \
--object-store file \ --object-store file \
--data-dir /path/in/container --data-dir /path/in/container
``` ```
{{% /show-in %}}
> [!Note] > [!Note]
> >
@ -207,6 +327,36 @@ Store data in an S3-compatible object store.
This is useful for production deployments that require high availability and durability. This is useful for production deployments that require high availability and durability.
Provide your bucket name and credentials to access the S3 object store. Provide your bucket name and credentials to access the S3 object store.
{{% show-in "enterprise" %}}
```bash
# S3 object store (default is the us-east-1 region)
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store s3 \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY
```
```bash
# Minio or other open source object store
# (using the AWS S3 API with additional parameters)
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store s3 \
--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
```
{{% /show-in %}}
{{% show-in "core" %}}
```bash ```bash
# S3 object store (default is the us-east-1 region) # 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
@ -231,12 +381,24 @@ influxdb3 serve \
--aws-endpoint ENDPOINT \ --aws-endpoint ENDPOINT \
--aws-allow-http --aws-allow-http
``` ```
{{% /show-in %}}
#### Memory object store #### Memory object store
Store data in RAM without persisting it on shutdown. Store data in RAM without persisting it on shutdown.
It's useful for rapid testing and development. It's useful for rapid testing and development.
{{% show-in "enterprise" %}}
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--object-store memory
```
{{% /show-in %}}
{{% show-in "core" %}}
```bash ```bash
# Memory object store # Memory object store
# Stores data in RAM; doesn't persist data # Stores data in RAM; doesn't persist data
@ -244,6 +406,7 @@ influxdb3 serve \
--node-id host01 \ --node-id host01 \
--object-store memory --object-store memory
``` ```
{{% /show-in %}}
For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/): For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/):
@ -251,15 +414,55 @@ For more information about server options, use the CLI help or view the [InfluxD
influxdb3 serve --help influxdb3 serve --help
``` ```
{{% show-in "enterprise" %}}
#### Licensing
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:
- **Trial**: 30-day trial license with full access to InfluxDB 3 Enterprise capabilities.
- **At-Home**: For at-home hobbyist use with limited access to InfluxDB 3 Enterprise capabilities.
- **Commercial**: Commercial license with full access to InfluxDB 3 Enterprise capabilities.
You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage your license](https://docs.influxdata.com/influxdb3/enterprise/admin/license/)page.
{{% /show-in %}}
### Authentication and authorization ### Authentication and authorization
{{% product-name %}} uses token-based authentication and authorization, which is enabled by default when you start the server. {{% 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 with `influxdb3` CLI commands and HTTP API requests. With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
{{% show-in "enterprise" %}}
{{% 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.
- **resource tokens**: Tokens that grant read and write access to specific resources (databases and system information endpoints) on the server.
- A database token grants access to write and query data in a
database
- A system token grants read access to system information endpoints and
metrics for the server
{{% /show-in %}}
{{% show-in "core" %}}
{{% product-name %}} supports _admin_ tokens, which grant access to all CLI actions and API endpoints.
{{% /show-in %}}
For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/).
#### Create an operator token #### Create an operator token
After you start the server, create your first admin token (the operator token): After you start the server, create your first admin token.
The first admin token you create is the _operator_ token for the server.
Use the `influxdb3` CLI or the HTTP API to create your operator token.
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
{{< code-tabs-wrapper >}} {{< code-tabs-wrapper >}}
{{% code-tabs %}} {{% code-tabs %}}
@ -288,17 +491,16 @@ Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}
{{< /code-tabs-wrapper >}} {{< /code-tabs-wrapper >}}
The command returns a token string for authenticating CLI commands and API requests. The command returns a token string for authenticating CLI commands and API requests.
Store your token securely—you cannot retrieve it from the database later.
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
#### Set your token for authentication #### Set your token for authentication
Use one of the following methods to authenticate requests. Use your operator token to authenticate server actions in {{% product-name %}},
In your commands, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step). such as creating additional tokens, performing administrative tasks, and writing and querying data.
Use one of the following methods to provide your token and authenticate `influxdb3` CLI commands.
In your command, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step).
{{< tabs-wrapper >}} {{< tabs-wrapper >}}
{{% tabs %}} {{% tabs %}}
@ -329,7 +531,7 @@ influxdb3 show databases --token AUTH_TOKEN
{{% /tab-content %}} {{% /tab-content %}}
{{< /tabs-wrapper >}} {{< /tabs-wrapper >}}
For HTTP API requests, include your token in the `Authorization` header: For HTTP API requests, include your token in the `Authorization` header--for example:
{{% code-placeholders "AUTH_TOKEN" %}} {{% code-placeholders "AUTH_TOKEN" %}}
```bash ```bash
@ -338,10 +540,13 @@ curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
#### Learn more about token management #### Learn more about tokens and permissions
- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Create, list, and delete admin tokens - [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Understand and manage operator and named admin tokens
- [Token types and permissions](/influxdb3/version/admin/tokens/) - Understanding operator and named admin tokens {{% show-in "enterprise" %}}
- [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, list, and delete resource tokens
{{% /show-in %}}
- [Authentication](/influxdb3/version/reference/internals/authentication/) - Understand authentication, authorizations, and permissions in {{% product-name %}}
### Data model ### Data model
@ -359,12 +564,13 @@ This tutorial covers many of the recommended tools.
| Tool | Administration | Write | Query | | Tool | Administration | Write | Query |
| :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: | | :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: |
| `influxdb3` CLI{{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | **`influxdb3` CLI** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| InfluxDB HTTP API {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | **InfluxDB HTTP API** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| **InfluxDB 3 Explorer** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | - | **{{< icon "check" >}}** |
| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | | [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - |
| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 Processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB 3 processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - | | [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - |
| [Chronograf](/chronograf/v1/) | - | - | - | | [Chronograf](/chronograf/v1/) | - | - | - |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - | | <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
@ -384,17 +590,19 @@ InfluxDB is a schema-on-write database. You can start writing data and InfluxDB
After a schema is created, InfluxDB validates future write requests against it before accepting the data. After a schema is created, InfluxDB validates future write requests against it before accepting the data.
Subsequent requests can add new fields on-the-fly, but can't add new tags. Subsequent requests can add new fields on-the-fly, but can't add new tags.
{{% show-in "core" %}}
> [!Note] > [!Note]
> #### Core is optimized for recent data > #### Core is optimized for recent data
> >
> {{% product-name %}} is optimized for recent data but accepts writes from any time period. > {{% product-name %}} is optimized for recent data but accepts writes from any time period.
> The system persists data to Parquet files for historical analysis with [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/) or third-party tools. > The system persists data to Parquet files for historical analysis with [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/) or third-party tools.
> For extended historical queries and optimized data organization, consider using [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/). > For extended historical queries and optimized data organization, consider using [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/).
{{% /show-in %}}
#### Write data in line protocol syntax #### Write data in line protocol syntax
{{% product-name %}} accepts data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) syntax. {{% product-name %}} accepts data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax.
The following code block is an example of time series data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) syntax: The following code block is an example of time series data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax:
- `cpu`: the table name. - `cpu`: the table name.
- `host`, `region`, `applications`: the tags. A tag set is an ordered, comma-separated list of key/value pairs where the values are strings. - `host`, `region`, `applications`: the tags. A tag set is an ordered, comma-separated list of key/value pairs where the values are strings.
@ -654,10 +862,12 @@ influxdb3 create -h
InfluxDB 3 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. SQL-like language customized for time series queries.
{{% show-in "core" %}}
{{< product-name >}} limits {{< product-name >}} limits
query time ranges to 72 hours (both recent and historical) to ensure query performance. query time ranges to 72 hours (both recent and historical) to ensure query performance.
For more information about the 72-hour limitation, see the For more information about the 72-hour limitation, see the
[update on InfluxDB 3 Cores 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/). [update on InfluxDB 3 Cores 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/).
{{% /show-in %}}
> [!Note] > [!Note]
> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3. > Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3.
@ -853,9 +1063,16 @@ docker pull quay.io/influxdb/influxdb3-explorer:latest
Run the interface using: Run the interface using:
{{% show-in "enterprise" %}}
```bash
docker run -p 8086:80 -p 8087:8888 quay.io/influxdb/influxdb3-explorer:latest --mode=normal
```
{{% /show-in %}}
{{% show-in "core" %}}
```bash ```bash
docker run --name influxdb3-explorer -p 8086:8888 quay.io/influxdb/influxdb3-explorer:latest docker run --name influxdb3-explorer -p 8086:8888 quay.io/influxdb/influxdb3-explorer:latest
``` ```
{{% /show-in %}}
With the default settings above, you can access the UI at http://localhost:8086. With the default settings above, you can access the UI at http://localhost:8086.
Set your expected database connection details on the Settings page. Set your expected database connection details on the Settings page.
@ -865,6 +1082,7 @@ visualization of your time series data.
### Last values cache ### 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. {{% 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/). 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" %}} {{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
@ -1233,3 +1451,325 @@ influxdb3 enable trigger \
``` ```
For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/). For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/).
{{% show-in "enterprise" %}}
### Multi-server setup
{{% product-name %}} is built to support multi-node setups for high availability, read replicas, and flexible implementations depending on use case.
### High availability
Enterprise is architecturally flexible, giving you options on how to configure multiple servers that work together for high availability (HA) and high performance.
Built on top of the diskless engine and leveraging the Object store, an HA setup ensures that if a node fails, you can still continue reading from, and writing to, a secondary node.
A two-node setup is the minimum for basic high availability, with both nodes having read-write permissions.
{{< img-hd src="/img/influxdb/influxdb-3-enterprise-high-availability.png" alt="Basic high availability setup" />}}
In a basic HA setup:
- Two nodes both write data to the same Object store and both handle queries
- Node 1 and Node 2 are _read replicas_ that read from each others Object store directories
- One of the nodes is designated as the Compactor node
> [!Note]
> Only one node can be designated as the Compactor.
> Compacted data is meant for a single writer, and many readers.
The following examples show how to configure and start two nodes
for a basic HA setup.
- _Node 1_ is for compaction (passes `compact` in `--mode`)
- _Node 2_ is for ingest and query
```bash
## NODE 1
# Example variables
# node-id: 'host01'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--mode ingest,query,compact \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind {{< influxdb/host >}} \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
```bash
## NODE 2
# Example variables
# node-id: 'host02'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host02 \
--cluster-id cluster01 \
--mode ingest,query \
--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
```
After the nodes have started, querying either node returns data for both nodes, and _NODE 1_ runs compaction.
To add nodes to this setup, start more read replicas with the same cluster ID.
### High availability with a dedicated Compactor
Data compaction in InfluxDB 3 is one of the more computationally expensive operations.
To ensure that your read-write nodes don't slow down due to compaction work, set up a compactor-only node for consistent and high performance across all nodes.
{{< img-hd src="/img/influxdb/influxdb-3-enterprise-dedicated-compactor.png" alt="Dedicated Compactor setup" />}}
The following examples show how to set up high availability with a dedicated Compactor node:
1. Start two read-write nodes as read replicas, similar to the previous example.
```bash
## NODE 1 — Writer/Reader Node #1
# Example variables
# node-id: 'host01'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--mode ingest,query \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind {{< influxdb/host >}} \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
```bash
## NODE 2 — Writer/Reader Node #2
# Example variables
# node-id: 'host02'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host02 \
--cluster-id cluster01 \
--mode ingest,query \
--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>
```
2. Start the dedicated compactor node with the `--mode=compact` option to ensure the node **only** runs compaction.
```bash
## NODE 3 — Compactor Node
# Example variables
# node-id: 'host03'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host03 \
--cluster-id cluster01 \
--mode compact \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
### High availability with read replicas and a dedicated Compactor
For a robust and effective setup for managing time-series data, you can run ingest nodes alongside read-only nodes and a dedicated Compactor node.
{{< img-hd src="/img/influxdb/influxdb-3-enterprise-workload-isolation.png" alt="Workload Isolation Setup" />}}
1. Start ingest nodes by assigning them the **`ingest`** mode.
To achieve the benefits of workload isolation, you'll send _only write requests_ to these ingest nodes. Later, you'll configure the _read-only_ nodes.
```bash
## NODE 1 — Writer Node #1
# Example variables
# node-id: 'host01'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host01 \
--cluster-id cluster01 \
--mode ingest \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind {{< influxdb/host >}} \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
<!-- The following examples use different ports for different nodes. Don't use the influxdb/host shortcode below. -->
```bash
## NODE 2 — Writer Node #2
# Example variables
# node-id: 'host02'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host02 \
--cluster-id cluster01 \
--mode ingest \
--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>
```
2. Start the dedicated Compactor node with ` compact`.
```bash
## NODE 3 — Compactor Node
# Example variables
# node-id: 'host03'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host03 \
--cluster-id cluster01 \
--mode compact \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
<AWS_SECRET_ACCESS_KEY>
```
3. Finally, start the query nodes as _read-only_ with `--mode query`.
```bash
## NODE 4 — Read Node #1
# Example variables
# node-id: 'host04'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host04 \
--cluster-id cluster01 \
--mode query \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind localhost:8383 \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
--aws-secret-access-key <AWS_SECRET_ACCESS_KEY>
```
```bash
## NODE 5 — Read Node #2
# Example variables
# node-id: 'host05'
# cluster-id: 'cluster01'
# bucket: 'influxdb-3-enterprise-storage'
influxdb3 serve \
--node-id host05 \
--cluster-id cluster01 \
--mode query \
--object-store s3 \
--bucket influxdb-3-enterprise-storage \
--http-bind localhost:8484 \
--aws-access-key-id <AWS_ACCESS_KEY_ID> \
<AWS_SECRET_ACCESS_KEY>
```
Congratulations, you have a robust setup for workload isolation using {{% product-name %}}.
### Writing and querying for multi-node setups
You can use the default port `8181` for any write or query, without changing any of the commands.
> [!Note]
> #### Specify hosts for writes and queries
>
> To benefit from this multi-node, isolated architecture, specify hosts:
>
> - In write requests, specify a host that you have designated as _write-only_.
> - In query requests, specify a host that you have designated as _read-only_.
>
> 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 querying a specific host
# HTTP-bound Port: 8585
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 {{% 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 \
--token AUTH_TOKEN \
--database DATABASE_NAME \
--table TABLE_NAME \
COLUMNS
```
#### Delete a file index
```bash
influxdb3 delete file_index \
--host http://localhost:8585 \
--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`
{{% /show-in %}}

View File

@ -11,7 +11,13 @@ Common use cases include:
InfluxDB is optimized for scenarios where near real-time data monitoring is essential and queries need to return quickly to support user experiences such as dashboards and interactive user interfaces. InfluxDB is optimized for scenarios where near real-time data monitoring is essential and queries need to return quickly to support user experiences such as dashboards and interactive user interfaces.
{{% show-in "enterprise" %}}
{{% product-name %}} is built on InfluxDB 3 Core, the InfluxDB 3 open source release. {{% product-name %}} is built on InfluxDB 3 Core, the InfluxDB 3 open source release.
{{% /show-in %}}
{{% show-in "core" %}}
{{% product-name %}} is the InfluxDB 3 open source release.
{{% /show-in %}}
Core's feature highlights include: Core's feature highlights include:
* Diskless architecture with object storage support (or local disk with no dependencies) * Diskless architecture with object storage support (or local disk with no dependencies)
@ -29,9 +35,18 @@ The Enterprise version adds the following features to Core:
* Row-level delete support (coming soon) * Row-level delete support (coming soon)
* Integrated admin UI (coming soon) * Integrated admin UI (coming soon)
{{% show-in "core" %}}
For more information, see how to [get started with Enterprise](/influxdb3/enterprise/get-started/).
{{% /show-in %}}
### What's in this guide ### What's in this guide
{{% show-in "enterprise" %}}
This guide covers Enterprise as well as InfluxDB 3 Core, including the following topics: This guide covers Enterprise as well as InfluxDB 3 Core, including the following topics:
{{% /show-in %}}
{{% show-in "core" %}}
This guide covers InfluxDB 3 Core (the open source release), including the following topics:
{{% /show-in %}}
- [Install and startup](#install-and-startup) - [Install and startup](#install-and-startup)
- [Authentication and authorization](#authentication-and-authorization) - [Authentication and authorization](#authentication-and-authorization)
@ -42,7 +57,9 @@ This guide covers Enterprise as well as InfluxDB 3 Core, including the following
- [Last values cache](#last-values-cache) - [Last values cache](#last-values-cache)
- [Distinct values cache](#distinct-values-cache) - [Distinct values cache](#distinct-values-cache)
- [Python plugins and the processing engine](#python-plugins-and-the-processing-engine) - [Python plugins and the processing engine](#python-plugins-and-the-processing-engine)
{{% show-in "enterprise" %}}
- [Multi-server setups](#multi-server-setup) - [Multi-server setups](#multi-server-setup)
{{% /show-in %}}
> [!Tip] > [!Tip]
> #### Find support for {{% product-name %}} > #### Find support for {{% product-name %}}
@ -54,6 +71,7 @@ This guide covers Enterprise as well as InfluxDB 3 Core, including the following
{{% product-name %}} runs on **Linux**, **macOS**, and **Windows**. {{% product-name %}} runs on **Linux**, **macOS**, and **Windows**.
{{% show-in "enterprise" %}}
{{% tabs-wrapper %}} {{% tabs-wrapper %}}
{{% tabs %}} {{% tabs %}}
[Linux or macOS](#linux-or-macos) [Linux or macOS](#linux-or-macos)
@ -107,18 +125,67 @@ Pull the image:
docker pull influxdb:3-enterprise docker pull influxdb:3-enterprise
``` ```
##### InfluxDB 3 Explorer -- Query Interface (beta) <!--------------- END DOCKER -------------->
{{% /tab-content %}}
{{% /tabs-wrapper %}}
{{% /show-in %}}
You can download the new InfluxDB 3 Explorer query interface using Docker. {{% show-in "core" %}}
Explorer is currently in beta. Pull the image: {{% tabs-wrapper %}}
{{% tabs %}}
[Linux or macOS](#linux-or-macos)
[Windows](#windows)
[Docker](#docker)
{{% /tabs %}}
{{% tab-content %}}
<!--------------- BEGIN LINUX AND MACOS -------------->
To get started quickly, download and run the install script--for example, using [curl](https://curl.se/download.html):
<!--pytest.mark.skip-->
```bash ```bash
docker pull quay.io/influxdb/influxdb3-explorer:latest curl -O https://www.influxdata.com/d/install_influxdb3.sh \
&& sh install_influxdb3.sh
```
Or, download and install [build artifacts](/influxdb3/core/install/#download-influxdb-3-core-binaries):
- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz.sha256)
- [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz.sha256)
- [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz.sha256)
> [!Note]
> macOS Intel builds are coming soon.
<!--------------- END LINUX AND MACOS -------------->
{{% /tab-content %}}
{{% tab-content %}}
<!--------------- BEGIN WINDOWS -------------->
Download and install the {{% product-name %}} [Windows (AMD64, x86_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip)
[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256)
<!--------------- END WINDOWS -------------->
{{% /tab-content %}}
{{% tab-content %}}
<!--------------- BEGIN DOCKER -------------->
The [`influxdb:3-core` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-core)
is available for x86_64 (AMD64) and ARM64 architectures.
Pull the image:
<!--pytest.mark.skip-->
```bash
docker pull influxdb:3-core
``` ```
<!--------------- END DOCKER --------------> <!--------------- END DOCKER -------------->
{{% /tab-content %}} {{% /tab-content %}}
{{% /tabs-wrapper %}} {{% /tabs-wrapper %}}
{{% /show-in %}}
_Build artifacts and images update with every merge into the {{% product-name %}} `main` branch._ _Build artifacts and images update with every merge into the {{% product-name %}} `main` branch._
@ -137,11 +204,22 @@ If your system doesn't locate `influxdb3`, then `source` the configuration file
source ~/.zshrc source ~/.zshrc
``` ```
> [!Tip]
> #### Run the InfluxDB 3 Explorer query interface (beta)
>
> InfluxDB 3 Explorer (currently in beta) is the user interface component of the InfluxDB 3 platform.
> It provides visual management of databases and tokens and an easy way to query your time series data.
>
> Use Docker to download and run InfluxDB 3 Explorer:
>
> ```bash
> docker pull quay.io/influxdb/influxdb3-explorer:latest
> ```
#### Start InfluxDB #### 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`, InfluxDB supports the following: local file system (`file`), `memory`,
S3 (and compatible services like Ceph or Minio) (`s3`), S3 (and compatible services like Ceph or Minio) (`s3`),
@ -149,8 +227,15 @@ To start your InfluxDB instance, use the `influxdb3 serve` command and provide t
The default is `file`. The default is `file`.
Depending on the object store type, you may need to provide additional options Depending on the object store type, you may need to provide additional options
for your object store configuration. for your object store configuration.
{{% show-in "enterprise" %}}
- `--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. - `--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. - `--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.
{{% /show-in %}}
{{% show-in "core" %}}
- `--node-id`: A string identifier that distinguishes individual server instances within the cluster.
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.
{{% /show-in %}}
The following examples show how to start {{% product-name %}} with different object store configurations. The following examples show how to start {{% product-name %}} with different object store configurations.
@ -161,8 +246,10 @@ The following examples show how to start {{% product-name %}} with different obj
> storage alone, eliminating the need for locally attached disks. > storage alone, eliminating the need for locally attached disks.
> {{% product-name %}} can also work with only local disk storage when needed. > {{% product-name %}} can also work with only local disk storage when needed.
{{% show-in "enterprise" %}}
> [!Note] > [!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 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.
{{% /show-in %}}
##### Filesystem object store ##### Filesystem object store
@ -171,6 +258,7 @@ This is the default object store type.
Replace the following with your values: Replace the following with your values:
{{% show-in "enterprise" %}}
```bash ```bash
# Filesystem object store # Filesystem object store
# Provide the filesystem directory # Provide the filesystem directory
@ -180,6 +268,17 @@ influxdb3 serve \
--object-store file \ --object-store file \
--data-dir ~/.influxdb3 --data-dir ~/.influxdb3
``` ```
{{% /show-in %}}
{{% show-in "core" %}}
```bash
# Filesystem object store
# Provide the filesystem directory
influxdb3 serve \
--node-id host01 \
--object-store file \
--data-dir ~/.influxdb3
```
{{% /show-in %}}
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: 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:
@ -187,7 +286,7 @@ To run the [Docker image](/influxdb3/version/install/#docker-image) and persist
- `--object-store file --data-dir /path/in/container`: Uses the mount for server storage - `--object-store file --data-dir /path/in/container`: Uses the mount for server storage
{{% show-in "enterprise" %}}
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```bash ```bash
# Filesystem object store with Docker # Filesystem object store with Docker
@ -201,8 +300,21 @@ docker run -it \
--object-store file \ --object-store file \
--data-dir /path/in/container --data-dir /path/in/container
``` ```
{{% /show-in %}}
{{% show-in "core" %}}
<!--pytest.mark.skip-->
```bash
# Filesystem object store with Docker
# Create a mount
# Provide the mount path
docker run -it \
-v /path/on/host:/path/in/container \
influxdb:3-core influxdb3 serve \
--node-id my_host \
--object-store file \
--data-dir /path/in/container
```
{{% /show-in %}}
> [!Note] > [!Note]
> >
@ -215,6 +327,7 @@ Store data in an S3-compatible object store.
This is useful for production deployments that require high availability and durability. This is useful for production deployments that require high availability and durability.
Provide your bucket name and credentials to access the S3 object store. Provide your bucket name and credentials to access the S3 object store.
{{% show-in "enterprise" %}}
```bash ```bash
# S3 object store (default is the us-east-1 region) # 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
@ -227,6 +340,7 @@ influxdb3 serve \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY --aws-secret-access-key AWS_SECRET_ACCESS_KEY
``` ```
```bash ```bash
# Minio or other open source object store # Minio or other open source object store
# (using the AWS S3 API with additional parameters) # (using the AWS S3 API with additional parameters)
@ -241,12 +355,40 @@ influxdb3 serve \
--aws-endpoint ENDPOINT \ --aws-endpoint ENDPOINT \
--aws-allow-http --aws-allow-http
``` ```
{{% /show-in %}}
{{% show-in "core" %}}
```bash
# S3 object store (default is the us-east-1 region)
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--object-store s3 \
--bucket OBJECT_STORE_BUCKET \
--aws-access-key AWS_ACCESS_KEY_ID \
--aws-secret-access-key AWS_SECRET_ACCESS_KEY
```
```bash
# Minio or other open source object store
# (using the AWS S3 API with additional parameters)
# Specify the object store type and associated options
influxdb3 serve \
--node-id host01 \
--object-store s3 \
--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
```
{{% /show-in %}}
#### Memory object store #### Memory object store
Store data in RAM without persisting it on shutdown. Store data in RAM without persisting it on shutdown.
It's useful for rapid testing and development. It's useful for rapid testing and development.
{{% show-in "enterprise" %}}
```bash ```bash
# Memory object store # Memory object store
# Stores data in RAM; doesn't persist data # Stores data in RAM; doesn't persist data
@ -255,6 +397,16 @@ influxdb3 serve \
--cluster-id cluster01 \ --cluster-id cluster01 \
--object-store memory --object-store memory
``` ```
{{% /show-in %}}
{{% show-in "core" %}}
```bash
# Memory object store
# Stores data in RAM; doesn't persist data
influxdb3 serve \
--node-id host01 \
--object-store memory
```
{{% /show-in %}}
For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/): For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/):
@ -262,6 +414,7 @@ For more information about server options, use the CLI help or view the [InfluxD
influxdb3 serve --help influxdb3 serve --help
``` ```
{{% show-in "enterprise" %}}
#### Licensing #### Licensing
When first starting a new instance, {{% product-name %}} prompts you to select a license type. When first starting a new instance, {{% product-name %}} prompts you to select a license type.
@ -273,6 +426,7 @@ InfluxDB 3 Enterprise licenses authorize the use of the InfluxDB 3 Enterprise so
- **Commercial**: Commercial license with full access to InfluxDB 3 Enterprise capabilities. - **Commercial**: Commercial license with full access to InfluxDB 3 Enterprise capabilities.
You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage your license](https://docs.influxdata.com/influxdb3/enterprise/admin/license/)page. You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage your license](https://docs.influxdata.com/influxdb3/enterprise/admin/license/)page.
{{% /show-in %}}
### Authentication and authorization ### Authentication and authorization
@ -280,8 +434,6 @@ You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage
With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests. With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
{{% show-in "enterprise" %}} {{% show-in "enterprise" %}}
{{% product-name %}} supports the following types of tokens: {{% product-name %}} supports the following types of tokens:
@ -293,19 +445,24 @@ With authentication enabled, you must provide a token with `influxdb3` CLI comma
- A system token grants read access to system information endpoints and - A system token grants read access to system information endpoints and
metrics for the server metrics for the server
{{% /show-in %}} {{% /show-in %}}
{{% show-in "core" %}}
{{% product-name %}} supports _admin_ tokens, which grant access to all CLI actions and API endpoints.
{{% /show-in %}}
For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/). For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/).
> [!Important]
> #### Securely store your token
>
> InfluxDB lets you view the token string only when you create the token.
> Store your token in a secure location, as you cannot retrieve it from the database later.
> InfluxDB 3 stores only the token's hash and metadata in the catalog.
#### Create an operator token #### Create an operator token
After you start the server, create your first admin token (the operator token): After you start the server, create your first admin token.
The first admin token you create is the _operator_ token for the server.
Use the `influxdb3` CLI or the HTTP API to create your operator token.
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
{{< code-tabs-wrapper >}} {{< code-tabs-wrapper >}}
{{% code-tabs %}} {{% code-tabs %}}
@ -334,17 +491,16 @@ Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}
{{< /code-tabs-wrapper >}} {{< /code-tabs-wrapper >}}
The command returns a token string for authenticating CLI commands and API requests. The command returns a token string for authenticating CLI commands and API requests.
Store your token securely—you cannot retrieve it from the database later.
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
#### Set your token for authentication #### Set your token for authentication
Use one of the following methods to authenticate requests. Use your operator token to authenticate server actions in {{% product-name %}},
In your commands, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step). such as creating additional tokens, performing administrative tasks, and writing and querying data.
Use one of the following methods to provide your token and authenticate `influxdb3` CLI commands.
In your command, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step).
{{< tabs-wrapper >}} {{< tabs-wrapper >}}
{{% tabs %}} {{% tabs %}}
@ -375,7 +531,7 @@ influxdb3 show databases --token AUTH_TOKEN
{{% /tab-content %}} {{% /tab-content %}}
{{< /tabs-wrapper >}} {{< /tabs-wrapper >}}
For HTTP API requests, include your token in the `Authorization` header: For HTTP API requests, include your token in the `Authorization` header--for example:
{{% code-placeholders "AUTH_TOKEN" %}} {{% code-placeholders "AUTH_TOKEN" %}}
```bash ```bash
@ -384,11 +540,13 @@ curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
#### Learn more about token management #### Learn more about tokens and permissions
- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Create, list, and delete admin tokens - [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Understand and manage operator and named admin tokens
{{% show-in "enterprise" %}}
- [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, list, and delete resource tokens - [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, list, and delete resource tokens
- [Token types and permissions](/influxdb3/version/admin/tokens/) - Understanding operator and named admin tokens {{% /show-in %}}
- [Authentication](/influxdb3/version/reference/internals/authentication/) - Understand authentication, authorizations, and permissions in {{% product-name %}}
### Data model ### Data model
@ -408,10 +566,11 @@ This tutorial covers many of the recommended tools.
| :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: | | :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: |
| **`influxdb3` CLI** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | **`influxdb3` CLI** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| **InfluxDB HTTP API** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | **InfluxDB HTTP API** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| **InfluxDB 3 Explorer** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | - | **{{< icon "check" >}}** |
| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | | [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - |
| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 Processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB 3 processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - | | [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - |
| [Chronograf](/chronograf/v1/) | - | - | - | | [Chronograf](/chronograf/v1/) | - | - | - |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - | | <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
@ -431,6 +590,15 @@ InfluxDB is a schema-on-write database. You can start writing data and InfluxDB
After a schema is created, InfluxDB validates future write requests against it before accepting the data. After a schema is created, InfluxDB validates future write requests against it before accepting the data.
Subsequent requests can add new fields on-the-fly, but can't add new tags. Subsequent requests can add new fields on-the-fly, but can't add new tags.
{{% show-in "core" %}}
> [!Note]
> #### Core is optimized for recent data
>
> {{% product-name %}} is optimized for recent data but accepts writes from any time period.
> The system persists data to Parquet files for historical analysis with [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/) or third-party tools.
> For extended historical queries and optimized data organization, consider using [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/).
{{% /show-in %}}
#### Write data in line protocol syntax #### Write data in line protocol syntax
{{% product-name %}} accepts data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax. {{% product-name %}} accepts data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax.
@ -471,14 +639,8 @@ Use the `influxdb3 write` command to write data to a database.
In the code samples, replace the following placeholders with your values: 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. - {{% 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 %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}}
- {{% 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 %}}
##### Write data via stdin ##### Write data via stdin
@ -697,7 +859,15 @@ influxdb3 create -h
### Query data ### Query data
InfluxDB 3 now supports native SQL for querying, in addition to InfluxQL, an SQL-like language customized for time series queries. InfluxDB 3 supports native SQL for querying, in addition to InfluxQL, an
SQL-like language customized for time series queries.
{{% show-in "core" %}}
{{< product-name >}} limits
query time ranges to 72 hours (both recent and historical) to ensure query performance.
For more information about the 72-hour limitation, see the
[update on InfluxDB 3 Cores 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/).
{{% /show-in %}}
> [!Note] > [!Note]
> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3. > Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3.
@ -893,9 +1063,16 @@ docker pull quay.io/influxdb/influxdb3-explorer:latest
Run the interface using: Run the interface using:
{{% show-in "enterprise" %}}
```bash ```bash
docker run -p 8086:80 -p 8087:8888 quay.io/influxdb/influxdb3-explorer:latest --mode=normal docker run -p 8086:80 -p 8087:8888 quay.io/influxdb/influxdb3-explorer:latest --mode=normal
``` ```
{{% /show-in %}}
{{% show-in "core" %}}
```bash
docker run --name influxdb3-explorer -p 8086:8888 quay.io/influxdb/influxdb3-explorer:latest
```
{{% /show-in %}}
With the default settings above, you can access the UI at http://localhost:8086. With the default settings above, you can access the UI at http://localhost:8086.
Set your expected database connection details on the Settings page. Set your expected database connection details on the Settings page.
@ -905,7 +1082,7 @@ visualization of your time series data.
### Last values cache ### 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. {{% 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.
Last value caches import historical data when first created, and reload data on restart to ensure cache consistency and eliminate cold start delays.
You can use the `influxdb3` CLI to [create a last value cache](/influxdb3/version/reference/cli/influxdb3/create/last_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" %}} {{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
@ -991,7 +1168,6 @@ Replace the following placeholders with your values:
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. 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. 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. Many of the options are similar to the last value cache.
Distinct values caches import historical data when first created, and reload data on restart to ensure cache consistency and eliminate cold start delays.
You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/). You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/).
@ -1035,7 +1211,7 @@ influxdb3 create distinct_cache \
#### Query a distinct values 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 ```bash
influxdb3 query \ influxdb3 query \
@ -1276,6 +1452,7 @@ influxdb3 enable trigger \
For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/). For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/).
{{% show-in "enterprise" %}}
### Multi-server setup ### Multi-server setup
{{% product-name %}} is built to support multi-node setups for high availability, read replicas, and flexible implementations depending on use case. {{% product-name %}} is built to support multi-node setups for high availability, read replicas, and flexible implementations depending on use case.
@ -1595,3 +1772,4 @@ Replace the following placeholders with your values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the file index in - {{% 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 %}}`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` - {{% code-placeholder-key %}}`COLUMNS`{{% /code-placeholder-key %}}: a comma-separated list of columns to index on, for example, `host,application`
{{% /show-in %}}