# InfluxDB 3 Core — full Markdown corpus > Generated 2026-08-26T22:49:41.546Z from https://docs.influxdata.com/influxdb3/core/ > See https://docs.influxdata.com/llms.txt for the cross-product table of contents. > Publisher: InfluxData (https://www.influxdata.com) > sameAs: https://github.com/influxdata, https://hub.docker.com/u/influxdata, https://www.crunchbase.com/organization/influxdb, https://www.linkedin.com/company/influxdb, https://twitter.com/influxdb, https://www.youtube.com/@InfluxData, https://www.facebook.com/influxdb/ --- # InfluxDB 3 Core documentation Source: https://docs.influxdata.com/influxdb3/core/ > [!Tip] > Comparing InfluxDB 3 products or planning a migration from InfluxDB 1 or 2? > See [Which InfluxDB 3 should I use?](/influxdb3/which-influxdb-3/) for a > full decision guide. InfluxDB 3 Core is a database built to collect, process, transform, and store event and time series data, and is ideal for use cases that require real-time ingest and fast query response times to build user interfaces, monitoring, and automation solutions. Common use cases include: * Monitoring sensor data * Server monitoring * Application performance monitoring * Network monitoring * Financial market and trading analytics * Behavioral analytics 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 3 Core is the InfluxDB 3 open source release. Core’s feature highlights include: * Diskless architecture with object storage support (or local disk with no dependencies) * Fast query response times (under 10ms for last-value queries, or 30ms for distinct metadata) * Embedded Python VM for plugins and triggers * Parquet file persistence * Compatibility with InfluxDB 1.x and 2.x write APIs [Get started with InfluxDB 3 Core](/influxdb3/core/get-started/) The Enterprise version adds the following features to Core: * Historical query capability and single series indexing * High availability * Read replicas * Enhanced security (coming soon) * Row-level delete support (coming soon) * Integrated admin UI (coming soon) For more information, see how to [get started with InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/). --- # Administer InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/admin/ The following articles provide information about managing your InfluxDB 3 Core resources: ### [Identify InfluxDB 3 Core version](/influxdb3/core/admin/identify-version/) Learn how to identify your InfluxDB 3 Core version using command-line tools, HTTP endpoints, and other methods. ### [Manage databases](/influxdb3/core/admin/databases/) An InfluxDB 3 Core database is a named location where time series data is stored. Each database can contain multiple tables. ### [Manage tables](/influxdb3/core/admin/tables/) Tables in InfluxDB 3 Core are synonymous with measurements and contain time series data. Each table has a defined schema with tag and field columns. ### [Manage tokens](/influxdb3/core/admin/tokens/) Manage tokens to authenticate and authorize access to server actions, resources, and data in an InfluxDB 3 Core instance. ### [Manage the Last Value Cache](/influxdb3/core/admin/last-value-cache/) The InfluxDB 3 Core Last Value Cache (LVC) lets you cache the most recent values for specific fields in a table, improving the performance of queries that return the most recent value of a field for specific time series or the last N values of a field. ### [Manage the Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/) The InfluxDB 3 Core Distinct Value Cache (DVC) lets you cache distinct values of one or more columns in a table, improving the performance of queries that return distinct tag and field values. ### [Query system data](/influxdb3/core/admin/query-system-data/) Query system tables to see data related to the server, queries, and tables in an InfluxDB 3 Core instance. Use the HTTP SQL query API to retrieve information about your database server and table schemas. ### [Manage the node lifecycle](/influxdb3/core/admin/node-lifecycle/) Understand how an InfluxDB 3 Core node registers in the catalog, how a graceful shutdown flushes the write-ahead log (WAL), and how to keep container and systemd deployments on the graceful shutdown path. ### [Back up and restore data](/influxdb3/core/admin/backup-restore/) Back up and restore your InfluxDB 3 Core instance by copying object storage files in the recommended order. ### [Performance tuning](/influxdb3/core/admin/performance-tuning/) Optimize InfluxDB 3 Core performance by tuning thread allocation, memory settings, and other configuration options for your specific workload. ### [Security](/influxdb3/core/admin/security/) Tune InfluxDB 3 Core security for local requirements. ### [Upgrade InfluxDB 3 Core](/influxdb3/core/admin/upgrade/) Learn how to upgrade your InfluxDB 3 Core instance to the latest version. ### [Upgrade to InfluxDB 3 Enterprise](/influxdb3/core/admin/upgrade-to-enterprise/) Upgrade from InfluxDB 3 Core to InfluxDB 3 Enterprise. Your existing data and plugins are compatible–no data migration is required. ### [Use the InfluxDB 3 MCP server](/influxdb3/core/admin/mcp-server/) Use the **InfluxDB Model Context Protocol (MCP) server** to interact with and manage InfluxDB 3 Core using natural language with LLM agents to query and analyze data, manage databases and more. Query InfluxDB 3 Core documentation from your IDE using the InfluxDB documentation Model Context Protocol (MCP) server. --- # Back up and restore data Source: https://docs.influxdata.com/influxdb3/core/admin/backup-restore/ InfluxDB 3 Core persists all data and metadata to object storage. How you back up and restore that data depends on your storage engine: InfluxDB 3 Core does not include built-in backup and restore commands. Back up and restore your data with the [manual object-storage procedure](#manual-backup-process), which copies object storage files in a specific order to ensure consistency. ## Supported object storage InfluxDB 3 supports the following object storage backends for data persistence: * **File system** (local directory) * **AWS S3** and S3-compatible storage ([MinIO](/influxdb3/core/object-storage/minio/)) * **Azure Blob Storage** * **Google Cloud Storage** > [!Note] > Backup and restore procedures don’t apply to memory-based [object stores](/influxdb3/core/reference/config-options/#object-store). ## File structure | Location | Description | |-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `/` | Root directory for all node state | | `/_catalog_checkpoint` | Catalog state checkpoint file | | `/catalog/` | Catalog log files tracking catalog state changes | | `/wal/` | [Write-ahead log files](/influxdb3/core/reference/internals/durability/#write-ahead-log-wal-persistence) containing written data | | `/snapshots/` | Snapshot files summarizing persisted [Parquet files](/influxdb3/core/reference/internals/durability/#parquet-storage) | | `/dbs////` |[Parquet files](/influxdb3/core/reference/internals/durability/#parquet-storage) organized by [database](/influxdb3/core/admin/databases/), [table](/influxdb3/core/admin/tables/), and time| |`/table-snapshots//
/`| Table snapshot files (regenerated on restart, optional for backup) | ## Manual backup process Use this manual object-storage procedure to back up InfluxDB 3 Core . It copies object storage files in a specific order to ensure consistency. > [!Important] > Copy files in the recommended order to reduce risk of creating inconsistent backups. Perform backups during downtime or minimal load periods when possible. **Recommended backup order:** 1. Snapshots directory 2. Database (dbs) directory 3. WAL directory 4. Catalog directory 5. Catalog checkpoint file #### File system #### ```bash #!/bin/bash NODE_ID="NODE_ID" DATA_DIR="/path/to/data" BACKUP_DIR="/backup/$(date +%Y%m%d-%H%M%S)" mkdir -p "$BACKUP_DIR" # Copy in recommended order cp -r $DATA_DIR/${NODE_ID}/snapshots "$BACKUP_DIR/" cp -r $DATA_DIR/${NODE_ID}/dbs "$BACKUP_DIR/" cp -r $DATA_DIR/${NODE_ID}/wal "$BACKUP_DIR/" cp -r $DATA_DIR/${NODE_ID}/catalog "$BACKUP_DIR/" cp $DATA_DIR/${NODE_ID}/_catalog_checkpoint "$BACKUP_DIR/" echo "Backup completed to $BACKUP_DIR" ``` Replace `NODE_ID` with your [node ID](/influxdb3/core/reference/config-options/#node-id). > [!Note] > This example works with Docker containers that use volume mounts for data persistence. Adjust the `DATA_DIR` path to match your volume mount configuration. ```bash #!/bin/bash NODE_ID="NODE_ID" SOURCE_BUCKET="SOURCE_BUCKET" BACKUP_BUCKET="BACKUP_BUCKET" BACKUP_PREFIX="backup-$(date +%Y%m%d-%H%M%S)" # Copy in recommended order aws s3 sync s3://${SOURCE_BUCKET}/${NODE_ID}/snapshots \ s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/snapshots/ aws s3 sync s3://${SOURCE_BUCKET}/${NODE_ID}/dbs \ s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/dbs/ aws s3 sync s3://${SOURCE_BUCKET}/${NODE_ID}/wal \ s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/wal/ aws s3 sync s3://${SOURCE_BUCKET}/${NODE_ID}/catalog \ s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/catalog/ aws s3 cp s3://${SOURCE_BUCKET}/${NODE_ID}/_catalog_checkpoint \ s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/ echo "Backup completed to s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}" ``` Replace the following: * `NODE_ID`: your [node ID](/influxdb3/core/reference/config-options/#node-id) * `SOURCE_BUCKET`: your InfluxDB data bucket * `BACKUP_BUCKET`: your backup destination bucket ## Manual restore process Use this manual object-storage procedure to restore InfluxDB 3 Core . > [!Warning] > Restoring overwrites existing data. Always verify you have correct backups before proceeding. **Recommended restore order:** 1. Catalog checkpoint file 2. Catalog directory 3. WAL directory 4. Database (dbs) directory 5. Snapshots directory #### File system restore example ```bash #!/bin/bash NODE_ID="NODE_ID" BACKUP_DIR="/backup/BACKUP_DATE" DATA_DIR="/path/to/data" # 1. Stop InfluxDB systemctl stop influxdb3-core || docker stop influxdb3-core # 2. Optional: Clear existing data for clean restore rm -rf ${DATA_DIR}/${NODE_ID}/* # 3. Restore in reverse order of backup mkdir -p ${DATA_DIR}/${NODE_ID} cp ${BACKUP_DIR}/_catalog_checkpoint ${DATA_DIR}/${NODE_ID}/ cp -r ${BACKUP_DIR}/catalog ${DATA_DIR}/${NODE_ID}/ cp -r ${BACKUP_DIR}/wal ${DATA_DIR}/${NODE_ID}/ cp -r ${BACKUP_DIR}/dbs ${DATA_DIR}/${NODE_ID}/ cp -r ${BACKUP_DIR}/snapshots ${DATA_DIR}/${NODE_ID}/ # 4. Set correct permissions (important for Docker) chown -R influxdb:influxdb ${DATA_DIR}/${NODE_ID} # 5. Start InfluxDB systemctl start influxdb3-core || docker start influxdb3-core ``` Replace the following: * `NODE_ID`: your [node ID](/influxdb3/core/reference/config-options/#node-id) * `BACKUP_DATE`: backup directory timestamp (for example, 20240115-143022) #### S3 restore example ```bash #!/bin/bash NODE_ID="NODE_ID" BACKUP_BUCKET="BACKUP_BUCKET" BACKUP_PREFIX="backup-BACKUP_DATE" TARGET_BUCKET="TARGET_BUCKET" # 1. Stop InfluxDB # Implementation depends on your deployment method # 2. Optional: Clear existing data for clean restore aws s3 rm s3://${TARGET_BUCKET}/${NODE_ID} --recursive # 3. Restore from backup aws s3 sync s3://${BACKUP_BUCKET}/${BACKUP_PREFIX}/${NODE_ID}/ \ s3://${TARGET_BUCKET}/${NODE_ID}/ # 4. Start InfluxDB # Implementation depends on your deployment method ``` Replace the following: * `NODE_ID`: your node ID * `BACKUP_DATE`: backup timestamp * `BACKUP_BUCKET`: bucket containing backup * `TARGET_BUCKET`: target bucket for restoration ## Recovery expectations > [!Warning] > Recovery succeeds to a consistent point in time, which is the **latest snapshot included** in the backup. Data written after that snapshot may not be present if its WAL was deleted after the backup. Any Parquet files without a snapshot reference are ignored. ## Object storage features and backup planning ### Versioning If your object storage provider supports it, consider enabling short-term object versioning on the object store backing InfluxDB 3 Core — typically 1–2 days — to protect against errant writes or accidental deletions. With versioning enabled, the object store retains distinct versions of each updated object, which can be used to recover from these incidents. InfluxDB 3 Core writes mostly immutable Parquet files and rarely updates existing objects, so versioning helps most with recovering specific accidentally deleted files. If many files are affected at once, recovering them through individual version restores becomes impractical. Versioning costs grow with object update frequency. InfluxDB 3 Core’s compaction process generates new Parquet files over time, so each compaction pass adds to the retained version count in a versioned bucket. Use the shortest retention window that meets your recovery needs, and treat versioning as a short-window safety net rather than a long-term backup substitute. ### Periodic backups Provider-side features like versioning, soft delete, and point-in-time recovery protect against many failure modes but do **not** replace backups. Periodic backups to a separate object store remain the only predictable, repeatable way to recover from: * Corruption or compromise of the primary object store. * Accidental or malicious deletion of data. * Bad data written into the primary store (a replica of bad data is not a valid recovery point). The [backup process](#manual-backup-process) above is provider-agnostic — you can use any provider-native tool to copy to a separate bucket, container, or account, as long as you preserve the documented directory structure and file ordering. Schedule copies during low-load periods or downtime windows when possible. ## Containerized deployments When running InfluxDB 3 Core in containers: * **Volume consistency**: Use the same volume mounts for backup and restore operations * **File permissions**: Ensure container user can read restored files (use `chown` if needed) * **Backup access**: Mount a backup directory to copy files from containers to the host ## Excluded files Files in `/table-snapshots/` are intentionally excluded from backup: * These files are periodically overwritten * They regenerate automatically on server restart * Including them doesn’t harm but increases backup size unnecessarily ## Backup timing * Perform backups during downtime or minimal load periods * Copying files while the database is active may create inconsistent backups * Consider using filesystem or storage snapshots if available * Compression is optional but recommended for long-term storage #### Related * [Manage databases](/influxdb3/core/admin/databases/) * [influxdb3 serve](/influxdb3/core/reference/cli/influxdb3/serve/) * [Install InfluxDB 3 Core](/influxdb3/core/install/) * [InfluxDB 3 Core internals](/influxdb3/core/reference/internals/durability/) [backup](/influxdb3/core/tags/backup/)[restore](/influxdb3/core/tags/restore/)[administration](/influxdb3/core/tags/administration/)[object storage](/influxdb3/core/tags/object-storage/) | Location | Description | | --- | --- | | Location | Description | | / | Root directory for all node state | | /_catalog_checkpoint | Catalog state checkpoint file | | /catalog/ | Catalog log files tracking catalog state changes | | /wal/ | Write-ahead log files containing written data | | /snapshots/ | Snapshot files summarizing persisted Parquet files | | /dbs//
// | Parquet files organized by database , table , and time | | /table-snapshots//
/ | Table snapshot files (regenerated on restart, optional for backup) | --- # Manage databases Source: https://docs.influxdata.com/influxdb3/core/admin/databases/ An InfluxDB 3 Core database is a named location where time series data is stored. Each database can contain multiple tables. > [!Note] > **If coming from InfluxDB v1**, the concepts of databases and retention policies > have been combined into a single concept–database. Retention policies are no > longer part of the InfluxDB data model. > However, InfluxDB 3 Core does > support InfluxQL, which requires databases and retention policies. > See [InfluxQL DBRP naming convention](/influxdb3/core/admin/databases/create/#influxql-dbrp-naming-convention). > > **If coming from InfluxDB v2, InfluxDB Cloud (TSM), or InfluxDB Cloud Serverless**,*database* and *bucket* are synonymous. ## Retention periods A database **retention period** is the maximum age of data stored in the database. The age of data is determined by the timestamp associated with each point. When a point’s timestamp is beyond the retention period (relative to now), the point is not queryable and will be deleted. By default, data does not expire. When you [create a database](/influxdb3/core/admin/databases/create/), you can optionally set a retention period. The minimum practical retention period is 1 hour (`1h`). For complete details about retention periods, including duration formats and limitations, see [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/). ## Database, table, and column limits InfluxDB 3 Core places the following limits on databases, tables, and columns: ### Database limit **Maximum number of databases**: 5 ### Table limit **Maximum number of tables across all databases**: 2000 InfluxDB 3 Core limits the number of tables you can have across *all*databases to 2000 . InfluxDB doesn’t limit how many tables you can have in an individual database, as long as the total across all databases is below the limit. Having more tables affects your InfluxDB 3 Core installation in the following ways: [](#may-improve-query-performance-view-more-info) **May improve query performance** *View more info* Schemas with many tables that contain[focused sets of tags and fields](/influxdb3/core/write-data/best-practices/schema-design/#design-for-performance)can make it easier for the query engine to identify what Parquet files contain the queried data, resulting in better query performance. [](#more-puts-into-object-storage-view-more-info) **More PUTs into object storage** *View more info* When using cloud-based object storage as your data backend, the more tables you have, the more `PUT` requests there are into your object store as InfluxDB persists data to Parquet files. Each `PUT` request incurs a monetary cost and increases the operating cost of InfluxDB 3 Core. ### Column limit **Maximum number of columns per table**: 500 Each row must include a time column, with the remaining columns representing tags and fields. As a result, a table can have one time column and up to 499*combined* field and tag columns. If you attempt to write to a table and exceed the column limit, the write request fails and InfluxDB returns an error. Higher numbers of columns has the following side-effects: [](#may-adversely-affect-system-performance) May adversely affect system performance InfluxData identified 500 columns as the safe limit for maintaining system performance and stability. Exceeding this threshold can result in[wide schemas](/influxdb3/core/write-data/best-practices/schema-design/#avoid-wide-schemas), which can negatively impact performance and resource use, depending on your queries, the shape of your schema, and data types in the schema. ## [Create a database](/influxdb3/core/admin/databases/create/) Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to create a new database in InfluxDB 3 Core. ```sh # influxdb3 CLI influxdb3 create database \ --retention-period 30d \ DATABASE_NAME # HTTP API curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "30d" }' ``` [Read more ](/influxdb3/core/admin/databases/create/) ## [List databases](/influxdb3/core/admin/databases/list/) Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to list databases in InfluxDB 3 Core. ```sh # influxdb3 CLI influxdb3 show databases # HTTP API curl --request GET "http://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer AUTH_TOKEN" ``` [Read more ](/influxdb3/core/admin/databases/list/) ## [Delete a database](/influxdb3/core/admin/databases/delete/) Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to delete a database from InfluxDB 3 Core. ```sh # influxdb3 CLI influxdb3 delete database DATABASE_NAME # HTTP API curl --request DELETE "http://localhost:8181/api/v3/configure/database?db=DATABASE_NAME" \ --header "Authorization: Bearer AUTH_TOKEN" ``` [Read more ](/influxdb3/core/admin/databases/delete/) #### Related * [InfluxDB schema design recommendations](/influxdb3/core/write-data/best-practices/schema-design/) * [influxdb3 CLI](/influxdb3/core/reference/cli/influxdb3/) * [Database API reference](/influxdb3/core/api/v3/#tag/Database) * [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/) * [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/) [databases](/influxdb3/core/tags/databases/) --- # Create a database Source: https://docs.influxdata.com/influxdb3/core/admin/databases/create/ Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/), the [HTTP API](/influxdb3/core/api/v3/), or [InfluxDB 3 Explorer](/influxdb3/explorer/) to create a database in InfluxDB 3 Core. * [Create a database using the influxdb3 CLI](#create-a-database-using-the-influxdb3-cli) * [Create a database using the HTTP API](#create-a-database-using-the-http-api) * [Create a database using InfluxDB 3 Explorer](#create-a-database-using-influxdb-3-explorer) * [Retention period](#retention-period) * [Database naming restrictions](#database-naming-restrictions) * [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention) * [Database limit](#database-limit) ## Create a database using the influxdb3 CLI Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/)to create a database. Provide the following: * Database name *(see [Database naming restrictions](#database-naming-restrictions))* * InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin) * *(Optional)* [Retention period](#retention-period). If omitted, data doesn’t expire. > [!Important] > #### Retention periods are immutable in Core > > In InfluxDB 3 Core, retention periods can only be set when creating a database > and cannot be changed afterward. If you need to change a retention period, you must > create a new database with the desired retention period and migrate your data. ```sh # Create a database with a 30-day retention period influxdb3 create database --retention-period 30d DATABASE_NAME # Create a database with a 90-day retention period using authentication influxdb3 create database \ --retention-period 90d \ --token AUTH_TOKEN \ DATABASE_NAME # Create a database with infinite retention (default) influxdb3 create database DATABASE_NAME ``` Replace the following: * `DATABASE_NAME`: the name of the database to create * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ## Create a database using the HTTP API To create a database using the HTTP API, send a `POST` request to the `/api/v3/configure/database` endpoint: ``` POST http://localhost:8181/api/v3/configure/database ``` Include the following in your request: * **Headers**: * `Content-Type: application/json` * `Authorization: Bearer` with your [admin token](/influxdb3/core/admin/tokens/) * **Request body** (JSON object): * `db` *(string, required)*: Database name * `retention_period` *(string, optional)*: [Retention period](#retention-period). If omitted, data doesn’t expire. > [!Important] > #### Retention periods are immutable in Core > > In InfluxDB 3 Core, retention periods can only be set when creating a database > and cannot be changed afterward. If you need to change a retention period, you must > create a new database with the desired retention period and migrate your data. ```bash # Create a database with a 30-day retention period curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "30d" }' # Create a database with a 90-day retention period curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "90d" }' # Create a database with infinite retention (default) curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME" }' ``` Replace the following: * `DATABASE_NAME`: the name of the database to create * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Response A successful request returns HTTP status `200` with the database configuration. ## Create a database using InfluxDB 3 Explorer > [!Caution] > Currently, you can’t set a retention period when creating a database in Explorer. > To create a database with a retention period, see one of the following: > > * [Create a database using the influxdb3 CLI](#create-a-database-using-the-influxdb3-cli) > * [Create a database using the HTTP API](#create-a-database-using-the-http-api) > [!Important] > #### Retention periods are immutable in Core > > After creating a database in InfluxDB 3 Core, you cannot change its retention period. Use the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface to create a database in InfluxDB 3 Core: 1. If you haven’t already, see how to [get started with Explorer and connect to your InfluxDB 3 Core server](/influxdb3/explorer/get-started/). 2. In Explorer, click **Manage Databases** in the left navigation. 3. Click **+ Create New**. 4. Enter a database name. 5. Click **Create Database**. For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). * [Retention period](#retention-period) * [Database naming restrictions](#database-naming-restrictions) * [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention) * [Database limit](#database-limit) ## Retention period By default, data does not expire. When creating a database, set a *retention period* to automatically delete expired data and optimize storage. ### Retention period syntax The retention period value is a time duration value made up of a numeric value plus a duration unit. For example, `30d` means 30 days. The retention period value cannot be negative or contain whitespace. #### Valid durations units include * **m**: minute * **h**: hour * **d**: day * **w**: week * **mo**: month * **y**: year > [!Warning] > #### Retention period constraints > > * **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). > * **Zero-duration periods**: Setting a retention period to `0` (for example,`0d` or `0h`) is allowed but marks all data for immediate deletion at query time.*This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention.* > * **Infinite retention**: Use `none` to set an infinite retention period. For more information about retention periods, see [Data retention](/influxdb3/core/reference/internals/data-retention/). > [!Important] > #### Retention periods are immutable in Core > > In InfluxDB 3 Core, retention periods can only be set when creating a database > and cannot be changed afterward. If you need to change a retention period, you must > create a new database with the desired retention period and migrate your data. > > For mutable retention periods and table-level retention, consider upgrading to[InfluxDB 3 Enterprise](/influxdb3/enterprise/). ## Database naming restrictions Database names must adhere to the following naming restrictions: * **Length**: Maximum 64 characters * **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`), and forward-slash (`/`) * **Prohibited characters**: Cannot contain whitespace, punctuation, or other special characters * **Starting character**: Should start with a letter or number and should not start with underscore (`_`) * **Case sensitivity**: Database names are case-sensitive > [!Caution] > #### Underscore prefix reserved for system use > > Names starting with an underscore (`_`) may be reserved for InfluxDB system use. > While InfluxDB 3 Core might not explicitly reject these names, using them risks > conflicts with current or future system features and may result in > unexpected behavior or data loss. ### Valid database name examples ```text mydb sensor_data prod-metrics logs/application webserver123 ``` ### Invalid database name examples ```text my database # Contains whitespace sensor.data # Contains period app@server # Contains special character _internal # Starts with underscore (reserved) very_long_database_name_that_exceeds_sixty_four_character_limit # Too long ``` For comprehensive information about naming restrictions for all InfluxDB identifiers, see [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/). ## InfluxQL DBRP naming convention In InfluxDB 1.x, data is stored in [databases](/influxdb/v1/concepts/glossary/#database)and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp). In InfluxDB 3 Core, databases and retention policies have been merged into*databases*, where databases have a retention period, but retention policies are no longer part of the data model. Because InfluxQL uses the 1.x data model, a database must be mapped to a v1 database and retention policy (DBRP) to be queryable with InfluxQL. **When naming a database that you want to query with InfluxQL**, use the following naming convention to automatically map v1 DBRP combinations to an InfluxDB 3 Core database: ```text database_name/retention_policy_name ``` ##### Database naming examples |v1 Database name|v1 Retention Policy name| New database name | |----------------|------------------------|-------------------------| | db | rp | db/rp | | telegraf | autogen | telegraf/autogen | | webmetrics | 1w-downsampled |webmetrics/1w-downsampled| ## Database limit **Maximum number of databases**: 5 *For more information about InfluxDB 3 Core database, table, and column limits, see [Database, table, and column limits](/influxdb3/core/admin/databases/#database-table-and-column-limits).* #### Related * [influxdb3 create database](/influxdb3/core/reference/cli/influxdb3/create/database/) * [Create database API](/influxdb3/core/api/database/#operation/PostConfigureDatabase) * [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/) * [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/) * [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/) | v1 Database name | v1 Retention Policy name | New database name | | --- | --- | --- | | v1 Database name | v1 Retention Policy name | New database name | | db | rp | db/rp | | telegraf | autogen | telegraf/autogen | | webmetrics | 1w-downsampled | webmetrics/1w-downsampled | --- # Delete a database Source: https://docs.influxdata.com/influxdb3/core/admin/databases/delete/ Use the [`influxdb3 delete database` command](/influxdb3/core/reference/cli/influxdb3/delete/database/), the [HTTP API](/influxdb3/core/api/v3/), or [InfluxDB 3 Explorer](/influxdb3/explorer/)to delete a database from InfluxDB 3 Core. > [!Caution] > #### Deleting a database cannot be undone > > Deleting a database is a destructive action. > Once a database is deleted, data stored in that database cannot be recovered. * [Delete a database using the influxdb3 CLI](#delete-a-database-using-the-influxdb3-cli) * [Delete a database using the HTTP API](#delete-a-database-using-the-http-api) * [Delete a database using InfluxDB 3 Explorer](#delete-a-database-using-influxdb-3-explorer) ## Delete a database using the influxdb3 CLI Provide the following: * Name of the database to delete * * InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin) ```sh influxdb3 delete database DATABASE_NAME ``` Replace the following: * `DATABASE_NAME`: the name of the database to delete Enter `yes` to confirm that you want to delete the database. ## Delete a database using the HTTP API To delete a database using the HTTP API, send a `DELETE` request to the `/api/v3/configure/database` endpoint: ``` DELETE http://localhost:8181/api/v3/configure/database ``` Include the following in your request: * **Query parameters**: * `db`: Database name to delete * **Headers**: * `Authorization: Bearer` with your [admin token](/influxdb3/core/admin/tokens/) ```bash curl --request DELETE "http://localhost:8181/api/v3/configure/database?db=DATABASE_NAME" \ --header "Authorization: Bearer AUTH_TOKEN" ``` Replace the following: * `DATABASE_NAME`: the name of the database to delete * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Response A successful deletion returns HTTP status `200` with no content body. ## Delete a database using InfluxDB 3 Explorer You can also delete databases using the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface: 1. If you haven’t already, see how to [get started with Explorer and connect to your InfluxDB 3 Core server](/influxdb3/explorer/get-started/). 2. In Explorer, click **Databases** in the left navigation. 3. Find the database you want to delete in the list. 4. Click the **Delete** icon (trash can) next to the database name. 5. In the confirmation dialog, type the database name to confirm. 6. Click **Delete Database**. > [!Caution] > This action cannot be undone. All data in the database will be permanently deleted. For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). #### Related * [influxdb3 delete database](/influxdb3/core/reference/cli/influxdb3/delete/database/) * [Delete database API](/influxdb3/core/api/database/#operation/DeleteConfigureDatabase) * [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/) --- # List databases Source: https://docs.influxdata.com/influxdb3/core/admin/databases/list/ Use the [`influxdb3 show databases` command](/influxdb3/core/reference/cli/influxdb3/show/databases/), the [`/api/v3/configure/database`](/influxdb3/core/api/v3/) HTTP API endpoint, or [InfluxDB 3 Explorer](/influxdb3/explorer/)to list databases in InfluxDB 3 Core. * [List databases using the influxdb3 CLI](#list-databases-using-the-influxdb3-cli) * [List databases using the HTTP API](#list-databases-using-the-http-api) * [List databases using InfluxDB 3 Explorer](#list-databases-using-influxdb-3-explorer) ## List databases using the influxdb3 CLI Provide the following: * *(Optional)* [Output format](#output-formats) with the `--format` option * *(Optional)* [Show deleted databases](#list-deleted-databases) with the`--show-deleted` option * InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin)with the `-t`, `--token` option ```sh influxdb3 show databases ``` ### Output formats The `influxdb3 show databases` command supports output formats: * `pretty` *(default)* * `json` * `jsonl` * `csv` * `parquet` *(must [output to a file](#output-to-a-parquet-file))* Use the `--format` flag to specify the output format: ```sh influxdb3 show databases --format json ``` #### Example output [](#view-example-pretty-formatted-output) View example pretty-formatted output ``` +---------------+ | iox::database | +---------------+ | home | | home_actions | | noaa | +---------------+ ``` [](#view-example-json-formatted-output) View example JSON-formatted output ```json [{"iox::database":"home"},{"iox::database":"home_actions"},{"iox::database":"noaa"}] ``` [](#view-example-json-line-formatted-output) View example JSON-line-formatted output ```jsonl {"iox::database":"home"} {"iox::database":"home_actions"} {"iox::database":"noaa"} ``` [](#view-example-csv-formatted-output) View example CSV-formatted output ```csv iox::database home home_actions noaa ``` #### Output to a Parquet file [Parquet](https://parquet.apache.org/) is a binary format. Use the `--output` option to specify the file where you want to save the Parquet data. ```sh influxdb3 show databases \ --format parquet \ --output databases.parquet ``` Alternatively, use the `influxdb3 query` command to query system tables: ```sh influxdb3 query \ --database _internal \ --format parquet \ --output databases.parquet \ "SELECT * FROM system.databases" ``` ### List deleted databases To list deleted databases, include the `--show-deleted` option with your`influxdb3 show databases` command: ```sh influxdb3 show databases --show-deleted ``` ## List databases using the HTTP API To list databases using the HTTP API, send a `GET` request to the `/api/v3/configure/database` endpoint. ``` GET http://localhost:8181/api/v3/configure/database?format=pretty ``` Include the `format` query parameter and specify one of the following formats: * `pretty` * `json` * `jsonl` * `csv` * `parquet` #### Pretty output #### Include the following in your request: * **Headers**: * `Authorization: Bearer` with your [token](/influxdb3/core/admin/tokens/) * **Query Parameters**: * `format=pretty` ```bash curl --request GET "http://localhost:8181/api/v3/configure/database?format=pretty" \ --header "Authorization: Bearer AUTH_TOKEN" ``` The response body contains a table of database names: ```text +---------------------+ | iox::database | +---------------------+ | _internal | | home | | home_actions | | noaa | +---------------------+ ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your [token](/influxdb3/core/admin/tokens/) * **Query Parameters**: * `format=json` ```bash curl --request GET "http://localhost:8181/api/v3/configure/database?format=json" \ --header "Authorization: Bearer AUTH_TOKEN" ``` The response body contains a JSON array of database objects whose keys are `iox::database`: ```json [ { "iox::database": "home" }, { "iox::database": "home_actions" }, { "iox::database": "noaa" } ] ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your [token](/influxdb3/core/admin/tokens/) * **Query Parameters**: * `format=parquet` * An output destination for the Parquet file ```bash curl "http://localhost:8181/api/v3/configure/database?format=parquet" \ -o databases.parquet \ --header "Authorization: Bearer AUTH_TOKEN" ``` For Parquet responses, you must provide an output destination because the format is binary. The response contains the databases list. A successful request returns HTTP status `200`. ## List databases using InfluxDB 3 Explorer You can also view all databases using the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface: 1. If you haven’t already, see how to [get started with Explorer and connect to your InfluxDB 3 Core server](/influxdb3/explorer/get-started/). 2. In Explorer, click **Databases** in the left navigation. 3. The Databases page displays a list of all databases with the following information: * Database name * Retention period (if configured) * Number of tables in the database * Creation date For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). #### Related * [influxdb3 show databases](/influxdb3/core/reference/cli/influxdb3/show/databases/) * [List databases API](/influxdb3/core/api/database/#operation/GetConfigureDatabase) * [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/) --- # Manage the Distinct Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/ The InfluxDB 3 Core Distinct Value Cache (DVC) lets you cache distinct values of one or more columns in a table, improving the performance of queries that return distinct tag and field values. The DVC is an in-memory cache that stores distinct values for specific columns in a table. When you create a DVC, you can specify what columns’ distinct values to cache, the maximum number of distinct value combinations to cache, and the maximum age of cached values. A DVC is associated with a table, which can have multiple DVCs. * [Create a Distinct Value Cache](#create-a-distinct-value-cache) * [Query a Distinct Value Cache](#query-a-distinct-value-cache) * [Show information about Distinct Value Caches](#show-information-about-distinct-value-caches) * [Delete a Distinct Value Cache](#delete-a-distinct-value-cache) * [Important things to know about the Distinct Value Cache](#important-things-to-know-about-the-distinct-value-cache) * [High cardinality limits](#high-cardinality-limits) * [Distinct Value Caches are flushed when the server stops](#distinct-value-caches-are-flushed-when-the-server-stops) Consider a dataset with the following schema: * wind\_data (table) * tags: * country * *multiple European countries* * county * *multiple European counties* * city * *multiple European cities* * fields: * wind\_speed (float) * wind\_direction (integer) If you cache distinct values for `country`, `county`, and `city`, the DVC looks similar to this: | country | county | city | |--------------|----------------|------------| | Austria | Salzburg | Salzburg | | Austria | Vienna | Vienna | | Belgium | Antwerp | Antwerp | | Belgium | West Flanders | Bruges | |Czech Republic| Liberec Region | Liberec | |Czech Republic| Prague | Prague | | Denmark | Capital Region | Copenhagen | | Denmark |Southern Denmark| Odense | | Estonia |Ida-Viru County |Kohtla-Järve| | Estonia |Ida-Viru County | Narva | | … | … | … | > [!Important] > #### Repeated values in DVC results > > Distinct values may appear multiple times in a column when querying the DVC, > but only when associated with distinct values in other columns. > If you query a single column in the DVC, no values are repeated in the results. > [!Note] > #### Null column values > > *Null* column values are still considered values and are cached in the DVC. > If you write data to a table and don’t provide a value for an existing column, > the column value is cached as *null* and treated as a distinct value. ## [Create a Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/create/) Use the [`influxdb3 create distinct_cache` command](/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/)to create a Distinct Value Cache. ```bash influxdb3 create distinct_cache \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ --table wind_data \ --columns country,county,city \ --max-cardinality 10000 \ --max-age 24h \ windDistinctCache ``` ## [Query a Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/query/) Use the [`distinct_cache()` SQL function](/influxdb3/core/reference/sql/functions/cache/#distinct_cache)in the `FROM` clause of an SQL `SELECT` statement to query data from the Distinct Value Cache. ```sql SELECT * FROM distinct_cache('table-name', 'cache-name') ``` > [!Important] > You must use SQL to query the DVC. > InfluxQL does not support the `distinct_cache()` function. ## [Show information about Distinct Value Caches](/influxdb3/core/admin/distinct-value-cache/show/) Use the `influxdb3 show system table` command to query and output Distinct Value Cache information from the `distinct_caches` system table. ```bash influxdb3 show system \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ table distinct_caches ``` ## [Delete a Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/delete/) Use the [`influxdb3 delete distinct_cache` command](/influxdb3/core/reference/cli/influxdb3/delete/distinct_cache/)to delete a Distinct Value Cache. ```bash influxdb3 delete distinct_cache \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ --table wind_data \ windDistinctCache ``` ## Important things to know about the Distinct Value Cache DVCs are stored in memory; the larger the cache, the more memory your InfluxDB 3 node requires to maintain it. Consider the following: * [Cache data loading](#cache-data-loading) * [High cardinality limits](#high-cardinality-limits) * [Distinct Value Caches are flushed when the server stops](#distinct-value-caches-are-flushed-when-the-server-stops) ## Cache data loading On cache creation, InfluxDB 3 Core loads historical data into the cache. On restart, the server automatically reloads cache data. ### High cardinality limits “Cardinality” refers to the number of unique key column combinations in your cached data and essentially defines the maximum number of rows to store in your DVC. While the InfluxDB 3 storage engine is not limited by cardinality, it does affect the DVC. You can define a custom maximum cardinality limit for a DVC, but higher cardinality increases memory requirements for storing the DVC and can affect DVC query performance. ### Distinct Value Caches are flushed when the server stops Because the DVC is an in-memory cache, the cache is flushed any time the server stops. After a server restart, InfluxDB 3 Core only writes new values to the DVC when you write data, so there may be a period of time when some values are unavailable in the DVC. #### Related * [distinct\_cache SQL function](/influxdb3/core/reference/sql/functions/cache/#distinct_cache) * [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/) [cache](/influxdb3/core/tags/cache/) | country | county | city | | --- | --- | --- | | country | county | city | | Austria | Salzburg | Salzburg | | Austria | Vienna | Vienna | | Belgium | Antwerp | Antwerp | | Belgium | West Flanders | Bruges | | Czech Republic | Liberec Region | Liberec | | Czech Republic | Prague | Prague | | Denmark | Capital Region | Copenhagen | | Denmark | Southern Denmark | Odense | | Estonia | Ida-Viru County | Kohtla-Järve | | Estonia | Ida-Viru County | Narva | | … | … | … | --- # Create a Distinct Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/create/ Use the [`influxdb3 create distinct_cache` command](/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/)to create a Distinct Value Cache (DVC). Provide the following: * **Database** (`-d`, `--database`): *(Required)* The name of the database to associate the DVC with. You can also use the `INFLUXDB3_DATABASE_NAME`environment variable to specify the database. * **Token** (`--token`): *(Required)* Your InfluxDB 3 Core authentication token. You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify the token. * **Table** (`-t`, `--table`): *(Required)* The name of the table to associate the DVC with. * **Columns** (`--columns`): *(Required)* Specify which columns to cache distinct values for. These are typically tag columns but can also be string fields. * **Maximum cardinality** (`--max-cardinality`): Specify the maximum number of distinct value combinations to store in the cache. The default maximum cardinality is `100000`. * **Maximum age** (`--max-age`): Specify the maximum age of distinct values to keep in the DVC in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form. The default maximum age is `24 hours`. * **Cache name**: A unique name for the cache. If you don’t provide one, InfluxDB automatically generates a cache name for you. ```bash influxdb3 create distinct_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ --columns COLUMNS \ --max-cardinality MAX_CARDINALITY \ --max-age MAX_AGE \ DVC_NAME ``` ## Use the HTTP API To use the HTTP API to create a Distinct Value Cache, send a `POST` request to the `/api/v3/configure/distinct_cache` endpoint. ``` POST /api/v3/configure/distinct_cache ``` ```bash curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "table": "TABLE_NAME", "name": "DVC_NAME", "columns": ["COLUMNS"], "max_cardinality": MAX_CARDINALITY, "max_age": MAX_AGE }' ``` ### Example ``` curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \ --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ --json '{ "db": "example-db", "table": "wind_data", "name": "windDistinctCache", "columns": ["country", "county", "city"], "max_cardinality": 10000, "max_age": 86400 }' ``` **Response codes:** * `201` : Success. The distinct cache has been created. * `204` : Not created. A distinct cache with this configuration already exists. * `400` : Bad request. > [!Note] > #### API parameter differences > > * **Columns format**: The API uses a JSON array (`["country", "county", "city"]`) > instead of the CLI’s comma-delimited format (`country,county,city`). > * **Maximum age format**: The API uses seconds (`86400`) instead of the CLI’s[humantime format](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) (`24h`, `1 day`). Replace the following: * `DATABASE_NAME`: the name of the database to associate the DVC with * `AUTH_TOKEN`: your InfluxDB 3 Core authentication token * `TABLE_NAME`: the name of the table to associate the DVC with * `COLUMNS`: a comma-delimited list of columns to cache distinct values for–for example:`country,county,city` * `MAX_CARDINALITY`: the maximum number of distinct value combinations to cache–for example: `10000` * `MAX_AGE`: the maximum age of distinct values to keep in the cache in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form–for example: `6h`, `1 day`, `1 week` * `DVC_NAME`: a unique name for the DVC The cache imports the distinct values from the table and starts caching them. > [!Important] > #### DVC size and persistence > > The DVC is stored in memory, so it’s important to consider the size and > persistence of the cache. For more information, see[Important things to know about the Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/#important-things-to-know-about-the-distinct-value-cache). #### Related * [influxdb3 create distinct\_cache](/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/) * [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Delete a Distinct Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/delete/ Use the [`influxdb3 delete distinct_cache` command](/influxdb3/core/reference/cli/influxdb3/delete/distinct_cache/)to delete a Distinct Value Cache (DVC). Provide the following: * **Database** (`-d`, `--database`): *(Required)* The name of the database that the DVC you want to delete is associated with. You can also use the`INFLUXDB3_DATABASE_NAME` environment variable to specify the database. * **Token** (`--token`): *(Required)* Your InfluxDB 3 Core authentication token. You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify the token. * **Table** (`-t`, `--table`): *(Required)* The name of the table that the DVC you want to delete is associated with. * **Cache name**: The name of the DVC to delete. ```bash influxdb3 delete distinct_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ DVC_NAME ``` Replace the following: * `DATABASE_NAME`: the name of the database that the DVC you want to delete is associated with * `AUTH_TOKEN`: your InfluxDB 3 Core admin authentication token * `TABLE_NAME`: the name of the table associated with the DVC you want to delete * `DVC_NAME`: the name of the DVC to delete > [!Caution] > This is a destructive action that cannot be undone. Once deleted, any queries > against the deleted DVC will return an error. #### Related * [influxdb3 delete distinct\_cache](/influxdb3/core/reference/cli/influxdb3/delete/distinct_cache/) * [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Query a Distinct Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/query/ Use the [`distinct_cache()` SQL function](/influxdb3/core/reference/sql/functions/cache/#distinct_cache)in the `FROM` clause of an SQL `SELECT` statement to query data from the Distinct Value Cache (DVC). > [!Important] > You must use SQL to query the DVC. > InfluxQL does not support the `distinct_cache()` function. `distinct_cache()` supports the following arguments: * **table\_name**: *(Required)* The name of the table the DVC is associated with formatted as a string literal. * **cache\_name**: The name of the DVC to query formatted as a string literal. This argument is only required if there is more than one DVC associated with the specified table. ```sql SELECT * FROM distinct_cache('table_name', 'cache_name') ``` You can use other [SQL clauses](/influxdb3/core/reference/sql/#statements-and-clauses)to modify query results. For example, you can use the `WHERE` clause to return the distinct tag values associated with another distinct tag value: ```sql SELECT city FROM distinct_cache('wind_data', 'windDistinctCache') WHERE country = 'Spain' ``` ## Use the HTTP API To use the HTTP API to query cached data, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint and include the [`distinct_cache()`](/influxdb3/core/reference/sql/functions/cache/#distinct_cache) function in your query. ``` GET /api/v3/query_sql ``` ``` POST /api/v3/query_sql ``` ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "q": "SELECT * FROM distinct_cache('\''TABLE_NAME'\'', '\''CACHE_NAME'\'')", "format": "json" }' ``` ## Example with WHERE clause ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ --json '{ "db": "example-db", "q": "SELECT room, temp FROM last_cache('\''home'\'', '\''homeCache'\'') WHERE room = '\''Kitchen'\''", "format": "json" }' ``` #### Related * [distinct\_cache SQL function](/influxdb3/core/reference/sql/functions/cache/#distinct_cache) * [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Show information about Distinct Value Caches Source: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/show/ Use the [`influxdb3 show system table` command](/influxdb3/core/reference/cli/influxdb3/show/system/table/)to query and output Distinct Value Cache information from the `distinct_caches`system table. ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table distinct_caches ``` This returns a table similar to the following: | table | name |column\_ids| column\_names |max\_cardinality|max\_age\_seconds| |----------|-----------------|-----------|-----------------------|----------------|-----------------| |wind\_data| wind\_distinct | [0, 1, 2] |[country, county, city]| 100000 | 86400 | | weather |weather\_distinct| [0] | [location] | 100 | 604800 | | bitcoin | bitcoin\_dis | [0, 1] | [code, crypto] | 5000 | 86400 | | home | home\_distinct | [0, 1] | [room, wall] | 12000 | 15770000 | ## Query specific columns from the distinct\_caches system table Use the `--select` option to query specific columns from the `distinct_caches`system table. Provide a comma-delimited list of columns to return: ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table distinct_caches \ --select name,column_names,max_age_seconds ``` ## Sort distinct\_caches system table output Use the `--order-by` option to sort data from the `distinct_caches` system table by specific columns. Provide a comma-delimited list of columns to sort by: ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table distinct_caches \ --order-by max_cardinality,max_age_seconds ``` > [!Note] > Results are sorted in ascending order based on the provided columns. In the examples above, replace the following: * `DATABASE_NAME`: the name of the database to query system data from * `AUTH_TOKEN`: your InfluxDB 3 Core authentication token ## Use the HTTP API To use the HTTP API to query and output cache information from the system table, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint. ``` GET /api/v3/query_sql ``` ``` POST /api/v3/query_sql ``` ### Query all caches ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "q": "SELECT * FROM system.distinct_caches", "format": "json" }' ``` ## Query specific cache details ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "q": "SELECT * FROM system.distinct_caches WHERE name = '\''CACHE_NAME'\''", "format": "json" }' ``` #### Related * [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/) [cache](/influxdb3/core/tags/cache/) | table | name | column_ids | column_names | max_cardinality | max_age_seconds | | --- | --- | --- | --- | --- | --- | | table | name | column_ids | column_names | max_cardinality | max_age_seconds | | wind_data | wind_distinct | [0, 1, 2] | [country, county, city] | 100000 | 86400 | | weather | weather_distinct | [0] | [location] | 100 | 604800 | | bitcoin | bitcoin_dis | [0, 1] | [code, crypto] | 5000 | 86400 | | home | home_distinct | [0, 1] | [room, wall] | 12000 | 15770000 | --- # Identify InfluxDB 3 Core version Source: https://docs.influxdata.com/influxdb3/core/admin/identify-version/ Identifying which InfluxDB product and version you’re using is essential for accessing the correct documentation, troubleshooting issues, and planning upgrades. > [!Note] > #### Identify your InfluxDB version > > If you are unsure which InfluxDB product you are using, use our interactive version detector to help identify it: > > [Detect my InfluxDB version](#) > *(Interactive feature in HTML: Opens version detector modal)* ## Quick detection methods ### InfluxDB 3 version detection Check the version using the `influxdb3` command: ```bash influxdb3 --version ``` Send a `GET` request to the `/ping` endpoint to examine HTTP response headers–for example: ```bash curl -i http://localhost:8181/ping ``` The response includes version information in the **headers** and **body**: * **Headers**: * `x-influxdb-version`: Version number (for example, 3.11.2) * `x-influxdb-build`: `Core` * **JSON body**: Contains `version`, `revision`, and `process_id` Example response: ``` HTTP/1.1 200 OK x-influxdb-build: Core x-influxdb-version: 3.11.2 {"version":"3.11.2","revision":"abc123def","process_id":"..."} ``` > [!Note] > #### SQL version() function > > The SQL `version()` function returns the[DataFusion](https://datafusion.apache.org/) query engine version, not the > InfluxDB product version. Use the methods above to identify your InfluxDB > version. ## Understanding InfluxDB products For a complete comparison of InfluxDB versions and deployment options, see the [InfluxDB platform overview](/platform/). ## Troubleshooting ### Can’t access your InfluxDB instance? If you can’t directly access your InfluxDB instance: 1. Use the [interactive version detector](#identify-your-influxdb-version) above or [Ask InfluxData AI](#) 2. Answer questions about your setup: * License type (paid or free) * Hosting model (cloud or self-hosted) * Server age * Query language preferences 3. Get product recommendations based on your answers ### Still not sure? If you’re still uncertain, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Get started with InfluxDB 3 Core](/influxdb3/core/get-started/) * [Administer InfluxDB 3 Core](/influxdb3/core/admin/) * [influxdb3 CLI](/influxdb3/core/reference/cli/influxdb3/) --- # Manage the Last Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/ The InfluxDB 3 Core Last Value Cache (LVC) lets you cache the most recent values for specific fields in a table, improving the performance of queries that return the most recent value of a field for specific series or the last N values of a field. The LVC is an in-memory cache that stores the last N number of values for specific fields of series in a table. When you create an LVC, you can specify what fields to cache, what tags to use to identify each series, and the number of values to cache for each unique series. An LVC is associated with a table, which can have multiple LVCs. * [Create a Last Value Cache](#create-a-last-value-cache) * [Query a Last Value Cache](#query-a-last-value-cache) * [Show information about Last Value Caches](#show-information-about-last-value-caches) * [Delete a Last Value Cache](#delete-a-last-value-cache) * [Important things to know about the Last Value Cache](#important-things-to-know-about-the-last-value-cache) * [High cardinality key columns](#high-cardinality-key-columns) * [Value count](#value-count) * [Last Value Caches are flushed when the server stops](#last-value-caches-are-flushed-when-the-server-stops) * [Defining value columns](#defining-value-columns) Consider a dataset with the following schema (similar to the[home sensor sample dataset](/influxdb3/core/reference/sample-data/#home-sensor-data)): * home (table) * tags: * room * kitchen * living room * wall * north * east * south * fields: * co (integer) * temp (float) * hum (float) If you cache the last value for each field per room and wall, the LVC looks similar to this: | room |wall |co |hum |temp| time | |-----------|-----|---|----|----|--------------------| | Kitchen |east |26 |36.5|22.7|2022-01-01T20:00:00Z| |Living Room|north|17 |36.4|22.2|2022-01-01T20:00:00Z| |Living Room|south|16 |36.3|22.1|2022-01-01T20:00:00Z| If you cache the last four values of each field per room and wall, the LVC looks similar to the following: | room |wall |co |hum |temp| time | |-----------|-----|---|----|----|--------------------| | Kitchen |east |26 |36.5|22.7|2022-01-01T20:00:00Z| | Kitchen |east | 9 |36.0|22.7|2022-01-01T17:00:00Z| | Kitchen |east | 3 |36.2|22.7|2022-01-01T15:00:00Z| | Kitchen |east | 0 |36.1|22.7|2022-01-01T10:00:00Z| |Living Room|north|17 |36.4|22.2|2022-01-01T20:00:00Z| |Living Room|north| 5 |35.9|22.6|2022-01-01T17:00:00Z| |Living Room|north| 1 |36.1|22.3|2022-01-01T15:00:00Z| |Living Room|north| 0 |36.0|21.8|2022-01-01T10:00:00Z| |Living Room|south|16 |36.3|22.1|2022-01-01T20:00:00Z| |Living Room|south| 4 |35.8|22.5|2022-01-01T17:00:00Z| |Living Room|south| 0 |36.0|22.3|2022-01-01T15:00:00Z| |Living Room|south| 0 |35.9|21.8|2022-01-01T10:00:00Z| > [!Note] > #### Null column values > > *Null* column values are still considered values and are cached in the LVC. > If you write data to a table and don’t provide a value for an existing column, > the column value is cached as *null*. ## [Create a Last Value Cache](/influxdb3/core/admin/last-value-cache/create/) Use the [`influxdb3 create last_cache` command](/influxdb3/core/reference/cli/influxdb3/create/last_cache/)to create a Last Value Cache. ```bash influxdb3 create last_cache \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ --table home \ --key-columns room,wall \ --value-columns temp,hum,co \ --count 5 \ --ttl 30mins \ homeLastCache ``` ## [Query a Last Value Cache](/influxdb3/core/admin/last-value-cache/query/) Use the [`last_cache()` SQL function](/influxdb3/core/reference/sql/functions/cache/#last_cache)in the `FROM` clause of an SQL `SELECT` statement to query data from the Last Value Cache. ```sql SELECT * FROM last_cache('table-name', 'cache-name') ``` > [!Important] > You must use SQL to query the LVC. > InfluxQL does not support the `last_cache()` function. ## [Show information about Last Value Caches](/influxdb3/core/admin/last-value-cache/show/) Use the `influxdb3 show system table` command to query and output Last Value Cache information from the `last_caches` system table. ```bash influxdb3 show system \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ table last_caches ``` ## [Delete a Last Value Cache](/influxdb3/core/admin/last-value-cache/delete/) Use the [`influxdb3 delete last_cache` command](/influxdb3/core/reference/cli/influxdb3/delete/last_cache/)to delete a Last Value Cache. ```bash influxdb3 delete last_cache \ --database example-db \ --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ --table home \ homeLastCache ``` ## Important things to know about the Last Value Cache LVCs are stored in memory; the larger the cache, the more memory your InfluxDB 3 node requires to maintain it. Consider the following: * [Cache data loading](#cache-data-loading) * [High cardinality key columns](#high-cardinality-key-columns) * [Value count](#value-count) * [Last Value Caches are flushed when the server stops](#last-value-caches-are-flushed-when-the-server-stops) ## Cache data loading On cache creation, InfluxDB 3 Core loads historical data into the cache. On restart, the server automatically reloads cache data. ### High cardinality key columns “Cardinality” refers to the number of unique key column combinations in your cached data. While the InfluxDB 3 storage engine is not limited by cardinality, it does affect the LVC. Higher cardinality increases memory requirements for storing the LVC and can affect LVC query performance. We recommend the following: * Only use tags important to your query workload as key columns in the LVC. Caching unnecessary tags or fields as key columns results in higher cardinality without any benefit. * Avoid including high-cardinality key columns in your LVC. * Don’t include multiple high-cardinality key columns in your LVC. To estimate total key column cardinality in an LVC, use the following equation: ```txt num_uniq_col_val_N [× num_uniq_col_val_N …] = key_column_cardinality ``` ### Value count By increasing the number of values to store in the LVC, you increase the number of rows stored in the cache and the amount of memory required to store them. Be judicious with the number of values to store. This count is per unique key column combination. If you include two tags as key columns, one with three unique values and the other with 10, you could have up to 30 unique key column combinations. If you want to keep the last 10 values, you could potentially have 300+ rows in the cache. To get an idea of the number of rows required to cache the specified number of values, use the following equation: ```txt key_column_cardinality × count = number_of_rows ``` ### Last Value Caches are flushed when the server stops Because the LVC is an in-memory cache, the cache is flushed any time the server stops. After a server restart, InfluxDB 3 Core only writes new values to the LVC when you write data, so there may be a period of time when some values are unavailable in the LVC. ### Defining value columns When creating an LVC, if you include the `--value-columns` options to specify which fields to cache as value columns, any new fields added in the future will not be added to the cache. However, if you omit the `--value-columns` option, all columns other than those specified as `--key-columns` are cached as value columns, including columns that are added later. #### Related * [last\_cache SQL function](/influxdb3/core/reference/sql/functions/cache/#last_cache) * [Manage Last Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/last-value-caches/) [cache](/influxdb3/core/tags/cache/) | room | wall | co | hum | temp | time | | --- | --- | --- | --- | --- | --- | | room | wall | co | hum | temp | time | | Kitchen | east | 26 | 36.5 | 22.7 | 2022-01-01T20:00:00Z | | Living Room | north | 17 | 36.4 | 22.2 | 2022-01-01T20:00:00Z | | Living Room | south | 16 | 36.3 | 22.1 | 2022-01-01T20:00:00Z | | room | wall | co | hum | temp | time | | --- | --- | --- | --- | --- | --- | | room | wall | co | hum | temp | time | | Kitchen | east | 26 | 36.5 | 22.7 | 2022-01-01T20:00:00Z | | Kitchen | east | 9 | 36.0 | 22.7 | 2022-01-01T17:00:00Z | | Kitchen | east | 3 | 36.2 | 22.7 | 2022-01-01T15:00:00Z | | Kitchen | east | 0 | 36.1 | 22.7 | 2022-01-01T10:00:00Z | | Living Room | north | 17 | 36.4 | 22.2 | 2022-01-01T20:00:00Z | | Living Room | north | 5 | 35.9 | 22.6 | 2022-01-01T17:00:00Z | | Living Room | north | 1 | 36.1 | 22.3 | 2022-01-01T15:00:00Z | | Living Room | north | 0 | 36.0 | 21.8 | 2022-01-01T10:00:00Z | | Living Room | south | 16 | 36.3 | 22.1 | 2022-01-01T20:00:00Z | | Living Room | south | 4 | 35.8 | 22.5 | 2022-01-01T17:00:00Z | | Living Room | south | 0 | 36.0 | 22.3 | 2022-01-01T15:00:00Z | | Living Room | south | 0 | 35.9 | 21.8 | 2022-01-01T10:00:00Z | --- # Create a Last Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/create/ Use the [`influxdb3 create last_cache` command](/influxdb3/core/reference/cli/influxdb3/create/last_cache/)to create a Last Value Cache (LVC). Provide the following: * **Database** (`-d`, `--database`): *(Required)* The name of the database to associate the LVC with. You can also use the `INFLUXDB3_DATABASE_NAME`environment variable to specify the database. * **Token** (`--token`): *(Required)* Your InfluxDB 3 Core authentication token. You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify the token. * **Table** (`-t`, `--table`): *(Required)* The name of the table to associate the LVC with. * **Key columns** (`--key-columns`): Specify which columns to include in the primary key of the cache. Rows in the LVC are uniquely identified by their timestamp and key columns, so include all the columns you need to identify each row. These are typically tags, but you can use any columns with the following types: * String * Integer * Unsigned integer * Boolean * **Value columns** (`--value-columns`): Specify which columns to cache as value columns. These are typically fields but can also be tags. By default, `time` and columns other than those specified as `--key-columns` are cached as value columns. * **Count** (`--count`): The number of values to cache per unique key column combination. The supported range is `[1-10]`. The default count is `1`. * **Time-to-Live (TTL)** (`--ttl`): The time-to-live for cached values in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form. The default TTL is four hours. * **Cache name**: A unique name for the cache. If you don’t provide one, InfluxDB automatically generates a cache name for you. ```bash influxdb3 create last_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ --key-columns KEY_COLUMNS \ --value-columns VALUE_COLUMNS \ --count COUNT \ --ttl TTL\ LVC_NAME ``` ## Use the HTTP API To use the HTTP API to create a Last Value Cache, send a `POST` request to the `/api/v3/configure/last_cache` endpoint. ``` POST /api/v3/configure/last_cache ``` ```bash curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "table": "TABLE_NAME", "name": "LVC_NAME", "key_columns": ["KEY_COLUMNS"], "value_columns": ["VALUE_COLUMNS"], "count": COUNT, "ttl": TTL }' ``` ### Example ``` curl -X POST "https://localhost:8181/api/v3/configure/last_cache" \ --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \ --json '{ "db": "example-db", "table": "home", "name": "homeLastCache", "key_columns": ["room", "wall"], "value_columns": ["temp", "hum", "co"], "count": 5, "ttl": 14400 }' ``` **Response codes:** * `201` : Success. Last cache created. * `400` : Bad request. * `401` : Unauthorized. * `404` : Cache not found. * `409` : Cache already exists. > [!Note] > #### API parameter differences > > Column format: The API uses JSON arrays ([“room”, “wall”]) instead of the CLI’s comma-delimited format (room,wall). > TTL format: The API uses seconds (14400) instead of the CLI’s humantime format (4h, 4 hours). Replace the following: * `DATABASE_NAME`: the name of the database to associate the LVC with * `AUTH_TOKEN`: your InfluxDB 3 Core authentication token * `TABLE_NAME`: the name of the table to associate the LVC with * `KEY_COLUMNS`: a comma-delimited list of columns to use to unique identify each series–for example: `room,wall` * `VALUE_COLUMNS`: a comma-delimited list of columns to cache as value columns–for example: `temp,hum,co` * `COUNT`: the number of last values to cache per series–for example: `5` * `TTL`: the TTL of cached values in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form–for example: `10s`, `1min 30sec`, `3 hours` * `LVC_NAME`: a unique name for the LVC The cache imports the distinct values from the table and starts caching them. > [!Important] > #### LVC size and persistence > > The LVC is stored in memory, so it’s important to consider the size and persistence > of the cache. For more information, see[Important things to know about the Last Value Cache.](/influxdb3/core/admin/last-value-cache/#important-things-to-know-about-the-last-value-cache) #### Related * [influxdb3 create last\_cache](/influxdb3/core/reference/cli/influxdb3/create/last_cache/) * [Manage Last Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/last-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Delete a Last Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/delete/ Use the [`influxdb3 delete last_cache` command](/influxdb3/core/reference/cli/influxdb3/delete/last_cache/)to delete a Last Value Cache (LVC). Provide the following: * **Database** (`-d`, `--database`): *(Required)* The name of the database that the LVC you want to delete is associated with. You can also use the`INFLUXDB3_DATABASE_NAME` environment variable to specify the database. * **Token** (`--token`): *(Required)* Your InfluxDB 3 Core authentication token. You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify the database. * **Table** (`-t`, `--table`): *(Required)* The name of the table that the LVC you want to delete is associated with. * **Cache name**: The name of the LVC to delete. ```bash influxdb3 delete last_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ LVC_NAME ``` ## Use the HTTP API To use the HTTP API to delete a Last Value Cache, send a `DELETE` request to the `/api/v3/configure/last_cache` endpoint with query parameters. ``` DELETE /api/v3/configure/last_cache ``` ```bash curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=DATABASE_NAME&table=TABLE_NAME&name=LVC_NAME" \ --header "Authorization: Bearer AUTH_TOKEN" ``` ## Example ```bash curl -X DELETE "https://localhost:8181/api/v3/configure/last_cache?db=example-db&table=home&name=homeLastCache" \ --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" ``` **Response codes:** * `200` : Success. The last cache has been deleted. * `400` : Bad request. * `401` : Unauthorized. * `404` : Cache not found. Replace the following: * `DATABASE_NAME`: the name of the database that the LVC you want to delete is associated with * `AUTH_TOKEN`: your InfluxDB 3 Core authentication token * `TABLE_NAME`: the name of the table that the LVC you want to delete is associated with * `LVC`: the name of the LVC to delete > [!Caution] > This is a destructive action that cannot be undone. Once deleted, any queries > against the deleted LVC will return an error. #### Related * [influxdb3 delete last\_cache](/influxdb3/core/reference/cli/influxdb3/delete/last_cache/) * [Manage Last Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/last-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Query a Last Value Cache Source: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/query/ Use the [`last_cache()` SQL function](/influxdb3/core/reference/sql/functions/cache/#last_cache)in the `FROM` clause of an SQL `SELECT` statement to query data from the Last Value Cache (LVC). > [!Important] > You must use SQL to query the LVC. > InfluxQL does not support the `last_cache()` function. `last_cache()` supports the following arguments: * **table\_name**: *(Required)* The name of the table the LVC is associated with formatted as a string literal. * **cache\_name**: The name of the LVC to query formatted as a string literal. This argument is only required if there is more than one LVC associated with the specified table. ```sql SELECT * FROM last_cache('table_name', 'cache_name') ``` You can use other [SQL clauses](/influxdb3/core/reference/sql/#statements-and-clauses)to modify query results. For example, you can use the `WHERE` clause to return the last value for a specific tag set: ```sql SELECT room, temp FROM last_cache('home', 'homeCache') WHERE room = 'Kitchen' ``` #### Related * [last\_cache SQL function](/influxdb3/core/reference/sql/functions/cache/#last_cache) * [Manage Last Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/last-value-caches/) [cache](/influxdb3/core/tags/cache/) --- # Show information about Last Value Caches Source: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/show/ Use the [`influxdb3 show system table` command](/influxdb3/core/reference/cli/influxdb3/show/system/table/)to query and output Last Value Cache information from the `last_caches` system table. ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table last_caches ``` This returns a table similar to the following: | table | name |key\_column\_ids|key\_column\_names|value\_column\_ids| value\_column\_names |count| ttl | |-------|-------------|----------------|------------------|------------------|----------------------------------------------------|-----|-----| |weather|weather\_last| [0] | [location] | [2, 3, 4, 5, 1] |[precip, temp\_avg, temp\_max, temp\_min, wind\_avg]| 1 |86400| |bitcoin|bitcoin\_last| [0, 1] | [code, crypto] | [4] | [price] | 1 |14400| |numbers|numbers\_last| [] | [] | [0, 1] | [a, b] | 5 |14400| | home | home\_last | [0] | [room] | [1, 2, 3] | [temp, hum, co] | 5 | 60 | ## Query specific columns from the last\_caches system table Use the `--select` option to query specific columns from the `last_caches`system table. Provide a comma-delimited list of columns to return: ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table last_caches \ --select name,key_column_names,value_column_names ``` ## Sort last\_caches system table output Use the `--order-by` option to sort data from the `last_caches` system table by specific columns. Provide a comma-delimited list of columns to sort by: ```bash influxdb3 show system \ --database DATABASE_NAME \ --token AUTH_TOKEN \ table last_caches \ --order-by table,ttl ``` > [!Note] > Results are sorted in ascending order based on the provided columns. In the examples above, replace the following: * `DATABASE_NAME`: the name of the database to query system data from * `AUTH_TOKEN`: your InfluxDB 3 Core authentication token ## Use the HTTP API To use the HTTP API to query and output cache information from the system table, send a `GET` or `POST` request to the `/api/v3/query_sql` endpoint. ``` GET /api/v3/query_sql ``` ``` POST /api/v3/query_sql ``` ### Query all last value caches ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "q": "SELECT * FROM system.last_caches", "format": "json" }' ``` ## Query specific cache details ```bash curl -X POST "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "DATABASE_NAME", "q": "SELECT * FROM system.last_caches WHERE name = '\''CACHE_NAME'\''", "format": "json" }' ``` #### Related * [Manage Last Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/last-value-caches/) [cache](/influxdb3/core/tags/cache/) | table | name | key_column_ids | key_column_names | value_column_ids | value_column_names | count | ttl | | --- | --- | --- | --- | --- | --- | --- | --- | | table | name | key_column_ids | key_column_names | value_column_ids | value_column_names | count | ttl | | weather | weather_last | [0] | [location] | [2, 3, 4, 5, 1] | [precip, temp_avg, temp_max, temp_min, wind_avg] | 1 | 86400 | | bitcoin | bitcoin_last | [0, 1] | [code, crypto] | [4] | [price] | 1 | 14400 | | numbers | numbers_last | [] | [] | [0, 1] | [a, b] | 5 | 14400 | | home | home_last | [0] | [room] | [1, 2, 3] | [temp, hum, co] | 5 | 60 | --- # Use the InfluxDB 3 MCP server Source: https://docs.influxdata.com/influxdb3/core/admin/mcp-server/ InfluxDB provides two Model Context Protocol (MCP) servers for integrating with AI assistants: * [Manage your InfluxDB instance with the database MCP server](#manage-your-influxdb-instance-with-the-database-mcp-server) * [Query documentation from your IDE](#query-documentation-from-your-ide) ## Manage your InfluxDB instance with the database MCP server The **InfluxDB database MCP server** lets you interact with InfluxDB 3 Core using natural language with large language model (LLM) agents. It enables database management, token handling, and SQL query generation in plain English—no coding required. This section walks you through configuring your LLM agent to run and use the InfluxDB database MCP server to interact with your InfluxDB 3 Core server . ### Prerequisites * Node.js v18+ *(if using `npx` to run the MCP server)* * Docker *(if using Docker to run the MCP server)* * A running and reachable InfluxDB 3 Core server . * A valid InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin/) * *(Optional)* An LLM assistant like Claude Desktop, ChatGPT Desktop, etc. ### Configure the database MCP server Use environment variables to configure the InfluxDB 3 MCP server and connect it to your InfluxDB 3 Core server . Set the following environment variables when you start the MCP server: #### Required InfluxDB connection variables * **INFLUX\_DB\_PRODUCT\_TYPE**: `core` * **INFLUX\_DB\_INSTANCE\_URL**: Your InfluxDB 3 Core URL–for example: ``` http://localhost:8181 ``` If using Docker to run the InfluxDB MCP server and you want to manage an InfluxDB instance running on `localhost`, use the internal Docker network to connect to your local InfluxDB 3 Core server–for example: ``` http://host.docker.internal:8181/ ``` * **INFLUX\_DB\_TOKEN**: Your InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin/) ### Configure your LLM agent to run the database MCP server To run the MCP server, use either Node.js and `npm` or Docker. Some LLM agents, like [Claude Desktop](https://claude.ai/download), start, run, and connect to the MCP server for you. The following instructions show how to configure**Claude Desktop** to use the InfluxDB database MCP server. #### Node.js #### 1. Clone the [influxdata/influxdb3\_mcp\_server repository](https://github.com/influxdata/influxdb3_mcp_server)from GitHub. 2. Navigate to the `influxdb3_mcp_server` project directory: ``` cd influxdb3_mcp_server/ ``` 3. Install dependencies: ``` npm install ``` 4. Build the MCP server: ``` npm run build ``` This builds the files necessary to run the MCP server and stores them in `./build`. The `./build/index.js` file starts the MCP server. #### Configure your LLM Agent to use the Node.js-based MCP server In **Claude Desktop**, go to **Settings** \> **Developer** and edit your configuration. Enter the following JSON configuration: ```json { "mcpServers": { "influxdb": { "command": "node", "args": ["/path/to/influxdb3_mcp_server/build/index.js"], "env": { "INFLUX_DB_PRODUCT_TYPE": "core", "INFLUX_DB_INSTANCE_URL": "http://localhost:8181", "INFLUX_DB_TOKEN": "AUTH_TOKEN" } } } } ``` Replace the following: * `path/to`: The absolute path to your `influxdb3_mcp_server` project directory. * `AUTH_TOKEN`: Your InfluxDB 3 Core token. The permissions granted by the token determine what operations your LLM agents can perform. #### Configure your LLM Agent to use the Docker-based MCP server In **Claude Desktop**, go to **Settings** \> **Developer** and edit your configuration. Enter the following JSON configuration: * [Connect to a remote InfluxDB server](#connect-to-a-remote-influxdb-server) * [Connect to a local InfluxDB server](#connect-to-a-local-influxdb-server) In the examples below, replace the following: * `path/to`: The absolute path to your `influxdb3_mcp_server` project directory. * `AUTH_TOKEN`: Your InfluxDB 3 Core token. The permissions granted by the token determine what operations your LLM agents can perform. ##### Connect to a remote InfluxDB server ```json { "mcpServers": { "influxdb": { "command": "docker", "args": [ "run", "--rm", "--interactive", "--env", "INFLUX_DB_PRODUCT_TYPE", "--env", "INFLUX_DB_INSTANCE_URL", "--env", "INFLUX_DB_TOKEN", "influxdata/influxdb3-mcp-server" ], "env": { "INFLUX_DB_PRODUCT_TYPE": "core", "INFLUX_DB_INSTANCE_URL": "http://localhost:8181", "INFLUX_DB_TOKEN": "AUTH_TOKEN" } } } } ``` ##### Connect to a local InfluxDB server ```json { "mcpServers": { "influxdb": { "command": "docker", "args": [ "run", "--rm", "--interactive", "--add-host=host.docker.internal:host-gateway", "--env", "INFLUX_DB_PRODUCT_TYPE", "--env", "INFLUX_DB_INSTANCE_URL", "--env", "INFLUX_DB_TOKEN", "influxdata/influxdb3-mcp-server" ], "env": { "INFLUX_DB_PRODUCT_TYPE": "core", "INFLUX_DB_INSTANCE_URL": "http://host.docker.internal:8181", "INFLUX_DB_TOKEN": "AUTH_TOKEN" } } } } ``` ### Supported features Once connected, you can use your LLM agent to perform tasks on your InfluxDB 3 Core server , including: * Create, update, and delete databases * List tables and inspect schemas * Create and manage tokens * Query data without writing SQL or InfluxQL * Check server health and connection status #### Examples of supported prompts > > > “List all tables in the `production` database.” > > > > “Create a read-only token for the `metrics` database.” > > > > “Analyze last week’s sensor data for anomalies.” > > > > “Create a new database called `iot_sensors` with a 30-day retention policy.” > > > > “Show me the schema for the `sensor_data` table.” > > ## Query documentation from your IDE The **InfluxDB documentation MCP server** lets AI tools and agents search InfluxDB InfluxDB 3 Core documentation directly from your development environment. Use it to find answers, code examples, and configuration details without leaving your IDE. ### Why use the documentation MCP server? When you connect the documentation MCP server to your AI coding assistant, the assistant can search InfluxDB and related tool documentation to answer your questions with accurate, up-to-date information. Instead of switching to a browser or guessing at syntax, you can ask questions in your IDE and get responses grounded in official documentation. **Common use cases:** * Get help writing queries, client library code, or CLI commands * Look up configuration options and environment variables * Find code examples for specific tasks * Troubleshoot errors with documentation-backed answers ### Install the documentation MCP server The documentation MCP server is a hosted service—you don’t need to install or run anything locally. Add the server URL to your AI assistant’s MCP configuration. > [!Note] > On first use, you’ll be prompted to sign in with a Google or GitHub account. > This authentication is used only for rate limiting—no personal data is collected. **MCP server URL:** ```text https://influxdb-docs.mcp.kapa.ai ``` The server uses SSE (Server-Sent Events) transport. #### Configure your AI assistant to use the documentation MCP server The following instructions show how to configure popular AI assistants to use the InfluxDB documentation MCP server. #### Claude Desktop #### In **Claude Desktop**, go to **Settings** \> **Developer** and edit your configuration. Add the following JSON configuration: ```json { "mcpServers": { "influxdb-docs": { "url": "https://influxdb-docs.mcp.kapa.ai" } } } ``` Save the file and restart Claude Desktop for the changes to take effect. In **ChatGPT Desktop**, go to **Settings** \> **Integrations** \> **Enable MCP** and add a new server. Add the following JSON configuration: ```json { "mcpServers": { "influxdb-docs": { "url": "https://influxdb-docs.mcp.kapa.ai", "transport": "sse" } } } ``` Save the configuration and restart ChatGPT Desktop. In **VS Code**, configure GitHub Copilot to use the MCP server: 1. Create or edit `.vscode/mcp.json` in your workspace or project directory 2. Add the following configuration: ```json { "servers": { "influxdb-docs": { "type": "http", "url": "https://influxdb-docs.mcp.kapa.ai" } } } ``` 1. Restart or reload VS Code 2. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) 3. Run **MCP: List Servers** to verify the server is registered The InfluxDB documentation MCP server will now be available through GitHub Copilot Chat. In **Cursor**, add the MCP server configuration to your MCP settings file. 1. Open **Settings** and navigate to **MCP Servers** 2. Click **Add MCP Server** or edit the configuration file directly 3. Add the following configuration to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global): ```json { "mcpServers": { "influxdb-docs": { "url": "https://influxdb-docs.mcp.kapa.ai", "transport": "streamableHttp" } } } ``` Save the file and restart Cursor. In **OpenCode**, configure the MCP server in your configuration file: 1. Create or edit `opencode.json` (or `opencode.jsonc`) in your workspace 2. Add the following configuration: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "influxdb-docs": { "type": "remote", "url": "https://influxdb-docs.mcp.kapa.ai", "enabled": true } } } ``` 1. Start OpenCode and use the `/init` command to verify the MCP server is accessible The InfluxDB documentation search tools will be available in your OpenCode sessions. ### Authentication and rate limits When you connect to the documentation MCP server for the first time, a sign-in window opens where you can choose to authenticate with a **Google** or **GitHub** account. The hosted MCP server uses your account only to generate a stable, opaque user ID for rate limiting—no personal data is collected: * **Google**: Requests only the `openid` scope. Does not request `email` or `profile`scopes—your name, email address, and other personal data are not collected. * **GitHub**: Requests no OAuth scopes. With no scopes requested, GitHub grants read-only access to public profile information only. The server does not access repositories, organizations, email addresses, or other GitHub data. The anonymous user ID enforces per-user rate limits to prevent abuse: * **40 requests** per user per hour * **200 requests** per user per day > [!Tip] > If you sign in with Google, the consent screen may display > “Associate you with your personal info on Google.” > This is Google’s generic wording for the `openid` scope—it means the app can recognize > that the same Google account is signing in again. > It does not grant access to your email, name, contacts, or other data. ### Search documentation with the MCP tool The documentation MCP server exposes a semantic search tool: ```text search_influxdb_knowledge_sources ``` This tool lets AI agents perform semantic retrieval over InfluxDB documentation and related knowledge sources. **What the tool does:** * Searches all InfluxDB documentation for a given query * Returns the most relevant chunks in descending order of relevance * Each chunk is a self-contained snippet from a single documentation page **Response format:** Each result includes: * `source_url`: URL of the original documentation page * `content`: The chunk content in Markdown MCP tool search results showing InfluxDB documentation ### Use the documentation MCP server After you install the documentation MCP server, your AI assistant can search InfluxDB documentation to help you with tasks. Ask questions naturally—the assistant uses the MCP server to find relevant documentation and provide accurate answers. #### Example prompts > > > “How do I write data to InfluxDB using Python?” > > > > “What’s the syntax for a SQL query with a WHERE clause in InfluxDB?” > > > > “Show me how to configure Telegraf to collect CPU metrics.” > > > > “What environment variables does the InfluxDB CLI use?” > > > > “How do I create a database token with read-only permissions?” > > #### Related * [InfluxDB 3 MCP Server GitHub Repository](https://github.com/influxdata/influxdb3_mcp_server) [MCP](/influxdb3/core/tags/mcp/)[LLM](/influxdb3/core/tags/llm/)[AI](/influxdb3/core/tags/ai/) --- # Manage the node lifecycle Source: https://docs.influxdata.com/influxdb3/core/admin/node-lifecycle/ Every InfluxDB 3 Core server process registers itself as a *node* in the catalog—the metadata store that tracks databases, tables, and nodes. The catalog is the source of truth for a node’s identity and state, and it persists in object storage—independently of the process, its container, or its host. Understanding how a node moves through its states helps you restart, upgrade, scale, and decommission InfluxDB 3 Core safely. * [Node states](#node-states) * [Lifecycle overview](#lifecycle-overview) * [Register a node](#register-a-node) * [Stop a node](#stop-a-node) * [Re-register a node](#re-register-a-node) * [Deploy with an orchestrator](#deploy-with-an-orchestrator) * [Verify node state](#verify-node-state) * [Troubleshoot node lifecycle issues](#troubleshoot-node-lifecycle-issues) ## Node states The catalog records one of the following states for each node: | State | Description | |----------|----------------------------------------------------------------------| |`running` | The node started and registered itself in the catalog | |`stopping`|A graceful stop was requested, but the node hasn’t acknowledged it yet| |`stopped` | The node acknowledged its final snapshot and completed shutdown | |`removing`| The node is marked for permanent removal from the cluster | > [!Note] > #### Core uses running and stopped > > InfluxDB 3 Core runs a single node and doesn’t provide node management > commands, so a InfluxDB 3 Core node only ever reads as `running` or`stopped`. > The `stopping` and `removing` states apply to[InfluxDB 3 Enterprise](/influxdb3/enterprise/admin/node-lifecycle/) clusters, > where an operator can stop and remove individual nodes. Node identity has two parts: * **Node ID**: The name you assign with[`--node-id`](/influxdb3/core/reference/config-options/#node-id). It identifies the node across restarts. * **Instance ID**: A UUID that InfluxDB 3 Core generates the first time a node ID registers. A node that restarts with the same node ID reuses its existing instance ID. ## Lifecycle overview stateDiagram-v2 [\*] --\> running: influxdb3 serve running --\> stopped: SIGTERM or SIGINT stopped --\> running: influxdb3 serve (same node ID) ## Register a node When you start a server with[`influxdb3 serve`](/influxdb3/core/reference/cli/influxdb3/serve/), the node registers itself in the catalog and enters the `running` state: ```bash influxdb3 serve \ --node-id NODE_ID \ --object-store file \ --data-dir ~/.influxdb3 ``` Replace `NODE_ID`with a unique identifier for the node. Registration is how a node claims its node ID. If the node ID already exists in the catalog, InfluxDB 3 Core applies the[re-registration rules](#re-register-a-node) before accepting the node. ## Stop a node Stop InfluxDB 3 Core by signaling the process—for example, press Ctrl-c in the foreground, run `systemctl stop influxdb3`, or stop the container.`SIGTERM` and `SIGINT` both start a graceful shutdown. During a graceful shutdown, the node does the following: 1. Stops accepting writes. 2. Flushes the write-ahead log (WAL) buffer to object storage. 3. Waits for an in-progress snapshot to finish. 4. Marks itself `stopped` in the catalog. Because the final flush writes buffered data to the WAL in object storage, acknowledged writes survive the shutdown. When the node restarts, WAL replay restores any writes that weren’t yet captured in a snapshot. > [!Important] > #### Give the process time to shut down > > A graceful shutdown isn’t instantaneous. > If your init system, container runtime, or orchestrator sends `SIGKILL`before the flush completes, the node can’t finish its final flush. > For guidance on timeouts, see[Deploy with an orchestrator](#deploy-with-an-orchestrator). ## Re-register a node Whether a node ID can be claimed again depends on the current state of the node in the catalog: |Current state| Can register again? | |-------------|------------------------------------------------------------| | `stopped` | Yes—any instance can take over the node ID | | `running` |Only the same instance ID (an idempotent retry or a restart)| Because a node restarting with the same node ID reuses its existing instance ID, an ordinary restart always satisfies these rules—even if the node still reads as `running` after an ungraceful stop. ## Deploy with an orchestrator Helm, Kubernetes, and Ansible deployments drive the node lifecycle on your behalf. The following guidance keeps orchestrated restarts on the graceful path. ### Kubernetes and Helm **Give each node a stable node ID.**Use a StatefulSet so pod names are stable and ordinal-based, and derive`--node-id` from the pod name. The official[InfluxDB 3 Core Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-core)does this already—it runs a StatefulSet and sets `--node-id=$(POD_NAME)` from`metadata.name`. A Deployment generates a new random pod name on every rollout, which registers a new node in the catalog on each restart and leaves the old entries behind. **Set a termination grace period that fits your WAL.**Kubernetes sends `SIGTERM`, waits `terminationGracePeriodSeconds`(default `30`), and then sends `SIGKILL`. A node that’s still flushing when `SIGKILL` arrives stops ungracefully. Set `terminationGracePeriodSeconds` well above your observed shutdown time: ```yaml spec: template: spec: terminationGracePeriodSeconds: 300 ``` > [!Important] > #### The Helm chart doesn’t set a grace period > > The InfluxDB 3 Core Helm chart doesn’t set`terminationGracePeriodSeconds`, so pods inherit the Kubernetes default of > 30 seconds. > For nodes with a large WAL, raise it in your `values.yaml` overrides and > confirm the shutdown completes in the pod logs. **Restarts reuse the same node.**A `helm upgrade` or `kubectl rollout restart` terminates and recreates the pod with the same name, so the node re-registers with its existing node ID and replays its WAL. ### Ansible and systemd **Let systemd send `SIGTERM`.**The systemd default `KillSignal` is `SIGTERM`, which starts a graceful shutdown—don’t override it with `SIGKILL`. **Raise `TimeoutStopSec`.**If the node doesn’t exit within `TimeoutStopSec`, systemd escalates to`SIGKILL`. Set it above your observed shutdown time: ```ini [Service] KillSignal=SIGTERM TimeoutStopSec=300 ``` **Wait for the node to return to `running`.**Confirm the node re-registered and finished WAL replay before you send traffic to it again. **Never use `kill -9`.**Ad hoc `kill -9`, `docker kill`, and force-stopped containers all skip the final flush. ## Verify node state InfluxDB 3 Core doesn’t provide node management commands, but you can query the `system.nodes` table in the `_internal` database to see the node’s registered state: ```bash influxdb3 query \ --database _internal \ --token AUTH_TOKEN \ "SELECT node_id, mode, state, updated_at FROM system.nodes" ``` Replace `AUTH_TOKEN`with a token that has permission to query the `_internal` database. ## Troubleshoot node lifecycle issues ### The node didn’t shut down cleanly If the process was killed before it finished flushing, restart it with the same node ID and object store configuration. WAL replay restores acknowledged writes that weren’t yet captured in a snapshot. ### A new node appears after each restart Each restart registered a new node ID. Check that your deployment assigns a stable[`--node-id`](/influxdb3/core/reference/config-options/#node-id)—see[Deploy with an orchestrator](#deploy-with-an-orchestrator). #### Related * [Upgrade InfluxDB 3 Core](/influxdb3/core/admin/upgrade/) * [Back up and restore data](/influxdb3/core/admin/backup-restore/) * [InfluxDB 3 Core internals](/influxdb3/core/reference/internals/durability/) * [influxdb3 serve](/influxdb3/core/reference/cli/influxdb3/serve/) [nodes](/influxdb3/core/tags/nodes/)[lifecycle](/influxdb3/core/tags/lifecycle/)[administration](/influxdb3/core/tags/administration/)[wal](/influxdb3/core/tags/wal/) | State | Description | | --- | --- | | State | Description | | running | The node started and registered itself in the catalog | | stopping | A graceful stop was requested, but the node hasn’t acknowledged it yet | | stopped | The node acknowledged its final snapshot and completed shutdown | | removing | The node is marked for permanent removal from the cluster | | Current state | Can register again? | | --- | --- | | Current state | Can register again? | | stopped | Yes—any instance can take over the node ID | | running | Only the same instance ID (an idempotent retry or a restart) | --- # Performance tuning Source: https://docs.influxdata.com/influxdb3/core/admin/performance-tuning/ Configure thread allocation, memory settings, and other parameters to optimize InfluxDB 3 Core performance based on your workload characteristics. * [Best practices](#best-practices) * [General monitoring principles](#general-monitoring-principles) * [Essential settings for performance](#essential-settings-for-performance) * [Common performance issues](#common-performance-issues) * [Configuration examples by workload](#configuration-examples-by-workload) * [Thread allocation details](#thread-allocation-details) * [Memory tuning](#memory-tuning) * [Advanced tuning options](#advanced-tuning-options) * [Startup optimization](#startup-optimization) * [Monitoring and validation](#monitoring-and-validation) * [Common performance issues](#common-performance-issues-1) ## Best practices 1. **Start with monitoring**: Understand your current bottlenecks before tuning 2. **Change one parameter at a time**: Isolate the impact of each change 3. **Test with production-like workloads**: Use realistic data and query patterns 4. **Document your configuration**: Keep track of what works for your workload 5. **Plan for growth**: Leave headroom for traffic increases 6. **Regular review**: Periodically reassess as workloads evolve ## General monitoring principles Before tuning performance, establish baseline metrics to identify bottlenecks: ### Key metrics to monitor 1. **CPU usage per core** * Monitor individual core utilization to identify thread pool imbalances * Watch for cores at 100% while others are idle (indicates thread allocation issues) * Use `top -H` or `htop` to view per-thread CPU usage 2. **Memory consumption** * Track heap usage vs available RAM * Monitor query execution memory pool utilization * Watch for OOM errors or excessive swapping 3. **IO and network** * Measure write throughput (points/second) * Track query response times * Monitor object store latency for cloud deployments * Check disk IO wait times with `iostat` ### Establish baselines ```bash # Monitor CPU per thread top -H -p $(pgrep influxdb3) # Track memory usage free -h watch -n 1 "free -h" # Check IO wait iostat -x 1 ``` > [!Tip] > For comprehensive metrics monitoring, see [Monitor metrics](/influxdb3/core/admin/monitor-metrics/). ## Essential settings for performance ### Thread allocation (–num-io-threads ) **IO threads** handle HTTP requests and line protocol parsing. **Default: 2** (often insufficient). > [!Note] > InfluxDB 3 Core automatically allocates remaining cores to DataFusion after reserving IO threads. You can configure both thread pools explicitly by setting the `--num-io-threads` and `--datafusion-num-threads` options. ```bash # Write-heavy: More IO threads influxdb3 --num-io-threads=12 serve \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 # Query-heavy: Fewer IO threads influxdb3 --num-io-threads=4 serve \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 ``` > [!Warning] > #### Increase IO threads for concurrent writers > > If you have multiple concurrent writers (for example, Telegraf agents), the default of 2 IO threads can bottleneck write performance. ### Memory pool (–exec-mem-pool-size) Controls memory for query execution. Default: 20% of RAM. ```bash # Increase for query-heavy workloads influxdb3 serve \ --exec-mem-pool-size=90% \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 # Decrease if experiencing memory pressure influxdb3 serve \ --exec-mem-pool-size=60% \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 ``` ### Data file cache (–file-cache-size) Caches frequently accessed data files in memory. ```bash # Enable caching for better query performance influxdb3 serve \ --file-cache-size=4gb \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 ``` ### WAL flush interval (–wal-flush-interval) Controls write latency vs throughput. Default: 1s. ```bash # Reduce latency for real-time data influxdb3 serve \ --wal-flush-interval=100ms \ --node-id=node0 \ --object-store=file --data-dir=~/.influxdb3 ``` ## Common performance issues ### High write latency **Symptoms:** Increasing write response times, timeouts, points dropped **Solutions:** 1. Increase [IO threads](#thread-allocation-num-io-threads) (default is only 2) 2. Reduce [WAL flush interval](#wal-flush-interval-wal-flush-interval) (from 1s to 100ms) 3. Check disk IO performance ### Slow query performance **Symptoms:** Long execution times, high memory usage, query timeouts **Solutions:**1. Increase [execution memory pool](#memory-pool-exec-mem-pool-size) (to 90%) 3. Enable [data file caching](#data-file-cache-file-cache-size) ### Memory pressure **Symptoms:** OOM errors, swapping, high memory usage **Solutions:** 1. Reduce [execution memory pool](#memory-pool-exec-mem-pool-size) (to 60%) 2. Lower snapshot threshold (`--force-snapshot-mem-size=70%`) ### CPU bottlenecks **Symptoms:** 100% CPU utilization, uneven thread usage (only 2 cores for writes) **Solutions:** 1. Rebalance [thread allocation](#thread-allocation-num-io-threads) 2. Check if only 2 cores are used for write parsing (increase IO threads) > [!Important] > #### “My ingesters are only using 2 cores” > > Increase `--num-io-threads` to 8-16+ for ingest nodes. ## Configuration examples by workload ### Write-heavy workloads (\>100k points/second) ```bash # 32-core system, high ingest rate influxdb3 --num-io-threads=12 serve \ --exec-mem-pool-size=80% \ --wal-flush-interval=100ms \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` ### Query-heavy workloads (complex analytics) ```bash # 32-core system, analytical queries influxdb3 --num-io-threads=4 serve \ --exec-mem-pool-size=90% \ --file-cache-size=2gb \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` ### Mixed workloads (real-time dashboards) ```bash # 32-core system, balanced operations influxdb3 --num-io-threads=8 serve \ --exec-mem-pool-size=70% \ --file-cache-size=1gb \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` ## Thread allocation details ### Calculate optimal thread counts Use this formula as a starting point: ``` Total cores = N Concurrent writers = W Query complexity factor = Q (1-10, where 10 is most complex) IO threads = min(W + 2, N * 0.4) DataFusion threads = N - IO threads ``` ### Example configurations by system size #### Small system (4 cores, 16 GB RAM) ```bash # Balanced configuration influxdb3 --num-io-threads=2 serve \ --exec-mem-pool-size=10GB \ --file-cache-size=500mb \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` #### Medium system (16 cores, 64 GB RAM) ```bash # Write-optimized configuration influxdb3 --num-io-threads=6 serve \ --exec-mem-pool-size=45GB \ --file-cache-size=2gb \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` #### Large system (64 cores, 256 GB RAM) ```bash # Query-optimized configuration influxdb3 --num-io-threads=8 serve \ --exec-mem-pool-size=200GB \ --file-cache-size=10gb \ --object-store-connection-limit=200 \ --node-id=node0 \ --object-store=file \ --data-dir=~/.influxdb3 ``` ## Memory tuning ### Execution memory pool Configure the query execution memory pool: ```bash # Absolute value with a unit suffix --exec-mem-pool-size=8gb # Percentage of available RAM --exec-mem-pool-size=80% # 80% of system RAM ``` **Guidelines:** * **Write-heavy**: 60-70% (leave room for OS cache) * **Query-heavy**: 80-90% (maximize query memory) * **Mixed**: 70% (balanced approach) ### Data file cache configuration Cache frequently accessed data files: ```bash # Set cache size --file-cache-size=2gb # Configure cache behavior --parquet-mem-cache-prune-interval=1m \ --parquet-mem-cache-prune-percentage=20 ``` ### WAL and snapshot tuning Control memory pressure from write buffers: ```bash # Force snapshot when memory usage exceeds threshold --force-snapshot-mem-size=80% # Configure WAL rotation --wal-flush-interval=10s \ --wal-files-per-snapshot=100 ``` ## Advanced tuning options For less common performance optimizations and detailed configuration options, see: ### DataFusion engine tuning Advanced DataFusion runtime parameters: * [`--datafusion-config`](/influxdb3/core/reference/cli/influxdb3/serve/#datafusion-config) ### HTTP and network tuning Request size and network optimization: * [`--max-http-request-size`](/influxdb3/core/reference/cli/influxdb3/serve/#max-http-request-size) - For large batches (default: 10 MB) * [`--http-bind`](/influxdb3/core/reference/cli/influxdb3/serve/#http-bind) - Bind address ### Object store optimization Performance tuning for cloud object stores: * [`--object-store-connection-limit`](/influxdb3/core/reference/cli/influxdb3/serve/#object-store-connection-limit) - Connection pool size * [`--object-store-max-retries`](/influxdb3/core/reference/cli/influxdb3/serve/#object-store-max-retries) - Retry configuration * [`--object-store-http2-only`](/influxdb3/core/reference/cli/influxdb3/serve/#object-store-http2-only) - Force HTTP/2 ### Complete configuration reference For all available configuration options, see: * [CLI serve command reference](/influxdb3/core/reference/cli/influxdb3/serve/) * [Configuration options](/influxdb3/core/reference/config-options/) ## Startup optimization Server startup time scales with the number of[snapshots](/influxdb3/core/admin/backup-restore/#file-structure)stored in the object store. Snapshots accumulate over time and are not automatically deleted. Without checkpointing, the server loads individual snapshots on startup. The number of snapshots is determined by the lookback window ([`gen1-lookback-duration`](/influxdb3/core/reference/config-options/#gen1-lookback-duration), default 1 month) divided by[`gen1-duration`](/influxdb3/core/reference/config-options/#gen1-duration)(default 10 minutes), with a minimum of 100. With default settings, a long-running server can accumulate up to \~4,320 snapshots, causing slow restarts. Two configuration options reduce startup time: * [`--checkpoint-interval`](/influxdb3/core/reference/config-options/#checkpoint-interval)– periodically consolidates snapshot metadata into monthly checkpoints. On startup, the server loads one to two checkpoints per calendar month, then loads only snapshots created since the last checkpoint. * [`--gen1-lookback-duration`](/influxdb3/core/reference/config-options/#gen1-lookback-duration)– limits how far back the server loads gen1 file index metadata on startup. Files outside this window still exist in object storage but are not indexed. > [!Note] > Enabling checkpointing does not delete old snapshots. > They remain in object storage but are no longer needed for startup. ### Recommended checkpoint intervals | Scenario |Recommended interval| |---------------------|--------------------| | Production servers | `1h` | |Development / testing| `10m` | ### Enable checkpoint creation ```bash influxdb3 serve --checkpoint-interval 1h ``` For all checkpoint configuration options, see[checkpoint-interval](/influxdb3/core/reference/config-options/#checkpoint-interval). ## Monitoring and validation ### Monitor thread utilization ```bash # Linux: View per-thread CPU usage top -H -p $(pgrep influxdb3) # Monitor specific threads watch -n 1 "ps -eLf | grep influxdb3 | head -20" ``` ### Check performance metrics Monitor key indicators: ```sql -- Query system.threads table (Enterprise) SELECT * FROM system.threads WHERE cpu_usage > 90 ORDER BY cpu_usage DESC; -- Check write throughput SELECT count(*) as points_written, max(timestamp) - min(timestamp) as time_range FROM your_measurement WHERE timestamp > now() - INTERVAL '1 minute'; ``` ### Validate configuration Verify your tuning changes: ```bash # Check effective configuration influxdb3 serve --help-all | grep -E "num-io-threads|num-datafusion-threads" # Monitor memory usage free -h watch -n 1 "free -h" # Check IO wait iostat -x 1 ``` ## Common performance issues ### High write latency **Symptoms:** * Increasing write response times * Timeouts from write clients * Points dropped or rejected **Solutions:** 1. Increase IO threads: `--num-io-threads=16` 2. Reduce batch sizes in writers 3. Increase WAL flush frequency 4. Check disk IO performance ### Slow query performance **Symptoms:** * Long query execution times * High memory usage during queries * Query timeouts **Solutions:** 1. Increase execution memory pool: `--exec-mem-pool-size=90%` 2. Enable data file caching: `--file-cache-size=4GB` 3. Optimize query patterns (smaller time ranges, fewer fields) ### Memory pressure **Symptoms:** * Out of memory errors * Frequent garbage collection * System swapping **Solutions:** 1. Reduce execution memory pool: `--exec-mem-pool-size=60%` 2. Lower snapshot threshold: `--force-snapshot-mem-size=70%` 3. Decrease cache sizes 4. Add more RAM or reduce workload ### CPU bottlenecks **Symptoms:** * 100% CPU utilization * Uneven thread pool usage * Performance plateaus **Solutions:** 1. Rebalance thread allocation based on workload 2. Add more CPU cores 3. Optimize client batching 4. #### Related * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) * [Query system data](/influxdb3/core/admin/query-system-data/) | Scenario | Recommended interval | | --- | --- | | Scenario | Recommended interval | | Production servers | 1h | | Development / testing | 10m | --- # Query system data Source: https://docs.influxdata.com/influxdb3/core/admin/query-system-data/ InfluxDB 3 Core stores data related to the database server, queries, and tables in *system tables*. You can query the system tables for information about your running server, databases, and table schemas. ## Query system tables * [Use the HTTP query API](#use-the-http-query-api) * [Examples](#examples) * [Show tables](#show-tables) * [View column information for a table](#view-column-information-for-a-table) * [Recently executed queries](#recently-executed-queries) * [Query plugin files](#query-plugin-files) * [Query trigger logs](#query-trigger-logs) ### Use the HTTP query API Use the HTTP API `/api/v3/query_sql` endpoint to retrieve system information about your database server and table schemas in InfluxDB 3 Core. To execute a query, send a `GET` or `POST` request to the endpoint: * `GET`: Pass parameters in the URL query string (for simple queries) * `POST`: Pass parameters in a JSON object (for complex queries and readability in your code) Include the following parameters: * `q`: *(Required)* The SQL query to execute. * `db`: *(Required)* The database to execute the query against. * `params`: A JSON object containing parameters to be used in a *parameterized query*. * `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`). JSONL (`jsonl`) is preferred because it streams results back to the client.`pretty` is for human-readable output. Default is `json`. #### Examples > [!Note] > #### system\_ sample data > > In examples, tables with `"table_name":"system_` are user-created tables for CPU, memory, disk, > network, and other resource statistics collected and written > by the user–for example, using the `psutil` Python library or[Telegraf](/telegraf/v1/get-started/) to collect > and write system metrics to an InfluxDB 3 database. ##### Show tables The following example sends a `GET` request that executes a `show tables` query to retrieve all user-created tables (`"table_schema":"iox"`), system tables, and information schema tables for a database: ```bash curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" ``` The response body contains the following JSONL: ```jsonl {"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"} ``` A table has one of the following `table_schema` values: * `iox`: tables created by the user of the database. * `system`: tables used by the system to show information about the running database server. Some of these tables show stored information such as configurations, while others, such as the `queries` table, hold ephemeral state in memory. * `information_schema`: views that show schema information for tables in the database. #### View column information for a table The following query sends a `POST` request that executes an SQL query to retrieve information about columns in the sample `system_swap` table schema: *Note: when you send a query in JSON, you must escape single quotes that surround field names.* ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'", "format": "jsonl" }' ``` The output is the following: ```jsonl {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"percent","ordinal_position":2,"is_nullable":"YES","data_type":"Float64","numeric_precision":24,"numeric_precision_radix":2} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"} ``` #### Recently executed queries To view recently executed queries, query the `queries` system table: ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM system.queries LIMIT 2", "format": "jsonl" }' ``` The output is similar to the following: ```jsonl {"id":"cdd63409-1822-4e65-8e3a-d274d553dbb3","phase":"success","issue_time":"2025-01-20T17:01:40.690067","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.032689S","permit_duration":"PT0.000202S","execute_duration":"PT0.000223S","end2end_duration":"PT0.033115S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false} {"id":"47f8d312-5e75-4db2-837a-6fcf94c09927","phase":"success","issue_time":"2025-01-20T17:02:32.627782","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.000583S","permit_duration":"PT0.000015S","execute_duration":"PT0.000063S","end2end_duration":"PT0.000662S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false} ``` #### Query plugin files To view loaded Processing Engine plugins, query the `plugin_files` system table in the `_internal` database. The `system.plugin_files` table provides information about plugin files loaded by the Processing Engine: **Columns:** * `plugin_name` (String): Name of a trigger using this plugin * `file_name` (String): Plugin filename * `file_path` (String): Full server path to the plugin file * `size_bytes` (Int64): File size in bytes * `last_modified` (Int64): Last modification timestamp (milliseconds since epoch) ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "_internal", "q": "SELECT * FROM system.plugin_files", "format": "jsonl" }' ``` The output is similar to the following: ```jsonl {"plugin_name":"my_trigger","file_name":"my_plugin.py","file_path":"/path/to/plugins/my_plugin.py","size_bytes":2048,"last_modified":1704067200000} {"plugin_name":"scheduled_trigger","file_name":"scheduler.py","file_path":"/path/to/plugins/scheduler.py","size_bytes":4096,"last_modified":1704153600000} ``` **Filter plugins by trigger name:** ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "_internal", "q": "SELECT * FROM system.plugin_files WHERE plugin_name = '"'my_trigger'"'", "format": "jsonl" }' ``` **Find plugins by file pattern:** ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "_internal", "q": "SELECT * FROM system.plugin_files WHERE file_name LIKE '"'%scheduler%'"'", "format": "jsonl" }' ``` #### Query trigger logs The `system.processing_engine_logs` table stores log entries from Processing Engine triggers. Logs are stored in **two locations**: * The trigger’s database (primary)–query here for trigger-specific debugging * The `_internal` database–contains logs from all triggers across all databases **Columns:** * `event_time` (Timestamp): When the log entry was recorded * `trigger_name` (String): Name of the trigger that generated the log * `log_level` (String): Log level (INFO, WARN, ERROR) * `log_text` (String): Log message content **Query logs for a specific trigger:** ```bash influxdb3 query \ --database DATABASE \ "SELECT event_time, log_level, log_text FROM system.processing_engine_logs WHERE trigger_name = 'TRIGGER' ORDER BY event_time DESC LIMIT 20" ``` Replace the following: * `DATABASE`: The database where you created the trigger * `TRIGGER`: The name of your trigger **Query all trigger logs (from \_internal):** ```bash influxdb3 query \ --database _internal \ "SELECT event_time, trigger_name, log_level, log_text FROM system.processing_engine_logs ORDER BY event_time DESC LIMIT 50" ``` #### Related * [Query data with SQL](/influxdb3/core/query-data/sql/) * [Execute queries](/influxdb3/core/query-data/execute-queries/) [query](/influxdb3/core/tags/query/)[api](/influxdb3/core/tags/api/)[system information](/influxdb3/core/tags/system-information/)[schemas](/influxdb3/core/tags/schemas/) --- # Security Source: https://docs.influxdata.com/influxdb3/core/admin/security/ InfluxDB 3 Core includes security features to protect your data and system resources. When you install using DEB or RPM packages, the default `systemd` unit file configures security sandboxing to isolate the database process from the host system. This page explains the filesystem layout, sandboxing directives, and how to customize security settings for your environment. * [Linux DEB and RPM](#linux-deb-and-rpm) * [Requirements](#requirements) * [Filesystem layout](#filesystem-layout) * [systemd unit in detail](#systemd-unit-in-detail) * [Default sandbox configuration](#default-sandbox-configuration) * [Site-specific directives](#site-specific-directives) * [Tuning the systemd unit](#tuning-the-systemd-unit) * [systemd references](#systemd-references) ## Linux DEB and RPM When you install via DEB or RPM on a `systemd`-enabled system, InfluxDB 3 Core runs in a sandboxed environment configured by the provided `systemd` unit file. ### Requirements * A `systemd`-enabled Linux system * `systemd` version 248 or later for full sandbox support (Debian 12+, RHEL 9+, Ubuntu 22.04+) > [!Note] > On older systems, `systemd` logs `Unknown lvalue ''` and starts the service without sandbox protection. ### Filesystem layout The provided unit file assumes the following filesystem layout: * `/etc/influxdb3`: directory for InfluxDB 3 Core configuration (`0755` permissions with `root:influxdb3` ownership by default) * `/etc/influxdb3/influxdb3-core.conf`: TOML configuration file * `/usr/bin/influxdb3`: InfluxDB 3 Core binary * `/usr/lib/influxdb3/python`: directory containing the embedded interpreter used by the InfluxDB 3 Core processing engine * `/var/lib/influxdb3`: writable directory for InfluxDB 3 Core * `/var/lib/influxdb3/data`: default directory for InfluxDB 3 Core data files when `object-store` is set to `file` (the default for DEB and RPM installations) * `/var/lib/influxdb3/plugins`: default directory for InfluxDB 3 Core plugin files * `/var/log/influxdb3`: writable directory for logging (unused by default) > [!Important] > If you store sensitive credentials in `/etc/influxdb3`, adjust permissions to `0750` to restrict access. ### `systemd` unit in detail The unit file is self-documenting. To view the full systemd configuration for the InfluxDB 3 service (`influxdb3-core`), enter the following command: ```bash systemctl cat influxdb3-core ``` The output is similar to the following: ``` # /usr/lib/systemd/system/influxdb3-core.service [Unit] Description=InfluxDB 3 Core After=network-online.target [Service] Type=simple ... ... ``` #### Default sandbox configuration The default sandbox configuration provides security isolation without breaking common use cases. The following options are set by default: ##### Basic Security Defaults for basic security, such as filesystem and user: * `StateDirectory=influxdb3` - writable area relative to `/var/lib` * `LogsDirectory=influxdb3` - writable area relative to `/var/log` (the unit is configured with `StandardOutput=journal` and `StandardError=journal` by default and will not use this directory) * `User=influxdb3`, `Group=influxdb3`, `SupplementaryGroups=` - run InfluxDB 3 Core as the unprivileged `influxdb3:influxdb3` user. InfluxDB 3 Core does not require any special privileges to run and this should always be set to an unprivileged user * `UMask=0027` - restrictive default file mode creation mask ##### Limit kernal attack surface Defaults to limit the kernal attack surface: * `SystemCallFilter=@system-service`, `SystemCallArchitectures=native`, `SystemCallFilter=~io_uring_setup keyctl userfaultfd`, and `LockPersonality=true` - basic set of allowed Linux system calls excluding a few unneeded ones that can be abused * `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX` - limit allowed address families to those needed for basic functionality (such as, IP networking and DNS resolution). Custom processing engine plugins that need kernel socket of route introspection may need to add `AF_NETLINK` to this list * `RestrictNamespaces=true` - disallow use of Linux namespaces ##### Limit privileges Defaults to limit privileges and disallow gaining or inheriting permissions and capabilities (blocks ICMP `ping`, `passwd`): * `NoNewPrivileges=true` * `RestrictSUIDSGID=true` * `CapabilityBoundingSet=` * `AmbientCapabilities=` ##### Host protection Defaults for host protection: * `ProtectSystem=strict` - make host files read-only * `ProtectHome=true` - disallow access to `/home` (tip: put credentials, configuration, etc in `/etc/influxdb3` or somewhere in `/var/lib/influxdb3` instead) * `PrivateTmp=true` - use separate `/tmp` and `/var/tmp` from host * `TemporaryFileSystem=/dev/shm:mode=1777` - use separate `/dev/shm` (override with `size=` to limit size too) * `PrivateDevices=true` - allow only pseudo devices with no host mount propagation * `ProtectKernelLogs=true` - disallow access to the kernel log ring buffer (needed if `PrivateDevices=false`) * `PrivateIPC=true` - use separate SysV IPC from host * `InaccessiblePaths=...` - disallow well-known system and user services’ named sockets (needed since `AF_UNIX` is allowed) * `ProtectProc=invisible` - hide processes not owned by this [user ( `influxdb3:influxdb3`)](#basic-security). This provides strong isolation but means that plugins can’t see other processes on the system, which could affect custom processing engine plugins that require this #### Site-specific directives The default configuration omits directives that depend on your environment–for example, the following directives require tuning based on your deployment requirements and resource constraints: * `IPAddressDeny` and `IPAddressAllow` for limiting communications by the database and processing engine to certain IP addresses * `MemoryHigh` and `MemoryMax` for limiting memory usage (the database process already has configurable controls for memory so this is primarily useful to limit the processing engine) * `Nice`, `CPUQuota`, `CPUSchedulingPolicy`, `LimitNPROC`, and `TasksMax` for limiting CPU usage (the database process already has configurable controls for CPU so this is primarily useful to limit the processing engine) * `IOWeight`, etc for limiting I/O operations (primarily useful for limiting the processing engine) * `ReadOnlyPaths`, `ReadWritePaths`, and `InaccessiblePaths` to allow/disallow other paths not covered by the default sandbox > [!Important] > Due to a limit in InfluxDB 3 Core related to socket activation, `PrivateNetwork=true` cannot be used at this time. ### Tuning the `systemd` unit While the `systemd` unit is verified to work with InfluxDB 3 Core and [official plugins](/influxdb3/core/plugins/library/official/), you may want to harden the unit further or loosen its restrictions in certain situations. To edit the unit file, enter the following command: ```bash systemctl edit influxdb3-core ``` > [!Note] > Avoid modifying the `influxdb3-core.service` file directly. > Use `systemctl edit` to add overrides. #### Example: loosen for ProtectProc=default If a custom plugin needs to read other processes’ information from `/proc`: 1. Run `sudo systemctl edit influxdb3-core` 2. Edit the file to contain: ``` ### Editing /etc/systemd/system/influxdb3-core.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file [Service] # the 'foo' plugin needs to see other user's processes ProtectProc=default ### Lines below this comment will be discarded ... ``` 3. Verify the changes (the shipped unit is listed first followed by overrides): ``` $ sudo systemctl daemon-reload && systemctl cat --no-pager influxdb3-core [Unit] Description=InfluxDB 3 Core After=network-online.target [Service] ... ProtectProc=invisible ... # /etc/systemd/system/influxdb3-core.service.d/override.conf [Service] # the 'foo' plugin needs to see other users' processes ProtectProc=default $ ``` 4. Restart the unit with `sudo systemctl restart influxdb3-core` #### Example: restrict networking `systemd` supports network filtering via BPF. When adding directives, the rule evaluation order is: 1. Access is granted if matches entry in IPAddressAllow 2. Otherwise access is denied if matches entry in IPAddressDeny 3. Otherwise access is granted For egress, the IP matches against sender and for ingress, it matches against the receiver. This filtering only matches on IP addresses, not ports; if you need more flexibility, use host firewall tools/cloud security groups instead. As an example, to limit communications to only localhost, use`systemctl edit influxdb3-core` to add: ``` ### Editing /etc/systemd/system/influxdb3-core.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file IPAddressDeny=any IPAddressAllow=localhost ### Lines below this comment will be discarded ... ``` Alternatively, to restrict networking to only public IP ranges, use this instead: ``` ### Editing /etc/systemd/system/influxdb3-core.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file IPAddressDeny=0.0.0.0/32 # 0.0.0.0 treated as 127.0.0.1 IPAddressDeny=127.0.0.0/8 # IPv4 loopback IPAddressDeny=10.0.0.0/8 # IPv4 internal (RFC1918) IPAddressDeny=172.16.0.0/12 # IPv4 internal (RFC1918) IPAddressDeny=192.168.0.0/16 # IPv4 internal (RFC1918) IPAddressDeny=169.254.0.0/16 # IPv4 link-local (RFC3927) IPAddressDeny=224.0.0.0/4 # IPv4 multicast IPAddressDeny=::1/128 # IPv6 loopback IPAddressDeny=fe80::/64 # IPv6 link-local IPAddressDeny=fc00::/7 # IPv6 unique local addr IPAddressDeny=ff00::/8 # IPv6 multicast ### Lines below this comment will be discarded ... ``` ### systemd references See the `systemd` documentation for additional information: * [systemd](https://www.freedesktop.org/software/systemd/man/latest/) * [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) * [systemd.exec](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html) * [systemd.resource-control](https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html) #### Related --- # Manage tables Source: https://docs.influxdata.com/influxdb3/core/admin/tables/ Tables are synonymous with measurements in InfluxDB 3 Core. They are typically created automatically when you write line protocol data, but you can also manually create them to define custom schemas or apply settings. before writing data. ### [Create a table](/influxdb3/core/admin/tables/create/) Use the influxdb3 CLI or HTTP API to create a table in a specified database in InfluxDB 3 Core. ```sh # influxdb3 CLI influxdb3 create table \ --tags tag1,tag2,tag3 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME # HTTP API curl -X POST "http://localhost:8181/api/v3/configure/table" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{"db": "DATABASE_NAME", "table": "TABLE_NAME", "tags": ["tag1", "tag2", "tag3"]}' ``` ### [List tables](/influxdb3/core/admin/tables/list/) Use the influxdb3 CLI or HTTP API to list tables in a specified database in InfluxDB 3 Core. Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. ```sh # influxdb3 CLI influxdb3 query \ --database DATABASE_NAME \ --token AUTH_TOKEN \ "SHOW TABLES" # HTTP API curl --get "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW TABLES" ``` ### [Delete a table](/influxdb3/core/admin/tables/delete/) Use the [`influxdb3 delete table` command](/influxdb3/core/reference/cli/influxdb3/delete/table/) or the [HTTP API](/influxdb3/core/api/v3/) to delete a table from a specified database in InfluxDB 3 Core. Supports both soft delete and hard delete operations. ```sh # CLI influxdb3 delete table \ --database \ --token \ # HTTP API curl -X DELETE "http://localhost:8181/api/v3/configure/table?db=&table=" \ --header "Authorization: Bearer " ``` #### Related * [InfluxDB schema design recommendations](/influxdb3/core/write-data/best-practices/schema-design/) * [influxdb3 CLI](/influxdb3/core/reference/cli/influxdb3/) * [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/) [tables](/influxdb3/core/tags/tables/) --- # Create a table Source: https://docs.influxdata.com/influxdb3/core/admin/tables/create/ Use the [`influxdb3 create table` command](/influxdb3/core/reference/cli/influxdb3/create/table/)or the [HTTP API](/influxdb3/core/api/v3/) to create a table in a specified database in InfluxDB 3 Core. With InfluxDB 3 Core, tables and measurements are synonymous. Typically, tables are created automatically on write using the table name specified in line protocol written to InfluxDB. However, you can manually create tables to define a custom schema or apply custom settings before writing data. * [Create a table using the influxdb3 CLI](#create-a-table-using-the-influxdb3-cli) * [Create a table using the HTTP API](#create-a-table-using-the-http-api) * [Data retention](#data-retention) * [Table naming restrictions](#table-naming-restrictions) ## Create a table using the influxdb3 CLI Use the `influxdb3 create table` command and provide the following: * *Required*: The name of the database to create the table in * *Required*: The name of the table to create (see [Table naming restrictions](#table-naming-restrictions)) * *Required*: Tag columns to include in the table (must have at least one tag column) * *Optional*: Field columns and their data types to include in the table > [!Note] > Tables must include at least one tag column. > Field columns are optional and can be added later when you write data. > [!Important] > #### Tag order affects query performance > > When considering your schema and creating your table, order your tags by query priority. > Place the most commonly queried tags first. > Columns that appear earlier are typically faster to filter and access during query execution. > > For more information, see [Optimize writes](/influxdb3/core/write-data/best-practices/optimize-writes/#sort-tags-by-query-priority). ```bash # Create a table with tag columns influxdb3 create table \ --tags tag1,tag2,tag3 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME # Create a table with tag and field columns influxdb3 create table \ --tags room,sensor_id \ --fields temp:float64,hum:float64,co:int64 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME ``` Replace the following: * `DATABASE_NAME`: the name of the database to create the table in * `TABLE_NAME`: the name of the table to create * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ## Create a table using the HTTP API To create a table using the HTTP API, send a `POST` request to the `/api/v3/configure/table` endpoint: ``` POST http://localhost:8181/api/v3/configure/table ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your authentication token * `Content-Type: application/json` * **Request body**: JSON object with table configuration * `db` *(string, required)*: Database name * `table` *(string, required)*: Table name * `tags` *(array, required)*: Tag column names * `fields` *(array, required)*: Field definitions with name and type. Provide an empty array if no fields are defined. ```bash # Create a table with tag columns curl -X POST "http://localhost:8181/api/v3/configure/table" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "table": "TABLE_NAME", "tags": ["tag1", "tag2", "tag3"], "fields": [] }' # Create a table with tag and field columns curl -X POST "http://localhost:8181/api/v3/configure/table" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "table": "TABLE_NAME", "tags": ["room", "sensor_id"], "fields": [ {"name": "temp", "type": "float64"}, {"name": "hum", "type": "float64"}, {"name": "co", "type": "int64"} ] }' ``` Replace the following: * `DATABASE_NAME`: the name of the database to create the table in * `TABLE_NAME`: the name of the table to create * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ## Data retention In InfluxDB 3 Core, tables use the database retention period. Points with timestamps outside of the database’s retention period are no longer queryable and are marked for deletion. To control data retention for your tables, set a retention period when [creating the database](/influxdb3/core/admin/databases/create/#retention-period). For more information, see [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/). > [!Note] > #### Upgrade to Enterprise for table-specific retention > > With InfluxDB 3 Enterprise, you can set table-level retention periods that override > the database retention period. This allows you to maintain different retention policies > for different types of data within the same database. > > For more information, see [InfluxDB 3 Enterprise](/influxdb3/enterprise/). ## Table naming restrictions Table names in InfluxDB 3 Core must adhere to the following naming restrictions: * **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`) * **Starting character**: Should start with a letter or number and should not start with underscore (`_`) * **Case sensitivity**: Table names are case-sensitive * **Quoting**: Use double quotes when names contain special characters or whitespace > [!Caution] > #### Underscore prefix reserved for system use > > Names starting with an underscore (`_`) may be reserved for InfluxDB system use. > While InfluxDB 3 Core might not explicitly reject these names, using them risks > conflicts with current or future system features and may result in > unexpected behavior or data loss. #### Related * [influxdb3 create table](/influxdb3/core/reference/cli/influxdb3/create/table/) * [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/) --- # Delete a table Source: https://docs.influxdata.com/influxdb3/core/admin/tables/delete/ Use the [`influxdb3 delete table` command](/influxdb3/core/reference/cli/influxdb3/delete/table/)or the [HTTP API](/influxdb3/core/api/v3/) to delete a table from a specified database in InfluxDB 3 Core. With InfluxDB 3 Core, tables and measurements are synonymous. By default, InfluxDB 3 Core performs a soft delete, which schedules the table for deletion and makes it unavailable for querying. You can also schedule a hard deletion to permanently remove the table and its data. > [!Caution] > #### Deleting a table cannot be undone > > Deleting a table is a destructive action. > Once a table is deleted, data stored in that table cannot be recovered. * [Delete a table using the influxdb3 CLI](#delete-a-table-using-the-influxdb3-cli) * [Delete a table using the HTTP API](#delete-a-table-using-the-http-api) ## Delete a table using the influxdb3 CLI Use the `influxdb3 delete table` command to delete a table: ```sh influxdb3 delete table \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME ``` Replace the following: * `DATABASE_NAME`: the name of the database containing the table * `TABLE_NAME`: the name of the table to delete * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Hard delete a table immediately To permanently delete a table and its data immediately, use the `--hard-delete now` flag: ```sh influxdb3 delete table \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --hard-delete now \ TABLE_NAME ``` ### Schedule a hard deletion To schedule a table for hard deletion at a specific time, use the `--hard-delete` flag with a timestamp: ```sh influxdb3 delete table \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --hard-delete "2025-12-31T23:59:59Z" \ TABLE_NAME ``` ## Delete a table using the HTTP API To delete a table using the HTTP API, send a `DELETE` request to the `/api/v3/configure/table` endpoint: ``` DELETE http://localhost:8181/api/v3/configure/table ``` Include the following in your request: * **Query parameters**: * `db`: Database name * `table`: Table name to delete * `hard_delete_at`: *(Optional)* Timestamp for hard deletion * **Headers**: * `Authorization: Bearer` with your authentication token ### Soft delete a table ```bash curl -X DELETE "http://localhost:8181/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME" \ --header "Authorization: Bearer AUTH_TOKEN" ``` Replace the following: * `DATABASE_NAME`: the name of the database containing the table * `TABLE_NAME`: the name of the table to delete * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Schedule a hard deletion To schedule a hard deletion at a specific time, include the `hard_delete_at` parameter with an ISO 8601 timestamp: ```bash curl -X DELETE "http://localhost:8181/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME&hard_delete_at=2025-12-31T23:59:59Z" \ --header "Authorization: Bearer AUTH_TOKEN" ``` ### Response A successful deletion returns HTTP status `200` with no content body. #### Example error response If the table doesn’t exist, the API returns HTTP status `404`: ```json { "error": "Table not found" } ``` #### Related * [influxdb3 delete table](/influxdb3/core/reference/cli/influxdb3/delete/table/) --- # List tables Source: https://docs.influxdata.com/influxdb3/core/admin/tables/list/ Use the [`influxdb3 query` command](/influxdb3/core/reference/cli/influxdb3/query/)or the [HTTP API](/influxdb3/core/api/v3/) to list tables in a specified database in InfluxDB 3 Core. With InfluxDB 3 Core, tables and measurements are synonymous. This guide shows how to retrieve a list of all tables (measurements) in a database. * [List tables using the influxdb3 CLI](#list-tables-using-the-influxdb3-cli) * [List tables using the HTTP API](#list-tables-using-the-http-api) ## List tables using the influxdb3 CLI Use the `influxdb3 query` command with the `SHOW TABLES` SQL statement: ```sh influxdb3 query \ --database DATABASE_NAME \ --token AUTH_TOKEN \ "SHOW TABLES" ``` Replace the following: * `DATABASE_NAME`: the name of the database to list tables from * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Example output ``` +---------------+---------------+------------+------------+ | table_catalog | table_schema | table_name | table_type | +---------------+---------------+------------+------------+ | public | iox | home | BASE TABLE | | public | iox | sensors | BASE TABLE | +---------------+---------------+------------+------------+ ``` ### Alternative: List tables using InfluxQL You can also use InfluxQL syntax to list measurements (tables): ```sh influxdb3 query \ --language influxql \ --database DATABASE_NAME \ --token AUTH_TOKEN \ "SHOW MEASUREMENTS" ``` ## List tables using the HTTP API To list tables using the HTTP API, send a `GET` request to the `/api/v3/query_sql` endpoint with a `SHOW TABLES` query: ``` GET http://localhost:8181/api/v3/query_sql ``` Include the following in your request: * **Query parameters**: * `db`: Database name * `q`: The SQL query (`SHOW TABLES`) * `format`: Response format (optional, defaults to `json`) * **Headers**: * `Authorization: Bearer` with your authentication token ```bash curl --get "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW TABLES" \ --data-urlencode "format=json" ``` Replace the following: * `DATABASE_NAME`: the name of the database to list tables from * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) ### Example response ```json { "results": [ { "series": [ { "name": "tables", "columns": ["table_catalog", "table_schema", "table_name", "table_type"], "values": [ ["public", "iox", "home", "BASE TABLE"], ["public", "iox", "sensors", "BASE TABLE"] ] } ] } ] } ``` ### Get response in CSV format To get the response in CSV format, set the `format` parameter to `csv`: ```bash curl --get "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW TABLES" \ --data-urlencode "format=csv" ``` #### Related * [influxdb3 query](/influxdb3/core/reference/cli/influxdb3/query/) --- # Manage tokens Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/ Manage tokens to authenticate and authorize access to server actions, resources, and data in your InfluxDB 3 Core instance. ## Provide your token If you start the InfluxDB 3 Core server with authentication enabled (the default), future server actions (CLI commands and HTTP API requests) require a valid token for authorization. The first admin token you create is the *operator* token (named `_admin`), which has full administrative privileges. You can use the operator token to authenticate your requests and manage additional authorization tokens. The mechanism for providing your token depends on the client you use to interact with InfluxDB 3 Core–for example: #### influxdb3 CLI #### When using the `influxdb3` CLI, you can set the `INFLUXDB3_AUTH_TOKEN` environment variable to automatically provide your authorization token to all `influxdb3` commands–for example: ```bash # Export your token as an environment variable export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN # Run an influxdb3 command influxdb3 query \ --database DATABASE_NAME \ "SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'" ``` To specify a token in the command and override the environment variable, pass the `--token` option with your authorization token–for example: ```bash # Include the --token option in your influxdb3 command influxdb3 query \ --token YOUR_AUTH_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'" ``` You can also set the `INFLUXDB3_AUTH_TOKEN` environment variable to automatically provide your authorization token to all `influxdb3` commands. To authenticate directly to the HTTP API, you can include your authorization token in the HTTP Authorization header of your request. The `Authorization: Bearer AUTH_TOKEN` scheme works with all HTTP API endpoints that require authentication. The following examples use `curl` to show to authenticate to the HTTP API. ```bash # Add your token to the HTTP Authorization header curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'" ``` ### Authenticate using v1 and v2 compatibility InfluxDB 3 provides compatibility with InfluxDB v1 and v2 APIs, allowing you to use the same authentication methods as in those versions. With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password scheme. With the InfluxDB v2-compatible `/api/v2/write` endpoint, you can use tokens in the InfluxDB v2 `Authorization: Token` scheme or in the OAuth `Authorization: Bearer` scheme. The following examples show how to authenticate with the InfluxDB v1-compatible and v2-compatible APIs in InfluxDB 3: ```bash # Token scheme with v2 /api/v2/write curl http://localhost:8181/api/v2/write\?bucket\=DATABASE_NAME \ --header "Authorization: Token AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` ```bash # Basic scheme with v1 /write # Username is ignored, but required for the request # Password is your auth token encoded in base64 curl "http://localhost:8181/write?db=DATABASE_NAME" \ --user "any:AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` ```bash # URL auth parameters with v1 /write # Username is ignored, but required for the request curl "http://localhost:8181/write?db=DATABASE_NAME&u=any&p=AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` Replace the following with your values: * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) * `DATABASE_NAME`: the name of the [database](/influxdb3/core/admin/databases) you want to query To use tokens with other clients for InfluxDB 3 Core, see the client-specific documentation: * [InfluxDB 3 Explorer](/influxdb3/explorer/) * [InfluxDB client libraries](/influxdb3/core/reference/client-libraries/) * [Telegraf](/telegraf/v1/) * [Grafana](/influxdb3/core/visualize-data/grafana/) ## [Manage admin tokens](/influxdb3/core/admin/tokens/admin/) Manage admin tokens in your InfluxDB 3 Core instance. An admin token grants access to all actions (CLI commands and API endpoints) for the server. --- # Manage admin tokens Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/ Manage InfluxDB 3 Core admin tokens to authorize server actions, `influxdb3` CLI commands, and HTTP API endpoints for your InfluxDB 3 Core instance. Administrative (*admin*) tokens provide full system access and management capabilities for your InfluxDB 3 Core instance. Admin tokens can create, edit, and delete other admin tokens. InfluxDB 3 Core supports two types of admin tokens: * **Operator token**: A system-generated administrative token with the name `_admin`. * Cannot be edited or deleted * Never expires * Cannot be recreated if lost (future functionality) * Can be regenerated using the CLI * **Named admin token**: User-defined administrative tokens with full admin permissions. * Can be created, edited, and deleted * Support expiration dates * Cannot modify or remove the operator token An InfluxDB 3 Core instance can have one operator token and unlimited named admin tokens. ## [Create an admin token](/influxdb3/core/admin/tokens/admin/create/) Use the [`influxdb3 create token --admin` command](/influxdb3/core/reference/cli/influxdb3/create/token/) or the HTTP API [`/api/v3/configure/token/admin`](/influxdb3/core/api/authentication/#operation/PostCreateAdminToken) endpoint to create an [admin token](/influxdb3/core/admin/tokens/admin/) for your InfluxDB 3 Core instance. An admin token grants access to all actions on the server. ##### CLI ```bash influxdb3 create token --admin ``` #### HTTP API ```bash curl -X POST "http://localhost:8181/api/v3/configure/token/admin" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` [Read more ](/influxdb3/core/admin/tokens/admin/create/) ## [List admin tokens](/influxdb3/core/admin/tokens/admin/list/) Use the `influxdb3` CLI or the `/api/v3` HTTP API to list admin tokens for your InfluxDB 3 Core instance. Use the `influxdb3 show tokens` command to list all tokens or use SQL to query token metadata directly from the `system.tokens` table. ##### CLI ```bash influxdb3 show tokens ``` ##### HTTP API ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT * FROM system.tokens WHERE permissions = '*:*:*'" \ --header 'Accept: application/json' \ --header "Authorization: Bearer AUTH_TOKEN" ``` [Read more ](/influxdb3/core/admin/tokens/admin/list/) ## [Regenerate an admin token](/influxdb3/core/admin/tokens/admin/regenerate/) Use the [`influxdb3 create token --admin` command](/influxdb3/core/reference/cli/influxdb3/create/token/) or the HTTP API [`/api/v3/configure/token/admin/regenerate`](/influxdb3/core/api/authentication/#operation/PostRegenerateAdminToken) endpoint to regenerate an [operator token](/influxdb3/core/admin/tokens/admin/) for your InfluxDB 3 Core instance. Regenerating an operator token deactivates the previous token. ##### CLI ```bash influxdb3 create token --admin \ --regenerate OPERATOR_TOKEN ``` #### HTTP API ```bash curl -X POST "http://localhost:8181/api/v3/configure/token/admin/regenerate" \ --header 'Authorization: Bearer OPERATOR_TOKEN' \ --header 'Accept: application/json' --header 'Content-Type: application/json' ``` [Read more ](/influxdb3/core/admin/tokens/admin/regenerate/) ## [Use a preconfigured admin token](/influxdb3/core/admin/tokens/admin/preconfigured/) Start InfluxDB 3 Core with a preconfigured “offline” admin token file. If no admin tokens already exist, InfluxDB automatically creates an admin token using the provided admin token file. [tokens](/influxdb3/core/tags/tokens/) --- # Create an admin token Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/create/ Use the [`influxdb3 create token --admin` subcommand](/influxdb3/core/reference/cli/influxdb3/create/token/)with the `--name` option or the HTTP API [`/api/v3/configure/token/admin`](/influxdb3/core/api/v3/) endpoint to create an admin token for your InfluxDB 3 Core instance. An admin token grants full access to all actions for your InfluxDB 3 instance and can be referenced by its name. InfluxDB 3 Core supports two types of admin tokens: * **Operator token**: A system-generated administrative token with the name `_admin`. * Cannot be edited or deleted * Never expires * Cannot be recreated if lost (future functionality) * Can be regenerated using the CLI * **Named admin token**: User-defined administrative tokens with full admin permissions. * Can be created, edited, and deleted * Support expiration dates * Cannot modify or remove the operator token An InfluxDB 3 Core instance can have one operator token and unlimited named admin tokens. [Create an operator token](#create-an-operator-token)[Create a named admin token](#create-a-named-admin-token) > [!Note] > #### Store secure tokens in a secret store > > Token strings are returned *only* on token creation. > We recommend storing database tokens in a **secure secret store**. > Anyone with access to the named admin token has full control over your InfluxDB 3 Core instance. > If you lose the named admin token string, you must regenerate the token. ## Create an operator token The first admin token your create for your InfluxDB 3 Core instance is the operator token. #### CLI #### Use the `influxdb3 create token --admin` command without a token name: ```bash influxdb3 create token --admin ``` Use the following endpoint to create an operator token: ``` POST /api/v3/configure/token/admin ``` ```bash curl -X POST "http://localhost:8181/api/v3/configure/token/admin" \ ``` The output contains the token string in plain text. ## Create a named admin token #### CLI #### Use the `influxdb3 create token --admin` command with a token name: ```bash influxdb3 create token --admin --token ADMIN_TOKEN --name "TOKEN_NAME" ``` Replace the following with your values: * `ADMIN_TOKEN`: your existing operator or named admin token * `TOKEN_NAME`: the name you want to assign to the new admin token The output contains the token string in plain text. Use the following endpoint to create a named admin token: ``` POST /api/v3/configure/token/admin ``` ```bash curl -X POST "http://localhost:8181/api/v3/configure/token/admin" \ --header 'Authorization: Bearer ADMIN_TOKEN' \ --json '{ "name": "TOKEN_NAME" }' ``` Replace the following with your values: * `ADMIN_TOKEN`: your existing operator or named admin token * `TOKEN_NAME`: the name you want to assign to the new admin token The response body contains the token string in plain text. *To use the token as the default for later commands, and to persist the token across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable.* --- # List admin tokens Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/list/ Use the `influxdb3` CLI or the `/api/v3` HTTP API to list *admin* tokens for your InfluxDB 3 Core instance. Admin tokens have `permissions=*:*:*`, which allows access to all data and resources in your InfluxDB 3 instance. > [!Note] > Token metadata includes the hashed token string. > InfluxDB 3 does not store the raw token string. > [!Important] > #### Required permissions > > Listing admin tokens requires a valid InfluxDB [admin token](/influxdb3/core/admin/tokens/) . > > > For more information, see how to [provide your token](/influxdb3/core/admin/tokens/#provide-your-token). > > ## List all tokens The `influxdb3 show tokens` CLI command lists all admin and resource tokens in your InfluxDB 3 instance. ```bash influxdb3 show tokens ``` ## Query token metadata To filter tokens and retrieve specific details using SQL, query the `system.tokens` table in the`_internal` system database–for example: ### Filter for admin tokens #### CLI #### ```bash influxdb3 query \ --database _internal \ --format csv \ "SELECT name, permissions FROM system.tokens WHERE permissions = '*:*:*'" ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT name, permissions FROM system.tokens WHERE permissions = '*:*:*'" \ --data-urlencode "format=csv" \ --header 'Accept: text/csv' \ --header "Authorization: Bearer AUTH_TOKEN" ``` ### Filter by date #### CLI #### ```bash influxdb3 query \ --db _internal \ "SELECT name, permissions FROM system.tokens WHERE created_at > '2025-01-01 00:00:00'" ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT name, permissions FROM system.tokens WHERE created_at > '2025-01-01 00:00:00'" \ --header "Accept: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" ``` ## Output formats Use the format option to specify the output format for commands. InfluxDB 3 Core commands used in this guide support the following output formats: * `json` *(default for HTTP API)* * `pretty` *(default for CLI)* * `jsonl` * `csv` * `parquet` *([output to a file](#output-to-a-parquet-file))* #### CLI #### ```bash influxdb3 show tokens \ --format jsonl ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT * FROM system.tokens" \ --data-urlencode "format=csv" \ --header 'Accept: text/csv' \ --header "Authorization: Bearer AUTH_TOKEN" ``` ### Output to a Parquet file [Parquet](https://parquet.apache.org/) is a binary format. To output to a Parquet file using the CLI, include the `--output` option with a destination path for the file. To output a Parquet file using the HTTP API, your client must be able to handle binary data–for example, using cURL’s `--output` option. #### CLI #### ```bash influxdb3 show tokens \ --format parquet \ --output /PATH/TO/FILE.parquet ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT * FROM system.tokens" \ --data-urlencode "format=parquet" \ --header "Accept: application/parquet" \ --header "Authorization: Bearer AUTH_TOKEN" \ --output /PATH/TO/FILE.parquet ``` Replace `/PATH/TO/FILE.parquet`with the path to the file where you want to save the Parquet data. ## Filter the token list Use command-line tools such as `grep` or `jq` to filter the output of the`influxdb3 show tokens` command or the HTTP API response–for example: #### CLI #### ```bash influxdb3 show tokens --format pretty | grep _admin ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT * FROM system.tokens" \ --data-urlencode "format=pretty" \ --header "Accept: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" | grep _admin ``` #### CLI #### ```bash influxdb3 show tokens --format json | jq '.[] | {name: .name, permissions: .permissions}' ``` ```bash curl -G \ "http://localhost:8181/api/v3/query_sql" \ --data-urlencode "db=_internal" \ --data-urlencode "q=SELECT name, created_at FROM system.tokens WHERE permissions = '*:*:*' AND created_at > '2025-01-01 00:00:00'" \ --data-urlencode "format=json" \ --header "Accept: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" | jq '.[] | {name: .name, created_at: .created_at}' ``` --- # Use a preconfigured admin token Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/preconfigured/ Start InfluxDB 3 Core with a preconfigured “offline” admin token file. If no admin tokens already exist, InfluxDB automatically creates an admin token using the provided admin token file. Offline tokens are designed to help with automated deployments. * [Generate an offline admin token file](#generate-an-offline-admin-token-file) * [Offline admin token file schema](#offline-admin-token-file-schema) * [Start InfluxDB with the preconfigured admin token](#start-influxdb-with-the-preconfigured-admin-token) * [Use Docker Compose with preconfigured admin tokens](#use-docker-compose-with-preconfigured-admin-tokens) * [Create an admin token file](#create-an-admin-token-file) * [Configure Docker Compose with secrets](#configure-docker-compose-with-secrets) * [CI/CD setup](#cicd-setup) ## Generate an offline admin token file Use the `influxdb3 create token --admin` command to generate an offline admin token file. Include the following options: \* Required * `--name`: The name of the admin token *(default is `_admin`)**(replace `TOKEN_NAME`)* * `--expiry`: Duration for the token to remain valid, in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)format (for example, `10d` for 10 days or `1y` for 1 year).*(replace `DURATION`)* * \* `--offline` * \* `--output-file`: File path to use for the generated token file*(replace `path/to/tokens.json`)* ```bash influxdb3 create token --admin \ --name TOKEN_NAME \ --expiry DURATION \ --offline \ --output-file path/to/admin-token.json ``` > [!Note] > #### You can write or generate your own admin token file > > The `influxdb3 create token --admin --offline` command makes generating > offline admin token files easy, but it is not required. > You can also write or generate your own admin token files using the[required JSON schema](#offline-admin-token-file-schema). > > ##### Token string security standards > > If writing or generating your own admin token file, ensure that the token > string is sufficiently secure. We recommend the following: > > * Use a cryptographically secure pseudorandom number generator. > * Ensure sufficient length and entropy. Generate and base64-encode a random > string of at least 16 bytes (128 bits). > * Prepend the generated string with `apiv3_` for InfluxDB compatibility. > [!Important] > #### Token file permissions > > Token file permissions should be restricted `0600` to protect the token. ### Offline admin token file schema An offline admin token file is a JSON-formatted file that contains a single object with the following fields: * **token**: The raw token string (must begin with `apiv3_`) * **name**: The token name (default is `_admin`) * **description**: *(Optional)* A description of the token * **expiry\_millis**: *(Optional)* Token expiration time as a millisecond Unix timestamp ```json { "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...", "name": "_admin", "description": "Admin token for InfluxDB 3", "expiry_millis": 1756400061529 } ``` ## Start InfluxDB with the preconfigured admin token When starting InfluxDB 3 Core, include the `--admin-token-file` option with the`influxdb3 serve` command or set the `INFLUXDB3_ADMIN_TOKEN_FILE` environment variable to provide the preconfigured offline admin token file: #### CLI option #### ```bash influxdb3 serve \ # ... \ --admin-token-file path/to/admin-token.json ``` ```bash INFLUXDB3_ADMIN_TOKEN_FILE=path/to/admin-token.json influxdb3 serve \ # ... \ ``` When the server starts, you can use the preconfigured admin token to interact with your InfluxDB 3 Core instance. ## Use Docker Compose with preconfigured admin tokens For containerized deployments, you can use Docker Compose with Docker secrets to securely manage your preconfigured admin token. ### Create an admin token file Create a JSON file with your admin token using the[offline admin token file schema](#offline-admin-token-file-schema): ```json { "token": "apiv3_your_token_here", "name": "admin", "description": "Admin token for automated deployment" } ``` For security, restrict file permissions: ```bash chmod 600 path/to/admin-token.json ``` ### Configure Docker Compose with secrets Use Docker secrets to securely provide the admin token file to your container: ```yaml # compose.yaml services: influxdb3-core: image: influxdb:3-core ports: - 8181:8181 command: - influxdb3 - serve - --node-id=node0 - --object-store=file - --data-dir=/var/lib/influxdb3/data - --admin-token-file=/run/secrets/admin-token secrets: - admin-token volumes: - type: bind source: ~/.influxdb3/data target: /var/lib/influxdb3/data secrets: admin-token: file: path/to/admin-token.json ``` Start the service: ```bash docker compose up -d ``` > [!Important] > #### Docker secrets security benefits > > Docker secrets provide better security than bind mounts for sensitive data: > > * Secrets are stored encrypted in memory > * Not visible in `docker inspect` output > * Not exposed in environment variables or logs > * Follow Docker and Kubernetes security best practices ### CI/CD setup For CI/CD pipelines and automated environments, create the admin token file from environment variables: ```bash # Create token file from CI/CD environment variable echo "{\"token\": \"$INFLUXDB3_ADMIN_TOKEN\", \"name\": \"admin\", \"description\": \"CI/CD admin token\"}" > admin-token.json chmod 600 admin-token.json ``` Then use the file in your Docker Compose configuration as shown above. #### Related * [Configuration options \> admin-token-file](/influxdb3/core/reference/config-options/#admin-token-file) * [influxdb3 create token --admin](/influxdb3/core/reference/cli/influxdb3/create/token/admin/) --- # Regenerate an admin token Source: https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/regenerate/ Use the `influxdb3` CLI or the HTTP API to regenerate the operator (`_admin`) token for your InfluxDB 3 Core instance. Regenerate a token to rotate it as part of your security practices or if you suspect the token has been compromised. Regenerating the operator token deactivates the previous token, stores the SHA512 hash and metadata of the new token, and returns the new token string. ## Prerequisite To regenerate an operator token, you need the current token string. ## Use the CLI or HTTP API to regenerate the operator token > [!Important] > #### Regenerating the operator token > > Regenerating the operator token invalidates the previous token. > Make sure to update any applications or scripts that use the operator token. To regenerate the operator token, use the [`influxdb3 serve create token` command](/influxdb3/core/reference/cli/influxdb3/create/token/) (CLI) or the[`/api/v3/configure/token/admin/regenerate` endpoint](/influxdb3/core/api/v3/configure/token/admin/regenerate) (HTTP API): #### CLI #### Use the `--regenerate` flag with the[`influxdb3 create token --admin`](/influxdb3/core/reference/cli/influxdb3/create/token/) subcommand–for example: ```bash influxdb3 create token --admin \ --regenerate \ --token OPERATOR_TOKEN ``` In your command, replace `OPERATOR_TOKEN`with the current operator (`_admin`) token string. The output contains the new token string and InfluxDB deactivates the previous token string. Use the following HTTP API endpoint: ``` POST /api/v3/configure/token/admin/regenerate ``` In your request, send an `Authorization` header with your current operator token string –for example: ```bash curl -X POST "http://localhost:8181/api/v3/configure/token/admin/regenerate" \ --header "Authorization: Bearer OPERATOR_TOKEN" \ --header "Accept: application/json" ``` In your command, replace `OPERATOR_TOKEN` with the current token string. The response body contains the new operator token string in plain text, and InfluxDB deactivates the previous token string. To use the token as the default for later commands, and to persist the token across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable. ## Lost admin token recovery If you’ve lost your admin token and cannot regenerate it using the standard method, you can use the admin token recovery server: 1. Start InfluxDB 3 Core with the `--admin-token-recovery-http-bind` option: ``` influxdb3 serve --admin-token-recovery-http-bind ``` 2. In a separate terminal, regenerate the admin token using the recovery endpoint: ``` influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182 ``` 3. The recovery server automatically shuts down after successful token regeneration. > [!Warning] > The recovery server provides unauthenticated access to regenerate admin tokens. Only use this option when necessary and ensure the recovery endpoint (by default `127.0.0.1:8182`) is only accessible from trusted networks. ## Important considerations * Regenerating the operator token invalidates the previous token. * If you lose the operator token, use the recovery server method described above. * `--regenerate` only works for the operator token. You can’t use the `--regenerate` flag with the `influxdb3 create token --admin` command to regenerate a named admin token. * Ensure that you update any applications or scripts that use the operator token with the new token string. * Always store your operator token securely and consider implementing proper secret management practices. --- # Upgrade to InfluxDB 3 Enterprise Source: https://docs.influxdata.com/influxdb3/core/admin/upgrade-to-enterprise/ Upgrade from InfluxDB 3 Core to InfluxDB 3 Enterprise. Your existing data and plugins are compatible with Enterprise–no data migration is required. * [Before you begin](#before-you-begin) * [Upgrade to Enterprise](#upgrade-to-enterprise) > [!Warning] > #### Downgrading is not supported > > After upgrading to InfluxDB 3 Enterprise, you cannot downgrade back to > InfluxDB 3 Core. Enterprise makes catalog changes that are incompatible with Core. > To revert to Core, you must restore from a backup taken before the upgrade. > > *Before upgrading, back up your data directory.* ## Before you begin 1. **Back up your data**: Create a backup of your InfluxDB 3 Core data directory before upgrading. For more information, see [Back up and restore data](/influxdb3/core/admin/backup-restore/). 2. **Note your current configuration**: Record your Core startup options, including `--data-dir`, `--object-store`, `--plugin-dir`, and any other configuration. You’ll use the same data directory with Enterprise. For a complete list of configuration options, see the[`influxdb3 serve` CLI reference](/influxdb3/enterprise/reference/cli/influxdb3/serve/). If you use a cloud object store (S3, Azure, or Google Cloud Storage), see[Configure object storage](/influxdb3/enterprise/admin/object-storage/). 3. **Choose a license type**: Decide which InfluxDB 3 Enterprise license you need: * **Trial**: 30-day full-featured trial * **At-Home**: Free for hobbyist use (2 CPU limit, single-node only) * **Commercial**: For production and commercial use For more information about licenses, see [Manage your license](/influxdb3/enterprise/admin/license/). ## Upgrade to Enterprise Choose your installation method: #### Quick install (Linux/macOS) #### ### Stop InfluxDB 3 Core Stop the running Core process: ```bash # If running in foreground, press Ctrl+C # If running in background, find and stop the process pkill -f "influxdb3 serve" ``` ### Install InfluxDB 3 Enterprise Run the quick install script for Enterprise: ```bash curl -O https://www.influxdata.com/d/install_influxdb3.sh \ && sh install_influxdb3.sh enterprise ``` ### Start InfluxDB 3 Enterprise Start Enterprise with your existing data directory. Enterprise requires a`--cluster-id` option that Core doesn’t use: ```bash influxdb3 serve \ --node-id NODE_ID \ --cluster-id CLUSTER_ID \ --object-store file \ --data-dir DATA_DIR \ --license-email EMAIL_ADDRESS ``` Replace the following: * `NODE_ID`: Your existing node identifier from Core * `CLUSTER_ID`: A new cluster identifier for Enterprise–for example, `cluster0` * `DATA_DIR`: The same data directory you used with Core * `EMAIL_ADDRESS`: Your email address for license activation When prompted, select your license type (`trial` or `home`), then verify your email address. ### Verify the upgrade After starting Enterprise, verify the upgrade was successful: ```bash # Check the version influxdb3 --version # Verify your license influxdb3 show license --host http://localhost:8181 ``` Query your existing data to confirm it’s accessible. ### Stop the Core container ```bash docker stop CORE_CONTAINER_NAME ``` Replace `CORE_CONTAINER_NAME` with the name of your InfluxDB 3 Core container. ### Pull the Enterprise image ```bash docker pull influxdb:3-enterprise ``` ### Start InfluxDB 3 Enterprise Start Enterprise using the same data volume. Enterprise requires a `--cluster-id`option and license configuration: ```bash docker run -d \ --name influxdb3-enterprise \ -p 8181:8181 \ -e INFLUXDB3_LICENSE_EMAIL=EMAIL_ADDRESS \ -v DATA_VOLUME:/var/lib/influxdb3/data \ -v PLUGIN_VOLUME:/var/lib/influxdb3/plugins \ influxdb:3-enterprise \ influxdb3 serve \ --node-id NODE_ID \ --cluster-id CLUSTER_ID \ --object-store file \ --data-dir /var/lib/influxdb3/data ``` Replace the following: * `EMAIL_ADDRESS`: Your email address for license activation * `DATA_VOLUME`: The same data volume you used with Core * `PLUGIN_VOLUME`: The same plugin volume you used with Core * `NODE_ID`: Your existing node identifier from Core * `CLUSTER_ID`: A new cluster identifier for Enterprise–for example, `cluster0` > [!Important] > #### License activation in Docker > > You must provide `INFLUXDB3_LICENSE_EMAIL` as an environment > variable because the interactive license prompt doesn’t work in containers. > After starting the container, check your email and click the verification link. [](#using-docker-compose) Using Docker Compose Update your `compose.yaml` to use the Enterprise image: ```yaml services: influxdb3: image: influxdb:3-enterprise container_name: influxdb3-enterprise ports: - 8181:8181 environment: - INFLUXDB3_LICENSE_EMAIL=${EMAIL_ADDRESS} command: - influxdb3 - serve - --node-id=NODE_ID - --cluster-id=CLUSTER_ID - --object-store=file - --data-dir=/var/lib/influxdb3/data volumes: # Use the same paths as Core - type: bind source: DATA_VOLUME target: /var/lib/influxdb3/data - type: bind source: PLUGIN_VOLUME target: /var/lib/influxdb3/plugins ``` Replace the following: * `EMAIL_ADDRESS`: Your email address for license activation (or a variable from your Compose `.env` file) * `NODE_ID`: Your existing node identifier from Core * `CLUSTER_ID`: A new cluster identifier for Enterprise–for example, `cluster0` * `DATA_VOLUME`: The same host data path you used with Core–for example, `~/.influxdb3/data` * `PLUGIN_VOLUME`: The same host plugin path you used with Core–for example, `~/.influxdb3/plugins` Then run: ```bash docker compose down docker compose up -d ``` ### Verify the upgrade After starting Enterprise, verify the upgrade was successful: #### Docker #### ```bash # Check the version docker exec influxdb3-enterprise \ influxdb3 --version # Verify your license docker exec influxdb3-enterprise \ influxdb3 show license --host http://localhost:8181 ``` ```bash # Check the version docker compose exec influxdb3-enterprise \ influxdb3 --version # Verify your license docker compose exec influxdb3-enterprise \ influxdb3 show license --host http://localhost:8181 ``` Query your existing data to confirm it’s accessible. ### Stop InfluxDB 3 Core ```bash sudo systemctl stop influxdb3-core ``` ### Install InfluxDB 3 Enterprise First, remove the Core package (this doesn’t remove your data or configuration): [](#deb-based-systems-debian-ubuntu) DEB-based systems (Debian, Ubuntu) ```bash # Debian/Ubuntu sudo apt-get remove influxdb3-core # doesn't remove /var/lib/influxdb3 or /etc/influxdb3 sudo apt-get update && sudo apt-get install influxdb3-enterprise ``` [](#rpm-based-systems-rhel-centos-fedora) RPM-based systems (RHEL, CentOS, Fedora) ```bash # RHEL/CentOS/Fedora sudo yum remove influxdb3-core # doesn't remove /var/lib/influxdb3 or /etc/influxdb3 sudo yum install influxdb3-enterprise ``` ### Configure InfluxDB 3 Enterprise The Enterprise package installs a self-documenting configuration file at`/etc/influxdb3/influxdb3-enterprise.conf`. Merge your Core settings into this file rather than overwriting it. 1. View the settings you configured in Core: ``` # Show uncommented (active) settings from Core configuration sudo grep -E '^ *[^#]' /etc/influxdb3/influxdb3-core.conf ``` 2. Merge Core settings into the Enterprise configuration: ``` # Back up the original Enterprise configuration sudo cp /etc/influxdb3/influxdb3-enterprise.conf \ /etc/influxdb3/influxdb3-enterprise.conf.orig # Merge settings from Core into Enterprise config sudo grep -E '^ *[^#]' /etc/influxdb3/influxdb3-core.conf | while IFS= read -r line; do key=$(echo "$line" | sed 's/=.*/=/') if sudo grep -qE "^ *${key}" /etc/influxdb3/influxdb3-enterprise.conf; then # Update existing uncommented line sudo sed -i "s|^ *${key}.*|${line}|" /etc/influxdb3/influxdb3-enterprise.conf else # Replace commented line with active setting sudo sed -i "s|^#${key}.*|${line}|" /etc/influxdb3/influxdb3-enterprise.conf fi done ``` 3. Add your license email to the Enterprise configuration: ``` sudo sed -i 's|^#license-email.*|license-email = "EMAIL_ADDRESS"|' \ /etc/influxdb3/influxdb3-enterprise.conf ``` Replace `EMAIL_ADDRESS` with your email address for license activation. 4. Verify the merged configuration: ``` sudo grep -E '^ *[^#]' /etc/influxdb3/influxdb3-enterprise.conf ``` The output should include your Core settings plus the license email and cluster ID–for example: ``` node-id = "primary-node" object-store = "file" data-dir = "/var/lib/influxdb3/data" plugin-dir = "/var/lib/influxdb3/plugins" cluster-id = "primary-cluster" license-email = "you@example.com" ``` The DEB/RPM packages use `primary-node` and `primary-cluster` as defaults, matching the behavior of running `influxdb3 serve` without `--node-id` or `--cluster-id`. ### Start InfluxDB 3 Enterprise ```bash sudo systemctl start influxdb3-enterprise ``` Check the logs to verify the server started successfully: ```bash journalctl --unit influxdb3-enterprise -f ``` After starting, check your email and click the verification link to activate your license. ### Verify the upgrade After starting Enterprise, verify the upgrade was successful: ```bash # Check the version influxdb3 --version # Verify your license influxdb3 show license --host http://localhost:8181 ``` Query your existing data to confirm it’s accessible. #### Related * [Back up and restore data](/influxdb3/core/admin/backup-restore/) * [Get started with InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/) * [Manage your InfluxDB 3 Enterprise license](/influxdb3/enterprise/admin/license/) [upgrade](/influxdb3/core/tags/upgrade/)[enterprise](/influxdb3/core/tags/enterprise/)[migration](/influxdb3/core/tags/migration/) --- # Upgrade InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/admin/upgrade/ Upgrade your InfluxDB 3 Core version. * [Before you upgrade](#before-you-upgrade) * [Upgrade an InfluxDB 3 instance](#upgrade-an-influxdb-3-instance) ## Before you upgrade Before upgrading your InfluxDB 3 Core instance, review the [release notes](/influxdb3/core/release-notes/) for compatibility requirements and then plan your upgrade strategy. > [!Important] > #### Upgrading to InfluxDB 3.10 is a one-way migration > > The first time you start InfluxDB 3.10, it automatically upgrades the on-disk > catalog format from v2 to v3. After migration, 3.9.x and older > binaries are unable to read the new catalog, and fail to start on the same > cluster data. > > Before upgrading, back up `{prefix}/catalogs/` and `{prefix}/_catalog_checkpoint`. > Restoring these objects is the only way to roll back to 3.9.x. ### Verify your current version Before upgrading, verify the InfluxDB 3 Core version running on each node. #### CLI #### ```bash influxdb3 --version ``` ```bash docker exec CONTAINER_NAME influxdb3 --version ``` Replace the following: * `CONTAINER_NAME`: The name of your InfluxDB 3 Core container The command returns version information similar to the following: ``` influxdb3 3.11.2 ``` > [!Tip] > ### Verify your InfluxDB version > > Before and after upgrading, verify the InfluxDB 3 Core version running on your instance. ## Upgrade an InfluxDB 3 instance #### Install script #### ```bash curl -O https://www.influxdata.com/d/install_influxdb3.sh \ && sh install_influxdb3.sh core ``` ```bash # 1. Download the new version curl -L https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_linux_amd64.tar.gz \ -o influxdb3-core.tar.gz # 2. Extract the archive tar xvzf influxdb3-core.tar.gz # 3. Stop the service sudo systemctl stop influxdb3-core # 4. Install the new binary sudo cp influxdb3 /usr/local/bin/ # 5. Start the service sudo systemctl start influxdb3-core ``` ```bash docker stop CONTAINER_NAME docker pull influxdb:core docker start CONTAINER_NAME ``` Replace the following: * `CONTAINER_NAME`: The name of your InfluxDB 3 Core container ```bash docker compose down docker compose pull docker compose up -d ``` ```powershell # Download the latest Windows binary Invoke-WebRequest ` -Uri "https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2-windows_amd64.zip" ` -OutFile "influxdb3-core.zip" # Extract the binary Expand-Archive -Path influxdb3-core.zip -DestinationPath . -Force # Stop the service, replace the binary, and start the service Stop-Service influxdb3 Copy-Item -Path "influxdb3.exe" -Destination "C:\Program Files\InfluxData\influxdb3\" -Force Start-Service influxdb3 ``` #### Related * [Back up and restore data](/influxdb3/core/admin/backup-restore/) * [Install InfluxDB 3 Core](/influxdb3/core/install/) * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) * [Manage databases](/influxdb3/core/admin/databases/) [upgrade](/influxdb3/core/tags/upgrade/)[administration](/influxdb3/core/tags/administration/)[catalog](/influxdb3/core/tags/catalog/) --- # InfluxDB HTTP API Source: https://docs.influxdata.com/influxdb3/core/api/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Use the InfluxDB 3 Core HTTP API to write data, query data, and manage databases, tables, and tokens. ### [Quick start](/influxdb3/core/api/quick-start/) Authenticate, write, and query with the API: ### [Authentication](/influxdb3/core/api/authentication/) Use one of the following schemes to authenticate to the InfluxDB 3 Core API: ### [Headers and parameters](/influxdb3/core/api/headers-and-parameters/) Most InfluxDB API endpoints require parameters in the request–for example, specifying the database to use. ### [Migrate from InfluxDB v1 or v2](/influxdb3/core/api/migrate-from-influxdb-v1-or-v2/) Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3 Core. ### [Auth token](/influxdb3/core/api/auth-token/) Create and manage tokens used for authenticating and authorizing access to InfluxDB 3 Core resources. ### [Cache distinct values](/influxdb3/core/api/cache-distinct-values/) The Distinct Value Cache (DVC) lets you cache distinct values of one or more columns in a table, improving the performance of queries that return distinct tag and field values. ### [Cache last value](/influxdb3/core/api/cache-last-value/) The Last Value Cache (LVC) lets you cache the most recent values for specific fields in a table, improving the performance of queries that return the most recent value of a field for specific series… ### [Database](/influxdb3/core/api/database/) Create, list, and delete databases in InfluxDB 3 Core. ### [Processing engine](/influxdb3/core/api/processing-engine/) Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins. ### [Query data](/influxdb3/core/api/query-data/) Query data stored in InfluxDB 3 Core using SQL or InfluxQL. ### [Server information](/influxdb3/core/api/server-information/) Retrieve server metrics, health status, and version information for InfluxDB 3 Core. ### [Table](/influxdb3/core/api/table/) Manage table schemas in an InfluxDB 3 Core database. ### [Write data](/influxdb3/core/api/write-data/) Write data to InfluxDB 3 Core using line protocol format. --- # All endpoints Source: https://docs.influxdata.com/influxdb3/core/api/all-endpoints/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) All InfluxDB 3 Core API endpoints, sorted by path. ## v3 API [DELETE`/api/v3/configure/database`Delete a database](/influxdb3/core/api/database/#operation/DeleteConfigureDatabase)[GET`/api/v3/configure/database`List databases](/influxdb3/core/api/database/#operation/GetConfigureDatabase)[POST`/api/v3/configure/database`Create a database](/influxdb3/core/api/database/#operation/PostConfigureDatabase)[PUT`/api/v3/configure/database`Update a database](/influxdb3/core/api/database/#operation/PutConfigureDatabase)[DELETE`/api/v3/configure/database/retention_period`Remove database retention period](/influxdb3/core/api/database/#operation/DeleteDatabaseRetentionPeriod)[DELETE`/api/v3/configure/distinct_cache`Delete distinct cache](/influxdb3/core/api/cache-distinct-values/#operation/DeleteConfigureDistinctCache)[DELETE`/api/v3/configure/distinct_cache`Delete distinct cache](/influxdb3/core/api/table/#operation/DeleteConfigureDistinctCache)[POST`/api/v3/configure/distinct_cache`Create distinct cache](/influxdb3/core/api/cache-distinct-values/#operation/PostConfigureDistinctCache)[POST`/api/v3/configure/distinct_cache`Create distinct cache](/influxdb3/core/api/table/#operation/PostConfigureDistinctCache)[DELETE`/api/v3/configure/last_cache`Delete last cache](/influxdb3/core/api/cache-last-value/#operation/DeleteConfigureLastCache)[DELETE`/api/v3/configure/last_cache`Delete last cache](/influxdb3/core/api/table/#operation/DeleteConfigureLastCache)[POST`/api/v3/configure/last_cache`Create last cache](/influxdb3/core/api/cache-last-value/#operation/PostConfigureLastCache)[POST`/api/v3/configure/last_cache`Create last cache](/influxdb3/core/api/table/#operation/PostConfigureLastCache)[POST`/api/v3/configure/plugin_environment/install_packages`Install plugin packages](/influxdb3/core/api/processing-engine/#operation/PostInstallPluginPackages)[POST`/api/v3/configure/plugin_environment/install_requirements`Install plugin requirements](/influxdb3/core/api/processing-engine/#operation/PostInstallPluginRequirements)[DELETE`/api/v3/configure/processing_engine_trigger`Delete processing engine trigger](/influxdb3/core/api/processing-engine/#operation/DeleteConfigureProcessingEngineTrigger)[POST`/api/v3/configure/processing_engine_trigger`Create processing engine trigger](/influxdb3/core/api/processing-engine/#operation/PostConfigureProcessingEngineTrigger)[POST`/api/v3/configure/processing_engine_trigger/disable`Disable processing engine trigger](/influxdb3/core/api/processing-engine/#operation/PostDisableProcessingEngineTrigger)[POST`/api/v3/configure/processing_engine_trigger/enable`Enable processing engine trigger](/influxdb3/core/api/processing-engine/#operation/PostEnableProcessingEngineTrigger)[DELETE`/api/v3/configure/table`Delete a table](/influxdb3/core/api/table/#operation/DeleteConfigureTable)[POST`/api/v3/configure/table`Create a table](/influxdb3/core/api/table/#operation/PostConfigureTable)[DELETE`/api/v3/configure/token`Delete token](/influxdb3/core/api/auth-token/#operation/DeleteToken)[POST`/api/v3/configure/token/admin`Create admin token](/influxdb3/core/api/auth-token/#operation/PostCreateAdminToken)[POST`/api/v3/configure/token/admin/regenerate`Regenerate admin token](/influxdb3/core/api/auth-token/#operation/PostRegenerateAdminToken)[POST`/api/v3/configure/token/named_admin`Create named admin token](/influxdb3/core/api/auth-token/#operation/PostCreateNamedAdminToken)[GET`/api/v3/engine/{request_path}`On Request processing engine plugin request](/influxdb3/core/api/processing-engine/#operation/GetProcessingEnginePluginRequest)[POST`/api/v3/engine/{request_path}`On Request processing engine plugin request](/influxdb3/core/api/processing-engine/#operation/PostProcessingEnginePluginRequest)[POST`/api/v3/plugin_test/schedule`Test scheduling plugin](/influxdb3/core/api/processing-engine/#operation/PostTestSchedulingPlugin)[POST`/api/v3/plugin_test/wal`Test WAL plugin](/influxdb3/core/api/processing-engine/#operation/PostTestWALPlugin)[PUT`/api/v3/plugins/directory`Update a multi-file plugin directory](/influxdb3/core/api/processing-engine/#operation/PutPluginDirectory)[POST`/api/v3/plugins/files`Create a plugin file](/influxdb3/core/api/processing-engine/#operation/PostPluginsFiles)[PUT`/api/v3/plugins/files`Update a plugin file](/influxdb3/core/api/processing-engine/#operation/PutPluginFile)[GET`/api/v3/query_influxql`Execute InfluxQL query](/influxdb3/core/api/query-data/#operation/GetExecuteInfluxQLQuery)[POST`/api/v3/query_influxql`Execute InfluxQL query](/influxdb3/core/api/query-data/#operation/PostExecuteQueryInfluxQL)[GET`/api/v3/query_sql`Execute SQL query](/influxdb3/core/api/query-data/#operation/GetExecuteQuerySQL)[POST`/api/v3/query_sql`Execute SQL query](/influxdb3/core/api/query-data/#operation/PostExecuteQuerySQL)[POST`/api/v3/write_lp`Write line protocol](/influxdb3/core/api/write-data/#operation/PostWriteLP) ## v2-compatible API [POST`/api/v2/write`Write line protocol (v2-compatible)](/influxdb3/core/api/write-data/#operation/PostV2Write) ## v1-compatible API [GET`/api/v1/health`Health check (v1)](/influxdb3/core/api/server-information/#operation/GetHealthV1)[GET`/health`Health check](/influxdb3/core/api/server-information/#operation/GetHealth)[GET`/metrics`Metrics](/influxdb3/core/api/server-information/#operation/GetMetrics)[GET`/ping`Ping the server](/influxdb3/core/api/server-information/#operation/GetPing)[POST`/ping`Ping the server](/influxdb3/core/api/server-information/#operation/ping)[GET`/query`Execute InfluxQL query (v1-compatible)](/influxdb3/core/api/query-data/#operation/GetV1ExecuteQuery)[POST`/query`Execute InfluxQL query (v1-compatible)](/influxdb3/core/api/query-data/#operation/PostExecuteV1Query)[POST`/write`Write line protocol (v1-compatible)](/influxdb3/core/api/write-data/#operation/PostV1Write) --- # Auth token Source: https://docs.influxdata.com/influxdb3/core/api/auth-token/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Create and manage tokens used for authenticating and authorizing access to InfluxDB 3 Core resources. DELETE`/api/v3/configure/token` ### Delete token Deletes a token. #### Parameters ##### Query parameters `token_name`requiredstring The name of the token to delete. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/token?token_name=TOKEN_NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The token has been deleted. 401Unauthorized access. `data`object `error`string 404Token not found. POST`/api/v3/configure/token/admin` ### Create admin token Creates an admin token. An admin token is a special type of token that has full access to all resources in the system. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/token/admin" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 201Success. The admin token has been created. The response body contains the token string and metadata. `created_at`string \ `expiry`string \ `hash`string `id`integer `name`string `token`string Example request body ```json { "created_at": "2025-04-18T14:02:45.331Z", "expiry": null, "hash": "00xx0Xx0xx00XX0x0", "id": 0, "name": "_admin", "token": "apiv3_00xx0Xx0xx00XX0x0" } ``` 401Unauthorized access. `data`object `error`string POST`/api/v3/configure/token/admin/regenerate` ### Regenerate admin token Regenerates an admin token and revokes the previous token with the same name. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/token/admin/regenerate" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 201Success. The admin token has been regenerated. `created_at`string \ `expiry`string \ `hash`string `id`integer `name`string `token`string Example request body ```json { "created_at": "2025-04-18T14:02:45.331Z", "expiry": null, "hash": "00xx0Xx0xx00XX0x0", "id": 0, "name": "_admin", "token": "apiv3_00xx0Xx0xx00XX0x0" } ``` 401Unauthorized access. `data`object `error`string POST`/api/v3/configure/token/named_admin` ### Create named admin token Creates a named admin token. A named admin token is a special type of admin token with a custom name for identification and management. #### Request bodyrequired Content-Type:`application/json` `expiry_secs`integer Optional expiration time in seconds. If not provided, the token does not expire. `token_name`requiredstring The name for the admin token. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/token/named_admin" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "expiry_secs": 0, "token_name": "TOKEN_NAME" }' ``` #### Responses 201Success. The named admin token has been created. The response body contains the token string and metadata. `created_at`string \ `expiry`string \ `hash`string `id`integer `name`string `token`string Example request body ```json { "created_at": "2025-04-18T14:02:45.331Z", "expiry": null, "hash": "00xx0Xx0xx00XX0x0", "id": 0, "name": "_admin", "token": "apiv3_00xx0Xx0xx00XX0x0" } ``` 401Unauthorized access. `data`object `error`string 409A token with this name already exists. #### Related * [Manage tokens](/influxdb3/core/admin/tokens/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Authentication Source: https://docs.influxdata.com/influxdb3/core/api/authentication/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Use one of the following schemes to authenticate to the InfluxDB 3 Core API: * Token authentication * Bearer authentication * Basic authentication * Querystring authentication ## Basic Authentication Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1ExecuteQuery) endpoints in InfluxDB 3. When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token and ignores the `username` part of the decoded credential. ### Syntax ```http Authorization: Basic ``` ### Example ```bash curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ --user "":"AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: * **`DATABASE_NAME`**: your InfluxDB 3 Core database * **`AUTH_TOKEN`**: an admin token or database token authorized for the database ## Bearer Authentication Use the OAuth Bearer authentication scheme to provide an authorization token to InfluxDB 3. Bearer authentication works with all endpoints. In your API requests, send an `Authorization` header. For the header value, provide the word `Bearer` followed by a space and a database token. ### Syntax ```http Authorization: Bearer AUTH_TOKEN ``` ### Example ```bash curl http://localhost:8181/api/v3/query_influxql \ --header "Authorization: Bearer AUTH_TOKEN" ``` ## Query String Authentication Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1ExecuteQuery) endpoints. When authenticating requests, InfluxDB 3 checks that the `p` (*password*) query parameter is an authorized token and ignores the `u` (*username*) query parameter. ### Syntax ```http https://localhost:8181/query/?[u=any]&p=AUTH_TOKEN https://localhost:8181/write/?[u=any]&p=AUTH_TOKEN ``` ### Examples ```bash curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: * **`DATABASE_NAME`**: your InfluxDB 3 Core database * **`AUTH_TOKEN`**: an admin token or database token authorized for the database ```bash ####################################### # Use an InfluxDB 1.x compatible username and password # to query the InfluxDB v1 HTTP API ####################################### # Use authentication query parameters: # ?p=AUTH_TOKEN ####################################### curl --get "http://localhost:8181/query" \ --data-urlencode "p=AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: * **`DATABASE_NAME`**: the database to query * **`AUTH_TOKEN`**: a database token with sufficient permissions to the database ## Token Authentication Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and a database token. The word `Token` is case-sensitive. ### Syntax ```http Authorization: Token AUTH_TOKEN ``` ### Example ```sh ######################################################## # Use the Token authentication scheme with /api/v2/write # to write data. ######################################################## curl --request post "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ --header "Authorization: Token AUTH_TOKEN" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` #### Related * [Authenticate v1 API requests](/influxdb3/core/guides/api-compatibility/v1/) * [Manage tokens](/influxdb3/core/admin/tokens/) --- # Cache distinct values Source: https://docs.influxdata.com/influxdb3/core/api/cache-distinct-values/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) The Distinct Value Cache (DVC) lets you cache distinct values of one or more columns in a table, improving the performance of queries that return distinct tag and field values. The DVC is an in-memory cache that stores distinct values for specific columns in a table. When you create a DVC, you can specify what columns’ distinct values to cache, the maximum number of distinct value combinations to cache, and the maximum age of cached values. A DVC is associated with a table, which can have multiple DVCs. POST`/api/v3/configure/distinct_cache` ### Create distinct cache Creates a distinct cache for a table. #### Request bodyrequired Content-Type:`application/json` `columns`requiredstring[] `db`requiredstring `max_age`integer Optional maximum age in seconds. `max_cardinality`integer Optional maximum cardinality. `name`string Optional cache name. `table`requiredstring Example request body ```json { "columns": [ "tag1", "tag2" ], "db": "mydb", "max_age": 3600, "max_cardinality": 1000, "table": "mytable" } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/distinct_cache" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"columns":["tag1","tag2"],"db":"mydb","max_age":3600,"max_cardinality":1000,"table":"mytable"}' ``` #### Responses 201Success. The distinct cache has been created. 400 Bad request. The server responds with status `400` if the request would overwrite an existing cache with a different configuration. 409Conflict. A distinct cache with this configuration already exists. DELETE`/api/v3/configure/distinct_cache` ### Delete distinct cache Deletes a distinct cache. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `table`requiredstring The name of the table containing the distinct cache. `name`requiredstring The name of the distinct cache to delete. #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/distinct_cache?db=DB&table=TABLE&name=NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The distinct cache has been deleted. 400Bad request. 401Unauthorized access. `data`object `error`string 404Cache not found. #### Related * [Manage the Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Cache last value Source: https://docs.influxdata.com/influxdb3/core/api/cache-last-value/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) The Last Value Cache (LVC) lets you cache the most recent values for specific fields in a table, improving the performance of queries that return the most recent value of a field for specific series or the last N values of a field. The LVC is an in-memory cache that stores the last N number of values for specific fields of series in a table. When you create an LVC, you can specify what fields to cache, what tags to use to identify each series, and the number of values to cache for each unique series. An LVC is associated with a table, which can have multiple LVCs. POST`/api/v3/configure/last_cache` ### Create last cache Creates a last cache for a table. #### Request bodyrequired Content-Type:`application/json` `count`integer Optional count. `db`requiredstring `key_columns`string[] Optional list of key columns. `name`string Optional cache name. `table`requiredstring `ttl`integer Optional time-to-live in seconds. `value_columns`string[] Optional list of value columns. Example request body ```json { "count": 100, "db": "mydb", "key_columns": [ "tag1" ], "table": "mytable", "ttl": 3600, "value_columns": [ "field1" ] } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/last_cache" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"count":100,"db":"mydb","key_columns":["tag1"],"table":"mytable","ttl":3600,"value_columns":["field1"]}' ``` #### Responses 201Success. Last cache created. 400Bad request. A cache with this name already exists or the request is malformed. 401Unauthorized access. `data`object `error`string 404Cache not found. DELETE`/api/v3/configure/last_cache` ### Delete last cache Deletes a last cache. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `table`requiredstring The name of the table containing the last cache. `name`requiredstring The name of the last cache to delete. #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/last_cache?db=DB&table=TABLE&name=NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The last cache has been deleted. 400Bad request. 401Unauthorized access. `data`object `error`string 404Cache not found. #### Related * [Manage the Last Value Cache](/influxdb3/core/admin/last-value-cache/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Database Source: https://docs.influxdata.com/influxdb3/core/api/database/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Create, list, and delete databases in InfluxDB 3 Core. GET`/api/v3/configure/database` ### List databases Retrieves a list of databases. #### Parameters ##### Query parameters `format`requiredstring `show_deleted`boolean Include soft-deleted databases in the response. By default, only active databases are returned. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/configure/database?format=FORMAT" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of databases. `databases`string[] 400Bad request. 401Unauthorized access. `data`object `error`string 404Database not found. POST`/api/v3/configure/database` ### Create a database Creates a new database in the system. #### Request bodyrequired Content-Type:`application/json` `db`requiredstring The database name. Database names cannot contain underscores (\_). Names must start and end with alphanumeric characters and can contain hyphens (-) in the middle. `retention_period`string The retention period for the database. Specifies how long data should be retained. Use duration format (for example, “1d”, “1h”, “30m”, “7d”). Example:`"7d"` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "db": "DB", "retention_period": "7d" }' ``` #### Responses 200Success. Database created. 400Bad request. 401Unauthorized access. `data`object `error`string 409Database already exists. PUT`/api/v3/configure/database` ### Update a database Updates database configuration, such as retention period. #### Request bodyrequired Content-Type:`application/json` `retention_period`string The retention period for the database. Specifies how long data should be retained. Use duration format (for example, “1d”, “1h”, “30m”, “7d”). Example:`"7d"` Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "retention_period": "7d" }' ``` #### Responses 200Success. The database has been updated. 400Bad request. 401Unauthorized access. `data`object `error`string 404Database not found. DELETE`/api/v3/configure/database` ### Delete a database Soft deletes a database. The database is scheduled for deletion and unavailable for querying. Use the `hard_delete_at` parameter to schedule a hard deletion. Use the `data_only` parameter to delete data while preserving the database schema and resources. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `data_only`boolean Delete only data while preserving the database schema and all associated resources (tokens, triggers, last value caches, distinct value caches, processing engine configurations). When `false` (default), the entire database is deleted. `remove_tables`boolean Used with `data_only=true` to remove table resources (caches) while preserving database-level resources (tokens, triggers, processing engine configurations). Has no effect when `data_only=false`. `hard_delete_at`string \ Schedule the database for hard deletion at the specified time. If not provided, the database will be soft deleted. Use ISO 8601 date-time format (for example, “2025-12-31T23:59:59Z”). #### Deleting a database cannot be undone Deleting a database is a destructive action. Once a database is deleted, data stored in that database cannot be recovered. Also accepts special string values: * `now` — hard delete immediately * `never` — soft delete only (default behavior) * `default` — use the system default hard deletion time Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/database?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Database deleted. 401Unauthorized access. `data`object `error`string 404Database not found. DELETE`/api/v3/configure/database/retention_period` ### Remove database retention period Removes the retention period from a database, setting it to infinite retention. #### Parameters ##### Query parameters `db`requiredstring The name of the database. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/database/retention_period?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The database retention period has been removed. 401Unauthorized access. `data`object `error`string 404Database not found. #### Related * [Manage databases](/influxdb3/core/admin/databases/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Headers and parameters Source: https://docs.influxdata.com/influxdb3/core/api/headers-and-parameters/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Most InfluxDB API endpoints require parameters in the request–for example, specifying the database to use. ### Common parameters The following table shows common parameters used by many InfluxDB API endpoints. Many endpoints may require other parameters in the query string or in the request body that perform functions specific to those endpoints. |Query parameter|Value type| Description | |---------------|----------|-----------------| | `db` | string |The database name| InfluxDB HTTP API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB API endpoints. Some endpoints may use other headers that perform functions more specific to those endpoints–for example, the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body. | Header |Value type| Description | |----------------|----------|------------------------------------------------| | `Accept` | string |The content type that the client can understand.| |`Authorization` | string | The authorization scheme and credential. | |`Content-Length`| integer | The size of the entity-body, in bytes. | | `Content-Type` | string | The format of the data in the request body. | | Query parameter | Value type | Description | | --- | --- | --- | | Query parameter | Value type | Description | | db | string | The database name | | Header | Value type | Description | | --- | --- | --- | | Header | Value type | Description | | Accept | string | The content type that the client can understand. | | Authorization | string | The authorization scheme and credential. | | Content-Length | integer | The size of the entity-body, in bytes. | | Content-Type | string | The format of the data in the request body. | --- # Migrate from InfluxDB v1 or v2 Source: https://docs.influxdata.com/influxdb3/core/api/migrate-from-influxdb-v1-or-v2/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3 Core. InfluxDB 3 provides compatibility endpoints that work with InfluxDB 1.x and 2.x client libraries and tools. Operations marked with v1 or v2 badges are compatible with the respective InfluxDB version. ### Migration guides * [Migrate from InfluxDB v1 or v2](/influxdb3/core/get-started/migrate-from-influxdb-v1-v2/) - For users migrating from InfluxDB 1.x, 2.x, or Cloud * [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) - v1 and v2 write endpoints * [Use the v1 HTTP query API](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) - InfluxQL queries via HTTP --- # Processing engine Source: https://docs.influxdata.com/influxdb3/core/api/processing-engine/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins. InfluxDB 3 Core provides the InfluxDB 3 processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database. Use Processing engine plugins and triggers to run code and perform tasks for different database events. POST`/api/v3/configure/plugin_environment/install_packages` ### Install plugin packages Installs the specified Python packages into the processing engine plugin environment. This endpoint is synchronous and blocks until the packages are installed. #### Parameters ##### Header parameters `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request bodyrequired Content-Type:`application/json` `packages`requiredstring[] A list of Python package names to install. Can include version specifiers (for example, “scipy==1.9.0”). Example:`["influxdb3-python","scipy","pandas==1.5.0","requests"]` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/plugin_environment/install_packages" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "packages": [ "influxdb3-python", "scipy", "pandas==1.5.0", "requests" ] }' ``` #### Responses 200Success. The packages are installed. 400Bad request. 401Unauthorized access. `data`object `error`string POST`/api/v3/configure/plugin_environment/install_requirements` ### Install plugin requirements Installs requirements from a requirements file (also known as a “pip requirements file”) into the processing engine plugin environment. This endpoint is synchronous and blocks until the requirements are installed. ### Related * [Processing engine and Python plugins](/influxdb3/core/plugins/) * [Python requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/) #### Parameters ##### Header parameters `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request bodyrequired Content-Type:`application/json` `requirements_location`requiredstring The path to the requirements file containing Python packages to install. Can be a relative path (relative to the plugin directory) or an absolute path. Example:`"requirements.txt"` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/plugin_environment/install_requirements" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "requirements_location": "requirements.txt" }' ``` #### Responses 200Success. The requirements have been installed. 400Bad request. 401Unauthorized access. `data`object `error`string POST`/api/v3/configure/processing_engine_trigger` ### Create processing engine trigger Creates a processing engine trigger with the specified plugin file and trigger specification. #### Request bodyrequired Content-Type:`application/json` `db`requiredstring `disabled`requiredboolean Whether the trigger is disabled. `plugin_filename`requiredstring The path and filename of the plugin to execute–for example,`schedule.py` or `endpoints/report.py`. The path can be absolute or relative to the `--plugin-dir` directory configured when starting InfluxDB 3. The plugin file must implement the trigger interface associated with the trigger’s specification. Prefix the path with `gh:` to fetch the plugin remotely from the configured `--plugin-repo` instead of reading it from the local `--plugin-dir`–for example, `gh:examples/wal_plugin/wal_plugin.py`. Despite the name, `gh:` doesn’t require GitHub–`--plugin-repo` accepts any HTTP/HTTPS URL that serves raw plugin files. For defaults, fetch behavior, and limitations, see [Use example plugins](/influxdb3/core/plugins/#use-example-plugins). `trigger_arguments`object Optional arguments passed to the plugin. `trigger_name`requiredstring `trigger_settings`requiredstring Configuration for trigger error handling and execution behavior. `trigger_specification`requiredstring Specifies when and how the processing engine trigger should be invoked. ## Supported trigger specifications: ### Cron-based scheduling Format: `cron:CRON_EXPRESSION` Uses extended (6-field) cron format (second minute hour day\_of\_month month day\_of\_week): ``` ┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ │ * * * * * * ``` Examples: * `cron:0 0 6 * * 1-5` - Every weekday at 6:00 AM * `cron:0 30 14 * * 5` - Every Friday at 2:30 PM * `cron:0 0 0 1 * *` - First day of every month at midnight ### Interval-based scheduling Format: `every:DURATION` Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years): * `every:30s` - Every 30 seconds * `every:5m` - Every 5 minutes * `every:1h` - Every hour * `every:1d` - Every day * `every:1w` - Every week * `every:1M` - Every month * `every:1y` - Every year **Maximum interval**: 1 year ### Table-based triggers * `all_tables` - Triggers on write events to any table in the database * `table:TABLE_NAME` - Triggers on write events to a specific table ### On-demand triggers Format: `request:REQUEST_PATH` Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual invocation: * `request:hello-world` - Creates endpoint `/api/v3/engine/hello-world` * `request:data-export` - Creates endpoint `/api/v3/engine/data-export` Example:`"cron:0 0 6 * * 1-5"` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "db": "DB", "disabled": false, "plugin_filename": "PLUGIN_FILENAME", "trigger_arguments": {}, "trigger_name": "TRIGGER_NAME", "trigger_settings": "TRIGGER_SETTINGS", "trigger_specification": "cron:0 0 6 * * 1-5" }' ``` #### Responses 200Success. Processing engine trigger created. 400Bad request. 401Unauthorized access. `data`object `error`string 404Trigger not found. DELETE`/api/v3/configure/processing_engine_trigger` ### Delete processing engine trigger Deletes a processing engine trigger. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `trigger_name`requiredstring `force`boolean Force deletion of the trigger even if it has active executions. By default, deletion fails if the trigger is currently executing. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/processing_engine_trigger?db=DB&trigger_name=TRIGGER_NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The processing engine trigger has been deleted. 400Bad request. 401Unauthorized access. `data`object `error`string 404Trigger not found. POST`/api/v3/configure/processing_engine_trigger/disable` ### Disable processing engine trigger Disables a processing engine trigger. #### Parameters ##### Query parameters `db`requiredstring The database name. `trigger_name`requiredstring The name of the trigger. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/processing_engine_trigger/disable?db=DB&trigger_name=TRIGGER_NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The processing engine trigger has been disabled. 400Bad request. 401Unauthorized access. `data`object `error`string 404Trigger not found. POST`/api/v3/configure/processing_engine_trigger/enable` ### Enable processing engine trigger Enables a processing engine trigger. #### Parameters ##### Query parameters `db`requiredstring The database name. `trigger_name`requiredstring The name of the trigger. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/processing_engine_trigger/enable?db=DB&trigger_name=TRIGGER_NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The processing engine trigger is enabled. 400Bad request. 401Unauthorized access. `data`object `error`string 404Trigger not found. GET`/api/v3/engine/{request_path}` ### On Request processing engine plugin request Executes the On Request processing engine plugin specified in the trigger’s `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: ```python def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None) ``` The response depends on the plugin implementation. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/engine/{request_path}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The plugin request has been executed. 400Malformed request. 401Unauthorized access. `data`object `error`string 404Plugin not found. 500Processing failure. POST`/api/v3/engine/{request_path}` ### On Request processing engine plugin request Executes the On Request processing engine plugin specified in the trigger’s `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: ```python def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None) ``` The response depends on the plugin implementation. #### Parameters ##### Header parameters `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/engine/{request_path}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The plugin request has been executed. 400Malformed request. 401Unauthorized access. `data`object `error`string 404Plugin not found. 500Processing failure. POST`/api/v3/plugin_test/schedule` ### Test scheduling plugin Executes a test of a scheduling plugin. #### Request bodyrequired Content-Type:`application/json` `cache_name`string Optional name of the cache to use in the test. `database`requiredstring The database name to use for the test. `filename`requiredstring The path and filename of the plugin to test. `input_arguments`object Optional key-value pairs of arguments to pass to the plugin. `schedule`string Optional schedule specification in cron or interval format. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/plugin_test/schedule" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cache_name": "CACHE_NAME", "database": "DATABASE", "filename": "FILENAME", "input_arguments": {}, "schedule": "SCHEDULE" }' ``` #### Responses 200Success. The plugin test has been executed. 400Bad request. 401Unauthorized access. `data`object `error`string 404Plugin not enabled. POST`/api/v3/plugin_test/wal` ### Test WAL plugin Executes a test of a write-ahead logging (WAL) plugin. #### Request bodyrequired Content-Type:`application/json` `cache_name`string Optional name of the cache to use in the test. `database`requiredstring The database name to use for the test. `filename`requiredstring The path and filename of the plugin to test. `input_arguments`object Optional key-value pairs of arguments to pass to the plugin. `input_lp`requiredstring Line protocol data to use as input for the test. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/plugin_test/wal" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cache_name": "CACHE_NAME", "database": "DATABASE", "filename": "FILENAME", "input_arguments": {}, "input_lp": "INPUT_LP" }' ``` #### Responses 200Success. The plugin test has been executed. 400Bad request. 401Unauthorized access. `data`object `error`string 404Plugin not enabled. PUT`/api/v3/plugins/directory` ### Update a multi-file plugin directory Replaces all files in a multi-file plugin directory. The`plugin_name` must match a registered trigger name. Each entry in the `files` array specifies a `relative_path` and `content`—the server writes them into the trigger’s plugin directory. Use this endpoint to update multi-file plugins (directories with`__init__.py` and supporting modules). For single-file plugins, use `PUT /api/v3/plugins/files` instead. #### Request bodyrequired Content-Type:`application/json` `files`requiredobject[] List of plugin files to include in the directory. `plugin_name`requiredstring The name of the plugin directory to update. Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://localhost:8181/api/v3/plugins/directory" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "files": [], "plugin_name": "PLUGIN_NAME" }' ``` #### Responses 200Success. The plugin directory has been updated. 401Unauthorized access. `data`object `error`string 403Forbidden. Admin token required. 500Plugin not found. The `plugin_name` does not match any registered trigger. POST`/api/v3/plugins/files` ### Create a plugin file Creates a single plugin file in the plugin directory. Writes the`content` to a file named after `plugin_name`. Does not require an existing trigger—use this to upload plugin files before creating triggers that reference them. #### Request bodyrequired Content-Type:`application/json` `content`requiredstring The content of the plugin file. `plugin_name`requiredstring The name of the plugin file to update. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/plugins/files" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "content": "CONTENT", "plugin_name": "PLUGIN_NAME" }' ``` #### Responses 200Success. The plugin file has been created. 401Unauthorized access. `data`object `error`string 403Forbidden. Admin token required. PUT`/api/v3/plugins/files` ### Update a plugin file Updates a single plugin file for an existing trigger. The`plugin_name` must match a registered trigger name—the server resolves the trigger’s `plugin_filename` and overwrites that file with the provided `content`. To upload a new plugin file before creating a trigger, use`POST /api/v3/plugins/files` instead. To update a multi-file plugin directory, use `PUT /api/v3/plugins/directory`. #### Request bodyrequired Content-Type:`application/json` `content`requiredstring The content of the plugin file. `plugin_name`requiredstring The name of the plugin file to update. Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://localhost:8181/api/v3/plugins/files" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "content": "CONTENT", "plugin_name": "PLUGIN_NAME" }' ``` #### Responses 200Success. The plugin file has been updated. 401Unauthorized access. `data`object `error`string 403Forbidden. Admin token required. 500Plugin not found. The `plugin_name` does not match any registered trigger. #### Related * [Processing engine and Python plugins](/influxdb3/core/processing-engine/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Query data Source: https://docs.influxdata.com/influxdb3/core/api/query-data/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Query data stored in InfluxDB 3 Core using SQL or InfluxQL. GET`/api/v3/query_influxql` ### Execute InfluxQL query Executes an InfluxQL query to retrieve data from the specified database. #### Parameters ##### Query parameters `db`string The name of the database. If you provide a query that specifies the database, you can omit the ‘db’ parameter from your request. `q`requiredstring `format`string `params`string JSON-encoded query parameters for parameterized queries. ##### Header parameters `Accept`string The content type that the client can understand. Allowed values:`application/json`, `application/jsonl`, `application/vnd.apache.parquet`, `text/csv` Default:`application/json` #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/query_influxql?q=Q" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. POST`/api/v3/query_influxql` ### Execute InfluxQL query Executes an InfluxQL query to retrieve data from the specified database. #### Parameters ##### Header parameters `Accept`string The content type that the client can understand. Allowed values:`application/json`, `application/jsonl`, `application/vnd.apache.parquet`, `text/csv` Default:`application/json` `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/query_influxql" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"db":"mydb","format":"json","params":{},"q":"SELECT * FROM mytable"}' ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. GET`/api/v3/query_sql` ### Execute SQL query Executes an SQL query to retrieve data from the specified database. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `q`requiredstring \ The query to execute. `format`string `params`string JSON-encoded query parameters for parameterized queries. ##### Header parameters `Accept`string The content type that the client can understand. Allowed values:`application/json`, `application/jsonl`, `application/vnd.apache.parquet`, `text/csv` Default:`application/json` `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/query_sql?db=DB&q=Q" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. POST`/api/v3/query_sql` ### Execute SQL query Executes an SQL query to retrieve data from the specified database. #### Parameters ##### Header parameters `Accept`string The content type that the client can understand. Allowed values:`application/json`, `application/jsonl`, `application/vnd.apache.parquet`, `text/csv` Default:`application/json` `Content-Type`string The format of the data in the request body. Allowed values:`application/json` #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"db":"mydb","format":"json","params":{},"q":"SELECT * FROM mytable"}' ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. GET`/query` ### Execute InfluxQL query (v1-compatible) Executes an InfluxQL query to retrieve data from the specified database. This endpoint is compatible with InfluxDB 1.x client libraries and third-party integrations such as Grafana. Use query parameters to specify the database and the InfluxQL query. #### Related * [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) #### Parameters ##### Query parameters `chunked`boolean If true, the response is divided into chunks of size `chunk_size`. `chunk_size`integer The number of records that will go into a chunk. This parameter is only used if `chunked=true`. Default:`10000` `db`string \ The database to query. If not provided, the InfluxQL query string must specify the database. `pretty`boolean If true, the JSON response is formatted in a human-readable format. `q`requiredstring The InfluxQL query string. `epoch`string Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision. `u`string Username for v1 compatibility authentication. When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients. `p`string Password for v1 compatibility authentication. For query string authentication, pass a database token with write permissions as this parameter. InfluxDB 3 checks that the `p` value is an authorized token. `rp`string Retention policy name. Honored but discouraged. InfluxDB 3 doesn’t use retention policies. ##### Header parameters `Accept`string The content type that the client can understand. If `text/csv` is specified, the `Content-type` response header is `application/csv` and the response is formatted as CSV. Returns an error if the format is invalid or non-UTF8. Allowed values:`application/json`, `application/csv`, `text/csv` Default:`application/json` `Authorization`string Authorization header for token-based authentication. Supported schemes: * `Bearer AUTH_TOKEN` - OAuth bearer token scheme * `Token AUTH_TOKEN` - InfluxDB v2 token scheme * `Basic ` - Basic authentication (username is ignored) Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/query?q=Q" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. POST`/query` ### Execute InfluxQL query (v1-compatible) Executes an InfluxQL query to retrieve data from the specified database. #### Related * [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) #### Parameters ##### Header parameters `Accept`string The content type that the client can understand. If `text/csv` is specified, the `Content-type` response header is `application/csv` and the response is formatted as CSV. Returns an error if the format is invalid or non-UTF8. Allowed values:`application/json`, `application/csv`, `text/csv` Default:`application/json` #### Request body Content-Type:`application/json` `chunk_size`integer The number of records that will go into a chunk. This parameter is only used if `chunked=true`. Default:`10000` `chunked`boolean If true, the response is divided into chunks of size `chunk_size`. `db`string The database to query. If not provided, the InfluxQL query string must specify the database. `epoch`string A unix timestamp precision. * `h` for hours * `m` for minutes * `s` for seconds * `ms` for milliseconds * `u` or `µ` for microseconds * `ns` for nanoseconds Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision. Allowed:`ns`, `u`, `µ`, `ms`, `s`, `m`, `h` `pretty`boolean If true, the JSON response is formatted in a human-readable format. `q`requiredstring The InfluxQL query string. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/query" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "chunk_size": 10000, "chunked": false, "db": "DB", "epoch": "ns", "pretty": false, "q": "Q" }' ``` #### Responses 200Success. The response body contains query results. `results`object[] Example request body ```json { "results": [ { "series": [ { "columns": [ "time", "value" ], "name": "mytable", "values": [ [ "2024-02-02T12:00:00Z", 42 ] ] } ] } ] } ``` 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 404Database not found. 405Method not allowed. 422Unprocessable entity. #### Related * [Query data](/influxdb3/core/query-data/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Quick start Source: https://docs.influxdata.com/influxdb3/core/api/quick-start/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Authenticate, write, and query with the API: 1. Create an admin token to authorize API requests. ``` curl -X POST "http://localhost:8181/api/v3/configure/token/admin" ``` 2. Check the status of the InfluxDB server. ``` curl "http://localhost:8181/health" \ --header "Authorization: Bearer ADMIN_TOKEN" ``` 3. Write data to InfluxDB. ``` curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" --header "Authorization: Bearer ADMIN_TOKEN" \ --data-raw "home,room=Kitchen temp=72.0 home,room=Living\ room temp=71.5" ``` If all data is written, the response is `204 No Content`. 4. Query data from InfluxDB. ``` curl -G "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer ADMIN_TOKEN" \ --data-urlencode "db=sensors" \ --data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \ --data-urlencode "format=jsonl" ``` Output: ``` {"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"} ``` For more information about using InfluxDB 3 Core, see the [Get started](/influxdb3/core/get-started/) guide. --- # Server information Source: https://docs.influxdata.com/influxdb3/core/api/server-information/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Retrieve server metrics, health status, and version information for InfluxDB 3 Core. GET`/api/v1/health` ### Health check (v1) Checks the status of the service. Returns `OK` if the service is running. This endpoint does not return version information. Use the [`/ping`](#operation/GetPing) endpoint to retrieve version details. > > > **Note**: This endpoint requires authentication by default in InfluxDB 3 Core. > > Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v1/health" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Service is running. Returns `OK`. 401Unauthorized. Authentication is required. 500Service is unavailable. GET`/health` ### Health check Checks the status of the service. Returns `OK` if the service is running. This endpoint does not return version information. Use the [`/ping`](#operation/GetPing) endpoint to retrieve version details. > > > **Note**: This endpoint requires authentication by default in InfluxDB 3 Core. > > Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/health" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Service is running. Returns `OK`. 401Unauthorized. Authentication is required. 500Service is unavailable. GET`/metrics` ### Metrics Retrieves Prometheus-compatible server metrics. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/metrics" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success GET`/ping` ### Ping the server Returns version information for the server. **Important**: Use a GET request. HEAD requests return `404 Not Found`. The response includes version information in both headers and the JSON body: * **Headers**: `x-influxdb-version` and `x-influxdb-build` * **Body**: JSON object with `version`, `revision`, and `process_id` > > > **Note**: This endpoint requires authentication by default in InfluxDB 3 Core. > > Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains server information. `process_id`string A unique identifier for the server process. Example:`"b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7"` `revision`string The git revision hash for the build. Example:`"83b589b883"` `version`string The InfluxDB version number. Example:`"3.8.0"` 401Unauthorized. Authentication is required. 404Not Found. Returned for HEAD requests. Use a GET request to retrieve version information. POST`/ping` ### Ping the server Returns version information for the server. Accepts POST in addition to GET. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains server information. `process_id`string A unique identifier for the server process. Example:`"b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7"` `revision`string The git revision hash for the build. Example:`"83b589b883"` `version`string The InfluxDB version number. Example:`"3.8.0"` 401Unauthorized. Authentication is required. 404Not Found. Returned for HEAD requests. Use a GET request to retrieve version information. #### Related * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Table Source: https://docs.influxdata.com/influxdb3/core/api/table/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Manage table schemas in an InfluxDB 3 Core database. POST`/api/v3/configure/distinct_cache` ### Create distinct cache Creates a distinct cache for a table. #### Request bodyrequired Content-Type:`application/json` `columns`requiredstring[] `db`requiredstring `max_age`integer Optional maximum age in seconds. `max_cardinality`integer Optional maximum cardinality. `name`string Optional cache name. `table`requiredstring Example request body ```json { "columns": [ "tag1", "tag2" ], "db": "mydb", "max_age": 3600, "max_cardinality": 1000, "table": "mytable" } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/distinct_cache" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"columns":["tag1","tag2"],"db":"mydb","max_age":3600,"max_cardinality":1000,"table":"mytable"}' ``` #### Responses 201Success. The distinct cache has been created. 400 Bad request. The server responds with status `400` if the request would overwrite an existing cache with a different configuration. 409Conflict. A distinct cache with this configuration already exists. DELETE`/api/v3/configure/distinct_cache` ### Delete distinct cache Deletes a distinct cache. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `table`requiredstring The name of the table containing the distinct cache. `name`requiredstring The name of the distinct cache to delete. #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/distinct_cache?db=DB&table=TABLE&name=NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The distinct cache has been deleted. 400Bad request. 401Unauthorized access. `data`object `error`string 404Cache not found. POST`/api/v3/configure/last_cache` ### Create last cache Creates a last cache for a table. #### Request bodyrequired Content-Type:`application/json` `count`integer Optional count. `db`requiredstring `key_columns`string[] Optional list of key columns. `name`string Optional cache name. `table`requiredstring `ttl`integer Optional time-to-live in seconds. `value_columns`string[] Optional list of value columns. Example request body ```json { "count": 100, "db": "mydb", "key_columns": [ "tag1" ], "table": "mytable", "ttl": 3600, "value_columns": [ "field1" ] } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/last_cache" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"count":100,"db":"mydb","key_columns":["tag1"],"table":"mytable","ttl":3600,"value_columns":["field1"]}' ``` #### Responses 201Success. Last cache created. 400Bad request. A cache with this name already exists or the request is malformed. 401Unauthorized access. `data`object `error`string 404Cache not found. DELETE`/api/v3/configure/last_cache` ### Delete last cache Deletes a last cache. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `table`requiredstring The name of the table containing the last cache. `name`requiredstring The name of the last cache to delete. #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/last_cache?db=DB&table=TABLE&name=NAME" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200Success. The last cache has been deleted. 400Bad request. 401Unauthorized access. `data`object `error`string 404Cache not found. POST`/api/v3/configure/table` ### Create a table Creates a new table within a database. #### Request bodyrequired Content-Type:`application/json` `db`requiredstring `fields`requiredobject[] `name`requiredstring `type`requiredstring Allowed:`utf8`, `int64`, `uint64`, `float64`, `bool` `retention_period`string The retention period for the table. Specifies how long data in this table should be retained. Use duration format (for example, “1d”, “1h”, “30m”, “7d”). Example:`"30d"` `table`requiredstring `tags`requiredstring[] Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/table" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "db": "DB", "fields": [], "retention_period": "30d", "table": "TABLE", "tags": [ "example" ] }' ``` #### Responses 200Success. The table has been created. 400Bad request. 401Unauthorized access. `data`object `error`string 404Database not found. DELETE`/api/v3/configure/table` ### Delete a table Soft deletes a table. The table is scheduled for deletion and unavailable for querying. Use the `hard_delete_at` parameter to schedule a hard deletion. Use the `data_only` parameter to delete data while preserving the table schema and resources. #### Deleting a table cannot be undone Deleting a table is a destructive action. Once a table is deleted, data stored in that table cannot be recovered. #### Soft-deleted tables keep a renamed, visible entry until hard deletion A soft delete renames the table to `-` instead of removing it. Until the table is hard deleted, this renamed entry still appears in `SHOW TABLES` output and in`information_schema.tables` queries. Filter out names that end in a deleted-at timestamp to account for these renamed entries when listing or counting tables. Deleting an already-deleted table returns `409 Conflict`. There’s no API to remove the renamed entry directly; only a scheduled or immediate (`hard_delete_at=now`) hard deletion removes it. #### Parameters ##### Query parameters `db`requiredstring The name of the database. `table`requiredstring `data_only`boolean Delete only data while preserving the table schema and all associated resources (last value caches, distinct value caches). When `false` (default), the entire table is deleted. `hard_delete_at`string \ Schedule the table for hard deletion at the specified time. If not provided, the table will be soft deleted. Use ISO 8601 format (for example, “2025-12-31T23:59:59Z”). Also accepts special string values: * `now` — hard delete immediately * `never` — soft delete only (default behavior) * `default` — use the system default hard deletion time Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/table?db=DB&table=TABLE" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success (no content). The table has been deleted. 401Unauthorized access. `data`object `error`string 404Table not found. 409Conflict. The table is already deleted. #### Related * [Manage tables](/influxdb3/core/admin/tables/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) --- # Write data Source: https://docs.influxdata.com/influxdb3/core/api/write-data/ [Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml) Write data to InfluxDB 3 Core using line protocol format. #### Timestamp precision across write APIs InfluxDB 3 provides multiple write endpoints for compatibility with different InfluxDB versions. The following table compares timestamp precision support across v1, v2, and v3 write APIs: | Precision |v1 (`/write`)|v2 (`/api/v2/write`)|v3 (`/api/v3/write_lp`)| |------------------|-------------|--------------------|-----------------------| |**Auto detection**| ❌ No | ❌ No | ✅ `auto` (default) | | **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` | | **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` | | **Microseconds** |✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` | | **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` | | **Minutes** | ✅ `m` | ❌ No | ❌ No | | **Hours** | ✅ `h` | ❌ No | ❌ No | | **Default** | Nanosecond | Nanosecond | **Auto** (guessed) | All timestamps are stored internally as nanoseconds. POST`/api/v3/write_lp` ### Write line protocol Writes line protocol data to the specified database. Use this endpoint to send data in[line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. #### Features * **Partial writes**: Use `accept_partial=true` to allow partial success when some lines in a batch fail * **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL synchronization, allowing faster response times but sacrificing durability guarantees * **Flexible precision**: Automatic timestamp precision detection with`precision=auto` (default) #### Auto precision detection When you use `precision=auto` or omit the precision parameter, InfluxDB 3 automatically detects the timestamp precision based on the magnitude of the timestamp value: * Timestamps \< 5e9 → Second precision (multiplied by 1,000,000,000) * Timestamps \< 5e12 → Millisecond precision (multiplied by 1,000,000) * Timestamps \< 5e15 → Microsecond precision (multiplied by 1,000) * Larger timestamps → Nanosecond precision (no conversion needed) #### Related * [Use the InfluxDB v3 write\_lp API to write data](/influxdb3/core/write-data/http-api/v3-write-lp/) #### Parameters ##### Query parameters `db`requiredstring `precision`string `accept_partial`boolean `no_sync`boolean #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/write_lp?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1 1234567890' ``` #### Responses 204Success (“No Content”). All data in the batch is written and queryable. 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 413Request entity too large. 422Unprocessable entity. POST`/api/v2/write` ### Write line protocol (v2-compatible) Writes line protocol to the specified database. This endpoint provides backward compatibility for InfluxDB 2.x write workloads using tools such as InfluxDB 2.x client libraries, the Telegraf `outputs.influxdb_v2` output plugin, or third-party tools. Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. #### Related * [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) #### Parameters ##### Query parameters `bucket`requiredstring A database name. InfluxDB creates the database if it doesn’t already exist, and then writes all points in the batch to the database. This parameter is named `bucket` for compatibility with InfluxDB v2 client libraries. `accept_partial`string `precision`string The precision for unix timestamps in the line protocol batch. ##### Header parameters `Content-Type`string The content type of the request payload. `Content-Encoding`string The compression applied to the line protocol in the request payload. To send a gzip payload, pass `Content-Encoding: gzip` header. Allowed values:`gzip`, `identity` Default:`identity` `Content-Length`integer The size of the entity-body, in bytes, sent to InfluxDB. `Accept`string The content type that the client can understand. Writes only return a response body if they fail (partially or completely)–for example, due to a syntax problem or type mismatch. Allowed values:`application/json` Default:`application/json` #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v2/write?bucket=BUCKET" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1 1234567890' ``` #### Responses 204Success (“No Content”). All data in the batch is written and queryable. 400Bad request. 401Unauthorized access. `data`object `error`string 403Access denied. 413Request entity too large. POST`/write` ### Write line protocol (v1-compatible) Writes line protocol to the specified database. This endpoint provides backward compatibility for InfluxDB 1.x write workloads using tools such as InfluxDB 1.x client libraries, the Telegraf `outputs.influxdb` output plugin, or third-party tools. Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. #### Related * [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) #### Parameters ##### Query parameters `db`requiredstring The name of the database. InfluxDB creates the database if it doesn’t already exist, and then writes all points in the batch to the database. `precision`string The precision for unix timestamps in the line protocol batch. `u`string Username for v1 compatibility authentication. When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients. `p`string Password for v1 compatibility authentication. For query string authentication, pass a database token with write permissions as this parameter. InfluxDB 3 checks that the `p` value is an authorized token. `rp`string Retention policy name. Honored but discouraged. InfluxDB 3 doesn’t use retention policies. `consistency`string Write consistency level. Ignored by InfluxDB 3. Provided for compatibility with InfluxDB 1.x clients. ##### Header parameters `Authorization`string Authorization header for token-based authentication. Supported schemes: * `Bearer AUTH_TOKEN` - OAuth bearer token scheme * `Token AUTH_TOKEN` - InfluxDB v2 token scheme * `Basic ` - Basic authentication (username is ignored) `Content-Type`string The content type of the request payload. `Accept`string The content type that the client can understand. Writes only return a response body if they fail (partially or completely)–for example, due to a syntax problem or type mismatch. Allowed values:`application/json` Default:`application/json` `Content-Encoding`string The compression applied to the line protocol in the request payload. To send a gzip payload, pass `Content-Encoding: gzip` header. `Content-Length`string The size of the entity-body, in bytes, sent to InfluxDB. #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/write?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1 1234567890' ``` #### Responses 204Success (“No Content”). All data in the batch is written and queryable. 400 Bad request. Some (a *partial write*) or all of the data from the batch was rejected and not written. If a partial write occurred, then some points from the batch are written and queryable. The response body: * indicates if a partial write occurred or all data was rejected. * contains details about the [rejected points](/influxdb3/core/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. 401Unauthorized access. `data`object `error`string 403Access denied. 413Request entity too large. #### Related * [Write data using HTTP APIs](/influxdb3/core/write-data/http-api/) * [Line protocol reference](/influxdb3/core/reference/syntax/line-protocol/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) | Precision | v1 ( /write ) | v2 ( /api/v2/write ) | v3 ( /api/v3/write_lp ) | | --- | --- | --- | --- | | Precision | v1 ( /write ) | v2 ( /api/v2/write ) | v3 ( /api/v3/write_lp ) | | Auto detection | ❌ No | ❌ No | ✅ auto (default) | | Seconds | ✅ s | ✅ s | ✅ second | | Milliseconds | ✅ ms | ✅ ms | ✅ millisecond | | Microseconds | ✅ u or µ | ✅ us | ✅ microsecond | | Nanoseconds | ✅ ns | ✅ ns | ✅ nanosecond | | Minutes | ✅ m | ❌ No | ❌ No | | Hours | ✅ h | ❌ No | ❌ No | | Default | Nanosecond | Nanosecond | Auto (guessed) | --- # Get started with InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/get-started/ > [!Note] > InfluxDB 3 Core is purpose-built for real-time data monitoring and recent data. > InfluxDB 3 Enterprise builds on top of Core with support for historical data > analysis and extended features. > querying, high availability, read replicas, and more. > Enterprise will soon unlock > enhanced security, row-level deletions, an administration UI, and more. > Learn more about [InfluxDB 3 Enterprise](/influxdb3/enterprise/). This guide walks through the basic steps of getting started with InfluxDB 3 Core, including the following: 1. [Set up InfluxDB 3 Core](/influxdb3/core/get-started/setup/) 2. [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) 3. [Query data in InfluxDB 3 Core](/influxdb3/core/get-started/query/) 4. [Process data in InfluxDB 3 Core](/influxdb3/core/get-started/process/) 5. [Migrate from InfluxDB v1 or v2](/influxdb3/core/get-started/migrate-from-influxdb-v1-v2/) > [!Tip] > #### Find support for InfluxDB 3 Core > > The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. > For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. ## Data model The InfluxDB 3 Core server contains logical databases; databases contain tables; and tables are comprised of columns. Compared to previous versions of InfluxDB, you can think of a database as an InfluxDB v2 `bucket` in v2 or an InfluxDB v1 `db/retention_policy`. A `table` is equivalent to an InfluxDB v1 and v2 `measurement`. Columns in a table represent time, tags, and fields. Columns can be one of the following types: * String dictionary (tag) * `int64` (field) * `float64` (field) * `uint64` (field) * `bool` (field) * `string` (field) * `time` (time with nanosecond precision) In InfluxDB 3 Core, every table has a primary key–the ordered set of tags and the time–for its data. The primary key uniquely identifies each and determines the sort order for all Parquet files related to the table. When you create a table, either through an explicit call or by writing data into a table for the first time, it sets the primary key to the tags in the order they arrived. Although InfluxDB is still a *schema-on-write* database, the tag column definitions for a table are immutable. Tags should hold unique identifying information like `sensor_id`, `building_id`, or `trace_id`. All other data should be stored as fields. ## Tools to use The following table compares tools that you can use to interact with InfluxDB 3 Core. This tutorial covers many of the recommended tools. | Tool |Administration|Write|Query| |------------------------------------------------------------------------------|--------------|-----|-----| | **[`influxdb3` CLI](/influxdb3/core/reference/cli/influxdb3/)** | **✓** |**✓**|**✓**| | **[InfluxDB HTTP API](/influxdb3/core/reference/api/)** | **✓** |**✓**|**✓**| | **[InfluxDB 3 Explorer](/influxdb3/explorer/)** | **✓** |**✓**|**✓**| |[InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) | \- |**✓**|**✓**| |[InfluxDB v2 client libraries](/influxdb3/core/reference/client-libraries/v2/)| \- |**✓**| \- | |[InfluxDB v1 client libraries](/influxdb3/core/reference/client-libraries/v1/)| \- |**✓**|**✓**| | [InfluxDB 3 processing engine](/influxdb3/core/plugins/) | |**✓**|**✓**| | [Telegraf](/telegraf/v1/) | \- |**✓**| \- | | [Chronograf](/chronograf/v1/) | \- | \- | \- | | `influx` CLI | \- | \- | \- | | `influxctl` CLI | \- | \- | \- | | InfluxDB v2.x user interface | \- | \- | \- | | **Third-party tools** | | | | | Flight SQL clients | \- | \- |**✓**| | [Grafana](/influxdb3/core/visualize-data/grafana/) | \- | \- |**✓**| [Set up InfluxDB 3 Core](/influxdb3/core/get-started/setup/) #### Related * [Query system data](/influxdb3/core/admin/query-system-data/) * [Write data to InfluxDB 3 Core](/influxdb3/core/write-data/) * [Query data in InfluxDB 3 Core](/influxdb3/core/query-data/) | Tool | Administration | Write | Query | | --- | --- | --- | --- | | Tool | Administration | Write | Query | | influxdb3 CLI | ✓ | ✓ | ✓ | | InfluxDB HTTP API | ✓ | ✓ | ✓ | | InfluxDB 3 Explorer | ✓ | ✓ | ✓ | | InfluxDB 3 client libraries | - | ✓ | ✓ | | InfluxDB v2 client libraries | - | ✓ | - | | InfluxDB v1 client libraries | - | ✓ | ✓ | | InfluxDB 3 processing engine | | ✓ | ✓ | | Telegraf | - | ✓ | - | | Chronograf | - | - | - | | influx CLI | - | - | - | | influxctl CLI | - | - | - | | InfluxDB v2.x user interface | - | - | - | | Third-party tools | | | | | Flight SQL clients | - | - | ✓ | | Grafana | - | - | ✓ | --- # Migrate from InfluxDB v1 or v2 Source: https://docs.influxdata.com/influxdb3/core/get-started/migrate-from-influxdb-v1-v2/ InfluxDB 3 provides compatibility APIs and tools for migrating existing InfluxDB v1 and v2 workloads. Use existing client libraries and tools with minimal changes to your code. ## Write data InfluxDB 3 supports v1 and v2 compatible write endpoints: * **`/api/v2/write`**: Compatible with InfluxDB v2 clients and tools * **`/write`**: Compatible with InfluxDB v1 clients and tools Both endpoints accept line protocol and write data the same way. For more information, see [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/). ## Query data InfluxDB 3 supports the v1 HTTP query API for InfluxQL queries: * **`/query`**: Compatible with InfluxDB v1 query clients For more information, see [Use the v1 HTTP query API](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/). ## Client libraries Use InfluxDB v1 and v2 client libraries with InfluxDB 3 Core: * [v2 client libraries](/influxdb3/core/reference/client-libraries/v2/) * [v1 client libraries](/influxdb3/core/reference/client-libraries/v1/) --- # Process data in InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/get-started/process/ The InfluxDB 3 Core processing engine is an embedded Python virtual machine (VM) that runs code inside the database to process and transform data. Create processing engine [plugins](#plugin) that run when [triggered](#trigger)by specific events. * [Before you begin](#before-you-begin) * [Processing engine terminology](#processing-engine-terminology) * [Plugin](#plugin) * [Trigger](#trigger) * [Trigger types](#trigger-types) * [Activate the processing engine](#activate-the-processing-engine) * [Create a plugin](#create-a-plugin) * [Test a plugin on the server](#test-a-plugin-on-the-server) * [Create a trigger](#create-a-trigger) * [Enable the trigger](#enable-the-trigger) ## Processing engine terminology ### Plugin A plugin is a Python function that has a signature compatible with a processing engine [trigger](#trigger). ### Trigger When you create a trigger, you specify a [plugin](#plugin), a database, optional arguments, and a trigger specification, which defines when the plugin is executed and what data it receives. #### Trigger types InfluxDB 3 provides the following types of triggers, each with specific specifications: * **WAL rows** (`table:` or `all_tables`): Sends a batch of written data (for a specific table or all tables) to a plugin when the database flushes data to the [Write-Ahead Log (WAL)](/influxdb3/core/reference/internals/durability/#write-ahead-log-wal-persistence (by default, every second). * **Scheduled** (`every:` or `cron:`): Executes a plugin on a user-configured schedule (using a crontab or a duration). This trigger type is useful for data collection and deadman monitoring. * **HTTP request** (`request:`): Binds a plugin to a custom HTTP API endpoint at`/api/v3/engine/`. The plugin receives the HTTP request headers and content, and can parse, process, and send the data into the database or to third-party services. ## Before you begin Before you can use the processing engine, you need: * A running InfluxDB 3 Core server * An admin token for authentication * A database to attach triggers to If you haven’t completed these steps, see [Set up InfluxDB 3 Core](/influxdb3/core/get-started/setup/). ## Activate the processing engine To activate the processing engine, include the `--plugin-dir ` option when starting the InfluxDB 3 Core server.`PLUGIN_DIR` is your file system location for storing [plugin](#plugin) files for the processing engine to run. > [!Note] > **Docker and DEB/RPM installations**: The Processing Engine is already enabled—no additional configuration needed. > To disable it, see [Enable and disable the Processing Engine](/influxdb3/core/reference/processing-engine/#enable-and-disable-the-processing-engine). > [!Note] > If you manually installed InfluxDB 3 Core from a tar archive, ensure the `influxdb3` binary and `python/` directory remain in the same parent directory. The install script handles this automatically. ```bash influxdb3 serve \ # ... --plugin-dir PLUGIN_DIR ``` Replace `PLUGIN_DIR`with the path to your plugin directory. This path can be absolute or relative to the current working directory of the `influxdb3` server. ## Create a plugin To create a plugin, write and store a Python file in your configured `PLUGIN_DIR`. The following example shows a WAL rows plugin, which receives data as it’s flushed to the Write-Ahead Log. The example shows how to process, query, and write data from within a plugin. ##### Example Python plugin for data writes ``` # Example: A data write plugin for the InfluxDB 3 Processing Engine # When creating a trigger, you can provide runtime arguments to your plugin, # allowing you to write generic code that uses variables such as monitoring # thresholds, environment variables, and host names. # # This example implements the process_writes signature compatible with a wal_rows # trigger specification. # Use the exact signature to define the function. # When you create a wal_rows trigger, you specify the database # and tables that the plugin receives written data from on every WAL flush # (default is once per second). def process_writes(influxdb3_local, table_batches, args=None): # Use logging to track plugin execution if args and "arg1" in args: influxdb3_local.info("arg1: " + args["arg1"]) # here we're using arguments provided at the time the trigger was set up # to feed into parameters that we'll put into a query query_params = {"room": "Kitchen"} # The following example shows how to execute a parameterized query. Only SQL is supported. # It queries the database that the trigger is configured for. query_result = influxdb3_local.query("SELECT * FROM home where room = '$room'", query_params) # The result is a list of Dict that have the column name as key and value as # value. influxdb3_local.info("query result: " + str(query_result)) # this is the data that is sent when data is written to the database and flushed to the WAL. # One batch for each table (will only be one if triggered on a single table) for table_batch in table_batches: # here you can see that the table_name is available. influxdb3_local.info("table: " + table_batch["table_name"]) # example to skip the table we're later writing data into if table_batch["table_name"] == "some_table": continue # and then the individual rows, which are Dict with keys of the column names and values for row in table_batch["rows"]: influxdb3_local.info("row: " + str(row)) # this shows building a line of LP to write back to the database. tags must go first and # their order is important and must always be the same for each individual table. Then # fields and lastly an optional time, which you can see in the next example below line = LineBuilder("some_table")\ .tag("tag1", "tag1_value")\ .tag("tag2", "tag2_value")\ .int64_field("field1", 1)\ .float64_field("field2", 2.0)\ .string_field("field3", "number three") # this writes it back (it actually just buffers it until the completion of this function # at which point it will write everything back that you put in) influxdb3_local.write(line) # here's another example, but with us setting a nanosecond timestamp at the end other_line = LineBuilder("other_table") other_line.int64_field("other_field", 1) other_line.float64_field("other_field2", 3.14) other_line.time_ns(1302) # and you can see that we can write to any DB in the server influxdb3_local.write_to_db("mytestdb", other_line) # just some log output as an example influxdb3_local.info("done") ``` ## Test a plugin on the server Use one of the [`influxdb3 test`](/influxdb3/core/reference/cli/influxdb3/test/)CLI commands to test your processing engine plugin safely without affecting actual data. During a plugin test: * A query executed by the plugin queries against the server you send the request to. * Writes aren’t sent to the server but are returned to you. To test a `process_writes` (WAL) plugin: 1. Save the [example plugin code](#example-python-plugin-for-data-writes) to a plugin file inside of the plugin directory. If you haven’t yet written data to the table in the example, comment out the lines where it queries. 2. To run the test, enter the following command with the following options: * `--lp` or `--file`: The line protocol to test * Optional: `--input-arguments`: A comma-delimited list of `=` arguments for your plugin code ```bash influxdb3 test wal_plugin \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --lp INPUT_LINE_PROTOCOL \ --input-arguments INPUT_ARGS \ PLUGIN_FILENAME ``` Replace the following: * `INPUT_LINE_PROTOCOL`: the line protocol to test * Optional: `INPUT_ARGS`: a comma-delimited list of `=` arguments for your plugin code–for example, `arg1=hello,arg2=world` * `DATABASE_NAME`: the name of the database to test against * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/)for your InfluxDB 3 Core server * `PLUGIN_FILENAME`: the name of the plugin file to test. Provide only the filename (for example, `test.py`), not a relative or absolute path. ### Example: Test a plugin ```bash # Test a plugin # Requires: # - A database named `mydb` with a table named `foo` # - A Python plugin file named `test.py` # Test a plugin influxdb3 test wal_plugin \ --lp "my_measure,tag1=asdf f1=1.0 123" \ --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ --database sensors \ --input-arguments "arg1=hello,arg2=world" \ test.py ``` The command runs the plugin code, yields the test data to the plugin, and then responds with the plugin result. You can quickly see how the plugin behaves, what data it would have written to the database, and any errors. You can then edit your Python code in the plugins directory, and rerun the test. The server reloads the file for every request to the `test` API. For more information about testing plugins, see the following: * [`influxdb3 test wal_plugin`](/influxdb3/core/reference/cli/influxdb3/test/wal_plugin/)or run `influxdb3 test wal_plugin -h` * [`influxdb3 test schedule_plugin`](/influxdb3/core/reference/cli/influxdb3/test/schedule_plugin/)or run `influxdb3 test schedule_plugin -h` ## Create a trigger With the plugin code inside the server plugin directory, and a successful test, you’re ready to create a trigger to run the plugin. Use the[`influxdb3 create trigger` command](/influxdb3/core/reference/cli/influxdb3/create/trigger/)to create a trigger. ```bash # Create a trigger that runs the single-file plugin influxdb3 create trigger \ --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ --database sensors \ --path test_plugin.py \ --trigger-spec "table:foo" \ --trigger-arguments "arg1=hello,arg2=world" \ trigger1 ``` > [!Note] > #### Plugin paths > > * For **single-file plugins**, provide just the `.py` filename to `--path` (for example, `test_plugin.py`). > * For **multi-file plugins**, provide the directory name containing `__init__.py`. > > When not using `--upload`, the server resolves paths relative to the configured `--plugin-dir`. > For details about multi-file plugin structure, see [Create your plugin file](/influxdb3/core/plugins/#create-your-plugin-file). ## Enable the trigger After you have created a plugin and trigger, enter the following command to enable the trigger and have it run the plugin as you write data: ```bash influxdb3 enable trigger \ --token AUTH_TOKEN \ --database DATABASE_NAME \ TRIGGER_NAME ``` Replace the following placeholders with your values: * `DATABASE_NAME`: the name of the database to enable the trigger in * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) * `TRIGGER_NAME`: 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 ``` ## Next steps If you’ve completed this Get Started guide for InfluxDB 3 Core, learn more about tools and options for: * [Writing data](/influxdb3/core/write-data/) * [Querying data](/influxdb3/core/query-data/) * [Processing data with plugins](/influxdb3/core/plugins/) * [Visualizing data](/influxdb3/core/visualize-data/) #### Related * [Processing engine and Python plugins](/influxdb3/core/plugins/) * [influxdb3 create trigger](/influxdb3/core/reference/cli/influxdb3/create/trigger/) --- # Query data in InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/get-started/query/ InfluxDB 3 Core supports both native SQL and InfluxQL for querying data. InfluxQL is an SQL-like query language designed for InfluxDB v1 and customized for time series queries. InfluxDB 3 Core limits query time ranges to approximately 72 hours (both recent and historical) to ensure query performance. For more information about the 72-hour limitation, see the [update on InfluxDB 3 Core’s 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/). > [!Note] > Flux, the language introduced in InfluxDB v2, is **not** supported in InfluxDB 3. * [Query data with the influxdb3 CLI](#query-data-with-the-influxdb3-cli) * [Example queries](#example-queries) * [Other tools for executing queries](#other-tools-for-executing-queries) * [SQL vs InfluxQL](#sql-vs-influxql) * [SQL](#sql) * [InfluxQL](#influxql) * [Optimize queries](#optimize-queries) * [Last values cache](#last-values-cache) * [Distinct values cache](#distinct-values-cache) ## Query data with the influxdb3 CLI To get started querying data in InfluxDB 3 Core, use the[`influxdb3 query` command](/influxdb3/core/reference/cli/influxdb3/query/)and provide the following: * `-H`, `--host`: The host URL of the server *(default is `http://127.0.0.1:8181`)* * `-d`, `--database`: *(Required)* The name of the database to query * `-l`, `--language`: The query language of the provided query string * `sql` *(default)* * `influxql` * SQL or InfluxQL query as a string > [!Important] > If the `INFLUXDB3_AUTH_TOKEN` environment variable defined in[Set up InfluxDB 3 Core](/influxdb3/core/get-started/setup/#set-your-token-for-authorization)isn’t set in your environment, set it or provide your token using > the `-t, --token` option in your command. To query the home sensor sample data you wrote in[Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/#write-data-using-the-cli), run the following command: #### SQL #### ```bash influxdb3 query \ --database DATABASE_NAME \ "SELECT * FROM home ORDER BY time" ``` ```bash influxdb3 query \ --database DATABASE_NAME \ --language influxql \ "SELECT * FROM home" ``` *Replace `DATABASE_NAME`with the name of the database to query.* To query from a specific time range, use the `WHERE` clause to designate the boundaries of your time range. #### SQL #### ```bash influxdb3 query \ --database DATABASE_NAME \ "SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time" ``` ```bash influxdb3 query \ --database DATABASE_NAME \ --language influxql \ "SELECT * FROM home WHERE time >= now() - 7d" ``` ### Example queries [](#list-tables-in-a-database) List tables in a database #### SQL #### ```sql SHOW TABLES ``` ```sql SHOW MEASUREMENTS ``` [](#return-the-average-temperature-of-all-rooms) Return the average temperature of all rooms #### SQL #### ```sql SELECT avg(temp) AS avg_temp FROM home ``` ```sql SELECT MEAN(temp) AS avg_temp FROM home ``` [](#return-the-average-temperature-of-the-kitchen) Return the average temperature of the kitchen #### SQL #### ```sql SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen' ``` ```sql SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen' ``` [](#query-data-from-an-absolute-time-range) Query data from an absolute time range #### SQL #### ```sql SELECT * FROM home WHERE time >= '2022-01-01T12:00:00Z' AND time <= '2022-01-01T18:00:00Z' ``` ```sql SELECT * FROM home WHERE time >= '2022-01-01T12:00:00Z' AND time <= '2022-01-01T18:00:00Z' ``` [](#query-data-from-a-relative-time-range) Query data from a relative time range #### SQL #### ```sql SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ``` ```sql SELECT * FROM home WHERE time >= now() - 7d ``` [](#calculate-average-humidity-in-3-hour-windows-per-room) Calculate average humidity in 3-hour windows per room #### SQL #### ```sql SELECT date_bin(INTERVAL '3 hours', time) AS time, room, avg(hum) AS avg_hum FROM home GROUP BY 1, room ORDER BY room, 1 ``` ```sql SELECT MEAN(hum) AS avg_hum FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(3h), room ``` ## Other tools for executing queries Other tools are available for querying data in InfluxDB 3 Core, including the following: [](#query-using-the-api) Query using the API #### Query using the API InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API. To query your database using the HTTP API, send a request to the `/api/v3/query_sql` or `/api/v3/query_influxql` endpoints. In the request, specify the database name in the `db` parameter and a query in the `q` parameter. You can pass parameters in the query string or inside a JSON object. Use the `format` parameter to specify the response format: `pretty`, `jsonl`, `parquet`, `csv`, and `json`. Default is `json`. ##### Example: Query passing URL-encoded parameters The following example sends an HTTP `GET` request with a URL-encoded SQL query: ```bash curl -G "http://localhost:8181/api/v3/query_sql" \ --header 'Authorization: Bearer AUTH_TOKEN' \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=select * from cpu limit 5" ``` Replace the following placeholders with your values: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ##### Example: Query passing JSON parameters The following example sends an HTTP `POST` request with parameters in a JSON payload: ```bash curl http://localhost:8181/api/v3/query_sql \ --data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}' ``` Replace the following placeholders with your values: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) [](#query-using-the-python-client) Query using the Python client #### Query using the Python client Use the InfluxDB 3 Python library to interact with the database and integrate with your application. We recommend installing the required packages in a Python virtual environment for your specific project. To get started, install the `influxdb3-python` package. ```bash pip install influxdb3-python ``` From here, you can connect to your database with the client library using just the **host** and \*\*database name: ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3( token='AUTH_TOKEN', host='http://localhost:8181', database='DATABASE_NAME' ) ``` Replace the following placeholders with your values: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The following example shows how to query using SQL, and then use PyArrow to explore the schema and process results. To authorize the query, the example retrieves the [token](/influxdb3/core/admin/tokens/) 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://localhost:8181', database='servers' ) # Execute the query and return an Arrow table table = client.query( query="SELECT * FROM cpu LIMIT 10", language="sql" ) print("\n#### View Schema information\n") print(table.schema) print("\n#### Use PyArrow to read the specified columns\n") print(table.column('usage_active')) print(table.select(['host', 'usage_active'])) print(table.select(['time', 'host', 'usage_active'])) print("\n#### Use PyArrow compute functions to aggregate data\n") print(table.group_by('host').aggregate([])) print(table.group_by('cpu').aggregate([('time_system', 'mean')])) ``` For more information about the Python client library, see the[`influxdb3-python` repository](https://github.com/InfluxCommunity/influxdb3-python)in GitHub. [](#query-using-influxdb-3-explorer) Query using InfluxDB 3 Explorer #### Query using InfluxDB 3 Explorer You can use the InfluxDB 3 Explorer web-based interface to query and visualize data, and administer your InfluxDB 3 Core instance. For more information, see how to [install InfluxDB 3 Explorer](/influxdb3/explorer/install/)using Docker and get started querying your data. ## SQL vs InfluxQL InfluxDB 3 Core supports two query languages–SQL and InfluxQL. While these two query languages are similar, there are important differences to consider. ### SQL The InfluxDB 3 SQL implementation provides a full-featured SQL query engine powered by [Apache DataFusion](https://datafusion.apache.org/). InfluxDB extends DataFusion with additional time series-specific functionality and supports the complex SQL queries, including queries that use joins, unions, window functions, and more. * [SQL query guides](/influxdb3/core/query-data/sql/) * [SQL reference](/influxdb3/core/reference/sql/) * [Apache DataFusion SQL reference](https://datafusion.apache.org/user-guide/sql/index.html) ### InfluxQL InfluxQL is a SQL-like query language built for InfluxDB v1 and supported in InfluxDB 3 Core. Its syntax and functionality is similar SQL, but specifically designed for querying time series data. InfluxQL does not offer the full range of query functionality that SQL does. If you are migrating from previous versions of InfluxDB, you can continue to use InfluxQL and the established InfluxQL-related APIs you have been using. * [InfluxQL query guides](/influxdb3/core/query-data/influxql/) * [InfluxQL reference](/influxdb3/core/reference/influxql/) * [InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/) ## Optimize queries InfluxDB 3 Core provides the following optimization options to improve specific kinds of queries: * [Last values cache](#last-values-cache) * [Distinct values cache](#distinct-values-cache) ### Last values cache The InfluxDB 3 Core last values cache (LVC) 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. For information about configuring and using the LVC, see: * [Manage a last values cache](/influxdb3/core/admin/last-value-cache/) * [Query the last values cache](/influxdb3/core/admin/last-value-cache/query/) ### Distinct values cache The InfluxDB 3 Core distinct values cache (DVC) stores distinct values for specified columns in a series or column hierarchy in memory. This is useful for fast metadata lookups, which can return in under 30 milliseconds. For information about configuring and using the DVC, see: * [Manage a distinct values cache](/influxdb3/core/admin/distinct-value-cache/) * [Query the distinct values cache](/influxdb3/core/admin/distinct-value-cache/query/) [Write data](/influxdb3/core/get-started/write/)[Processing engine](/influxdb3/core/get-started/process/) #### Related * [Query data in InfluxDB 3 Core](/influxdb3/core/query-data/) * [SQL reference documentation](/influxdb3/core/reference/sql/) * [Apache DataFusion SQL reference](https://datafusion.apache.org/user-guide/sql/index.html) * [InfluxQL reference documentation](/influxdb3/core/reference/influxql/) --- # Set up InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/get-started/setup/ * [Prerequisites](#prerequisites) * [Quick-Start Mode (Development)](#quick-start-mode-development) * [Start InfluxDB](#start-influxdb) * [Object store examples](#object-store-examples) * [Set up authorization](#set-up-authorization) * [Create an operator token](#create-an-operator-token) * [Set your token for authorization](#set-your-token-for-authorization) ## Prerequisites To get started, you’ll need: * **InfluxDB 3 Core**: [Install and verify the latest version](/influxdb3/core/install/) on your system. * If you want to persist data, have access to one of the following: * A directory on your local disk where you can persist data (used by examples in this guide) * S3-compatible object store and credentials ## Quick-Start Mode (Development) For development, testing, and home use, you can start InfluxDB 3 Core without any arguments. The system automatically generates required configuration values based on your system’s hostname: ```bash influxdb3 ``` When you run `influxdb3` without arguments, the following values are auto-generated: * **`node-id`**: `{hostname}-node` (or `primary-node` if hostname is unavailable) * **`object-store`**: `file` * **`data-dir`**: `~/.influxdb` The system displays warning messages showing the auto-generated identifiers: ``` Using auto-generated node id: mylaptop-node. For production deployments, explicitly set --node-id ``` > [!Important] > #### When to use quick-start mode > > Quick-start mode is designed for development, testing, and home lab environments > where simplicity is prioritized over explicit configuration. > > **For production deployments**, use explicit configuration values with the[`influxdb3 serve` command](/influxdb3/core/reference/cli/influxdb3/serve/)as shown in the [Start InfluxDB](#start-influxdb) section below. > > Quick-start mode listens on all network interfaces. > Before you start the server on a network that others can reach, see[Create your admin token before you expose the server](#start-influxdb). **Configuration precedence**: Environment variables override auto-generated defaults. For example, if you set `INFLUXDB3_NODE_ID=my-node`, the system uses `my-node` instead of generating `{hostname}-node`. ## Start InfluxDB Use the [`influxdb3 serve` command](/influxdb3/core/reference/cli/influxdb3/serve/)to start InfluxDB 3 Core. Provide the following: * `--node-id`: A string identifier that distinguishes individual server instances. This forms the final part of the storage path: `/`. * `--object-store`: Specifies the type of object store to use. InfluxDB supports the following: * `file`: local file system * `memory`: in memory *(no object persistence)* * `memory-throttled`: like `memory` but with latency and throughput that somewhat resembles a cloud-based object store * `s3`: AWS S3 and S3-compatible services like Ceph or Minio * `google`: Google Cloud Storage * `azure`: Azure Blob Storage * Other object store parameters depending on the selected `object-store` type. For example, if you use `s3`, you must provide the bucket name and credentials. * *(Optional)* `--http-bind`: The address and port for the HTTP API*(default is `0.0.0.0:8181`, which listens on all network interfaces)*. To accept only local connections until you create your first admin token, specify `127.0.0.1:8181`. > [!Caution] > #### Create your admin token before you expose the server > > Until the first admin token exists, the `/api/v3/configure/token/admin`endpoint accepts unauthenticated requests, and the server listens on all > network interfaces by default. > Anyone who can reach the port during that window can claim the operator token > and then use the processing engine to run code on the host. > > Close the window using one of the following methods: > > * Start the server with `--http-bind 127.0.0.1:8181` (with Docker, publish > the port as `127.0.0.1:8181:8181`),[create your admin token](#create-an-operator-token), and then restart the > server on the address you intend to use. > * Block the server port with a firewall until you create the token. > * Start the server with a[preconfigured admin token](/influxdb3/core/admin/tokens/admin/preconfigured/)so the endpoint never accepts unauthenticated requests. > We recommend this method for automated and production deployments. > [!Note] > #### Diskless architecture > > InfluxDB 3 supports a diskless architecture that can operate with object > storage alone, eliminating the need for locally attached disks. > InfluxDB 3 Core can also work with only local disk storage when needed. For this getting started guide, use the `file` object store to persist data to your local disk. ```bash # File system object store # Provide the file system directory influxdb3 serve \ --node-id host01 \ --object-store file \ --data-dir ~/.influxdb3 ``` ### Object store examples [](#file-system-object-store) File system 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 # File system object store # Provide the file system directory influxdb3 serve \ --node-id host01 \ --object-store file \ --data-dir ~/.influxdb3 ``` [](#docker-with-a-mounted-file-system-object-store) Docker with a mounted file system object store To run the [Docker image](/influxdb3/core/install/#pull-the-docker-image) and persist data to the local file system, mount a volume for the object store–for example, provide the following options with your `docker run` command: * `--volume /path/on/host:/path/in/container`: Mounts a directory from your file system to the container * `--object-store file --data-dir /path/in/container`: Uses the volume for object storage ``` # File system object store with Docker # Create a mount # Provide the mount path docker run -it \ --volume /path/on/host:/path/in/container \ influxdb:3-core influxdb3 serve \ --node-id my_host \ --object-store file \ --data-dir /path/in/container ``` > [!Note] > The InfluxDB 3 Core 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/). [](#docker-compose-with-a-mounted-file-system-object-store) Docker compose with a mounted file system object store Open `compose.yaml` for editing and add a `services` entry for InfluxDB 3 Core–for example: ```yaml # compose.yaml services: influxdb3-core: image: influxdb:3-core ports: - 8181:8181 command: - influxdb3 - serve - --node-id=node0 - --object-store=file - --data-dir=/var/lib/influxdb3/data - --plugin-dir=/var/lib/influxdb3/plugins # Optional: only needed for processing engine plugins volumes: - type: bind # Path to store data on your host system source: ~/.influxdb3/data # Path to store data in the container target: /var/lib/influxdb3/data - type: bind # Path to store plugins on your host system source: ~/.influxdb3/plugins # Path to store plugins in the container target: /var/lib/influxdb3/plugins ``` Use the Docker Compose CLI to start the server–for example: ```bash docker compose pull && docker compose up influxdb3-core ``` The command pulls the latest InfluxDB 3 Core Docker image and starts`influxdb3` in a container with host port `8181` mapped to container port`8181`, the server default for HTTP connections. > [!Tip] > #### Custom port mapping > > To customize your `influxdb3` server hostname and port, specify the[`--http-bind` option or the `INFLUXDB3_HTTP_BIND_ADDR` environment variable](/influxdb3/core/reference/config-options/#http-bind). > > For more information about mapping your container port to a specific host port, see the > Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/). [](#s3-object-storage) S3 object storage 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 # Specify the object store type and associated options influxdb3 serve \ --node-id host01 \ --object-store s3 \ --bucket OBJECT_STORE_BUCKET \ --aws-default-region AWS_REGION \ --aws-access-key-id AWS_ACCESS_KEY_ID \ --aws-secret-access-key AWS_SECRET_ACCESS_KEY ``` > [!Note] > If not specified, `--aws-default-region` defaults to `us-east-1`. > Specify a different region if your bucket is in another AWS region to avoid redirect errors. ```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 ``` [](#memory-based-object-store) Memory-based 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/core/reference/cli/influxdb3/serve/): ```bash influxdb3 serve --help ``` > [!Tip] > #### Use the InfluxDB 3 Explorer query interface > > You can complete the remaining steps in this guide using InfluxDB 3 Explorer, > the web-based query and administrative interface for InfluxDB 3. > Explorer provides visual management of databases and tokens and an > easy way to write and query your time series data. > > For more information, see the [InfluxDB 3 Explorer documentation](/influxdb3/explorer/). ## Set up authorization InfluxDB 3 Core uses token-based authorization to authorize actions in the database. Authorization is enabled by default when you start the server. With authorization enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests. InfluxDB 3 Core supports *admin* tokens, which grant access to all CLI actions and API endpoints. > [!Tip] > ### Preconfigured admin tokens for automated deployments > > For CI/CD pipelines or automated deployments, you can start InfluxDB 3 Core with a preconfigured admin token file instead of creating tokens manually after startup. > For more information, see [Use a preconfigured admin token](/influxdb3/core/admin/tokens/admin/preconfigured/). ### Create an 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 create token` command](/influxdb3/core/reference/cli/influxdb3/create/token/)with the `--admin` option to create your operator token: #### CLI #### ```bash influxdb3 create token --admin ``` ```bash # With Docker — in a new terminal: docker exec -it CONTAINER_NAME influxdb3 create token --admin ``` Replace `CONTAINER_NAME` with the name of your running Docker container. The command returns a token string for authenticating CLI commands and API requests. > [!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. Now that an admin token exists, the server requires a token for all requests. If you started the server on `127.0.0.1` to protect the[bootstrap window](#start-influxdb), you can now restart it on the address you want to use–for example, `--http-bind IP_ADDRESS:8181` to listen on a specific interface, or omit `--http-bind` to listen on all interfaces (default is`--http-bind 0.0.0.0:8181`). ### Set your token for authorization Use your operator token to authenticate server actions in InfluxDB 3 Core, such as performing administrative tasks and writing and querying data. #### Authorize CLI commands Use one of the following methods to provide your token and authenticate `influxdb3` CLI commands. In your command, replace `YOUR_AUTH_TOKEN` with your token string (for example, the [operator token](#create-an-operator-token) from the previous step). ##### Set an environment variable (recommended) #### macOS and Linux #### ```bash export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ```powershell $env:INFLUXDB3_AUTH_TOKEN = "YOUR_AUTH_TOKEN" ``` ``` set INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN # Make sure to include a space character at the end of this command. ``` ##### Use the `--token` option ```bash influxdb3 show databases --token YOUR_AUTH_TOKEN ``` #### Authorize HTTP API requests For HTTP API requests, include your token in the `Authorization` header–for example: ```bash curl "http://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer YOUR_AUTH_TOKEN" ``` #### Learn more about tokens and permissions * [Manage admin tokens](/influxdb3/core/admin/tokens/admin/) - Understand and manage operator and named admin tokens * [Authentication](/influxdb3/core/reference/internals/authentication/) - Understand authentication, authorizations, and permissions in InfluxDB 3 Core [Get started](/influxdb3/core/get-started/)[Write data](/influxdb3/core/get-started/write/) #### Related * [Install InfluxDB 3 Core](/influxdb3/core/install/) * [Manage tokens](/influxdb3/core/admin/tokens/) * [Use the InfluxDB 3 MCP server](/influxdb3/core/admin/mcp-server/) * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) --- # Write data to InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/get-started/write/ InfluxDB 3 Core is designed for high write-throughput and uses an efficient, human-readable write syntax called *[line protocol](#line-protocol)*. InfluxDB is a schema-on-write database, meaning you can start writing data and InfluxDB creates the logical database, tables, and their schemas automatically, without any required intervention. Once InfluxDB creates the schema, it validates future write requests against the schema before accepting new data. Both new tags and fields can be added later as your schema changes. > [!Note] > #### InfluxDB 3 Core is optimized for recent data > > InfluxDB 3 Core 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/). * [Line protocol](#line-protocol) * [Construct line protocol](#construct-line-protocol) * [Write data using the CLI](#write-data-using-the-cli) * [Other tools for writing data](#other-tools-for-writing-data) ## Line protocol InfluxDB 3 Core accepts data in[line protocol](/influxdb3/core/reference/syntax/line-protocol/) syntax. Line protocol consists of the following elements: \* Required * \* **table**: A string that identifies the[table](/influxdb3/core/reference/glossary/#table) to store the data in. * **tag set**: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. *Spaces, commas, and equal characters must be escaped.* * \* **field set**: Comma-delimited list of key value pairs, each representing a field. Field keys are unquoted strings. *Spaces and commas must be escaped.*Field values can be one of the following types: * [strings](/influxdb3/clustered/reference/syntax/line-protocol/#string) (quoted) * [floats](/influxdb3/clustered/reference/syntax/line-protocol/#float) * [integers](/influxdb3/clustered/reference/syntax/line-protocol/#integer) * [unsigned integers](/influxdb3/clustered/reference/syntax/line-protocol/#uinteger) * [booleans](/influxdb3/clustered/reference/syntax/line-protocol/#boolean) * **timestamp**: [Unix timestamp](/influxdb3/clustered/reference/syntax/line-protocol/#unix-timestamp)associated with the data. InfluxDB supports up to nanosecond precision. [](#how-are-influxdb-line-protocol-elements-parsed) How are InfluxDB line protocol elements parsed? * **table**: Everything before the *first unescaped comma before the first whitespace*. * **tag set**: Key-value pairs between the *first unescaped comma* and the *first unescaped whitespace*. * **field set**: Key-value pairs between the *first and second unescaped whitespaces*. * **timestamp**: Integer value after the *second unescaped whitespace*. * Lines are separated by the newline character (`\n`). Line protocol is whitespace sensitive. *For schema design recommendations, see[InfluxDB schema design recomendations](/influxdb3/core/write-data/best-practices/schema-design/).* myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 ## Construct line protocol With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB 3 Core. Consider a use case where you collect data from sensors in your home. Each sensor collects temperature, humidity, and carbon monoxide readings. To collect this data, use the following schema: * **table**: `home` * **tags** * `room`: Living Room or Kitchen * **fields** * `temp`: temperature in °C (float) * `hum`: percent humidity (float) * `co`: carbon monoxide in parts per million (integer) * **timestamp**: Unix timestamp in *second* precision The following line protocol sample represents data collected hourly beginning at**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**.*These timestamps are dynamic and can be updated by clicking the icon in the bottom right corner.* ##### Home sensor data line protocol ```text home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ``` ## Write data using the CLI To quickly get started writing data, use the[`influxdb3 write` command](/influxdb3/core/reference/cli/influxdb3/write/). Include the following: * `--database` option that identifies the target database * `--token` option that specifies the token to use *(unless the `INFLUXDB3_AUTH_TOKEN`environment variable is already set)* * Quoted line protocol data via standard input (stdin) ```bash influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --precision s \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' ``` In the code samples, replace the following placeholders with your values: * `DATABASE_NAME`: the name of the [database](/influxdb3/core/admin/databases/) to write to * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ### Write data from a file To write line protocol you have saved to a file, pass the `--file` option–for example, save the[sample line protocol](#home-sensor-data-line-protocol) to a file named `sensor_data`and then enter the following command: ``` influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --precision s \ --accept-partial \ --file path/to/sensor_data ``` Replace the following placeholders with your values: * `DATABASE_NAME`: the name of the [database](/influxdb3/core/admin/databases/) to write to. * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ## Other tools for writing data There are many ways to write data to your InfluxDB 3 Core database, including: * [InfluxDB HTTP API](/influxdb3/core/write-data/http-api/): Recommended for batching and higher-volume write workloads. * [InfluxDB client libraries](/influxdb3/core/write-data/client-libraries/): Client libraries that integrate with your code to construct data as time series points and write the data as line protocol to your InfluxDB 3 Core database. * [Telegraf](/telegraf/v1/): A data collection agent with over 300 plugins for collecting, processing, and writing data. For more information, see [Write data to InfluxDB 3 Core](/influxdb3/core/write-data/). [Set up InfluxDB](/influxdb3/core/get-started/setup/)[Query data](/influxdb3/core/get-started/query/) #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/write-data/) * [Line protocol reference](/influxdb3/core/reference/line-protocol/) --- # Install InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/install/ > [!Note] > #### Upgrade to InfluxDB 3 Enterprise > > If you want to upgrade from InfluxDB 3 Core to InfluxDB 3 Enterprise > for features like high availability, read replicas, and historical query capability, > see [Upgrade to Enterprise](/influxdb3/core/admin/upgrade-to-enterprise/). * [System Requirements](#system-requirements) * [Install](#install) * [Quick install for Linux and macOS](#quick-install-for-linux-and-macos) * [Download and install the latest build artifacts](#download-and-install-the-latest-build-artifacts) * [Pull the Docker image](#pull-the-docker-image) * [Linux DEB or RPM](#linux-deb-or-rpm) * [TOML configuration (Linux)](#toml-configuration-linux) * [Run as a system service (Linux)](#run-as-a-system-service-linux) * [Verify the installation](#verify-the-installation) ## System Requirements #### Operating system InfluxDB 3 Core runs on **Linux**, **macOS**, and **Windows**. #### Object storage A key feature of InfluxDB 3 is its use of object storage to store time series data in Apache Parquet format. You can choose to store these files on your local file system. Performance on your local filesystem will likely be better, but object storage has the advantage of not running out of space and being accessible by other systems over the network. InfluxDB 3 Core natively supports Amazon S3, Azure Blob Storage, and Google Cloud Storage. You can also use many local object storage implementations that provide an S3-compatible API, such as [Minio](https://min.io/). ## Install InfluxDB 3 Core runs on **Linux**, **macOS**, and **Windows**. Choose one of the following methods to install InfluxDB 3 Core: * [Quick install for Linux and macOS](#quick-install-for-linux-and-macos) * [Download and install the latest build artifacts](#download-and-install-the-latest-build-artifacts) * [Pull the Docker image](#pull-the-docker-image) * [Linux DEB or RPM](#linux-deb-or-rpm) ### Quick install for Linux and macOS To install InfluxDB 3 Core on **Linux** or **macOS**, download and run the quick installer script for InfluxDB 3 Core–for example, using [`curl`](https://curl.se/)to download the script: ```bash curl -O https://www.influxdata.com/d/install_influxdb3.sh \ && sh install_influxdb3.sh ``` > [!Note] > The quick installer script is updated with each InfluxDB 3 Core release, > so it always installs the latest version. > [!Important] > #### Production deployment > > For production deployments, use [Linux DEB or RPM](#linux-deb-or-rpm)for built-in systemd sandboxing, or [Docker](#pull-the-docker-image) with your own > container security configuration. > > For detailed security options, see [Manage security](/influxdb3/core/admin/security/). ### Download and install the latest build artifacts You can also download and install InfluxDB 3 Core build artifacts directly: [](#linux-binaries) Linux binaries * [Linux | AMD64 (x86\_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_linux_amd64.tar.gz)•[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_linux_amd64.tar.gz.sha256) * [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_linux_arm64.tar.gz)•[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_linux_arm64.tar.gz.sha256) [](#macos-binaries) macOS binaries * [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_darwin_arm64.tar.gz)•[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2_darwin_arm64.tar.gz.sha256) > [!Note] > macOS Intel builds are coming soon. [](#windows-binaries) Windows binaries * [Windows (AMD64, x86\_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2-windows_amd64.zip)•[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.11.2-windows_amd64.zip.sha256) ### Pull the Docker image Run the following command to pull the [`influxdb:3-core` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-core), available for x86\_64 (AMD64) and ARM64 architectures: ```bash docker pull influxdb:3-core ``` Docker automatically pulls the appropriate image for your system architecture. [](#pull-for-a-specific-system-architecture) Pull for a specific system architecture To specify the system architecture, use platform-specific tags–for example: ```bash # For x86_64/AMD64 docker pull \ --platform linux/amd64 \ influxdb:3-core ``` ```bash # For ARM64 docker pull \ --platform linux/arm64 \ influxdb:3-core ``` [](#pin-to-a-specific-version) Pin to a specific version The `3-core` tag always points to the latest 3.x release. To keep a deployment on a fixed version, pull a version-specific tag instead: ```bash # Pin to a specific patch release docker pull influxdb:3.11.2-core # Pin to the latest patch in a minor series--for example, 3.10 docker pull influxdb:3.10-core ``` To browse recent InfluxDB 3 image tags (Core and Enterprise), newest first, see[`influxdb` tags on Docker Hub](https://hub.docker.com/_/influxdb/tags?name=3.&ordering=last_updated). ### Linux DEB or RPM When installed via DEB or RPM on a `systemd`-enabled system, InfluxDB 3 Core runs in a sandboxed environment. The included `systemd` unit file configures the environment to provide security isolation for typical deployments. For more information, see [Manage security](/influxdb3/core/admin/security/). > [!Note] > DEB and RPM installation is **recommended for non-Docker production deployments** due to built-in `systemd` sandboxing. [](#deb-based-systems) DEB-based systems Use `apt-get` to install InfluxDB 3 Core from the InfluxData repository: ```bash curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \ | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \ && cat influxdata-archive.key \ | gpg --dearmor \ | sudo tee /usr/share/keyrings/influxdata-archive.gpg > /dev/null \ && echo 'deb [signed-by=/usr/share/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \ | sudo tee /etc/apt/sources.list.d/influxdata.list sudo apt-get update && sudo apt-get install influxdb3-core ``` [](#rpm-based-systems) RPM-based systems Use `yum` to install InfluxDB 3 Core from the InfluxData repository: ```bash curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key test -d /usr/share/influxdata-archive-keyring/keyrings || sudo mkdir -p /usr/share/influxdata-archive-keyring/keyrings gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \ | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \ && sudo cp ./influxdata-archive.key /usr/share/influxdata-archive-keyring/keyrings/influxdata-archive.asc \ && cat < [!Note] > The following examples use `sudo` for systems that require elevated privileges. > On some systems (such as Amazon Linux or other RHEL-based distributions where you may already be running as root), you can omit `sudo` from the commands. ```bash # Start the service sudo systemctl start influxdb3-core # Stop the service sudo systemctl stop influxdb3-core # Restart the service (use after configuration changes) sudo systemctl restart influxdb3-core ``` ###### Check status and logs ```bash # Check status (sudo to ensure full journal output) sudo systemctl status influxdb3-core # Quick state checks (no sudo needed) systemctl is-enabled influxdb3-core systemctl is-active influxdb3-core # Recent logs sudo journalctl --unit influxdb3-core -n 200 --no-pager # Follow logs sudo journalctl --unit influxdb3-core -f ``` ###### Inspect the packaged unit The packaged unit configures security sandboxing for typical deployments (see [Manage security](/influxdb3/core/admin/security/)). To inspect the packaged unit and its resolved properties: ```bash # Show the unit file systemctl cat influxdb3-core # Show all resolved properties (paths, environment, sandboxing options) systemctl show influxdb3-core ``` ###### Apply configuration changes Edit the TOML configuration file and restart the service to apply changes: ```bash sudoedit /etc/influxdb3/influxdb3-core.conf sudo systemctl restart influxdb3-core sudo systemctl status influxdb3-core sudo journalctl --unit influxdb3-core -n 100 --no-pager ``` `influxdb3 serve` does not support configuration reload; a restart is required after editing the TOML file or changing environment variables. The TOML file is read by the systemd launcher and converted to`INFLUXDB3_*` environment variables before `influxdb3 serve` runs; CLI flags still override values from the TOML file. For details, see[TOML configuration files](/influxdb3/core/reference/config-options/#toml-configuration-files). ##### Run using SysV On SysV init systems, `influxdb3-core` is disabled on install and can be enabled by adjusting `/etc/default/influxdb3-core` to contain `ENABLED=yes`. To start the database, enter the following commands: ```bash # Start the database /etc/init.d/influxdb3-core start # View status /etc/init.d/influxdb3-core status # View logs tail -f /var/lib/influxdb3/influxdb3-core.log ``` ### Verify the installation After installing InfluxDB 3 Core, enter the following command to verify that it installed successfully: ```bash influxdb3 --version ``` If your system can’t locate `influxdb3` following a [quick install](#quick-install-for-linux-and-macos), `source` the configuration file (for example, `.bashrc`, `.zshrc`) for your shell–for example: ```zsh source ~/.zshrc ``` [Get started with InfluxDB 3 Core](/influxdb3/core/get-started/) #### Related * [Upgrade InfluxDB 3 Core](/influxdb3/core/admin/upgrade/) [install](/influxdb3/core/tags/install/) --- # Configure object storage Source: https://docs.influxdata.com/influxdb3/core/object-storage/ InfluxDB 3 Core can be configured to use different object storage providers to store time series data in Parquet format. The process of configuring and connecting to different object storage providers varies. The following guides walk through configuring, connecting to, and using different object storage providers as your InfluxDB 3 Core object store. ### [MinIO](/influxdb3/core/object-storage/minio/) Use [MinIO](https://min.io) as the object store for your InfluxDB 3 Core instance. InfluxDB uses the MinIO S3-compatible API to interact with your MinIO server or cluster. #### Related * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) [object storage](/influxdb3/core/tags/object-storage/)[S3](/influxdb3/core/tags/s3/) --- # Use MinIO for object storage Source: https://docs.influxdata.com/influxdb3/core/object-storage/minio/ Use [MinIO](https://min.io) as the Object store for your InfluxDB 3 Core instance. InfluxDB uses the MinIO S3-compatible API to interact with your MinIO server or cluster. > > > MinIO is a high-performance, S3-compatible object storage solution released > under the GNU AGPL v3.0 license. Designed for speed and scalability, it powers > AI/ML, analytics, and data-intensive workloads with industry-leading performance. > > > > [MinIO GitHub repository](https://github.com/minio/minio?tab=readme-ov-file#readme) > > MinIO provides both an open source version ([MinIO Community Edition](https://min.io/open-source/download)) and an enterprise version ([MinIO AIStor](https://min.io/download)). While both can be used as your InfluxDB 3 Core object store,**this guide walks through using MinIO Community Edition**. * [Object store requirements](#object-store-requirements) * [Set up MinIO](#set-up-minio) * [Configure InfluxDB to connect to MinIO](#configure-influxdb-to-connect-to-minio) * [Confirm the object store is working](#confirm-the-object-store-is-working) ## Object store requirements InfluxDB 3 Core uses the object store as the source of truth for catalog state. The catalog write path relies on conditional PUT (PUT-if-not-exists) to serialize catalog log writes, and every node depends on immediate visibility of writes made by any other node. Your MinIO deployment must provide the object store semantics InfluxDB 3 Core depends on. ### Consistency semantics InfluxDB 3 Core requires at least the following from any S3-compatible object store, including MinIO: * **Strong read-after-write consistency**: a `GET` immediately after a successful `PUT` returns the new object. * **Strong list-after-write consistency**: a `LIST` immediately after a successful `PUT` includes the new key. * **Conditional PUT (PUT-if-not-exists) semantics**: concurrent creates of the same key serialize so that exactly one write succeeds and the other returns`AlreadyExists`. A backend that violates these semantics can cause catalog split-brain, stale reads on node startup, and unexpected node-state warnings. > [!Note] > Deploy MinIO on locally attached storage formatted with a POSIX-strong > filesystem such as XFS. > Avoid NFS-backed storage and topologies where multiple MinIO instances share > the same backing volume—both can violate the consistency semantics > InfluxDB 3 Core depends on. > See MinIO’s[deployment guidance](https://min.io/docs/minio/linux/operations/installation.html)for details. ### Verify your object store InfluxDB 3 Core 3.10.0 and later includes the[`influxdb3 debug object-store-check`](/influxdb3/core/reference/cli/influxdb3/debug/object-store-check/)command that validates an object store against the preceding semantic requirements. Run it against your MinIO endpoint before putting the deployment into production, and again after any change to the MinIO topology or backing storage: ```bash influxdb3 debug object-store-check \ --object-store s3 \ --bucket influxdb3 \ --aws-endpoint http://localhost:9000 \ --aws-access-key-id MINIO_USERNAME \ --aws-secret-access-key MINIO_PASSWORD \ --aws-allow-http \ --check-prefix oscheck ``` The tool confines all writes to `/oscheck-/` and reports any semantic violation it finds. If the synthetic checks pass but a real catalog is still failing to load, pass `--probe-prefix ` to replay the loader’s object store operations against your real catalog in read-only mode. See [`influxdb3 debug object-store-check`](/influxdb3/core/reference/cli/influxdb3/debug/object-store-check/)for the full flag reference. ## Set up MinIO 1. **Install and deploy a MinIO server or cluster**. You can install MinIO locally for testing and development or you can deploy a production MinIO cluster across multiple machines. The MinIO documentation provides detailed instructions for installing and deploying MinIO based on your target operating system: * [Install and deploy MinIO on **Linux**](https://min.io/docs/minio/linux/operations/installation.html)*(recommended for production deployments)* * [Install and deploy MinIO with **Kubernetes**](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html) * [Install and deploy MinIO with **Docker**](https://min.io/docs/minio/container/operations/installation.html) * [Install and deploy MinIO on **macOS**](https://min.io/docs/minio/macos/operations/installation.html) * [Install and deploy MinIO on **Windows**](https://min.io/docs/minio/windows/operations/installation.html) 2. **Download and install the MinIO Client (`mc`)**. The MinIO client, or `mc` CLI, lets you perform administrative tasks on your MinIO server or cluster like creating users, assigning access policies, and more. Download and install the `mc` CLI for your local operating system and architecture. [See the **MinIO Client** section of the MinIO downloads page](https://min.io/open-source/download). 3. **Configure the `mc` CLI to connect to your MinIO server or cluster**. The `mc` CLI uses “aliases” to connect to a MinIO server or cluster. The alias refers to a set of connection credentials used to connect to and authorize with your MinIO server. Use the `mc alias set` command and provide the following: * **Alias**: A unique name or identifier for this credential set (`ALIAS`) * **MinIO URL**: The URL of your MinIO server or cluster (`https://localhost:9000`if running locally) * **Root username:** The root username you specified when setting up your MinIO server or cluster (`ROOT_USERNAME`) * **Root password**: The root password you specified when setting up your MinIO server or cluster (`ROOT_PASSWORD`) ``` mc alias set ALIAS http://localhost:9000 ROOT_USERNAME ROOT_PASSWORD ``` 4. **Create a MinIO bucket**. Use the *MinIO Console* or the *`mc mb` command* to create a new bucket in your MinIO server or cluster. #### MinIO Console #### The MinIO Console is a graphical user interface that lets you manage and browse buckets in your MinIO server or cluster. By default, the console is served on port`9001`. If running MinIO on your local machine, visit [http://localhost:9001](http://localhost:9001)to access the MinIO Console. If MinIO is running on a remote server, use your custom domain or IP to access the MinIO console. 1. In the Minio Console, click **Create Bucket**. 2. Enter a bucket name. For this guide, use `influxdb3`. 3. Click **Create Bucket**. Use the `mc mb` command to create a new MinIO bucket named `influxdb3`. Provide the MinIO alias configured in [step 3](#configure-alias) and the bucket name using the `ALIAS/BUCKET_NAME` syntax–for example: ``` mc mb ALIAS/influxdb3 ``` 5. **Create a MinIO user**. Use the `mc admin user add` command to create a new user. Provide the following: * **MinIO alias**: The MinIO server alias (created in [step 3](#configure-alias)) to add the user to (`ALIAS`) * **Username**: A unique username for the user (`MINIO_USERNAME`) * **Password**: A password for the user (`MINIO_PASSWORD`) ``` mc admin user add ALIAS MINIO_USERNAME MINIO_PASSWORD ``` MinIO user credentials are equivalent to credentials you would typically use to authorize with AWS S3: * A MinIO username is equivalent to an AWS access key ID * A MinIO password is equivalent to an AWS secret key 6. **Create an access policy that grants full access to the `influxdb3` bucket**. MinIO uses S3 compatible access policies to authorize access to buckets. To create a new access policy: 1. Create a file named `influxdb3-policy.json` that contains the following JSON: ``` { "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetBucketLocation", "s3:ListBucket" ], "Effect": "Allow", "Resource": ["arn:aws:s3:::influxdb3"] }, { "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Effect": "Allow", "Resource": ["arn:aws:s3:::influxdb3/*"] } ] } ``` 2. Use the `mc admin policy create` command to create the new access policy in your MinIO server or cluster. Provide the following: * **MinIO alias**: The MinIO server alias (created in [step 3](#configure-alias)) to add the access policy to (`ALIAS`) * **Policy name**: A unique name for the policy (`POLICY_NAME`) * **Policy file**: The relative or absolute file path of your`influxdb3-policy.json` policy file (`/path/to/influxdb3-policy.json`) ``` mc admin policy create \ ALIAS \ POLICY_NAME \ /path/to/influxdb3-policy.json ``` 7. **Attach the access policy to your user.** Use the `mc admin policy attach` command to attach the access policy to your user. MinIO supports attaching access policies to both users and user groups. All users in a user group inherit policies attached to the group. For information about managing MinIO user groups, see[MinIO Group Management](https://min.io/docs/minio/linux/administration/identity-access-management/minio-group-management.html). Provide the following: * **MinIO alias**: The MinIO server alias created in [step 3](#configure-alias)(`ALIAS`) * **Policy name**: A unique username for the user (`POLICY_NAME`) * **Username** or **group name**: The user or user group to assign the policy to (`MINIO_USERNAME` or`MINIO_GROUP_NAME`) #### user #### ``` mc admin policy attach ALIAS POLICY_NAME --user MINIO_USERNAME ``` ``` mc admin policy attach ALIAS POLICY_NAME --group MINIO_GROUP_NAME ``` Your MinIO server or cluster is now set up and ready to be used with InfluxDB 3 Core. ## Configure InfluxDB to connect to MinIO To use your MinIO server or cluster as the object store for your InfluxDB 3 Core instance, provide the following options or environment variables with the`influxdb3 serve` command: #### Command options #### * `--node-id`: Your InfluxDB 3 Core node ID (`INFLUXDB_NODE_ID`) * `--object-store`: `s3` * `--bucket`: `influxdb3` * `--aws-endpoint`: Your MinIO URL (`http://localhost:9000` if running locally) * `--aws-access-key-id`: Your MinIO username (`MINIO_USERNAME`) * `--aws-secret-access-key`: Your MinIO password (`MINIO_PASSWORD`) * `--aws-allow-http`: *(Optional)* Include if *not* using HTTPS to connect to your MinIO server or cluster ``` influxdb3 serve \ --node-id INFLUXDB_NODE_ID \ --object-store s3 \ --bucket influxdb3 \ --aws-endpoint http://localhost:9000 \ --aws-access-key-id MINIO_USERNAME \ --aws-secret-access-key MINIO_PASSWORD \ --aws-allow-http ``` * `INFLUXDB3_NODE_ID`: Your InfluxDB 3 Core node ID (`INFLUXDB_NODE_ID`) * `INFLUXDB3_OBJECT_STORE`: `s3` * `INFLUXDB3_BUCKET`: `influxdb3` * `AWS_ENDPOINT`: Your MinIO URL (`http://localhost:9000` if running locally) * `AWS_ACCESS_KEY_ID`: Your MinIO username (`MINIO_USERNAME`) * `AWS_SECRET_ACCESS_KEY`: Your MinIO password (`MINIO_PASSWORD`) * `AWS_ALLOW_HTTP`: *(Optional)* Set to `true` if *not* using HTTPS to connect to your MinIO server or cluster (default is `false`) ``` export INFLUXDB3_NODE_ID=INFLUXDB_NODE_ID export INFLUXDB3_OBJECT_STORE=s3 export INFLUXDB3_BUCKET=influxdb3 export AWS_ENDPOINT=http://localhost:9000 export AWS_ACCESS_KEY_ID=MINIO_USERNAME export AWS_SECRET_ACCESS_KEY=MINIO_PASSWORD export AWS_ALLOW_HTTP=true influxdb3 serve ``` ## Confirm the object store is working When InfluxDB 3 Core starts, it will seed your MinIO object store with the necessary directory structure and begin storing data there. Confirm the object store is functioning properly: 1. View the `influxdb3 serve` log output to confirm that the server is running correctly. 2. Inspect the contents of your MinIO `influxdb3` bucket to confirm that the necessary directory structure is created. You can use the **MinIO Console**or the **`mc ls` command** to view the contents of a bucket–for example: ``` mc ls ALIAS/influxdb3 ``` #### Related * [Install and Deploy MinIO](https://min.io/docs/minio/linux/operations/installation.html) * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) [object storage](/influxdb3/core/tags/object-storage/)[S3](/influxdb3/core/tags/s3/) --- # Processing engine and Python plugins Source: https://docs.influxdata.com/influxdb3/core/plugins/ Use the Processing Engine in InfluxDB 3 Core to extend your database with custom Python code. Trigger your code on write, on a schedule, or on demand to automate workflows, transform data, and create API endpoints. ## What is the Processing Engine? The Processing Engine is an embedded Python virtual machine that runs inside your InfluxDB 3 Core database. You configure *triggers* to run your Python *plugin* code in response to: * **Data writes** - Process and transform data as it enters the database * **Scheduled events** - Run code at defined intervals or specific times * **HTTP requests** - Expose custom API endpoints that execute your code You can use the Processing Engine’s in-memory cache to manage state between executions and build stateful applications directly in your database. This guide walks you through setting up the Processing Engine, creating your first plugin, and configuring triggers that execute your code on specific events. ## Before you begin Ensure you have: * A working InfluxDB 3 Core instance * Access to command line * Python installed if you’re writing your own plugin * Basic knowledge of the InfluxDB CLI Once you have all the prerequisites in place, follow these steps to implement the Processing Engine for your data automation needs. * [Set up the Processing Engine](#set-up-the-processing-engine) * [Add a Processing Engine plugin](#add-a-processing-engine-plugin) * [Upload plugins from local machine](#upload-plugins-from-local-machine) * [Update existing plugins](#update-existing-plugins) * [View loaded plugins](#view-loaded-plugins) * [Create a trigger](#create-a-trigger) * [Manage plugin dependencies](#manage-plugin-dependencies) * [Plugin security](#plugin-security) ## Set up the Processing Engine The Processing Engine activates when `--plugin-dir` or `INFLUXDB3_PLUGIN_DIR` is configured. ### Default behavior by deployment type | Deployment |Default state| Configuration | |----------------|-------------|-----------------------------------------| | Docker images | **Enabled** | `INFLUXDB3_PLUGIN_DIR=/plugins` | |DEB/RPM packages| **Enabled** |`plugin-dir="/var/lib/influxdb3/plugins"`| | Binary/source | Disabled | No `plugin-dir` configured | If you installed InfluxDB 3 Core using Docker or a DEB/RPM package, the Processing Engine is already enabled—skip to [Add a Processing Engine plugin](#add-a-processing-engine-plugin). To disable the Processing Engine, see [Enable and disable the Processing Engine](/influxdb3/core/reference/processing-engine/#enable-and-disable-the-processing-engine). ### Enable the Processing Engine manually To activate the Processing Engine when running from a binary or source build, start your InfluxDB 3 Core server with the `--plugin-dir` flag. This flag tells InfluxDB where to load your plugin files. > [!Important] > #### Keep the influxdb3 binary with its python directory > > The influxdb3 binary requires the adjacent `python/` directory to function. > If you manually extract from tar.gz, keep them in the same parent directory: > > ``` > your-install-location/ > ├── influxdb3 > └── python/ > ``` > > Add the parent directory to your PATH; do not move the binary out of this directory. ```bash influxdb3 serve \ --NODE_ID \ --object-store OBJECT_STORE_TYPE \ --plugin-dir PLUGIN_DIR ``` In the example above, replace the following: * `NODE_ID`: Unique identifier for your instance * `OBJECT_STORE_TYPE`: Type of object store (for example, file or s3) * `PLUGIN_DIR`: Absolute path to the directory where plugin files are stored. Store all plugin files in this directory or its subdirectories. > [!Note] > #### Use custom plugin repositories > > By default, plugins referenced with the `gh:` prefix are fetched from the official[influxdata/influxdb3\_plugins](https://github.com/influxdata/influxdb3_plugins) repository. > To use a custom repository, add the `--plugin-repo` flag when starting the server. > See [Use a custom plugin repository](#option-3-use-a-custom-plugin-repository) for details. ### Configure distributed environments When running InfluxDB 3 Core in a distributed setup, follow these steps to configure the Processing Engine: 1. Decide where each plugin should run * Data processing plugins, such as WAL plugins, run on ingester nodes * HTTP-triggered plugins run on nodes handling API requests * Scheduled plugins can run on any configured node 2. Enable plugins on the correct instance 3. Maintain identical plugin files across all instances where plugins run * Use shared storage or file synchronization tools to keep plugins consistent > [!Note] > #### Provide plugins to nodes that run them > > Configure your plugin directory on the same system as the nodes that run the triggers and plugins. ## Add a Processing Engine plugin A plugin is a Python script that defines a function with a trigger-compatible (*trigger spec*) signature. When the specified event occurs, InfluxDB runs the plugin. ### Choose a plugin strategy You have two main options for adding plugins to your InfluxDB instance: * [Use example plugins](#use-example-plugins) - Get started with prebuilt plugins * [Create a custom plugin](#create-a-custom-plugin) - Build your own for specialized use cases ### Use example plugins InfluxData maintains a repository of official and community plugins that you can use immediately in your Processing Engine setup. Browse the [plugin library](/influxdb3/core/plugins/library/) to find examples and InfluxData official plugins for: * **Data transformation**: Process and transform incoming data * **Alerting**: Send notifications based on data thresholds * **Aggregation**: Calculate statistics on time series data * **Integration**: Connect to external services and APIs * **System monitoring**: Track resource usage and health metrics For community contributions, see the [influxdb3\_plugins repository](https://github.com/influxdata/influxdb3_plugins) on GitHub. #### Add example plugins You have two options for using plugins from the repository: ##### Option 1: Copy plugins locally Clone the `influxdata/influxdb3_plugins` repository and copy plugins to your configured plugin directory: ``` # Clone the repository git clone https://github.com/influxdata/influxdb3_plugins.git # Copy a plugin to your configured plugin directory cp influxdb3_plugins/influxdata/system_metrics/system_metrics.py /path/to/plugins/ ``` ##### Option 2: Reference plugins directly from GitHub Skip downloading plugins by referencing them directly from GitHub using the `gh:` prefix: ```bash # Create a trigger using a plugin from GitHub influxdb3 create trigger \ --trigger-spec "every:1m" \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --database my_database \ system_metrics ``` This approach: * Ensures you’re using the latest version * Simplifies updates and maintenance * Reduces local storage requirements **Syntax:** ``` gh: ``` The path after `gh:` is appended to the configured `--plugin-repo`. > [!Note] > #### The gh: prefix isn’t GitHub-specific > > Despite the name, `gh:` doesn’t require GitHub or a Git repository. `--plugin-repo` accepts any HTTP/HTTPS URL that serves raw plugin files–for example, an internal static file host or object storage endpoint. `gh:` just tells InfluxDB 3 Core to fetch the plugin remotely from that URL instead of reading it from the local `--plugin-dir`. By default, `gh:`-prefixed plugins resolve against the official [`influxdata/influxdb3_plugins`](https://github.com/influxdata/influxdb3_plugins) repository at `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/`. For example, `gh:examples/wal_plugin/wal_plugin.py` resolves to: ``` https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/examples/wal_plugin/wal_plugin.py ``` **How `gh:` plugin resolution works:** 1. InfluxDB 3 Core detects the `gh:` prefix in the plugin path. 2. It strips the prefix and appends the remaining path to the configured plugin repository URL. 3. An HTTP `GET` request fetches the plugin source code. 4. If the fetch succeeds (HTTP 2xx), InfluxDB 3 Core validates the plugin and creates the trigger. 5. If the fetch fails, the command returns an error with the HTTP status code and URL–for example: ``` error fetching plugin from repository: 404 Not Found https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/not_found.py ``` InfluxDB 3 Core fetches the plugin at trigger creation time (to validate it), and again each time the trigger starts–for example, on server startup or when you re-enable a disabled trigger. Unlike local plugins, GitHub plugins aren’t automatically reloaded when the source changes–disable and re-enable the trigger to fetch updates. Only single-file plugins are supported through the `gh:` prefix; multi-file plugin directories must be uploaded locally (see [Upload plugins from local machine](#upload-plugins-from-local-machine)). ##### Option 3: Use a custom plugin repository For organizations that maintain their own plugin repositories or need to use private/internal plugins, configure a custom plugin repository URL: ```bash # Start the server with a custom plugin repository influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins \ --plugin-repo "https://internal.company.com/influxdb-plugins/" ``` Then reference plugins from your custom repository using the `gh:` prefix: ```bash # Fetches from: https://internal.company.com/influxdb-plugins/myorg/custom_plugin.py influxdb3 create trigger \ --trigger-spec "every:5m" \ --path "gh:myorg/custom_plugin.py" \ --database my_database \ custom_trigger ``` **Use cases for custom repositories:** * **Private plugins**: Host proprietary plugins not suitable for public repositories * **Air-gapped environments**: Use internal mirrors when external internet access is restricted * **Development and staging**: Test plugins from development branches before production deployment * **Compliance requirements**: Meet data governance policies requiring internal hosting The `--plugin-repo` option accepts any HTTP/HTTPS URL that serves raw plugin files. You can also set it with the `INFLUXDB3_PLUGIN_REPO` environment variable. See the [plugin-repo configuration option](/influxdb3/core/reference/config-options/#plugin-repo) for more details. Plugins have various functions such as: * Receive plugin-specific arguments (such as written data, call time, or an HTTP request) * Access keyword arguments (as `args`) passed from *trigger arguments* configurations * Access the `influxdb3_local` shared API to write data, query data, and managing state between executions For more information about available functions, arguments, and how plugins interact with InfluxDB, see how to [Extend plugins](/influxdb3/core/extend-plugin/). ### Create a custom plugin To build custom functionality, you can create your own Processing Engine plugin. #### Prerequisites Before you begin, make sure: * The Processing Engine is enabled on your InfluxDB 3 Core instance. * You’ve configured the `--plugin-dir` where plugin files are stored. * You have access to that plugin directory. #### Steps to create a plugin: * [Choose your plugin type](#choose-your-plugin-type) * [Create your plugin file](#create-your-plugin-file) * [Next Steps](#next-steps) #### Choose your plugin type Choose a plugin type based on your automation goals: | Plugin Type | Best For | |----------------|-------------------------------------------| | **Data write** | Processing data as it arrives | | **Scheduled** |Running code at specific intervals or times| |**HTTP request**| Running code on demand via API endpoints | #### Create your plugin file Plugins now support both single-file and multifile architectures: **Single-file plugins:** * Create a `.py` file in your plugins directory * Add the appropriate function signature based on your chosen plugin type * Write your processing logic inside the function **Multifile plugins:** * Create a directory in your plugins directory * Add an `__init__.py` file as the entry point (required) * Organize supporting modules in additional `.py` files * Import and use modules within your plugin code ##### Example multifile plugin structure ``` my_plugin/ ├── __init__.py # Required - entry point with trigger function ├── utils.py # Supporting module ├── processors.py # Data processing functions └── config.py # Configuration helpers ``` The `__init__.py` file must contain your trigger function: ```python # my_plugin/__init__.py from .processors import process_data from .config import get_settings def process_writes(influxdb3_local, table_batches, args=None): settings = get_settings() for table_batch in table_batches: process_data(influxdb3_local, table_batch, settings) ``` Supporting modules can contain helper functions: ```python # my_plugin/processors.py def process_data(influxdb3_local, table_batch, settings): # Processing logic here pass ``` After writing your plugin, [create a trigger](#create-a-trigger) to connect it to a database event and define when it runs. #### Create a data write plugin Use a data write plugin to process data as it’s written to the database. These plugins use [`table:` or `all_tables:`](#trigger-on-data-writes) trigger specifications. Ideal use cases include: * Data transformation and enrichment * Alerting on incoming values * Creating derived metrics ``` def process_writes(influxdb3_local, table_batches, args=None): # Process data as it's written to the database for table_batch in table_batches: table_name = table_batch["table_name"] rows = table_batch["rows"] # Log information about the write influxdb3_local.info(f"Processing {len(rows)} rows from {table_name}") # Write derived data back to the database line = LineBuilder("processed_data") line.tag("source_table", table_name) line.int64_field("row_count", len(rows)) influxdb3_local.write(line) ``` #### Create a scheduled plugin Scheduled plugins run at defined intervals using [`every:` or `cron:`](#trigger-on-a-schedule) trigger specifications. Use them for: * Periodic data aggregation * Report generation * System health checks ``` def process_scheduled_call(influxdb3_local, call_time, args=None): # Run code on a schedule # Query recent data results = influxdb3_local.query("SELECT * FROM metrics WHERE time > now() - INTERVAL '1 hour'") # Process the results if results: influxdb3_local.info(f"Found {len(results)} recent metrics") else: influxdb3_local.warn("No recent metrics found") ``` #### Create an HTTP request plugin HTTP request plugins respond to API calls using [`request:`](#trigger-on-http-requests) trigger specifications. Use them for: * Creating custom API endpoints * Webhooks for external integrations * User interfaces for data interaction ``` def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None): # Handle HTTP requests to a custom endpoint # Log the request parameters influxdb3_local.info(f"Received request with parameters: {query_parameters}") # Process the request body if request_body: import json data = json.loads(request_body) influxdb3_local.info(f"Request data: {data}") # Return a response (automatically converted to JSON) return {"status": "success", "message": "Request processed"} ``` #### Next steps After writing your plugin: * [Create a trigger](#create-a-trigger) to connect your plugin to database events * [Install any Python dependencies](#manage-plugin-dependencies) your plugin requires * Learn how to [extend plugins with the API](/influxdb3/core/extend-plugin/) ### Upload plugins from local machine For local development and testing, you can upload plugin files directly from your machine when creating triggers. This eliminates the need to manually copy files to the server’s plugin directory. * [Upload a plugin using the influxdb3 CLI](#upload-a-plugin-using-the-influxdb3-cli) * [Upload a plugin using the HTTP API](#upload-a-plugin-using-the-http-api) #### Upload a plugin using the influxdb3 CLI Use the `--upload` flag with `--path` to transfer local files or directories: ```bash # Upload single-file plugin influxdb3 create trigger \ --trigger-spec "every:10s" \ --path "/local/path/to/plugin.py" \ --upload \ --database metrics \ my_trigger # Upload multifile plugin directory influxdb3 create trigger \ --trigger-spec "every:30s" \ --path "/local/path/to/plugin-dir" \ --upload \ --database metrics \ complex_trigger ``` For more information, see the [`influxdb3 create trigger` CLI reference](/influxdb3/core/reference/cli/influxdb3/create/trigger/). #### Upload a plugin using the HTTP API To upload a plugin file using the HTTP API, send a `PUT` request to the `/api/v3/plugins/files` endpoint: ``` PUT http://localhost:8181/api/v3/plugins/files ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your admin token * `Content-Type: application/octet-stream` * **Query parameters**: * `path` *(string, required)*: Path to the plugin file relative to the plugin directory ```bash # Upload a single-file plugin curl -X PUT "http://localhost:8181/api/v3/plugins/files?path=plugin.py" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/octet-stream" \ --data-binary "@/local/path/to/plugin.py" ``` Replace `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/admin) > [!Important] > #### Admin privileges required > > Plugin uploads require an admin token. This security measure prevents unauthorized code execution on the server. **When to use plugin upload:** * Local plugin development and testing * Deploying plugins without SSH access to the server * Rapid iteration on plugin code * Automating plugin deployment in CI/CD pipelines ### Update existing plugins Modify plugin code for running triggers without recreating them. This allows you to iterate on plugin development while preserving trigger configuration and history. * [Update a plugin using the influxdb3 CLI](#update-a-plugin-using-the-influxdb3-cli) * [Update a plugin using the HTTP API](#update-a-plugin-using-the-http-api) #### Update a plugin using the influxdb3 CLI Use the `influxdb3 update trigger` command: ```bash # Update single-file plugin influxdb3 update trigger \ --database metrics \ --trigger-name my_trigger \ --path "/path/to/updated/plugin.py" # Update multifile plugin influxdb3 update trigger \ --database metrics \ --trigger-name complex_trigger \ --path "/path/to/updated/plugin-dir" ``` For complete reference, see [`influxdb3 update trigger`](/influxdb3/core/reference/cli/influxdb3/update/trigger/). #### Update a plugin using the HTTP API To update a plugin file using the HTTP API, send a `PUT` request to the `/api/v3/plugins/files` endpoint: ``` PUT http://localhost:8181/api/v3/plugins/files ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your admin token * `Content-Type: application/octet-stream` * **Query parameters**: * `path` *(string, required)*: Path to the plugin file relative to the plugin directory ```bash # Update a plugin file curl -X PUT "http://localhost:8181/api/v3/plugins/files?path=plugin.py" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/octet-stream" \ --data-binary "@/path/to/updated/plugin.py" ``` Replace `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/admin) **The update operation:** * Replaces plugin files immediately * Preserves trigger configuration (spec, schedule, arguments) * Requires admin token for security * Works with both local paths and uploaded files ### View loaded plugins Monitor which plugins are loaded in your system for operational visibility and troubleshooting. **Option 1: Use the CLI command** ```bash # List all plugins influxdb3 show plugins --token $ADMIN_TOKEN # JSON format for programmatic access influxdb3 show plugins --format json --token $ADMIN_TOKEN ``` **Option 2: Query the system table** The `system.plugin_files` table in the `_internal` database provides detailed plugin file information: ```bash influxdb3 query \ -d _internal \ "SELECT * FROM system.plugin_files ORDER BY plugin_name" \ --token $ADMIN_TOKEN ``` **Available columns:** * `plugin_name` (String): Trigger name * `file_name` (String): Plugin file name * `file_path` (String): Full server path * `size_bytes` (Int64): File size * `last_modified` (Int64): Modification timestamp (milliseconds) **Example queries:** ```sql -- Find plugins by name SELECT * FROM system.plugin_files WHERE plugin_name = 'my_trigger'; -- Find large plugins SELECT plugin_name, size_bytes FROM system.plugin_files WHERE size_bytes > 10000; -- Check modification times SELECT plugin_name, file_name, last_modified FROM system.plugin_files ORDER BY last_modified DESC; ``` For more information, see the [`influxdb3 show plugins` reference](/influxdb3/core/reference/cli/influxdb3/show/plugins/) and [Query system data](/influxdb3/core/admin/query-system-data/#query-plugin-files). ## Create a trigger A trigger connects your plugin code to database events. When the specified event occurs, the processing engine executes your plugin. * [Understand trigger types](#understand-trigger-types) * [Create a trigger using the influxdb3 CLI](#create-a-trigger-using-the-influxdb3-cli) * [Create a trigger using the HTTP API](#create-a-trigger-using-the-http-api) * [Trigger specification examples](#trigger-specification-examples) ### Understand trigger types |Plugin Type | Trigger Specification | When Plugin Runs | |------------|-----------------------------------------|-------------------------------| | Data write | `table:` or `all_tables` |When data is written to tables | | Scheduled |`every:` or `cron:`| At specified time intervals | |HTTP request| `request:` |When HTTP requests are received| ### Create a trigger using the influxdb3 CLI Use the `influxdb3 create trigger` command with the appropriate trigger specification: ```bash influxdb3 create trigger \ --trigger-spec SPECIFICATION \ --path PLUGIN_FILE \ --database DATABASE_NAME \ TRIGGER_NAME ``` In the example above, replace the following: * `SPECIFICATION`: Trigger specification * `PLUGIN_FILE`: Plugin filename relative to your configured plugin directory * `DATABASE_NAME`: Name of the database * `TRIGGER_NAME`: Name of the new trigger > [!Note] > #### Plugin paths > > * For **single-file plugins**, provide just the `.py` filename to `--path` (for example, `test_plugin.py`). > * For **multi-file plugins**, provide the directory name containing `__init__.py`. > > When not using `--upload`, the server resolves paths relative to the configured `--plugin-dir`. > For details about multi-file plugin structure, see [Create your plugin file](#create-your-plugin-file). For complete reference, see [`influxdb3 create trigger`](/influxdb3/core/reference/cli/influxdb3/create/trigger/). ### Create a trigger using the HTTP API To create a trigger using the HTTP API, send a `POST` request to the `/api/v3/configure/processing_engine_trigger` endpoint: ``` POST http://localhost:8181/api/v3/configure/processing_engine_trigger ``` Include the following in your request: * **Headers**: * `Authorization: Bearer` with your authentication token * `Content-Type: application/json` * **Request body**: JSON object with trigger configuration * `db` *(string, required)*: Database name * `trigger_name` *(string, required)*: Trigger name * `plugin_filename` *(string, required)*: Plugin filename relative to the plugin directory * `trigger_specification` *(string, required)*: When the plugin runs (see [trigger types](#understand-trigger-types)) * `trigger_settings` *(object, required)*: Configuration for error handling and execution * `run_async` *(boolean)*: Whether to run asynchronously (default: `false`) * `error_behavior` *(string)*: How to handle errors: `Log`, `Retry`, or `Disable` (default: `Log`) * `disabled` *(boolean, required)*: Whether the trigger is disabled * `trigger_arguments` *(object, optional)*: Arguments passed to the plugin ```bash # Create a basic trigger curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "TRIGGER_NAME", "plugin_filename": "PLUGIN_FILE", "trigger_specification": "TRIGGER_SPEC", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' ``` In the example above, replace the following: * `DATABASE_NAME`: Name of the database * `TRIGGER_NAME`: Name of the new trigger * `PLUGIN_FILE`: Plugin filename relative to your configured plugin directory * `TRIGGER_SPEC`: Trigger specification (see [examples](#trigger-specification-examples)) * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ### Trigger specification examples The following examples demonstrate how to create triggers for different event types. #### Trigger on data writes #### influxdb3 CLI #### ```bash # Trigger on writes to a specific table # The plugin file must be in your configured plugin directory influxdb3 create trigger \ --trigger-spec "table:sensor_data" \ --path "process_sensors.py" \ --database my_database \ sensor_processor # Trigger on writes to all tables influxdb3 create trigger \ --trigger-spec "all_tables" \ --path "process_all_data.py" \ --database my_database \ all_data_processor ``` ```bash # Trigger on writes to a specific table curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "sensor_processor", "plugin_filename": "process_sensors.py", "trigger_specification": "table:sensor_data", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' # Trigger on writes to all tables curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "all_data_processor", "plugin_filename": "process_all_data.py", "trigger_specification": "all_tables", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The trigger runs when the database flushes ingested data for the specified tables to the Write-Ahead Log (WAL) in the Object store (default is every second). The plugin receives the written data and table information. #### Trigger on data writes with table exclusion If you want to use a single trigger for all tables but exclude specific tables, you can use trigger arguments and your plugin code to filter out unwanted tables–for example: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path processor.py \ --trigger-spec "all_tables" \ --trigger-arguments "exclude_tables=temp_data,debug_info,system_logs" \ data_processor ``` Replace the following: * DATABASE\_NAME: the name of the database * AUTH\_TOKEN: your [token](/influxdb3/core/admin/tokens/) Then, in your plugin: ```python # processor.py def on_write(self, database, table_name, batch): # Get excluded tables from trigger arguments excluded_tables = set(self.args.get('exclude_tables', '').split(',')) if table_name in excluded_tables: return # Process allowed tables self.process_data(database, table_name, batch) ``` ##### Recommendations * **Early return**: Check exclusions as early as possible in your plugin. * **Efficient lookups**: Use sets for O(1) lookup performance with large exclusion lists. * **Performance**: Log skipped tables for debugging but avoid excessive logging in production. * **Multiple triggers**: For few tables, consider creating separate table-specific triggers instead of filtering within plugin code. See HTTP API [Processing engine endpoints](/influxdb3/core/api/v3/#tag/Processing-engine) for managing triggers. #### Trigger on a schedule #### influxdb3 CLI #### ```bash # Run every 5 minutes influxdb3 create trigger \ --trigger-spec "every:5m" \ --path "periodic_check.py" \ --database my_database \ regular_check # Run on a cron schedule (8am daily) # Supports extended cron format with seconds influxdb3 create trigger \ --trigger-spec "cron:0 0 8 * * *" \ --path "daily_report.py" \ --database my_database \ daily_report ``` ```bash # Run every 5 minutes curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "regular_check", "plugin_filename": "periodic_check.py", "trigger_specification": "every:5m", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' # Run on a cron schedule (8am daily) # Supports extended cron format with seconds curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "daily_report", "plugin_filename": "daily_report.py", "trigger_specification": "cron:0 0 8 * * *", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The plugin receives the scheduled call time. #### Trigger on HTTP requests #### influxdb3 CLI #### ```bash # Create an endpoint at /api/v3/engine/webhook influxdb3 create trigger \ --trigger-spec "request:webhook" \ --path "webhook_handler.py" \ --database my_database \ webhook_processor ``` ```bash # Create an endpoint at /api/v3/engine/webhook curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "webhook_processor", "plugin_filename": "webhook_handler.py", "trigger_specification": "request:webhook", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) Access your endpoint at `/api/v3/engine/{REQUEST_PATH}` (in this example, `/api/v3/engine/webhook`). The trigger is enabled by default and runs when an HTTP request is received at the specified path. To run the plugin, send a `GET` or `POST` request to the endpoint–for example: ```bash curl http://localhost:8181/api/v3/engine/webhook ``` The plugin receives the HTTP request object with methods, headers, and body. To view triggers associated with a database, use the `influxdb3 show summary` command: ```bash influxdb3 show summary --database my_database --token AUTH_TOKEN ``` ### Pass arguments to plugins Use trigger arguments to pass configuration from a trigger to the plugin it runs. You can use this for: * Threshold values for monitoring * Connection properties for external services * Configuration settings for plugin behavior #### influxdb3 CLI #### ```bash influxdb3 create trigger \ --trigger-spec "every:1h" \ --path "threshold_check.py" \ --trigger-arguments threshold=90,notify_email=admin@example.com \ --database my_database \ threshold_monitor ``` ```bash curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "threshold_monitor", "plugin_filename": "threshold_check.py", "trigger_specification": "every:1h", "trigger_settings": { "run_async": false, "error_behavior": "Log" }, "trigger_arguments": { "threshold": "90", "notify_email": "admin@example.com" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The arguments are passed to the plugin as a `Dict[str, str]` where the key is the argument name and the value is the argument value: ``` def process_scheduled_call(influxdb3_local, call_time, args=None): if args and "threshold" in args: threshold = float(args["threshold"]) email = args.get("notify_email", "default@example.com") # Use the arguments in your logic influxdb3_local.info(f"Checking threshold {threshold}, will notify {email}") ``` ### Control trigger execution By default, triggers run synchronously—each instance waits for previous instances to complete before executing. To allow multiple instances of the same trigger to run simultaneously, configure triggers to run asynchronously: #### influxdb3 CLI #### ```bash # Allow multiple trigger instances to run simultaneously influxdb3 create trigger \ --trigger-spec "table:metrics" \ --path "heavy_process.py" \ --run-asynchronous \ --database my_database \ async_processor ``` ```bash # Allow multiple trigger instances to run simultaneously curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "async_processor", "plugin_filename": "heavy_process.py", "trigger_specification": "table:metrics", "trigger_settings": { "run_async": true, "error_behavior": "Log" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ### Configure error handling for a trigger To configure error handling behavior for a trigger, specify one of the following values: * `log` (default): Log all plugin errors to stdout and the `system.processing_engine_logs` table in the trigger’s database. * `retry`: Attempt to run the plugin again immediately after an error. * `disable`: Automatically disable the plugin when an error occurs (can be re-enabled later). #### influxdb3 CLI #### For more information, see how to [Query trigger logs](/influxdb3/core/admin/query-system-data/#query-trigger-logs). ```bash # Automatically retry on error influxdb3 create trigger \ --trigger-spec "table:important_data" \ --path "critical_process.py" \ --error-behavior retry \ --database my_database \ critical_processor # Disable the trigger on error influxdb3 create trigger \ --trigger-spec "request:webhook" \ --path "webhook_handler.py" \ --error-behavior disable \ --database my_database \ auto_disable_processor ``` ```bash # Automatically retry on error curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "critical_processor", "plugin_filename": "critical_process.py", "trigger_specification": "table:important_data", "trigger_settings": { "run_async": false, "error_behavior": "Retry" }, "disabled": false }' # Disable the trigger on error curl -X POST "http://localhost:8181/api/v3/configure/processing_engine_trigger" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "trigger_name": "auto_disable_processor", "plugin_filename": "webhook_handler.py", "trigger_specification": "request:webhook", "trigger_settings": { "run_async": false, "error_behavior": "Disable" }, "disabled": false }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) ## Manage plugin dependencies Use the `influxdb3 install package` command to add third-party libraries (like `pandas`, `requests`, or `influxdb3-python`) to your plugin environment. This installs packages into the Processing Engine’s embedded Python environment to ensure compatibility with your InfluxDB instance. #### influxdb3 CLI #### ```bash # Use the CLI to install a Python package influxdb3 install package pandas ``` ```bash # Use the CLI to install a Python package in a Docker container docker exec -it CONTAINER_NAME influxdb3 install package pandas ``` ```bash # Use the HTTP API to install Python packages curl -X POST "http://localhost:8181/api/v3/configure/plugin_environment/install_packages" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "packages": ["pandas", "requests", "numpy"] }' ``` Replace `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/admin) For complete reference, see [Install plugin packages](/influxdb3/core/api/v3/#operation/PostInstallPluginPackages). These examples install the specified Python packages (for example, pandas) into the Processing Engine’s embedded virtual environment. * Use the CLI command when running InfluxDB directly on your system. * Use the Docker variant if you’re running InfluxDB in a containerized environment. * Use the HTTP API for programmatic package installation or CI/CD workflows. > [!Important] > #### Use bundled Python for plugins > > When you start the server with the `--plugin-dir` option, InfluxDB 3 creates a Python virtual environment (`/venv`) for your plugins. > If you need to create a custom virtual environment, use the Python interpreter bundled with InfluxDB 3. Don’t use the system Python. > Creating a virtual environment with the system Python (for example, using `python -m venv`) can lead to runtime errors and plugin failures. > > For more information, see the [processing engine README](https://github.com/influxdata/influxdb/blob/main/README_processing_engine.md). InfluxDB creates a Python virtual environment in your plugins directory with the specified packages installed. ### Disable package installation for secure environments For air-gapped deployments or environments with strict security requirements, you can disable Python package installation while maintaining Processing Engine functionality. Start the server with `--package-manager disabled`: ```bash influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins \ --package-manager disabled ``` When package installation is disabled: * The Processing Engine continues to function normally for triggers * Plugin code executes without restrictions * Package installation commands are blocked * Pre-installed dependencies in the virtual environment remain available **Pre-install required dependencies:** Before disabling the package manager, install all required Python packages: ```bash # Install packages first influxdb3 install package pandas requests numpy # Then start with disabled package manager influxdb3 serve \ --plugin-dir ~/.plugins \ --package-manager disabled ``` **Use cases for disabled package management:** * Air-gapped environments without internet access * Compliance requirements prohibiting runtime package installation * Centrally managed dependency environments * Security policies requiring pre-approved packages only For more configuration options, see [–package-manager](/influxdb3/core/reference/config-options/#package-manager). ## Plugin security The Processing Engine includes security features to protect your InfluxDB 3 Core instance from unauthorized code execution and file system attacks. ### Plugin path validation All plugin file paths are validated to prevent directory traversal attacks. The system blocks: * **Relative paths with parent directory references** (`../`, `../../`) * **Absolute paths** (`/etc/passwd`, `/usr/bin/script.py`) * **Symlinks that escape the plugin directory** When creating or updating triggers, plugin paths must resolve within the configured `--plugin-dir`. **Example of blocked paths:** ```bash # These will be rejected influxdb3 create trigger \ --path "../../../etc/passwd" \ # Blocked: parent directory traversal ... influxdb3 create trigger \ --path "/tmp/malicious.py" \ # Blocked: absolute path ... ``` **Valid plugin paths:** ```bash # These are allowed influxdb3 create trigger \ --path "myapp/plugin.py" \ # Relative to plugin-dir ... influxdb3 create trigger \ --path "transforms/data.py" \ # Subdirectory in plugin-dir ... ``` ### Upload and update permissions Plugin upload and update operations require admin tokens to prevent unauthorized code deployment: * `--upload` flag requires admin privileges * `update trigger` command requires admin token * Standard resource tokens cannot upload or modify plugin code This security model ensures only administrators can introduce or modify executable code in your database. ### Best practices **For development:** * Use the `--upload` flag to deploy plugins during development * Test plugins in non-production environments first * Review plugin code before deployment **For production:** * Pre-deploy plugins to the server’s plugin directory via secure file transfer * Use custom plugin repositories for vetted, approved plugins * Disable package installation (`--package-manager disabled`) in locked-down environments * Audit plugin files using the [`system.plugin_files` table](#view-loaded-plugins) * Implement change control processes for plugin updates For more security configuration options, see [Configuration options](/influxdb3/core/reference/config-options/). #### Related * [influxdb3 test wal\_plugin](/influxdb3/core/reference/cli/influxdb3/test/wal_plugin/) * [influxdb3 create trigger](/influxdb3/core/reference/cli/influxdb3/create/trigger/) [processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/) | Deployment | Default state | Configuration | | --- | --- | --- | | Deployment | Default state | Configuration | | Docker images | Enabled | INFLUXDB3_PLUGIN_DIR=/plugins | | DEB/RPM packages | Enabled | plugin-dir="/var/lib/influxdb3/plugins" | | Binary/source | Disabled | No plugin-dir configured | | Plugin Type | Best For | | --- | --- | | Plugin Type | Best For | | Data write | Processing data as it arrives | | Scheduled | Running code at specific intervals or times | | HTTP request | Running code on demand via API endpoints | | Plugin Type | Trigger Specification | When Plugin Runs | | --- | --- | --- | | Plugin Type | Trigger Specification | When Plugin Runs | | Data write | table: or all_tables | When data is written to tables | | Scheduled | every: or cron: | At specified time intervals | | HTTP request | request: | When HTTP requests are received | --- # Extend plugins with API features and state management Source: https://docs.influxdata.com/influxdb3/core/plugins/extend-plugin/ The Processing Engine includes a shared API that your plugins can use to interact with data, write new records in line protocol format, and maintain state between executions. These capabilities let you build plugins that transform, analyze, and respond to time series data as it flows through your database. The plugin API lets you: * [Write data](#write-data) * [Query data](#query-data) * [Log messages for monitoring and debugging](#log-messages-for-monitoring-and-debugging) * [Maintain state with the in-memory cache](#maintain-state-with-the-in-memory-cache) * [Store and retrieve cached data](#store-and-retrieve-cached-data) * [Use TTL appropriately](#use-ttl-appropriately) * [Share data across plugins](#share-data-across-plugins) * [Build a counter](#building-a-counter) * [Guidelines for in-memory caching](#guidelines-for-in-memory-caching) * [Consider cache limitations](#consider-cache-limitations) ## Get started with the shared API Each plugin automatically has access to the shared API through the `influxdb3_local` object. You don’t need to import any libraries. The API becomes available as soon as your plugin runs. If your plugin requires third-party Python packages (like `pandas`, `requests`, or `influxdb3-python`), see [Manage plugin dependencies](/influxdb3/core/plugins/#manage-plugin-dependencies) for installation instructions. ## Write data To write data into your database, use the `LineBuilder` API to create line protocol data: ```python # Create a line protocol entry line = LineBuilder("weather") line.tag("location", "us-midwest") line.float64_field("temperature", 82.5) line.time_ns(1627680000000000000) # Write the data to the database influxdb3_local.write(line) ``` InfluxDB 3 buffers your writes while the plugin runs and flushes them when the plugin completes. [](#view-the-linebuilder-python-implementation) View the `LineBuilder` Python implementation ```python from typing import Optional from collections import OrderedDict class InfluxDBError(Exception): """Base exception for InfluxDB-related errors""" pass class InvalidMeasurementError(InfluxDBError): """Raised when measurement name is invalid""" pass class InvalidKeyError(InfluxDBError): """Raised when a tag or field key is invalid""" pass class InvalidLineError(InfluxDBError): """Raised when a line protocol string is invalid""" pass class LineBuilder: def __init__(self, measurement: str): if ' ' in measurement: raise InvalidMeasurementError("Measurement name cannot contain spaces") self.measurement = measurement self.tags: OrderedDict[str, str] = OrderedDict() self.fields: OrderedDict[str, str] = OrderedDict() self._timestamp_ns: Optional[int] = None def _validate_key(self, key: str, key_type: str) -> None: """Validate that a key does not contain spaces, commas, or equals signs.""" if not key: raise InvalidKeyError(f"{key_type} key cannot be empty") if ' ' in key: raise InvalidKeyError(f"{key_type} key '{key}' cannot contain spaces") if ',' in key: raise InvalidKeyError(f"{key_type} key '{key}' cannot contain commas") if '=' in key: raise InvalidKeyError(f"{key_type} key '{key}' cannot contain equals signs") def tag(self, key: str, value: str) -> 'LineBuilder': """Add a tag to the line protocol.""" self._validate_key(key, "tag") self.tags[key] = str(value) return self def uint64_field(self, key: str, value: int) -> 'LineBuilder': """Add an unsigned integer field to the line protocol.""" self._validate_key(key, "field") if value < 0: raise ValueError(f"uint64 field '{key}' cannot be negative") self.fields[key] = f"{value}u" return self def int64_field(self, key: str, value: int) -> 'LineBuilder': """Add an integer field to the line protocol.""" self._validate_key(key, "field") self.fields[key] = f"{value}i" return self def float64_field(self, key: str, value: float) -> 'LineBuilder': """Add a float field to the line protocol.""" self._validate_key(key, "field") # Check if value has no decimal component self.fields[key] = f"{int(value)}.0" if value % 1 == 0 else str(value) return self def string_field(self, key: str, value: str) -> 'LineBuilder': """Add a string field to the line protocol.""" self._validate_key(key, "field") # Escape quotes and backslashes in string values escaped_value = value.replace('"', '\\"').replace('\\', '\\\\') self.fields[key] = f'"{escaped_value}"' return self def bool_field(self, key: str, value: bool) -> 'LineBuilder': """Add a boolean field to the line protocol.""" self._validate_key(key, "field") self.fields[key] = 't' if value else 'f' return self def time_ns(self, timestamp_ns: int) -> 'LineBuilder': """Set the timestamp in nanoseconds.""" self._timestamp_ns = timestamp_ns return self def build(self) -> str: """Build the line protocol string.""" # Start with measurement name (escape commas only) line = self.measurement.replace(',', '\\,') # Add tags if present if self.tags: tags_str = ','.join( f"{k}={v}" for k, v in self.tags.items() ) line += f",{tags_str}" # Add fields (required) if not self.fields: raise InvalidLineError(f"At least one field is required: {line}") fields_str = ','.join( f"{k}={v}" for k, v in self.fields.items() ) line += f" {fields_str}" # Add timestamp if present if self._timestamp_ns is not None: line += f" {self._timestamp_ns}" return line ``` ## Query data Your plugins can execute SQL queries and process results directly: ```python # Simple query results = influxdb3_local.query("SELECT * FROM metrics WHERE time > now() - INTERVAL '1 hour'") # Parameterized query for safer execution params = {"table": "metrics", "threshold": 90} results = influxdb3_local.query("SELECT * FROM $table WHERE value > $threshold", params) ``` Query results are a `List` of `Dict[String, Any]`, where each dictionary represents a row. Column names are keys, and column values are the corresponding values. ## Log messages for monitoring and debugging Use the shared API’s `info`, `warn`, and `error` functions to log messages from your plugin. Each function accepts one or more arguments, converts them to strings, and logs them as a space-separated message. Add logging to monitor plugin execution and assist with debugging: ```python influxdb3_local.info("Starting data processing") influxdb3_local.warn("Could not process some records") influxdb3_local.error("Failed to connect to external API") # Log structured data obj_to_log = {"records": 157, "errors": 3} influxdb3_local.info("Processing complete", obj_to_log) ``` The system writes all log messages to the server logs and stores them in [system tables](/influxdb3/core/reference/cli/influxdb3/show/system/summary/), where you can query them using SQL. ## Maintain state with the in-memory cache The Processing Engine provides an in-memory cache that enables your plugins to persist and retrieve data between executions. Access the cache using the `cache` property of the shared API: ```python # Basic usage pattern influxdb3_local.cache.METHOD(PARAMETERS) ``` `cache` provides the following methods to retrieve and manage cached values: | Method | Parameters |Returns| Description | |--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------| | `put` |`key` (str): The key to store the value under
`value` (Any): Any Python object to cache
`ttl` (Optional[float], default=None): Time in seconds before expiration
`use_global` (bool, default=False): If True, uses global namespace| None | Stores a value in the cache with an optional time-to-live | | `get` | `key` (str): The key to retrieve
`default` (Any, default=None): Value to return if key not found
`use_global` (bool, default=False): If True, uses global namespace | Any | Retrieves a value from the cache or returns default if not found | |`delete`| `key` (str): The key to delete
`use_global` (bool, default=False): If True, uses global namespace | bool |Deletes a value from the cache. Returns True if deleted, False if not found| ### Understanding cache namespaces The cache system offers two distinct namespaces: | Namespace | Scope | Best For | |------------------------------|----------------------------|------------------------------------------------------------------------------------| |**Trigger-specific** (default)|Isolated to a single trigger| Plugin state, counters, timestamps specific to one plugin | | **Global** | Shared across all triggers |Configuration, lookup tables, service states that should be available to all plugins| ### Common cache operations * [Store and retrieve cached data](#store-and-retrieve-cached-data) * [Store cached data with expiration](#store-cached-data-with-expiration) * [Share data across plugins](#share-data-across-plugins) * [Build a counter](#building-a-counter) ### Store and retrieve cached data ```python # Store a value influxdb3_local.cache.put("last_run_time", time.time()) # Retrieve a value with a default if not found last_time = influxdb3_local.cache.get("last_run_time", default=0) # Delete a cached value influxdb3_local.cache.delete("temporary_data") ``` ### Store cached data with expiration ```python # Cache with a 5-minute TTL (time-to-live) influxdb3_local.cache.put("api_response", response_data, ttl=300) ``` ### Share data across plugins ```python # Store in the global namespace influxdb3_local.cache.put("config", {"version": "1.0"}, use_global=True) # Retrieve from the global namespace config = influxdb3_local.cache.get("config", use_global=True) ``` ### Building a counter You can track how many times a plugin has run: ```python # Get current counter or default to 0 counter = influxdb3_local.cache.get("execution_count", default=0) # Increment counter counter += 1 # Store the updated value influxdb3_local.cache.put("execution_count", counter) influxdb3_local.info(f"This plugin has run {counter} times") ``` ## Guidelines for in-memory caching To get the most out of the in-memory cache, follow these guidelines: * [Use the trigger-specific namespace](#use-the-trigger-specific-namespace) * [Use TTL appropriately](#use-ttl-appropriately) * [Cache computation results](#cache-computation-results) * [Warm the cache](#warm-the-cache) * [Consider cache limitations](#consider-cache-limitations) ### Use the trigger-specific namespace The Processing Engine provides a cache that supports stateful operations while maintaining isolation between different triggers. For most use cases, use the trigger-specific namespace to keep plugin state isolated. Use the global namespace only when you need to share data across triggers. ### Use TTL appropriately Set appropriate expiration times based on how frequently your data changes: ```python # Cache external API responses for 5 minutes influxdb3_local.cache.put("weather_data", api_response, ttl=300) ``` ### Cache computation results Store the results of expensive calculations that you frequently utilize: ```python # Cache aggregated statistics influxdb3_local.cache.put("daily_stats", calculate_statistics(data), ttl=3600) ``` ### Warm the cache For critical data, prime the cache at startup. This can be especially useful for global namespace data where multiple triggers need the data: ```python # Check if cache needs to be initialized if not influxdb3_local.cache.get("lookup_table"): influxdb3_local.cache.put("lookup_table", load_lookup_data()) ``` ### Consider cache limitations * **Memory Usage**: Since the system stores cache contents in memory, monitor your memory usage when caching large datasets. * **Server Restarts**: Because the server clears the cache on restart, design your plugins to handle cache initialization (as noted above). * **Concurrency**: Be cautious of accessing inaccurate or out-of-date data when multiple trigger instances might simultaneously update the same cache key. ## Next Steps With an understanding of the InfluxDB 3 Shared Plugin API, you can start building data workflows that transform, analyze, and respond to your time series data. For official plugins and examples that you can extend, see the [plugin library](/influxdb3/core/plugins/library/). #### Related * [influxdb3 create trigger](/influxdb3/core/reference/cli/influxdb3/create/trigger/) * [influxdb3 test](/influxdb3/core/reference/cli/influxdb3/test/) * [Processing engine reference](/influxdb3/core/reference/processing-engine/) [processing engine](/influxdb3/core/tags/processing-engine/)[plugins](/influxdb3/core/tags/plugins/)[API](/influxdb3/core/tags/api/)[python](/influxdb3/core/tags/python/) | Method | Parameters | Returns | Description | | --- | --- | --- | --- | | Method | Parameters | Returns | Description | | put | key (str): The key to store the value under value (Any): Any Python object to cache ttl (Optional[float], default=None): Time in seconds before expiration use_global (bool, default=False): If True, uses global namespace | None | Stores a value in the cache with an optional time-to-live | | get | key (str): The key to retrieve default (Any, default=None): Value to return if key not found use_global (bool, default=False): If True, uses global namespace | Any | Retrieves a value from the cache or returns default if not found | | delete | key (str): The key to delete use_global (bool, default=False): If True, uses global namespace | bool | Deletes a value from the cache. Returns True if deleted, False if not found | | Namespace | Scope | Best For | | --- | --- | --- | | Namespace | Scope | Best For | | Trigger-specific (default) | Isolated to a single trigger | Plugin state, counters, timestamps specific to one plugin | | Global | Shared across all triggers | Configuration, lookup tables, service states that should be available to all plugins | --- # Plugin library Source: https://docs.influxdata.com/influxdb3/core/plugins/library/ Browse plugins for InfluxDB 3 Core. Use these plugins to extend your database functionality with custom Python code that runs on write events, schedules, or HTTP requests. ### [Example plugins](/influxdb3/core/plugins/library/examples/) Start with example plugins that demonstrate common use cases. ### [Official plugins](/influxdb3/core/plugins/library/official/) Production-ready plugins developed and maintained by InfluxData. ## Requirements All plugins require: * InfluxDB 3 Core or InfluxDB 3 Enterprise with Processing Engine enabled * Python environment (managed automatically by InfluxDB 3) * Appropriate trigger configuration ## Plugin metadata Plugins in this library include a JSON metadata schema in a docstring header that defines supported trigger types and configuration parameters. This metadata enables: * the [InfluxDB 3 Explorer UI](/influxdb3/explorer/) to display and configure the plugin * automated testing and validation of plugins in the repository ## Using TOML Configuration Files Many plugins in this library support using TOML configuration files to specify all plugin arguments. This is useful for complex configurations or when you want to version control your plugin settings. ### Important Requirements **To use TOML configuration files, you must set the `PLUGIN_DIR` environment variable in the InfluxDB 3 Core host environment.** This is required in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core: * `--plugin-dir` tells InfluxDB 3 Core where to find plugin Python files * `PLUGIN_DIR` environment variable tells the plugins where to find TOML configuration files ### Set up TOML Configuration 1. **Start InfluxDB 3 Core with the PLUGIN\_DIR environment variable set**: ``` PLUGIN_DIR=~/.plugins influxdb3 serve --node-id node0 --object-store file --data-dir ~/.influxdb3 --plugin-dir ~/.plugins ``` 2. **Copy or create a TOML configuration file in your plugin directory**: ``` # Example: copy a plugin's configuration template cp plugin_config_example.toml ~/.plugins/my_config.toml ``` 3. **Edit the TOML file** to match your requirements. The TOML file should contain all the arguments defined in the plugin’s argument schema. 4. **Create a trigger with the `config_file_path` argument**: When creating a trigger, specify the `config_file_path` argument to point to your TOML configuration file. * Specify only the filename (not the full path) * The file must be located under `PLUGIN_DIR` ``` influxdb3 create trigger \ --database mydb \ --plugin-filename plugin_name.py \ --trigger-spec "every:1d" \ --trigger-arguments config_file_path=my_config.toml \ my_trigger_name ``` For more information on using TOML configuration files, see the project [README](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/) --- # Example plugins Source: https://docs.influxdata.com/influxdb3/core/plugins/library/examples/ Example plugins demonstrate common use cases and patterns for extending InfluxDB 3 Core with custom Python code. ### [WAL plugin](/influxdb3/core/plugins/library/examples/wal-plugin/) Example Write-Ahead Log (WAL) plugin that demonstrates processing data as it’s written to the database. [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[examples](/influxdb3/core/tags/examples/) --- # WAL plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/examples/wal-plugin/ The example WAL plugin monitors data write operations in InfluxDB 3 by tracking row counts for each table during WAL (Write-Ahead Log) flush events. It creates summary reports in a `write_reports` table to help analyze data ingestion patterns and rates. The plugin can optionally double-count rows for a specified table to demonstrate configurable behavior. ## Configuration ### Optional parameters | Parameter | Type |Default| Description | |--------------------|------|-------|-----------------------------------------------------------------------------------------| |`double_count_table`|string| none |Table name for which to double the row count in write reports (for testing/demonstration)| ## Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`) ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` ## Trigger setup ### Write monitoring Monitor all table writes and generate write reports: ```bash influxdb3 create trigger \ --database monitoring \ --plugin-filename examples/wal_plugin/wal_plugin.py \ --trigger-spec "all_tables" \ wal_monitoring ``` ### Write monitoring with special handling Monitor writes with special handling for a specific table: ```bash influxdb3 create trigger \ --database monitoring \ --plugin-filename examples/wal_plugin/wal_plugin.py \ --trigger-spec "all_tables" \ --trigger-arguments 'double_count_table=temperature' \ wal_monitoring_special ``` ## Example usage ### Example: Basic write monitoring Set up write monitoring to track data ingestion: ``` # Create the monitoring trigger influxdb3 create trigger \ --database testdb \ --plugin-filename examples/wal_plugin/wal_plugin.py \ --trigger-spec "all_tables" \ write_monitor # Write test data to various tables influxdb3 write \ --database testdb \ "temperature,location=office value=22.5" influxdb3 write \ --database testdb \ "humidity,location=office value=45.2" influxdb3 write \ --database testdb \ "pressure,location=office value=1013.25" # The plugin automatically generates write reports in the `write_reports` measurement. # Query the write reports influxdb3 query \ --database testdb \ "SELECT * FROM write_reports ORDER BY time DESC" ``` ### Expected output ``` table_name | row_count | time ------------|-----------|----- pressure | 1 | 2024-01-01T12:02:00Z humidity | 1 | 2024-01-01T12:01:00Z temperature | 1 | 2024-01-01T12:00:00Z ``` ### Example: Monitoring with special table handling Monitor writes with doubled counting for temperature data: ``` # Create trigger with special handling influxdb3 create trigger \ --database testdb \ --plugin-filename examples/wal_plugin/wal_plugin.py \ --trigger-spec "all_tables" \ --trigger-arguments 'double_count_table=temperature' \ write_monitor_special # Write test data influxdb3 write \ --database testdb \ "temperature,location=office value=22.5" influxdb3 write \ --database testdb \ "humidity,location=office value=45.2" # Query the write reports influxdb3 query \ --database testdb \ "SELECT * FROM write_reports ORDER BY time DESC" ``` ### Expected output ``` table_name | row_count | time ------------|-----------|----- humidity | 1 | 2024-01-01T12:01:00Z temperature | 2 | 2024-01-01T12:00:00Z ``` **Note**: The temperature table shows a row count of 2 despite only writing 1 row, demonstrating the `double_count_table` parameter. ## Generated Measurements ### write\_reports Tracks the number of rows written to each table during WAL flush events. **Tags:** * `table_name`: Name of the table that received writes **Fields:** * `row_count`: Number of rows written in this WAL flush (integer) **Special behavior:** * If `double_count_table` parameter matches the table name, the row count will be doubled * The plugin automatically skips the `write_reports` table to avoid infinite recursion ## Code overview ### Files * `wal_plugin.py`: Main plugin code that processes write batches and generates reports ### Main functions #### `process_writes(influxdb3_local, table_batches, args)` Entry point for processing write batches. Called each time data is written to the database. **Parameters:** * `influxdb3_local`: InfluxDB client for writing and logging * `table_batches`: List of table batches containing written data * `args`: Configuration arguments from trigger setup **Processing logic:** 1. Iterates through each table batch in the write operation 2. Skips the `write_reports` table to prevent recursion 3. Counts rows in each batch 4. Applies special handling if `double_count_table` matches 5. Writes report record to `write_reports` measurement ### Logging Logs are stored in the `_internal` database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query \ --database _internal \ --token AUTH_TOKEN \ "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'wal_monitoring'" ``` Replace `AUTH_TOKEN` with your [admin token](/influxdb3/core/admin/tokens/). ## Troubleshooting ### Common issues #### Issue: No write reports appearing **Solution**: 1. Verify the trigger was created successfully: ``` influxdb3 show summary --database DATABASE_NAME --token AUTH_TOKEN ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) 2. Check that data is actually being written to tables other than `write_reports` 3. Review logs for errors #### Issue: Infinite recursion with write\_reports **Solution**: This shouldn’t happen as the plugin automatically skips the `write_reports` table, but if you see this: 1. Check that you haven’t modified the plugin to remove the skip logic 2. Verify the table name comparison is working correctly #### Issue: Row counts seem incorrect **Solution**: 1. Remember that row counts represent WAL flush batches, not individual write operations 2. Multiple write operations may be batched together before the plugin processes them 3. Check if `double_count_table` is set and affecting specific tables ### Performance considerations * This plugin processes every write operation, so it adds minimal overhead * The plugin generates one additional write per table per WAL flush batch * Consider the storage impact of write reports for high-volume systems ### Use cases * **Write monitoring**: Track data ingestion patterns and volumes * **Debugging**: Identify which tables are receiving writes * **Performance analysis**: Monitor write batch sizes and patterns * **Data validation**: Verify expected write volumes * **Testing**: Use `double_count_table` parameter for testing scenarios ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [WAL plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/examples/wal-plugin) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[wal](/influxdb3/core/tags/wal/)[data-write](/influxdb3/core/tags/data-write/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | double_count_table | string | none | Table name for which to double the row count in write reports (for testing/demonstration) | --- # Official plugins Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/ Official plugins developed and maintained by InfluxData for production use with InfluxDB 3 Core. ### [Basic transformation plugin](/influxdb3/core/plugins/library/official/basic-transformation/) Provides common data transformation functions for modifying and enriching time series data. ### [Downsampler plugin](/influxdb3/core/plugins/library/official/downsampler/) Automatically downsample and aggregate time series data at configurable intervals. ### [Forecast error evaluator plugin](/influxdb3/core/plugins/library/official/forecast-error-evaluator/) Evaluate forecast accuracy by comparing predicted values against actual measurements. ### [InfluxDB to Iceberg plugin](/influxdb3/core/plugins/library/official/influxdb-to-iceberg/) Export time series data from InfluxDB to Apache Iceberg table format for data lake integration. ### [MAD-based anomaly detection plugin](/influxdb3/core/plugins/library/official/mad-anomaly-detection/) Detect anomalies using Median Absolute Deviation (MAD) statistical analysis. ### [Notifier plugin](/influxdb3/core/plugins/library/official/notifier/) Send notifications and alerts to various channels including email, Slack, and webhooks. ### [Prophet forecasting plugin](/influxdb3/core/plugins/library/official/prophet-forecasting/) Generate time series forecasts using Facebook Prophet for predictive analytics. ### [State change plugin](/influxdb3/core/plugins/library/official/state-change/) Detect and track state changes in time series data for event monitoring. ### [Stateless ADTK detector plugin](/influxdb3/core/plugins/library/official/stateless-adtk-detector/) Perform anomaly detection using the Anomaly Detection Toolkit (ADTK) without maintaining state. ### [System metrics plugin](/influxdb3/core/plugins/library/official/system-metrics/) Collects comprehensive system performance metrics including CPU, memory, disk, and network statistics. ### [Threshold deadman checks plugin](/influxdb3/core/plugins/library/official/threshold-deadman-checks/) Monitor data thresholds and detect missing data with deadman checks for alerting. [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[official](/influxdb3/core/tags/official/) --- # Basic transformation plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/basic-transformation/ The Basic Transformation Plugin enables real-time and scheduled transformation of time series data in InfluxDB 3 Core. Transform field and tag names, convert values between units, and apply custom string replacements to standardize or clean your data. The plugin supports both scheduled batch processing of historical data and real-time transformation as data is written. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type | Default | Description | |--------------------|------|----------------|-------------------------------------------------| | `measurement` |string| required | Source measurement containing data to transform | |`target_measurement`|string| required | Destination measurement for transformed data | | `target_database` |string|current database| Database for storing transformed data | | `dry_run` |string| “false” |When “true”, logs transformations without writing| ### Transformation parameters | Parameter | Type |Default| Description | |------------------------|------|-------|---------------------------------------------------------------------------------------------------| |`names_transformations` |string| none |Field/tag name transformation rules. Format: `'field1:"transform1 transform2".field2:"transform3"'`| |`values_transformations`|string| none | Field value transformation rules. Format: `'field1:"transform1".field2:"transform2"'` | | `custom_replacements` |string| none | Custom string replacements. Format: `'rule_name:"find=replace"'` | | `custom_regex` |string| none | Regex patterns for field matching. Format: `'pattern_name:"temp%"'` | ### Data selection parameters | Parameter | Type | Default | Description | |-----------------|------|-------------------------|----------------------------------------------------------------------------------------| | `window` |string|required (scheduled only)| Historical data window. Format: `` (for example, “30d”, “1h”) | |`included_fields`|string| all fields and tags |Dot-separated list of fields and tags to include (for example, “temp.humidity.location”)| |`excluded_fields`|string| none | Dot-separated list of fields and tags to exclude | | `filters` |string| none | Query filters. Format: `'field:"operator value"'` | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configurations * [basic\_transformation\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/basic_transformation/basic_transformation_config_scheduler.toml) - for scheduled triggers * [basic\_transformation\_config\_data\_writes.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/basic_transformation/basic_transformation_config_data_writes.toml) - for data write triggers For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Data requirements The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled * **Python packages**: * `pint` (for unit conversions) ## Schema requirements The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. > [!Warning] > #### Requires existing schema > > By design, the plugin returns an error if the schema doesn’t exist or doesn’t contain the expected columns. ## Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package pint ``` ## Trigger setup ### Scheduled transformation Run transformations periodically on historical data: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'measurement=temperature,window=24h,target_measurement=temperature_normalized,names_transformations=temp:"snake",values_transformations=temp:"convert_degC_to_degF"' \ hourly_temp_transform ``` ### Real-time transformation Transform data as it’s written: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=sensor_data,target_measurement=sensor_data_clean,names_transformations=.*:"snake remove_special_chars normalize_underscores"' \ realtime_clean ``` ## Example usage ### Example 1: Temperature unit conversion Convert temperature readings from Celsius to Fahrenheit while standardizing field names: ```bash # Create the trigger influxdb3 create trigger \ --database weather \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "every:30m" \ --trigger-arguments 'measurement=raw_temps,window=1h,target_measurement=temps_fahrenheit,names_transformations=Temperature:"snake",values_transformations=temperature:"convert_degC_to_degF"' \ temp_converter # Write test data influxdb3 write \ --database weather \ "raw_temps,location=office Temperature=22.5" # Query transformed data (after trigger runs) influxdb3 query \ --database weather \ "SELECT * FROM temps_fahrenheit" ``` ### Expected output |location|temperature| time | |--------|-----------|--------------------| | office | 72.5 |2024-01-01T00:00:00Z| **Transformation details:** * Before: `Temperature=22.5` (Celsius) * After: `temperature=72.5` (Fahrenheit, field name converted to snake\_case) ### Example 2: Field name standardization Clean and standardize field names from various sensors: ```bash # Create trigger with multiple transformations influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=raw_sensors,target_measurement=clean_sensors,names_transformations=.*:"remove_special_chars snake collapse_underscore trim_underscore"' \ field_cleaner # Write data with inconsistent field names influxdb3 write \ --database sensors \ "raw_sensors,device=sensor1 \"Room Temperature\"=20.1,\"__Humidity_%\"=45.2" # Query cleaned data influxdb3 query \ --database sensors \ "SELECT * FROM clean_sensors" ``` ### Expected output |device |room\_temperature|humidity| time | |-------|-----------------|--------|--------------------| |sensor1| 20.1 | 45.2 |2024-01-01T00:00:00Z| **Transformation details:** * Before: `"Room Temperature"=20.1`, `"__Humidity_%"=45.2` * After: `room_temperature=20.1`, `humidity=45.2` (field names standardized) ### Example 3: Custom string replacements Replace specific strings in field values: ```bash # Create trigger with custom replacements influxdb3 create trigger \ --database inventory \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "every:1d" \ --trigger-arguments 'measurement=products,window=7d,target_measurement=products_updated,values_transformations=status:"status_replace",custom_replacements=status_replace:"In Stock=available.Out of Stock=unavailable"' \ status_updater ``` ## Using TOML Configuration Files This plugin supports using TOML configuration files to specify all plugin arguments. This is useful for complex configurations or when you want to version control your plugin settings. ### Important Requirements **To use TOML configuration files, you must set the `PLUGIN_DIR` environment variable in the InfluxDB 3 Core host environment.** This is required in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core: * `--plugin-dir` tells InfluxDB 3 Core where to find plugin Python files * `PLUGIN_DIR` environment variable tells the plugins where to find TOML configuration files ### Setting Up TOML Configuration 1. **Start InfluxDB 3 Core with the PLUGIN\_DIR environment variable set**: ``` PLUGIN_DIR=~/.plugins influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. **Copy the example TOML configuration file to your plugin directory**: ``` cp basic_transformation_config_scheduler.toml ~/.plugins/ # or for data writes: cp basic_transformation_config_data_writes.toml ~/.plugins/ ``` 3. **Edit the TOML file** to match your requirements. The TOML file contains all the arguments defined in the plugin’s argument schema (see the JSON schema in the docstring at the top of basic\_transformation.py). 4. **Create a trigger using the `config_file_path` argument**: ``` influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/basic_transformation/basic_transformation.py" \ --trigger-spec "every:1d" \ --trigger-arguments config_file_path=basic_transformation_config_scheduler.toml \ basic_transform_trigger ``` ## Code overview ### Files * `basic_transformation.py`: The main plugin code containing handlers for scheduled tasks and data write transformations * `basic_transformation_config_data_writes.toml`: Example TOML configuration file for data write triggers * `basic_transformation_config_scheduler.toml`: Example TOML configuration file for scheduled triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing the action or error ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled transformation tasks. Queries historical data within the specified window and applies transformations. Key operations: 1. Parses configuration from arguments 2. Queries source measurement with filters 3. Applies name and value transformations 4. Writes transformed data to target measurement #### `process_writes(influxdb3_local, table_batches, args)` Handles real-time transformation during data writes. Processes incoming data batches and applies transformations before writing. Key operations: 1. Filters relevant table batches 2. Applies transformations to each row 3. Writes to target measurement immediately #### `apply_transformations(value, transformations)` Core transformation engine that applies a chain of transformations to a value. Supported transformations: **Case conversions:** * `lower` - Convert to lowercase * `upper` - Convert to uppercase * `snake` - Convert to snake\_case * `camel` - Convert to camelCase * `pascal` - Convert to PascalCase * `kebab` - Convert to kebab-case * `title` - Convert to Title Case * `capitalize_first` - Capitalize first letter only * `capitalize_words` - Capitalize each word **String cleaning and normalization:** * `space_to_underscore` - Replace spaces with underscores * `remove_space` - Remove all spaces * `alnum_underscore_only` - Keep only alphanumeric and underscore characters * `collapse_underscore` - Collapse multiple underscores into one * `trim_underscore` - Remove leading/trailing underscores * `normalize_whitespace` - Normalize whitespace to single spaces * `normalize_dashes` - Normalize dashes and underscores to dashes * `normalize_underscores` - Normalize dashes and spaces to underscores **Character filtering:** * `remove_digits` - Remove all digits * `remove_punctuation` - Remove punctuation marks * `keep_alphanumeric` - Keep only letters and numbers * `remove_special_chars` - Remove special characters (keep letters, numbers, spaces, \_, -) **String extraction and filtering:** * `extract_numbers_only` - Extract only numeric characters * `extract_letters_only` - Extract only alphabetic characters **Mathematical operations (for numeric values):** * `abs` - Absolute value * `round2` - Round to 2 decimal places * `sqrt` - Square root * `ln` - Natural logarithm * `floor` - Round down to nearest integer * `ceil` - Round up to nearest integer **Value conversion and clamping:** * `to_percentage` - Multiply by 100 (convert to percentage) * `from_percentage` - Divide by 100 (convert from percentage) * `clamp_min_zero` - Limit minimum value to zero * `clamp_max_hundred` - Limit maximum value to 100 * `boolean_to_int` - Convert boolean values to 1/0 **Other operations:** * `reverse` - Reverse the string * Unit conversions: `convert__to_` * Custom replacements: User-defined string substitutions ## Troubleshooting ### Common issues #### Issue: Transformations not applying **Solution**: Check that field names match exactly (case-sensitive). Use regex patterns for flexible matching: ```bash --trigger-arguments 'custom_regex=temp_fields:"temp%",values_transformations=temp_fields:"convert_degC_to_degF"' ``` #### Issue: “Permission denied” errors in logs **Solution**: Ensure the plugin file has execute permissions: ```bash chmod +x ~/.plugins/basic_transformation.py ``` #### Issue: Unit conversion failing **Solution**: Verify unit names are valid pint units. Common units: * Temperature: `degC`, `degF`, `degK` * Length: `meter`, `foot`, `inch` * Time: `second`, `minute`, `hour` #### Issue: No data in target measurement **Solution**: 1. Check dry\_run is not set to “true” 2. Verify source measurement contains data 3. Check logs for errors: ``` influxdb3 query \ --database YOUR_DATABASE \ "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` ### Debugging tips 1. **Enable dry run** to test transformations: ``` --trigger-arguments 'dry_run=true,...' ``` 2. **Use specific time windows** for testing: ``` --trigger-arguments 'window=1h,...' ``` 3. **Check field names** in source data: ``` influxdb3 query --database mydb "SHOW FIELD KEYS FROM measurement" ``` ### Performance considerations * Field name caching reduces query overhead (1-hour cache) * Batch processing for scheduled tasks improves throughput * Retry mechanism (3 attempts) handles transient write failures * Use filters to process only relevant data ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Basic transformation plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/basic_transformation) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[transformation](/influxdb3/core/tags/transformation/)[data-processing](/influxdb3/core/tags/data-processing/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Source measurement containing data to transform | | target_measurement | string | required | Destination measurement for transformed data | | target_database | string | current database | Database for storing transformed data | | dry_run | string | “false” | When “true”, logs transformations without writing | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | names_transformations | string | none | Field/tag name transformation rules. Format: 'field1:"transform1 transform2".field2:"transform3"' | | values_transformations | string | none | Field value transformation rules. Format: 'field1:"transform1".field2:"transform2"' | | custom_replacements | string | none | Custom string replacements. Format: 'rule_name:"find=replace"' | | custom_regex | string | none | Regex patterns for field matching. Format: 'pattern_name:"temp%"' | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | window | string | required (scheduled only) | Historical data window. Format: (for example, “30d”, “1h”) | | included_fields | string | all fields and tags | Dot-separated list of fields and tags to include (for example, “temp.humidity.location”) | | excluded_fields | string | none | Dot-separated list of fields and tags to exclude | | filters | string | none | Query filters. Format: 'field:"operator value"' | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | | location | temperature | time | | --- | --- | --- | | location | temperature | time | | office | 72.5 | 2024-01-01T00:00:00Z | | device | room_temperature | humidity | time | | --- | --- | --- | --- | | device | room_temperature | humidity | time | | sensor1 | 20.1 | 45.2 | 2024-01-01T00:00:00Z | --- # Downsampler plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/downsampler/ The Downsampler Plugin enables time-based data aggregation and downsampling in InfluxDB 3 Core. Reduce data volume by aggregating measurements over specified time intervals using functions like avg, sum, min, max, median, count, stddev, first\_value, last\_value, var, or approx\_median. The plugin supports both scheduled batch processing of historical data and on-demand downsampling through HTTP requests. Each downsampled record includes metadata about the original data points compressed. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type | Default | Description | |--------------------|------|-------------------------|-----------------------------------------------------------------------------------------| |`source_measurement`|string| required | Source measurement containing data to downsample | |`target_measurement`|string| required | Destination measurement for downsampled data | | `window` |string|required (scheduled only)|Time window for each downsampling job. Format: `` (for example, “1h”, “1d”)| ### Aggregation parameters | Parameter | Type | Default | Description | |-----------------|------|----------|-------------------------------------------------------------------------------------------| | `interval` |string| “10min” |Time interval for downsampling. Format: `` (for example, “10min”, “2h”, “1d”)| | `calculations` |string| “avg” | Aggregation functions. Single function or dot-separated field:aggregation pairs | |`specific_fields`|string|all fields| Dot-separated list of fields to downsample (for example, “co.temperature”) | |`excluded_fields`|string| none | Dot-separated list of fields and tags to exclude from downsampling results | ### Filtering parameters | Parameter | Type |Default| Description | |------------|------|-------|-------------------------------------------------------------------| |`tag_values`|string| none |Tag filters. Format: `tag:value1@value2@value3` for multiple values| | `offset` |string| “0” | Time offset to apply to the window | ### Advanced parameters | Parameter | Type | Default | Description | |-----------------|-------|---------|---------------------------------------------------| |`target_database`|string |“default”| Database for storing downsampled data | | `max_retries` |integer| 5 | Maximum number of retries for write operations | | `batch_size` |string | “30d” |Time interval for batch processing (HTTP mode only)| ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [downsampling\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/downsampler/downsampling_config_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Schema management Each downsampled record includes three additional metadata columns: * `record_count`: the number of original points compressed into this single downsampled row * `time_from`: the minimum timestamp among the original points in the interval * `time_to`: the maximum timestamp among the original points in the interval ## Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. No additional Python packages required for this plugin. ## Trigger setup ### Scheduled downsampling Run downsampling periodically on historical data: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/downsampler/downsampler.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'source_measurement=cpu_metrics,target_measurement=cpu_hourly,interval=1h,window=6h,calculations=avg,specific_fields=usage_user.usage_system' \ cpu_hourly_downsample ``` ### On-demand downsampling Trigger downsampling via HTTP requests: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/downsampler/downsampler.py" \ --trigger-spec "request:downsample" \ downsample_api ``` ## Example usage ### Example 1: CPU metrics hourly aggregation Downsample CPU usage data from 1-minute intervals to hourly averages: ```bash # Create the trigger influxdb3 create trigger \ --database system_metrics \ --path "gh:influxdata/downsampler/downsampler.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'source_measurement=cpu,target_measurement=cpu_hourly,interval=1h,window=6h,calculations=avg,specific_fields=usage_user.usage_system.usage_idle' \ cpu_hourly_downsample # Write test data influxdb3 write \ --database system_metrics \ "cpu,host=server1 usage_user=45.2,usage_system=12.1,usage_idle=42.7" # Query downsampled data (after trigger runs) influxdb3 query \ --database system_metrics \ "SELECT * FROM cpu_hourly WHERE time >= now() - 1d" ``` ### Expected output | host |usage\_user|usage\_system|usage\_idle|record\_count| time\_from | time\_to | time | |-------|-----------|-------------|-----------|-------------|--------------------|--------------------|--------------------| |server1| 44.8 | 11.9 | 43.3 | 60 |2024-01-01T00:00:00Z|2024-01-01T00:59:59Z|2024-01-01T01:00:00Z| **Aggregation details:** * Before: 60 individual CPU measurements over 1 hour * After: 1 aggregated measurement with averages and metadata * Metadata shows original record count and time range ### Example 2: Multi-field aggregation with different functions Apply different aggregation functions to different fields: ```bash # Create trigger with field-specific aggregations influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/downsampler/downsampler.py" \ --trigger-spec "every:10min" \ --trigger-arguments 'source_measurement=environment,target_measurement=environment_10min,interval=10min,window=30min,calculations=temperature:avg.humidity:avg.pressure:max' \ env_multi_agg # Write data with various sensor readings influxdb3 write \ --database sensors \ "environment,location=office temperature=22.5,humidity=45.2,pressure=1013.25" # Query aggregated data influxdb3 query \ --database sensors \ "SELECT * FROM environment_10min WHERE time >= now() - 1h" ``` ### Expected output |location|temperature|humidity|pressure|record\_count| time | |--------|-----------|--------|--------|-------------|--------------------| | office | 22.3 | 44.8 | 1015.1 | 10 |2024-01-01T00:10:00Z| ### Example 3: HTTP API downsampling with backfill Use HTTP API for on-demand downsampling with historical data: ```bash # Send HTTP request for backfill downsampling curl -X POST http://localhost:8181/api/v3/engine/downsample \ --header "Authorization: Bearer YOUR_TOKEN" \ --data '{ "source_measurement": "metrics", "target_measurement": "metrics_daily", "target_database": "analytics", "interval": "1d", "batch_size": "7d", "calculations": [["cpu_usage", "avg"], ["memory_usage", "max"], ["disk_usage", "avg"]], "backfill_start": "2024-01-01T00:00:00Z", "backfill_end": "2024-01-31T00:00:00Z", "max_retries": 3 }' ``` ## Code overview ### Files * `downsampler.py`: The main plugin code containing handlers for scheduled and HTTP-triggered downsampling * `downsampling_config_scheduler.toml`: Example TOML configuration file for scheduled triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event (with nanosecond precision) * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing the action or error with unique task\_id for traceability ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled downsampling tasks. Queries historical data within the specified window and applies aggregation functions. Key operations: 1. Parses configuration from arguments or TOML file 2. Queries source measurement with optional tag filters 3. Applies time-based aggregation with specified functions 4. Writes downsampled data with metadata columns #### `process_http_request(influxdb3_local, request_body, args)` Handles HTTP-triggered on-demand downsampling. Processes batch downsampling with configurable time ranges for backfill scenarios. Key operations: 1. Parses JSON request body parameters 2. Processes data in configurable time batches 3. Applies aggregation functions to historical data 4. Returns processing statistics and results #### `aggregate_data(data, interval, calculations)` Core aggregation engine that applies statistical functions to time-series data. Supported aggregation functions: * `avg`: Average value * `sum`: Sum of values * `min`: Minimum value * `max`: Maximum value * `median`: Median value * `count`: Count of values * `stddev`: Standard deviation * `first_value`: First value in time interval * `last_value`: Last value in time interval * `var`: Variance of values * `approx_median`: Approximate median (faster than exact median) ## Troubleshooting ### Common issues #### Issue: No data in target measurement **Solution**: Check that source measurement exists and contains data in the specified time window: ```bash influxdb3 query --database mydb "SELECT COUNT(*) FROM source_measurement WHERE time >= now() - 1h" ``` #### Issue: Aggregation function not working **Solution**: Verify field names and aggregation syntax. Use SHOW FIELD KEYS to check available fields: ```bash influxdb3 query --database mydb "SHOW FIELD KEYS FROM source_measurement" ``` #### Issue: Tag filters not applied **Solution**: Check tag value format. Use @ separator for multiple values: ```bash --trigger-arguments 'tag_values=host:server1@server2@server3' ``` #### Issue: HTTP endpoint not accessible **Solution**: Verify the trigger was created with correct request specification: ```bash influxdb3 list triggers --database mydb ``` ### Debugging tips 1. **Check execution logs** with task ID filtering: ``` influxdb3 query --database YOUR_DATABASE \ "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%task_id%' ORDER BY event_time DESC LIMIT 10" ``` 2. **Test with smaller time windows** for debugging: ``` --trigger-arguments 'window=5min,interval=1min' ``` 3. **Verify field types** before aggregation: ``` influxdb3 query --database mydb "SELECT * FROM source_measurement LIMIT 1" ``` ### Performance considerations #### Consolidate calculations in fewer triggers For best performance, define a single trigger per measurement that performs all necessary field calculations. Avoid creating multiple separate triggers that each handle only one field or calculation. Internal testing showed significant performance differences based on trigger design: * **Many triggers** (one calculation each): When 134 triggers were created, each handling a single calculation for a measurement, the cluster showed degraded performance with high CPU and memory usage. * **Consolidated triggers** (all calculations per measurement): When triggers were restructured so each one performed all necessary field calculations for a measurement, CPU usage dropped to approximately 4% and memory remained stable. #### Recommended Combine all field calculations for a measurement in one trigger: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/downsampler/downsampler.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'source_measurement=temperature,target_measurement=temperature_hourly,interval=1h,window=6h,calculations=temp:avg.temp:max.temp:min,specific_fields=temp' \ temperature_hourly_downsample ``` #### Not recommended Multiple triggers for the same measurement creates unnecessary overhead: ```bash # Avoid creating multiple triggers for calculations on the same measurement influxdb3 create trigger ... --trigger-arguments 'calculations=temp:avg' avg_trigger influxdb3 create trigger ... --trigger-arguments 'calculations=temp:max' max_trigger influxdb3 create trigger ... --trigger-arguments 'calculations=temp:min' min_trigger ``` #### Use specific\_fields to limit processing If your measurement contains fields that you don’t need to downsample, use the `specific_fields` parameter to specify only the relevant ones. Without this parameter, the downsampler processes all fields and applies the default aggregation (such as `avg`) to fields not listed in your calculations, which can lead to unnecessary processing and storage. ```bash # Only downsample the 'temp' field, ignore other fields in the measurement --trigger-arguments 'specific_fields=temp' # Downsample multiple specific fields --trigger-arguments 'specific_fields=temp.humidity.pressure' ``` #### Additional performance tips * **Batch processing**: Use appropriate `batch_size` for HTTP requests to balance memory usage and performance * **Retry logic**: Configure `max_retries` based on network reliability * **Metadata overhead**: Metadata columns add approximately 20% storage overhead but provide valuable debugging information * **Index optimization**: Tag filters are more efficient than field filters for large datasets ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Downsampler plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/downsampler) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[downsampling](/influxdb3/core/tags/downsampling/)[aggregation](/influxdb3/core/tags/aggregation/)[performance](/influxdb3/core/tags/performance/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | source_measurement | string | required | Source measurement containing data to downsample | | target_measurement | string | required | Destination measurement for downsampled data | | window | string | required (scheduled only) | Time window for each downsampling job. Format: (for example, “1h”, “1d”) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | interval | string | “10min” | Time interval for downsampling. Format: (for example, “10min”, “2h”, “1d”) | | calculations | string | “avg” | Aggregation functions. Single function or dot-separated field:aggregation pairs | | specific_fields | string | all fields | Dot-separated list of fields to downsample (for example, “co.temperature”) | | excluded_fields | string | none | Dot-separated list of fields and tags to exclude from downsampling results | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | tag_values | string | none | Tag filters. Format: tag:value1@value2@value3 for multiple values | | offset | string | “0” | Time offset to apply to the window | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | target_database | string | “default” | Database for storing downsampled data | | max_retries | integer | 5 | Maximum number of retries for write operations | | batch_size | string | “30d” | Time interval for batch processing (HTTP mode only) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | | host | usage_user | usage_system | usage_idle | record_count | time_from | time_to | time | | --- | --- | --- | --- | --- | --- | --- | --- | | host | usage_user | usage_system | usage_idle | record_count | time_from | time_to | time | | server1 | 44.8 | 11.9 | 43.3 | 60 | 2024-01-01T00:00:00Z | 2024-01-01T00:59:59Z | 2024-01-01T01:00:00Z | | location | temperature | humidity | pressure | record_count | time | | --- | --- | --- | --- | --- | --- | | location | temperature | humidity | pressure | record_count | time | | office | 22.3 | 44.8 | 1015.1 | 10 | 2024-01-01T00:10:00Z | --- # Forecast error evaluator plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/forecast-error-evaluator/ The Forecast Error Evaluator Plugin validates forecast model accuracy for time series data in InfluxDB 3 Core by comparing predicted values with actual observations. The plugin periodically computes error metrics (MSE, MAE, RMSE, MAPE, or SMAPE), detects anomalies based on error thresholds, and sends notifications when forecast accuracy degrades. It includes debounce logic to suppress transient anomalies and supports multi-channel notifications via the Notification Sender Plugin. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type |Default | Description | |----------------------|------|--------|----------------------------------------------------------------------------| |`forecast_measurement`|string|required| Measurement containing forecasted values | | `actual_measurement` |string|required| Measurement containing actual (ground truth) values | | `forecast_field` |string|required| Field name for forecasted values | | `actual_field` |string|required| Field name for actual values | | `error_metric` |string|required| Error metric to compute: “mse”, “mae”, “rmse”, “mape”, or “smape” | | `error_thresholds` |string|required|Threshold levels. Format: `INFO-"0.5":WARN-"0.9":ERROR-"1.2":CRITICAL-"1.5"`| | `window` |string|required|Time window for data analysis. Format: `` (for example, “1h”) | | `senders` |string|required| Dot-separated list of notification channels (for example, “slack.discord”) | ### Notification parameters | Parameter | Type | Default | Description | |-------------------|-------|----------------|-----------------------------------------------------------------------------------------------------------------| |`notification_text`|string |default template|Template for notification message with variables `$measurement`, `$level`, `$field`, `$error`, `$metric`, `$tags`| |`notification_path`|string | “notify” | URL path for the notification sending plugin | | `port_override` |integer| 8181 | Port number where InfluxDB accepts requests | ### Timing parameters | Parameter | Type |Default| Description | |------------------------|------|-------|--------------------------------------------------------------------------------| |`min_condition_duration`|string| none |Minimum duration for anomaly condition to persist before triggering notification| | `rounding_freq` |string| “1s” | Frequency to round timestamps for alignment | ### Authentication parameters | Parameter | Type | Default | Description | |----------------------|------|------------|--------------------------------------------------------------------| |`influxdb3_auth_token`|string|env variable|API token for InfluxDB 3 Core. Can be set via `INFLUXDB3_AUTH_TOKEN`| ### Sender-specific parameters #### Slack notifications | Parameter | Type |Default | Description | |-------------------|------|--------|---------------------------| |`slack_webhook_url`|string|required| Webhook URL from Slack | | `slack_headers` |string| none |Base64-encoded HTTP headers| #### Discord notifications | Parameter | Type |Default | Description | |---------------------|------|--------|---------------------------| |`discord_webhook_url`|string|required| Webhook URL from Discord | | `discord_headers` |string| none |Base64-encoded HTTP headers| #### HTTP notifications | Parameter | Type |Default | Description | |------------------|------|--------|------------------------------------| |`http_webhook_url`|string|required|Custom webhook URL for POST requests| | `http_headers` |string| none | Base64-encoded HTTP headers | #### SMS notifications (via Twilio) | Parameter | Type | Default | Description | |--------------------|------|------------|-------------------------------------------------| | `twilio_sid` |string|env variable| Twilio Account SID (or `TWILIO_SID` env var) | | `twilio_token` |string|env variable| Twilio Auth Token (or `TWILIO_TOKEN` env var) | |`twilio_from_number`|string| required |Twilio sender number (for example, “+1234567890”)| | `twilio_to_number` |string| required | Recipient number (for example, “+0987654321”) | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [forecast\_error\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/forecast_error_evaluator/forecast_error_config_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Notification Sender Plugin for InfluxDB 3 Core**: Required for sending notifications. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). * **Python packages**: * `pandas` (for data processing) * `requests` (for HTTP notifications) ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package pandas influxdb3 install package requests ``` 3. Install the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) (required) ## Trigger setup ### Scheduled forecast validation Run forecast error evaluation periodically: ```bash influxdb3 create trigger \ --database weather_forecasts \ --path "gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py" \ --trigger-spec "every:30m" \ --trigger-arguments 'forecast_measurement=temperature_forecast,actual_measurement=temperature_actual,forecast_field=predicted_temp,actual_field=temp,error_metric=rmse,error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0",window=1h,senders=slack,slack_webhook_url="$SLACK_WEBHOOK_URL"' \ forecast_validation ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ## Example usage ### Example 1: Temperature forecast validation with Slack alerts Validate temperature forecast accuracy and send Slack notifications: ```bash # Create the trigger influxdb3 create trigger \ --database weather_db \ --path "gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py" \ --trigger-spec "every:15m" \ --trigger-arguments 'forecast_measurement=temp_forecast,actual_measurement=temp_actual,forecast_field=predicted,actual_field=temperature,error_metric=rmse,error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0",window=30m,senders=slack,slack_webhook_url="$SLACK_WEBHOOK_URL",min_condition_duration=10m' \ temp_forecast_check # Write forecast data influxdb3 write \ --database weather_db \ "temp_forecast,location=station1 predicted=22.5" # Write actual data influxdb3 write \ --database weather_db \ "temp_actual,location=station1 temperature=21.8" # Check logs after trigger runs influxdb3 query \ --database YOUR_DATABASE \ "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'temp_forecast_check'" ``` **Expected output** * Plugin computes RMSE between forecast and actual values * If RMSE \> 0.5, sends INFO-level notification * If RMSE \> 1.0, sends WARN-level notification * Only triggers if condition persists for 10+ minutes (debounce) Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. **Notification example:** [WARN] Forecast error alert in temp\_forecast.predicted: rmse=1.2. Tags: location=station1 ### Example 2: Multi-metric validation with multiple channels Monitor multiple forecast metrics with different notification channels: ```bash # Create trigger with Discord and HTTP notifications influxdb3 create trigger \ --database analytics \ --path "gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'forecast_measurement=sales_forecast,actual_measurement=sales_actual,forecast_field=predicted_sales,actual_field=sales_amount,error_metric=mae,error_thresholds=WARN-"1000":ERROR-"5000":CRITICAL-"10000",window=6h,senders=discord.http,discord_webhook_url="$DISCORD_WEBHOOK_URL",http_webhook_url="$HTTP_WEBHOOK_URL",notification_text="[$$level] Sales forecast error: $$metric=$$error (threshold exceeded)",rounding_freq=5min' \ sales_forecast_monitor ``` Set `DISCORD_WEBHOOK_URL` and `HTTP_WEBHOOK_URL` to your webhook URLs. ### Example 3: SMS alerts for critical forecast failures Set up SMS notifications for critical forecast accuracy issues: ```bash # Set environment variables (recommended for sensitive data) export TWILIO_SID="your_twilio_sid" export TWILIO_TOKEN="your_twilio_token" # Create trigger with SMS notifications influxdb3 create trigger \ --database production_forecasts \ --path "gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py" \ --trigger-spec "every:5m" \ --trigger-arguments 'forecast_measurement=demand_forecast,actual_measurement=demand_actual,forecast_field=predicted_demand,actual_field=actual_demand,error_metric=mse,error_thresholds=CRITICAL-"100000",window=15m,senders=sms,twilio_from_number="+1234567890",twilio_to_number="+0987654321",notification_text="CRITICAL: Production demand forecast error exceeded threshold. MSE: $$error",min_condition_duration=2m' \ critical_forecast_alert ``` ## Using TOML Configuration Files This plugin supports using TOML configuration files for complex configurations. ### Important Requirements **To use TOML configuration files, you must set the `PLUGIN_DIR` environment variable in the InfluxDB 3 Core host environment:** ```bash PLUGIN_DIR=~/.plugins influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` ### Example TOML Configuration ```toml # forecast_error_config_scheduler.toml forecast_measurement = "temperature_forecast" actual_measurement = "temperature_actual" forecast_field = "predicted_temp" actual_field = "temperature" error_metric = "rmse" error_thresholds = 'INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0"' window = "1h" senders = "slack" slack_webhook_url = "$SLACK_WEBHOOK_URL" min_condition_duration = "10m" rounding_freq = "1min" notification_text = "[$$level] Forecast validation alert: $$metric=$$error in $$measurement.$$field" # Authentication (use environment variables instead when possible) influxdb3_auth_token = "your_token_here" ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Create trigger using TOML config ```bash influxdb3 create trigger \ --database weather_db \ --path "gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py" \ --trigger-spec "every:30m" \ --trigger-arguments config_file_path=forecast_error_config_scheduler.toml \ forecast_validation_trigger ``` ## Code overview ### Files * `forecast_error_evaluator.py`: The main plugin code containing scheduler handler for forecast validation * `forecast_error_config_scheduler.toml`: Example TOML configuration file ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing validation results or errors ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled forecast validation tasks. Queries forecast and actual measurements, computes error metrics, and triggers notifications. Key operations: 1. Parses configuration from arguments or TOML file 2. Queries forecast and actual measurements within time window 3. Aligns timestamps using rounding frequency 4. Computes specified error metric (MSE, MAE, RMSE, MAPE, or SMAPE) 5. Evaluates thresholds and applies debounce logic 6. Sends notifications via configured channels #### `compute_error_metric(forecast_values, actual_values, metric_type)` Core error computation engine that calculates forecast accuracy metrics. Supported error metrics: * `mse`: Mean Squared Error - measures average squared differences * `mae`: Mean Absolute Error - measures average absolute differences * `rmse`: Root Mean Squared Error - square root of MSE, same units as original data * `mape`: Mean Absolute Percentage Error - percentage-based error * `smape`: Symmetric Mean Absolute Percentage Error - bounded 0-200%, handles over/under-estimation symmetrically #### `evaluate_thresholds(error_value, threshold_config)` Evaluates computed error against configured thresholds to determine alert level. Returns alert level based on threshold ranges: * `INFO`: Informational threshold exceeded * `WARN`: Warning threshold exceeded * `ERROR`: Error threshold exceeded * `CRITICAL`: Critical threshold exceeded ## Troubleshooting ### Common issues #### Issue: No overlapping timestamps between forecast and actual data **Solution**: Check that both measurements have data in the specified time window and use `rounding_freq` for alignment: ```bash influxdb3 query --database mydb "SELECT time, field_value FROM forecast_measurement WHERE time >= now() - 1h" influxdb3 query --database mydb "SELECT time, field_value FROM actual_measurement WHERE time >= now() - 1h" ``` #### Issue: Notifications not being sent **Solution**: Verify the Notification Sender Plugin is installed and webhook URLs are correct: ```bash # Check if notifier plugin exists ls ~/.plugins/notifier_plugin.py # Test webhook URL manually curl -X POST "your_webhook_url" -d '{"text": "test message"}' ``` #### Issue: Error threshold format not recognized **Solution**: Use proper threshold format with level prefixes. Note that MAPE and SMAPE thresholds are in percentages: ```bash # For absolute metrics (MSE, MAE, RMSE) --trigger-arguments 'error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0"' # For percentage metrics (MAPE, SMAPE) --trigger-arguments 'error_thresholds=INFO-"5.0":WARN-"10.0":ERROR-"20.0":CRITICAL-"30.0"' ``` #### Issue: MAPE/SMAPE calculation errors with zero values **Solution**: MAPE cannot be calculated when actual values are zero, and SMAPE cannot be calculated when both forecast and actual are zero. The plugin automatically skips such rows and logs warnings. For datasets with frequent zero values, consider using MAE or RMSE instead. #### Issue: Environment variables not loaded **Solution**: Set environment variables before starting InfluxDB: ```bash export INFLUXDB3_AUTH_TOKEN="your_token" export TWILIO_SID="your_sid" influxdb3 serve --plugin-dir ~/.plugins ``` ### Debugging tips 1. **Check data availability** in both measurements: ```bash influxdb3 query --database mydb \ "SELECT COUNT(*) FROM forecast_measurement WHERE time >= now() - window" ``` 1. **Verify timestamp alignment** with rounding frequency: ```bash --trigger-arguments 'rounding_freq=5min' ``` 1. **Test with shorter windows** for faster debugging: ```bash --trigger-arguments 'window=10m,min_condition_duration=1m' ``` 1. **Monitor notification delivery** in logs: ```bash influxdb3 query --database YOUR_DATABASE \ "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notification%'" ``` ### Performance considerations * **Data alignment**: Use appropriate `rounding_freq` to balance accuracy and performance * **Window size**: Larger windows increase computation time but provide more robust error estimates * **Debounce duration**: Balance between noise suppression and alert responsiveness * **Notification throttling**: Built-in retry logic prevents notification spam * **Memory usage**: Plugin processes data in pandas DataFrames - consider memory for large datasets ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Forecast error evaluator plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/forecast_error_evaluator) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[forecasting](/influxdb3/core/tags/forecasting/)[evaluation](/influxdb3/core/tags/evaluation/)[analytics](/influxdb3/core/tags/analytics/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | forecast_measurement | string | required | Measurement containing forecasted values | | actual_measurement | string | required | Measurement containing actual (ground truth) values | | forecast_field | string | required | Field name for forecasted values | | actual_field | string | required | Field name for actual values | | error_metric | string | required | Error metric to compute: “mse”, “mae”, “rmse”, “mape”, or “smape” | | error_thresholds | string | required | Threshold levels. Format: INFO-"0.5":WARN-"0.9":ERROR-"1.2":CRITICAL-"1.5" | | window | string | required | Time window for data analysis. Format: (for example, “1h”) | | senders | string | required | Dot-separated list of notification channels (for example, “slack.discord”) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | notification_text | string | default template | Template for notification message with variables $measurement , $level , $field , $error , $metric , $tags | | notification_path | string | “notify” | URL path for the notification sending plugin | | port_override | integer | 8181 | Port number where InfluxDB accepts requests | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | min_condition_duration | string | none | Minimum duration for anomaly condition to persist before triggering notification | | rounding_freq | string | “1s” | Frequency to round timestamps for alignment | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | influxdb3_auth_token | string | env variable | API token for InfluxDB 3 Core. Can be set via INFLUXDB3_AUTH_TOKEN | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | slack_webhook_url | string | required | Webhook URL from Slack | | slack_headers | string | none | Base64-encoded HTTP headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | discord_webhook_url | string | required | Webhook URL from Discord | | discord_headers | string | none | Base64-encoded HTTP headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | http_webhook_url | string | required | Custom webhook URL for POST requests | | http_headers | string | none | Base64-encoded HTTP headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | twilio_sid | string | env variable | Twilio Account SID (or TWILIO_SID env var) | | twilio_token | string | env variable | Twilio Auth Token (or TWILIO_TOKEN env var) | | twilio_from_number | string | required | Twilio sender number (for example, “+1234567890”) | | twilio_to_number | string | required | Recipient number (for example, “+0987654321”) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # InfluxDB to Iceberg plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/influxdb-to-iceberg/ The InfluxDB to Iceberg Plugin enables data transfer from InfluxDB 3 Core to Apache Iceberg tables. Transfer time series data to Iceberg for long-term storage, analytics, or integration with data lake architectures. The plugin supports both scheduled batch transfers of historical data and on-demand transfers via HTTP API. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Scheduler trigger parameters #### Required parameters | Parameter | Type |Default | Description | |-----------------|------|--------|----------------------------------------------------------------------------------| | `measurement` |string|required| Source measurement containing data to transfer | | `window` |string|required|Time window for data transfer. Format: `` (for example, “1h”, “30d”)| |`catalog_configs`|string|required| Base64-encoded JSON string containing Iceberg catalog configuration | #### Optional parameters | Parameter | Type | Default | Description | |--------------------|------|----------------|----------------------------------------------------------------------------------| | `included_fields` |string|all fields/tags |Dot-separated list of fields and tags to include (for example, “usage\_user.host”)| | `excluded_fields` |string| none | Dot-separated list of fields and tags to exclude | | `namespace` |string| “default” | Iceberg namespace for the target table | | `table_name` |string|measurement name| Iceberg table name | |`auto_update_schema`|string| false |Automatically update Iceberg table schema when data doesn’t match existing schema | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [influxdb\_to\_iceberg\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/influxdb_to_iceberg/influxdb_to_iceberg_config_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ### HTTP trigger parameters #### Request body structure | Parameter | Type |Required| Description | |--------------------|-------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `measurement` |string | Yes | Source measurement containing data to transfer | | `catalog_configs` |object | Yes |Iceberg catalog configuration dictionary. See [PyIceberg catalog documentation](https://py.iceberg.apache.org/configuration/)| | `included_fields` | array | No | List of field and tag names to include in replication | | `excluded_fields` | array | No | List of field and tag names to exclude from replication | | `namespace` |string | No | Target Iceberg namespace (default: “default”) | | `table_name` |string | No | Target Iceberg table name (default: measurement name) | | `batch_size` |string | No | Batch size duration for processing (default: “1d”). Format: `` | | `backfill_start` |string | No | ISO 8601 datetime with timezone for backfill start | | `backfill_end` |string | No | ISO 8601 datetime with timezone for backfill end | |`auto_update_schema`|boolean| No | Automatically update Iceberg table schema when data doesn’t match existing schema (default: false) | ## Schema management * Automatically creates Iceberg table schema from the first batch of data * Maps pandas data types to Iceberg types: * `int64` → `IntegerType` * `float64` → `FloatType` * `datetime64[us]` → `TimestampType` * `object` → `StringType` * Fields with no null values are marked as `required` * The `time` column is converted to `datetime64[us]` for Iceberg compatibility * Tables are created in format: `.` ### Automatic schema updates When `auto_update_schema=true`: * **New fields**: Automatically added to Iceberg table schema as optional (nullable) columns * **Missing fields**: Added to DataFrame with null values based on existing schema types * **Schema evolution**: Ensures data compatibility between InfluxDB and Iceberg without manual intervention * **Backward compatibility**: Existing data remains valid as new columns are always optional ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled * **Python packages**: * `pandas` (for data manipulation) * `pyarrow` (for Parquet support) * `pyiceberg[catalog-options]` (for Iceberg integration) ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package pandas influxdb3 install package pyarrow influxdb3 install package "pyiceberg[s3fs,hive,sql-sqlite]" ``` **Note:** Include the appropriate PyIceberg extras based on your catalog type: * `[s3fs]` for S3 storage * `[hive]` for Hive metastore * `[sql-sqlite]` for SQL catalog with SQLite * See [PyIceberg documentation](https://py.iceberg.apache.org/#installation) for all options ## Schema requirement The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. ## Trigger setup ### Scheduled data transfer Periodically transfer data from InfluxDB 3 Core to Iceberg: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/influxdb_to_iceberg/influxdb_to_iceberg.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'measurement=cpu,window=1h,catalog_configs="eyJ1cmkiOiAiaHR0cDovL25lc3NpZTo5MDAwIn0=",namespace=monitoring,table_name=cpu_metrics' \ hourly_iceberg_transfer ``` ### HTTP API endpoint Create an on-demand transfer endpoint: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/influxdb_to_iceberg/influxdb_to_iceberg.py" \ --trigger-spec "request:replicate" \ iceberg_http_transfer ``` Enable the trigger: ```bash influxdb3 enable trigger --database mydb iceberg_http_transfer ``` The endpoint is registered at `/api/v3/engine/replicate`. ## Example usage ### Example 1: Basic scheduled transfer Transfer CPU metrics to Iceberg every hour: ```bash # Create trigger with base64-encoded catalog config # Original JSON: {"uri": "http://nessie:9000"} # Base64: eyJ1cmkiOiAiaHR0cDovL25lc3NpZTo5MDAwIn0= influxdb3 create trigger \ --database metrics \ --path "gh:influxdata/influxdb_to_iceberg/influxdb_to_iceberg.py" \ --trigger-spec "every:1h" \ --trigger-arguments 'measurement=cpu,window=24h,catalog_configs="eyJ1cmkiOiAiaHR0cDovL25lc3NpZTo5MDAwIn0="' \ cpu_to_iceberg # Write test data influxdb3 write \ --database metrics \ "cpu,host=server1 usage_user=45.2,usage_system=12.1" # After trigger runs, data is available in Iceberg table "default.cpu" ``` **Expected output** * Creates Iceberg table `default.cpu` with schema matching the measurement * Transfers all CPU data from the last 24 hours * Appends new data on each hourly run ### Example 2: HTTP backfill with field filtering Backfill specific fields from historical data: ```bash # Create and enable HTTP trigger influxdb3 create trigger \ --database metrics \ --path "gh:influxdata/influxdb_to_iceberg/influxdb_to_iceberg.py" \ --trigger-spec "request:replicate" \ iceberg_backfill influxdb3 enable trigger --database metrics iceberg_backfill # Request backfill via HTTP curl -X POST http://localhost:8181/api/v3/engine/replicate \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "measurement": "temperature", "catalog_configs": { "type": "sql", "uri": "sqlite:///path/to/catalog.db" }, "included_fields": ["temp_celsius", "humidity", "sensor_id"], "namespace": "weather", "table_name": "temperature_history", "batch_size": "12h", "backfill_start": "2024-01-01T00:00:00+00:00", "backfill_end": "2024-01-07T00:00:00+00:00" }' ``` **Expected output** * Creates Iceberg table `weather.temperature_history` * Transfers only `temp_celsius` and `humidity` fields * Processes data in 12-hour batches for the specified week * Returns status of the backfill operation ### Example 3: S3-backed Iceberg catalog Transfer data to Iceberg tables stored in S3: ```bash # Create catalog config JSON cat > catalog_config.json << EOF { "type": "sql", "uri": "sqlite:///iceberg/catalog.db", "warehouse": "s3://my-bucket/iceberg-warehouse/", "s3.endpoint": "http://minio:9000", "s3.access-key-id": "minioadmin", "s3.secret-access-key": "minioadmin", "s3.path-style-access": true } EOF # Encode to base64 CATALOG_CONFIG=$(base64 < catalog_config.json) # Create trigger influxdb3 create trigger \ --database metrics \ --path "gh:influxdata/influxdb_to_iceberg/influxdb_to_iceberg.py" \ --trigger-spec "every:30m" \ --trigger-arguments "measurement=sensor_data,window=1h,catalog_configs=\"$CATALOG_CONFIG\",namespace=iot,table_name=sensors" \ s3_iceberg_transfer ``` ## Code overview ### Files * `influxdb_to_iceberg.py`: The main plugin code containing handlers for scheduled and HTTP triggers * `influxdb_to_iceberg_config_scheduler.toml`: Example TOML configuration file for scheduled triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing the action or error ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled data transfers. Queries data within the specified window and appends to Iceberg tables. Key operations: 1. Parses configuration and decodes catalog settings 2. Queries source measurement with optional field filtering 3. Creates Iceberg table if needed 4. Appends data to Iceberg table #### `process_http_request(influxdb3_local, request_body, args)` Handles on-demand data transfers via HTTP. Supports backfill operations with configurable batch sizes. Key operations: 1. Validates request body parameters 2. Determines backfill time range 3. Processes data in batches 4. Returns transfer status ## Troubleshooting ### Common issues #### Issue: “Failed to decode catalog\_configs” error **Solution**: Ensure the catalog configuration is properly base64-encoded: ```bash # Create JSON file echo '{"uri": "http://nessie:9000"}' > config.json # Encode to base64 base64 config.json ``` #### Issue: “Failed to create Iceberg table” error **Solution**: 1. Verify catalog configuration is correct 2. Check warehouse path permissions 3. Ensure required PyIceberg extras are installed:`bash influxdb3 install package "pyiceberg[s3fs]"` #### Issue: No data in Iceberg table after transfer **Solution**: 1. Check if source measurement contains data:`bash influxdb3 query --database mydb "SELECT COUNT(*) FROM measurement"` 2. Verify time window covers data:`bash influxdb3 query --database mydb "SELECT MIN(time), MAX(time) FROM measurement"` 3. Check logs for errors:`bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_level = 'ERROR'"` #### Issue: “Incompatible change: cannot add required column” error **Solution**: This occurs when trying to add a required (non-nullable) column to an existing table. With `auto_update_schema=true`, new columns are automatically added as optional. If you encounter this error: 1. Ensure `auto_update_schema=true` in your configuration 2. Check that you’re using the latest version of the plugin ### Debugging tips 1. **Test catalog connectivity**: ```python from pyiceberg.catalog import load_catalog catalog = load_catalog("my_catalog", **catalog_configs) print(catalog.list_namespaces()) ``` 1. **Verify field names**: ``` influxdb3 query --database mydb "SHOW FIELD KEYS FROM measurement" ``` 2. **Use smaller windows** for initial testing: ``` --trigger-arguments 'window=5m,...' ``` ### Performance considerations * **File sizing**: Each scheduled run creates new Parquet files. Use appropriate window sizes to balance file count and size * **Batch processing**: For HTTP transfers, adjust `batch_size` based on available memory * **Field and tag filtering**: Use `included_fields` to reduce data volume when only specific fields and tags are needed * **Catalog choice**: SQL catalogs (SQLite) are simpler but REST catalogs scale better ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [InfluxDB to Iceberg plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/influxdb_to_iceberg) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[iceberg](/influxdb3/core/tags/iceberg/)[export](/influxdb3/core/tags/export/)[data-lake](/influxdb3/core/tags/data-lake/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Source measurement containing data to transfer | | window | string | required | Time window for data transfer. Format: (for example, “1h”, “30d”) | | catalog_configs | string | required | Base64-encoded JSON string containing Iceberg catalog configuration | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | included_fields | string | all fields/tags | Dot-separated list of fields and tags to include (for example, “usage_user.host”) | | excluded_fields | string | none | Dot-separated list of fields and tags to exclude | | namespace | string | “default” | Iceberg namespace for the target table | | table_name | string | measurement name | Iceberg table name | | auto_update_schema | string | false | Automatically update Iceberg table schema when data doesn’t match existing schema | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | | Parameter | Type | Required | Description | | --- | --- | --- | --- | | Parameter | Type | Required | Description | | measurement | string | Yes | Source measurement containing data to transfer | | catalog_configs | object | Yes | Iceberg catalog configuration dictionary. See PyIceberg catalog documentation | | included_fields | array | No | List of field and tag names to include in replication | | excluded_fields | array | No | List of field and tag names to exclude from replication | | namespace | string | No | Target Iceberg namespace (default: “default”) | | table_name | string | No | Target Iceberg table name (default: measurement name) | | batch_size | string | No | Batch size duration for processing (default: “1d”). Format: | | backfill_start | string | No | ISO 8601 datetime with timezone for backfill start | | backfill_end | string | No | ISO 8601 datetime with timezone for backfill end | | auto_update_schema | boolean | No | Automatically update Iceberg table schema when data doesn’t match existing schema (default: false) | --- # MAD-based anomaly detection plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/mad-anomaly-detection/ The MAD-Based Anomaly Detection Plugin provides real-time anomaly detection for time series data in InfluxDB 3 Core using Median Absolute Deviation (MAD). Detect outliers in your field values as data is written, with configurable thresholds for both count-based and duration-based alerts. The plugin maintains in-memory deques for efficient computation and integrates with the Notification Sender Plugin to deliver alerts via multiple channels. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type |Default | Description | |----------------|------|--------|--------------------------------------------------------------------------| | `measurement` |string|required| Source measurement to monitor for anomalies | |`mad_thresholds`|string|required| MAD threshold conditions. Format: `field:k:window_count:threshold` | | `senders` |string|required|Dot-separated list of notification channels (for example, “slack.discord”)| ### MAD threshold parameters | Component | Description | Example | |--------------|-----------------------------------------------------|-----------| | `field_name` | The numeric field to monitor | `temp` | | `k` | MAD multiplier for anomaly threshold | `2.5` | |`window_count`| Number of recent points for MAD computation | `20` | | `threshold` |Count (integer) or duration (for example, “2m”, “1h”)|`5` or `2m`| Multiple thresholds are separated by `@`: `temp:2.5:20:5@load:3:10:2m` ### Optional parameters | Parameter | Type | Default | Description | |-------------------------|------|------------------------------------|------------------------------------------------------------------------------------------| | `influxdb3_auth_token` |string| env var | API token for InfluxDB 3 Core (or use INFLUXDB3\_AUTH\_TOKEN env var) | | `state_change_count` |string| “0” | Maximum allowed value flips before suppressing notifications | |`notification_count_text`|string|see *Default notification templates*| Template for count-based alerts with variables: $table, $field, $threshold\_count, $tags | |`notification_time_text` |string|see *Default notification templates*|Template for duration-based alerts with variables: $table, $field, $threshold\_time, $tags| | `notification_path` |string| “notify” | URL path for the notification sending plugin | | `port_override` |string| “8181” | Port number where InfluxDB accepts requests | #### Default notification templates * Count: `"MAD count alert: Field $field in $table outlier for $threshold_count consecutive points. Tags: $tags"` * Time: `"MAD duration alert: Field $field in $table outlier for $threshold_time. Tags: $tags"` ### Notification channel parameters #### Slack | Parameter | Type |Required| Description | |-------------------|------|--------|---------------------------| |`slack_webhook_url`|string| Yes | Webhook URL from Slack | | `slack_headers` |string| No |Base64-encoded HTTP headers| #### Discord | Parameter | Type |Required| Description | |---------------------|------|--------|---------------------------| |`discord_webhook_url`|string| Yes | Webhook URL from Discord | | `discord_headers` |string| No |Base64-encoded HTTP headers| #### HTTP | Parameter | Type |Required| Description | |------------------|------|--------|------------------------------------| |`http_webhook_url`|string| Yes |Custom webhook URL for POST requests| | `http_headers` |string| No | Base64-encoded HTTP headers | #### SMS/WhatsApp (via Twilio) | Parameter | Type |Required| Description | |--------------------|------|--------|------------------------------------------------| | `twilio_sid` |string| Yes |Twilio Account SID (or use TWILIO\_SID env var) | | `twilio_token` |string| Yes |Twilio Auth Token (or use TWILIO\_TOKEN env var)| |`twilio_from_number`|string| Yes | Sender phone number | | `twilio_to_number` |string| Yes | Recipient phone number | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [mad\_anomaly\_config\_data\_writes.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/mad_check/mad_anomaly_config_data_writes.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Python packages**: * `requests` (for notification delivery) * **Notification Sender Plugin** *(optional)*: Required if using the `senders` parameter. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package requests ``` 3. *(Optional)* For notifications, install the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) and create an HTTP trigger for it. ## Schema requirement The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. ## Trigger setup ### Real-time anomaly detection Detect anomalies as data is written: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/mad_check/mad_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=cpu,mad_thresholds="temp:2.5:20:5@load:3:10:2m",senders=slack,slack_webhook_url="$SLACK_WEBHOOK_URL"' \ mad_anomaly_detector ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ## Example usage ### Example 1: Basic count-based anomaly detection Detect when temperature exceeds 2.5 MADs from the median for 5 consecutive points: ```bash # Create trigger for count-based detection influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/mad_check/mad_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=environment,mad_thresholds="temperature:2.5:20:5",senders=slack,slack_webhook_url="$SLACK_WEBHOOK_URL"' \ temp_anomaly_detector # Write test data with an anomaly influxdb3 write \ --database sensors \ "environment,room=office temperature=22.1" influxdb3 write \ --database sensors \ "environment,room=office temperature=22.3" influxdb3 write \ --database sensors \ "environment,room=office temperature=45.8" # Anomaly # Continue writing anomalous values... ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. **Expected output** * Plugin maintains a 20-point window of recent temperature values * Computes median and MAD from this window * When temperature exceeds median ± 2.5\*MAD for 5 consecutive points, sends Slack notification * Notification includes: “MAD count alert: Field temperature in environment outlier for 5 consecutive points. Tags: room=office” ### Example 2: Duration-based anomaly detection with multiple fields Monitor CPU load and memory usage with different thresholds: ```bash # Create trigger with multiple thresholds influxdb3 create trigger \ --database monitoring \ --path "gh:influxdata/mad_check/mad_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=system_metrics,mad_thresholds="cpu_load:3:30:2m@memory_used:2.5:30:5m",senders=slack.discord,slack_webhook_url="$SLACK_WEBHOOK_URL",discord_webhook_url="$DISCORD_WEBHOOK_URL"' \ system_anomaly_detector ``` Set `SLACK_WEBHOOK_URL` and `DISCORD_WEBHOOK_URL` to your webhook URLs. **Expected output** * Monitors two fields independently: * `cpu_load`: Alerts when exceeds 3 MADs for 2 minutes * `memory_used`: Alerts when exceeds 2.5 MADs for 5 minutes * Sends notifications to both Slack and Discord ### Example 3: Anomaly detection with flip suppression Prevent alert fatigue from rapidly fluctuating values: ```bash # Create trigger with flip suppression influxdb3 create trigger \ --database iot \ --path "gh:influxdata/mad_check/mad_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments 'measurement=sensor_data,mad_thresholds="vibration:2:50:10",state_change_count=3,senders=http,http_webhook_url="$HTTP_WEBHOOK_URL",notification_count_text="Vibration anomaly detected on $table. Field: $field, Tags: $tags"' \ vibration_monitor ``` Set `HTTP_WEBHOOK_URL` to your HTTP webhook endpoint. **Expected output** * Detects vibration anomalies exceeding 2 MADs for 10 consecutive points * If values flip between normal/anomalous more than 3 times in the 50-point window, suppresses notifications * Sends custom formatted message to HTTP endpoint ## Using TOML Configuration Files This plugin supports using TOML configuration files to specify all plugin arguments. ### Important Requirements **To use TOML configuration files, you must set the `PLUGIN_DIR` environment variable in the InfluxDB 3 Core host environment.** ### Setting Up TOML Configuration 1. **Start InfluxDB 3 Core with the PLUGIN\_DIR environment variable set**: ```bash PLUGIN_DIR=~/.plugins influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 1. **Copy the example TOML configuration file to your plugin directory**: ```bash cp mad_anomaly_config_data_writes.toml ~/.plugins/ ``` 1. **Edit the TOML file** to match your requirements: ``` # Required parameters measurement = "cpu" mad_thresholds = "temp:2.5:20:5@load:3:10:2m" senders = "slack" # Notification settings slack_webhook_url = "$SLACK_WEBHOOK_URL" notification_count_text = "Custom alert: $field anomaly detected" ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. 2. **Create a trigger using the `config_file_path` argument**: ``` influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/mad_check/mad_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments config_file_path=mad_anomaly_config_data_writes.toml \ mad_toml_trigger ``` ## Code overview ### Files * `mad_check_plugin.py`: The main plugin code containing the handler for data write triggers * `mad_anomaly_config_data_writes.toml`: Example TOML configuration file ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing the action or error ### Main functions #### `process_writes(influxdb3_local, table_batches, args)` Handles real-time anomaly detection on incoming data. Key operations: 1. Filters table batches for the specified measurement 2. Maintains in-memory deques of recent values per field 3. Computes MAD for each monitored field 4. Tracks consecutive outliers and duration 5. Sends notifications when thresholds are met ### Key algorithms #### MAD (Median Absolute Deviation) Calculation ```python median = statistics.median(values) mad = statistics.median([abs(x - median) for x in values]) threshold = k * mad is_anomaly = abs(value - median) > threshold ``` #### Flip Detection Counts transitions between normal and anomalous states within the window to prevent alert fatigue from rapidly changing values. ## Troubleshooting ### Common issues #### Issue: No notifications being sent **Solution**: 1. Verify the Notification Sender Plugin is installed and running 2. Check webhook URLs are correct:`bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notification%'"` 3. Ensure notification channel parameters are provided for selected senders #### Issue: “Invalid MAD thresholds format” error **Solution**: Check threshold format is correct: * Count-based: `field:k:window:count` (for example, `temp:2.5:20:5`) * Duration-based: `field:k:window:duration` (for example, `temp:2.5:20:2m`) * Multiple thresholds separated by `@` #### Issue: Too many false positive alerts **Solution**: 1. Increase the k multiplier (for example, from 2.5 to 3.0) 2. Increase the threshold count or duration 3. Enable flip suppression with `state_change_count` 4. Increase the window size for more stable statistics #### Issue: Missing anomalies (false negatives) **Solution**: 1. Decrease the k multiplier 2. Decrease the threshold count or duration 3. Check if data has seasonal patterns that affect the median ### Debugging tips 1. **Monitor deque sizes**: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%Deque%'" ``` 1. **Check MAD calculations**: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%MAD:%'" ``` 1. **Test with known anomalies**: Write test data with obvious outliers to verify detection ### Performance considerations * **Memory usage**: Each field maintains a deque of `window_count` values * **Computation**: MAD is computed on every data write for monitored fields * **Caching**: Measurement and tag names are cached for 1 hour * **Notification retries**: Failed notifications retry up to 3 times with exponential backoff ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [MAD-based anomaly detection plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/mad_check) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[anomaly-detection](/influxdb3/core/tags/anomaly-detection/)[statistics](/influxdb3/core/tags/statistics/)[monitoring](/influxdb3/core/tags/monitoring/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Source measurement to monitor for anomalies | | mad_thresholds | string | required | MAD threshold conditions. Format: field:k:window_count:threshold | | senders | string | required | Dot-separated list of notification channels (for example, “slack.discord”) | | Component | Description | Example | | --- | --- | --- | | Component | Description | Example | | field_name | The numeric field to monitor | temp | | k | MAD multiplier for anomaly threshold | 2.5 | | window_count | Number of recent points for MAD computation | 20 | | threshold | Count (integer) or duration (for example, “2m”, “1h”) | 5 or 2m | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | influxdb3_auth_token | string | env var | API token for InfluxDB 3 Core (or use INFLUXDB3_AUTH_TOKEN env var) | | state_change_count | string | “0” | Maximum allowed value flips before suppressing notifications | | notification_count_text | string | see Default notification templates | Template for count-based alerts with variables: $table, $field, $threshold_count, $tags | | notification_time_text | string | see Default notification templates | Template for duration-based alerts with variables: $table, $field, $threshold_time, $tags | | notification_path | string | “notify” | URL path for the notification sending plugin | | port_override | string | “8181” | Port number where InfluxDB accepts requests | | Parameter | Type | Required | Description | | --- | --- | --- | --- | | Parameter | Type | Required | Description | | slack_webhook_url | string | Yes | Webhook URL from Slack | | slack_headers | string | No | Base64-encoded HTTP headers | | Parameter | Type | Required | Description | | --- | --- | --- | --- | | Parameter | Type | Required | Description | | discord_webhook_url | string | Yes | Webhook URL from Discord | | discord_headers | string | No | Base64-encoded HTTP headers | | Parameter | Type | Required | Description | | --- | --- | --- | --- | | Parameter | Type | Required | Description | | http_webhook_url | string | Yes | Custom webhook URL for POST requests | | http_headers | string | No | Base64-encoded HTTP headers | | Parameter | Type | Required | Description | | --- | --- | --- | --- | | Parameter | Type | Required | Description | | twilio_sid | string | Yes | Twilio Account SID (or use TWILIO_SID env var) | | twilio_token | string | Yes | Twilio Auth Token (or use TWILIO_TOKEN env var) | | twilio_from_number | string | Yes | Sender phone number | | twilio_to_number | string | Yes | Recipient phone number | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # Notifier plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/notifier/ The Notifier Plugin provides multi-channel notification capabilities for InfluxDB 3 Core, enabling real-time alert delivery through various communication channels. Send notifications via Slack, Discord, HTTP webhooks, SMS, or WhatsApp based on incoming HTTP requests. Acts as a centralized notification dispatcher that receives data from other plugins or external systems and routes notifications to the appropriate channels. ## Configuration This HTTP plugin receives all configuration via the request body. No trigger arguments are required. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Request body parameters Send these parameters as JSON in the HTTP POST request body: | Parameter | Type |Default | Description | |-------------------|------|--------|-------------------------------------------| |`notification_text`|string|required| Text content of the notification message | | `senders_config` |object|required|Configuration for each notification channel| ### Sender-specific configuration (in request body) The `senders_config` object accepts channel configurations where keys are sender names and values contain channel-specific settings: #### Slack notifications | Parameter | Type |Default | Description | |-------------------|------|--------|---------------------------| |`slack_webhook_url`|string|required| Slack webhook URL | | `slack_headers` |string| none |Base64-encoded JSON headers| #### Discord notifications | Parameter | Type |Default | Description | |---------------------|------|--------|---------------------------| |`discord_webhook_url`|string|required| Discord webhook URL | | `discord_headers` |string| none |Base64-encoded JSON headers| #### HTTP webhook notifications | Parameter | Type |Default | Description | |------------------|------|--------|--------------------------------| |`http_webhook_url`|string|required|Custom webhook URL for HTTP POST| | `http_headers` |string| none | Base64-encoded JSON headers | #### SMS notifications (via Twilio) | Parameter | Type |Default | Description | |--------------------|------|--------|-------------------------------------------------| | `twilio_sid` |string|required|Twilio Account SID (or use `TWILIO_SID` env var) | | `twilio_token` |string|required|Twilio Auth Token (or use `TWILIO_TOKEN` env var)| |`twilio_from_number`|string|required| Sender phone number in E.164 format | | `twilio_to_number` |string|required| Recipient phone number in E.164 format | #### WhatsApp notifications (via Twilio) | Parameter | Type |Default | Description | |--------------------|------|--------|-------------------------------------------------| | `twilio_sid` |string|required|Twilio Account SID (or use `TWILIO_SID` env var) | | `twilio_token` |string|required|Twilio Auth Token (or use `TWILIO_TOKEN` env var)| |`twilio_from_number`|string|required| Sender WhatsApp number in E.164 format | | `twilio_to_number` |string|required| Recipient WhatsApp number in E.164 format | ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Python packages**: * `httpx` (for HTTP requests) * `twilio` (for SMS/WhatsApp notifications) ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package httpx influxdb3 install package twilio ``` ## Trigger setup ### HTTP trigger Create an HTTP trigger to handle notification requests: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/notifier/notifier_plugin.py" \ --trigger-spec "request:notify" \ notification_trigger ``` This registers an HTTP endpoint at `/api/v3/engine/notify`. ### Enable trigger ```bash influxdb3 enable trigger --database mydb notification_trigger ``` ## Example usage ### Example 1: Slack notification Send a notification to Slack: ```bash curl -X POST http://localhost:8181/api/v3/engine/notify \ -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notification_text": "Alert: High CPU usage detected on server1", "senders_config": { "slack": { "slack_webhook_url": "'"$SLACK_WEBHOOK_URL"'" } } }' ``` Set `INFLUXDB3_AUTH_TOKEN` and `SLACK_WEBHOOK_URL` to your credentials. **Expected output** Notification sent to Slack channel with message: “Alert: High CPU usage detected on server1” ### Example 2: SMS notification Send an SMS via Twilio: ```bash curl -X POST http://localhost:8181/api/v3/engine/notify \ -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notification_text": "Critical alert: System down", "senders_config": { "sms": { "twilio_from_number": "'"$TWILIO_FROM_NUMBER"'", "twilio_to_number": "'"$TWILIO_TO_NUMBER"'" } } }' ``` Set `TWILIO_FROM_NUMBER` and `TWILIO_TO_NUMBER` to your phone numbers. Twilio credentials can be set via `TWILIO_SID` and `TWILIO_TOKEN` environment variables. ### Example 3: Multi-channel notification Send notifications via multiple channels simultaneously: ```bash curl -X POST http://localhost:8181/api/v3/engine/notify \ -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notification_text": "Performance warning: Memory usage above threshold", "senders_config": { "slack": { "slack_webhook_url": "'"$SLACK_WEBHOOK_URL"'" }, "discord": { "discord_webhook_url": "'"$DISCORD_WEBHOOK_URL"'" } } }' ``` Set `SLACK_WEBHOOK_URL` and `DISCORD_WEBHOOK_URL` to your webhook URLs. ## Code overview ### Files * `notifier_plugin.py`: The main plugin code containing the HTTP handler for notification dispatch ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'notification_trigger'" ``` ### Main functions #### `process_http_request(influxdb3_local, request_body, args)` Handles incoming HTTP notification requests. Parses the request body, extracts notification text and sender configurations, and dispatches notifications to configured channels. Key operations: 1. Validates request body for required `notification_text` and `senders_config` 2. Iterates through sender configurations (Slack, Discord, HTTP, SMS, WhatsApp) 3. Dispatches notifications with built-in retry logic and error handling 4. Returns success/failure status for each channel ## Troubleshooting ### Common issues #### Issue: Notification not delivered **Solution**: Verify webhook URLs are correct and accessible. Check Twilio credentials and phone number formats. Review logs for specific error messages. #### Issue: Authentication errors **Solution**: Ensure Twilio credentials are set via environment variables or request parameters. Verify webhook URLs have proper authentication if required. #### Issue: Rate limiting **Solution**: Plugin includes built-in retry logic with exponential backoff. Consider implementing client-side rate limiting for high-frequency notifications. ### Environment variables For security, set Twilio credentials as environment variables: ```bash export TWILIO_SID=your_account_sid export TWILIO_TOKEN=your_auth_token ``` ### Viewing logs Check processing logs in the InfluxDB system tables: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notifier%' ORDER BY event_time DESC LIMIT 10" ``` ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Notifier plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/notifier) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[notifications](/influxdb3/core/tags/notifications/)[alerting](/influxdb3/core/tags/alerting/)[integration](/influxdb3/core/tags/integration/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | notification_text | string | required | Text content of the notification message | | senders_config | object | required | Configuration for each notification channel | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | slack_webhook_url | string | required | Slack webhook URL | | slack_headers | string | none | Base64-encoded JSON headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | discord_webhook_url | string | required | Discord webhook URL | | discord_headers | string | none | Base64-encoded JSON headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | http_webhook_url | string | required | Custom webhook URL for HTTP POST | | http_headers | string | none | Base64-encoded JSON headers | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | twilio_sid | string | required | Twilio Account SID (or use TWILIO_SID env var) | | twilio_token | string | required | Twilio Auth Token (or use TWILIO_TOKEN env var) | | twilio_from_number | string | required | Sender phone number in E.164 format | | twilio_to_number | string | required | Recipient phone number in E.164 format | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | twilio_sid | string | required | Twilio Account SID (or use TWILIO_SID env var) | | twilio_token | string | required | Twilio Auth Token (or use TWILIO_TOKEN env var) | | twilio_from_number | string | required | Sender WhatsApp number in E.164 format | | twilio_to_number | string | required | Recipient WhatsApp number in E.164 format | --- # Prophet forecasting plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/prophet-forecasting/ The Prophet Forecasting Plugin enables time series forecasting for data in InfluxDB 3 Core using Facebook’s Prophet library. Generate predictions for future data points based on historical patterns, including seasonality, trends, and custom events. Supports both scheduled batch forecasting and on-demand HTTP-triggered forecasts with model persistence and validation capabilities. * **Model persistence**: Save and reuse trained models for consistent predictions * **Forecast validation**: Built-in accuracy assessment using Mean Squared Relative Error (MSRE) * **Holiday support**: Built-in holiday calendars and custom holiday configuration * **Advanced seasonality**: Configurable seasonality modes and changepoint detection * **Flexible time intervals**: Support for seconds, minutes, hours, days, weeks, months, quarters, and years ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Scheduled trigger parameters Set these parameters with `--trigger-arguments` when creating a scheduled trigger: | Parameter | Type |Default | Description | |--------------------|------|--------|------------------------------------------------------------------------| | `measurement` |string|required| Source measurement containing historical data | | `field` |string|required| Field name to forecast | | `window` |string|required| Historical data window. Format: `` (for example, “30d”) | |`forecast_horizont` |string|required| Forecast duration. Format: `` (for example, “2d”) | | `tag_values` |string|required|Dot-separated tag filters (for example, “region:us-west.device:sensor1”)| |`target_measurement`|string|required| Destination measurement for forecast results | | `model_mode` |string|required| Operation mode: “train” or “predict” | | `unique_suffix` |string|required| Unique model identifier for versioning | ### HTTP request parameters Send these parameters as JSON in the HTTP POST request body: | Parameter | Type |Default | Description | |--------------------|------|--------|---------------------------------------------------------------| | `measurement` |string|required| Source measurement containing historical data | | `field` |string|required| Field name to forecast | |`forecast_horizont` |string|required|Forecast duration. Format: `` (for example, “7d”)| | `tag_values` |object|required|Tag filters as JSON object (for example, {“region”:“us-west”}) | |`target_measurement`|string|required| Destination measurement for forecast results | | `unique_suffix` |string|required| Unique model identifier for versioning | | `start_time` |string|required| Historical window start (ISO 8601 format) | | `end_time` |string|required| Historical window end (ISO 8601 format) | ### Advanced parameters | Parameter | Type | Default | Description | |-------------------------|------------|----------|--------------------------------------------------------| | `seasonality_mode` | string |“additive”|Prophet seasonality mode: “additive” or “multiplicative”| |`changepoint_prior_scale`| number | 0.05 | Flexibility of trend changepoints | | `changepoints` |string/array| none | Changepoint dates (ISO format) | | `holiday_date_list` |string/array| none | Custom holiday dates (ISO format) | | `holiday_names` |string/array| none | Holiday names corresponding to dates | | `holiday_country_names` |string/array| none | Country codes for built-in holidays | | `inferred_freq` | string | auto |Manual frequency specification (for example, “1D”, “1H”)| | `validation_window` | string | “0s” | Validation period duration | | `msre_threshold` | number | infinity | Maximum acceptable Mean Squared Relative Error | | `target_database` | string | current | Database for forecast storage | | `save_mode` | string | “false” | Whether to save/load models (HTTP only) | ### Notification parameters | Parameter | Type |Default | Description | |----------------------|------|--------|-----------------------------------| | `is_sending_alert` |string|“false” |Enable alerts on validation failure| | `notification_text` |string|template| Custom alert message template | | `senders` |string| none |Dot-separated notification channels| | `notification_path` |string|“notify”| Notification endpoint path | |`influxdb3_auth_token`|string|env var | Authentication token | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [prophet\_forecasting\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/prophet_forecasting/prophet_forecasting_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Python packages**: * `pandas` (for data manipulation) * `numpy` (for numerical operations) * `requests` (for HTTP requests) * `prophet` (for time series forecasting) * **Notification Sender Plugin** *(optional)*: Required if using the `senders` parameter. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package pandas influxdb3 install package numpy influxdb3 install package requests influxdb3 install package prophet ``` 3. *(Optional)* For notifications, install the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) and create an HTTP trigger for it. ## Trigger setup ### Scheduled trigger Create a trigger for periodic forecasting: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/prophet_forecasting/prophet_forecasting.py" \ --trigger-spec "every:1d" \ --trigger-arguments "measurement=temperature,field=value,window=30d,forecast_horizont=2d,tag_values=region:us-west.device:sensor1,target_measurement=temperature_forecast,model_mode=train,unique_suffix=20250619_v1" \ prophet_forecast_trigger ``` ### HTTP trigger Create a trigger for on-demand forecasting: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/prophet_forecasting/prophet_forecasting.py" \ --trigger-spec "request:forecast" \ prophet_forecast_http_trigger ``` ### Enable triggers ```bash influxdb3 enable trigger --database mydb prophet_forecast_trigger influxdb3 enable trigger --database mydb prophet_forecast_http_trigger ``` ## Example usage ### Example 1: Basic scheduled forecasting Write historical data and create a forecast: ```bash # Write historical temperature data influxdb3 write \ --database mydb \ "temperature,region=us-west,device=sensor1 value=22.5" # Create and enable the trigger influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/prophet_forecasting/prophet_forecasting.py" \ --trigger-spec "every:1d" \ --trigger-arguments "measurement=temperature,field=value,window=30d,forecast_horizont=2d,tag_values=region:us-west.device:sensor1,target_measurement=temperature_forecast,model_mode=train,unique_suffix=v1" \ prophet_forecast influxdb3 enable trigger --database mydb prophet_forecast # Query forecast results (after trigger runs) influxdb3 query \ --database mydb \ "SELECT time, forecast, yhat_lower, yhat_upper FROM temperature_forecast ORDER BY time DESC LIMIT 5" ``` **Expected output** ``` +----------------------+---------+------------+------------+ | time | forecast| yhat_lower | yhat_upper | +----------------------+---------+------------+------------+ | 2025-06-21T00:00:00Z | 23.2 | 21.8 | 24.6 | | 2025-06-20T00:00:00Z | 22.9 | 21.5 | 24.3 | +----------------------+---------+------------+------------+ ``` ### Example 2: On-demand HTTP forecasting Example HTTP request for on-demand forecasting: ```bash curl -X POST http://localhost:8181/api/v3/engine/forecast \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "measurement": "temperature", "field": "value", "forecast_horizont": "7d", "tag_values": {"region":"us-west","device":"sensor1"}, "target_measurement": "temperature_forecast", "unique_suffix": "model_v1_20250722", "start_time": "2025-05-20T00:00:00Z", "end_time": "2025-06-19T00:00:00Z", "seasonality_mode": "additive", "changepoint_prior_scale": 0.05, "validation_window": "3d", "msre_threshold": 0.05 }' ``` ### Advanced forecasting with holidays ```bash curl -X POST http://localhost:8181/api/v3/engine/forecast \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "measurement": "sales", "field": "revenue", "forecast_horizont": "30d", "tag_values": {"store":"main_branch"}, "target_measurement": "revenue_forecast", "unique_suffix": "retail_model_v2", "start_time": "2024-01-01T00:00:00Z", "end_time": "2025-06-01T00:00:00Z", "holiday_country_names": ["US"], "holiday_date_list": ["2025-07-04"], "holiday_names": ["Independence Day"], "changepoints": ["2025-01-01", "2025-03-01"], "inferred_freq": "1D" }' ``` ## Output data structure Forecast results are written to the target measurement with the following structure: ### Tags * `model_version`: Model identifier from unique\_suffix parameter * Additional tags from original measurement query filters ### Fields * `forecast`: Predicted value (yhat from Prophet model) * `yhat_lower`: Lower bound of confidence interval * `yhat_upper`: Upper bound of confidence interval * `run_time`: Forecast execution timestamp (ISO 8601 format) ### Timestamp * `time`: Forecast timestamp in nanoseconds ## Code overview ### Files * `prophet_forecasting.py`: The main plugin code containing handlers for scheduled and HTTP triggers * `prophet_forecasting_scheduler.toml`: Example TOML configuration file for scheduled triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'prophet_forecast_trigger'" ``` ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled forecasting tasks. Queries historical data, trains or loads Prophet model, generates forecasts, and writes results. Key operations: 1. Parses configuration from arguments or TOML file 2. Queries historical data within specified window 3. Trains Prophet model or loads existing model 4. Generates forecasts for specified horizon 5. Optionally validates against actual data and sends alerts #### `process_http_request(influxdb3_local, request_body, args)` Handles on-demand forecast requests via HTTP. Supports backfill operations with configurable time ranges. ## Troubleshooting ### Common issues #### Issue: Model training failures **Solution**: Ensure sufficient historical data points for the specified window. Verify data contains required time column and forecast field. Check for data gaps that might affect frequency inference. Set `inferred_freq` manually if automatic detection fails. #### Issue: Validation failures **Solution**: Review MSRE threshold settings - values too low may cause frequent failures. Ensure validation window provides sufficient data for comparison. Check that validation data aligns temporally with forecast period. #### Issue: HTTP trigger issues **Solution**: Verify JSON request body format matches expected schema. Check authentication tokens and database permissions. Ensure start\_time and end\_time are in valid ISO 8601 format with timezone. #### Issue: Model persistence problems **Solution**: Verify plugin directory permissions for model storage. Check disk space availability in plugin directory. Ensure unique\_suffix values don’t conflict between different model versions. ### Model storage * **Location**: Models stored in `prophet_models/` directory within plugin directory * **Naming**: Files named `prophet_model_{unique_suffix}.json` * **Versioning**: Use descriptive unique\_suffix values for model management ### Time format support Supported time units for window, forecast\_horizont, and validation\_window: * `s` (seconds), `min` (minutes), `h` (hours) * `d` (days), `w` (weeks) * `m` (months ≈30.42 days), `q` (quarters ≈91.25 days), `y` (years = 365 days) ### Validation process When validation\_window is set: 1. Training data: `current_time - window` to `current_time - validation_window` 2. Validation data: `current_time - validation_window` to `current_time` 3. MSRE calculation: `mean((actual - predicted)² / actual²)` 4. Threshold comparison and optional alert dispatch ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Prophet forecasting plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/prophet_forecasting) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[forecasting](/influxdb3/core/tags/forecasting/)[prophet](/influxdb3/core/tags/prophet/)[machine-learning](/influxdb3/core/tags/machine-learning/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Source measurement containing historical data | | field | string | required | Field name to forecast | | window | string | required | Historical data window. Format: (for example, “30d”) | | forecast_horizont | string | required | Forecast duration. Format: (for example, “2d”) | | tag_values | string | required | Dot-separated tag filters (for example, “region:us-west.device:sensor1”) | | target_measurement | string | required | Destination measurement for forecast results | | model_mode | string | required | Operation mode: “train” or “predict” | | unique_suffix | string | required | Unique model identifier for versioning | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Source measurement containing historical data | | field | string | required | Field name to forecast | | forecast_horizont | string | required | Forecast duration. Format: (for example, “7d”) | | tag_values | object | required | Tag filters as JSON object (for example, {“region”:“us-west”}) | | target_measurement | string | required | Destination measurement for forecast results | | unique_suffix | string | required | Unique model identifier for versioning | | start_time | string | required | Historical window start (ISO 8601 format) | | end_time | string | required | Historical window end (ISO 8601 format) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | seasonality_mode | string | “additive” | Prophet seasonality mode: “additive” or “multiplicative” | | changepoint_prior_scale | number | 0.05 | Flexibility of trend changepoints | | changepoints | string/array | none | Changepoint dates (ISO format) | | holiday_date_list | string/array | none | Custom holiday dates (ISO format) | | holiday_names | string/array | none | Holiday names corresponding to dates | | holiday_country_names | string/array | none | Country codes for built-in holidays | | inferred_freq | string | auto | Manual frequency specification (for example, “1D”, “1H”) | | validation_window | string | “0s” | Validation period duration | | msre_threshold | number | infinity | Maximum acceptable Mean Squared Relative Error | | target_database | string | current | Database for forecast storage | | save_mode | string | “false” | Whether to save/load models (HTTP only) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | is_sending_alert | string | “false” | Enable alerts on validation failure | | notification_text | string | template | Custom alert message template | | senders | string | none | Dot-separated notification channels | | notification_path | string | “notify” | Notification endpoint path | | influxdb3_auth_token | string | env var | Authentication token | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # State change plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/state-change/ The State Change Plugin provides comprehensive field monitoring and threshold detection for InfluxDB 3 Core data streams. Detect field value changes, monitor threshold conditions, and trigger notifications when specified criteria are met. Supports both scheduled batch monitoring and real-time data write monitoring with configurable stability checks and multi-channel alerts. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type |Default | Description | |--------------------|------|--------|----------------------------------------------------------------------------------------------| | `measurement` |string|required| Measurement to monitor for field changes | |`field_change_count`|string|required|Dot-separated field thresholds (for example, “temp:3.load:2”). Supports count-based conditions| | `senders` |string|required| Dot-separated notification channels with multi-channel alert support (Slack, Discord, etc.) | | `window` |string|required| Time window for analysis. Format: `` (for example, “10m”, “1h”) | ### Data write trigger parameters | Parameter | Type |Default | Description | |------------------|------|--------|------------------------------------------------------------------------------------------------------------------| | `measurement` |string|required| Measurement to monitor for threshold conditions | |`field_thresholds`|string|required|Flexible threshold conditions with count-based and duration-based support (for example, “temp:30:10@status:ok:1h”)| | `senders` |string|required| Dot-separated notification channels with multi-channel alert support (Slack, Discord, HTTP, SMS, WhatsApp) | ### Notification parameters | Parameter | Type |Default | Description | |-------------------------|------|--------|-------------------------------------------------------------------------------------| | `influxdb3_auth_token` |string|env var |InfluxDB 3 Core API token with environment variable support for credential management| | `notification_text` |string|template| Customizable message template for scheduled notifications with dynamic variables | |`notification_count_text`|string|template| Customizable message template for count-based notifications with dynamic variables | |`notification_time_text` |string|template| Customizable message template for time-based notifications with dynamic variables | | `notification_path` |string|“notify”| Notification endpoint path | | `port_override` |number| 8181 | InfluxDB port override | ### Advanced parameters | Parameter | Type |Default| Description | |---------------------|------|-------|------------------------------------------------------------------------------------------| |`state_change_window`|number| 1 |Recent values to check for stability (configurable state change detection to reduce noise)| |`state_change_count` |number| 1 | Max changes allowed within stability window (configurable state change detection) | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. Example TOML configuration files provided: * [state\_change\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/state_change/state_change_config_scheduler.toml) - for scheduled triggers * [state\_change\_config\_data\_writes.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/state_change/state_change_config_data_writes.toml) - for data write triggers For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ### Channel-specific configuration Notification channels require additional parameters based on the sender type (same as the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/)). ## Schema requirement The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Notification Sender Plugin for InfluxDB 3 Core**: Required for sending notifications. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). * **Python packages**: * `requests` (for HTTP notifications) ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package requests ``` 3. *Optional*: For notifications, install and configure the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) ## Trigger setup ### Scheduled trigger Create a trigger for periodic field change monitoring: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "every:10m" \ --trigger-arguments "measurement=cpu,field_change_count=temp:3.load:2,window=10m,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \ state_change_scheduler ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Data write trigger Create a trigger for real-time threshold monitoring: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments "measurement=cpu,field_thresholds=temp:30:10@status:ok:1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \ state_change_datawrite ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Enable triggers ```bash influxdb3 enable trigger --database mydb state_change_scheduler influxdb3 enable trigger --database mydb state_change_datawrite ``` ## Example usage ### Example 1: Scheduled field change monitoring Monitor field changes over a time window and alert when thresholds are exceeded: ```bash # Write test data with changing values (7 writes = 6 changes) influxdb3 write \ --database sensors \ "temperature,location=office value=22.5" influxdb3 write \ --database sensors \ "temperature,location=office value=25.0" influxdb3 write \ --database sensors \ "temperature,location=office value=22.8" influxdb3 write \ --database sensors \ "temperature,location=office value=26.5" influxdb3 write \ --database sensors \ "temperature,location=office value=23.0" influxdb3 write \ --database sensors \ "temperature,location=office value=27.2" influxdb3 write \ --database sensors \ "temperature,location=office value=24.0" # Create and enable the trigger influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "every:15m" \ --trigger-arguments "measurement=temperature,field_change_count=value:5,window=1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \ temp_change_monitor influxdb3 enable trigger --database sensors temp_change_monitor ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. **Expected output** When the field changes more than 5 times within 1 hour, a notification is sent: “Temperature sensor value changed 6 times in 1h for tags location=office” ### Example 2: Advanced scheduled field change monitoring Monitor field changes over a time window and alert when thresholds are exceeded: ```bash influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "every:15m" \ --trigger-arguments "measurement=temperature,field_change_count=value:5,window=1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL,notification_text=Temperature sensor $field changed $changes times in $window for tags $tags" \ temp_change_monitor ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Real-time threshold detection Monitor data writes for threshold conditions: ```bash influxdb3 create trigger \ --database monitoring \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments "measurement=system_metrics,field_thresholds=cpu_usage:80:5@memory_usage:90:10min,senders=discord,discord_webhook_url=$DISCORD_WEBHOOK_URL" \ system_threshold_monitor ``` Set `DISCORD_WEBHOOK_URL` to your Discord incoming webhook URL. ### Multi-condition monitoring Monitor multiple fields with different threshold types: ```bash influxdb3 create trigger \ --database application \ --path "gh:influxdata/state_change/state_change_check_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments "measurement=app_health,field_thresholds=error_rate:0.05:3@response_time:500:30s@status:down:1,senders=slack.sms,slack_webhook_url=$SLACK_WEBHOOK_URL,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \ app_health_monitor ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ## Code overview ### Files * `state_change_check_plugin.py`: The main plugin code containing handlers for scheduled and data write triggers * `state_change_config_scheduler.toml`: Example TOML configuration for scheduled triggers * `state_change_config_data_writes.toml`: Example TOML configuration for data write triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'state_change_scheduler'" ``` ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled field change monitoring. Queries data within the specified window and counts field value changes. #### `process_writes(influxdb3_local, table_batches, args)` Handles real-time threshold monitoring on data writes. Evaluates incoming data against configured thresholds. ## Troubleshooting ### Common issues #### Issue: No notifications triggered **Solution**: Verify notification channel configuration (webhook URLs, credentials). Check threshold values are appropriate for your data. Ensure the Notifier Plugin is installed and configured. Review plugin logs for error messages. #### Issue: Too many notifications **Solution**: Adjust `state_change_window` and `state_change_count` for stability filtering. Increase threshold values to reduce sensitivity. Consider longer monitoring windows for scheduled triggers. #### Issue: Authentication errors **Solution**: Set `INFLUXDB3_AUTH_TOKEN` environment variable. Verify token has appropriate database permissions. Check Twilio credentials for SMS/WhatsApp notifications. ### Field threshold formats **Count-based thresholds** * Format: `field_name:"value":count` * Example: `temp:"30.5":10` (10 occurrences of temperature = 30.5) **Time-based thresholds** * Format: `field_name:"value":duration` * Example: `status:"error":5min` (status = error for 5 minutes) * Supported units: `s`, `min`, `h`, `d`, `w` **Multiple conditions** * Separate with `@`: `temp:"30":5@humidity:"high":10min` ### Message template variables **Scheduled notifications** * `$table`: Measurement name * `$field`: Field name * `$changes`: Number of changes detected * `$window`: Time window * `$tags`: Tag values **Data write notifications** * `$table`: Measurement name * `$field`: Field name * `$value`: Threshold value * `$duration`: Time duration or count * `$row`: Unique row identifier ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [State change plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/state_change) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[state-tracking](/influxdb3/core/tags/state-tracking/)[event-detection](/influxdb3/core/tags/event-detection/)[monitoring](/influxdb3/core/tags/monitoring/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Measurement to monitor for field changes | | field_change_count | string | required | Dot-separated field thresholds (for example, “temp:3.load:2”). Supports count-based conditions | | senders | string | required | Dot-separated notification channels with multi-channel alert support (Slack, Discord, etc.) | | window | string | required | Time window for analysis. Format: (for example, “10m”, “1h”) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Measurement to monitor for threshold conditions | | field_thresholds | string | required | Flexible threshold conditions with count-based and duration-based support (for example, “temp:30:10@status:ok:1h”) | | senders | string | required | Dot-separated notification channels with multi-channel alert support (Slack, Discord, HTTP, SMS, WhatsApp) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | influxdb3_auth_token | string | env var | InfluxDB 3 Core API token with environment variable support for credential management | | notification_text | string | template | Customizable message template for scheduled notifications with dynamic variables | | notification_count_text | string | template | Customizable message template for count-based notifications with dynamic variables | | notification_time_text | string | template | Customizable message template for time-based notifications with dynamic variables | | notification_path | string | “notify” | Notification endpoint path | | port_override | number | 8181 | InfluxDB port override | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | state_change_window | number | 1 | Recent values to check for stability (configurable state change detection to reduce noise) | | state_change_count | number | 1 | Max changes allowed within stability window (configurable state change detection) | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # Stateless ADTK detector plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/stateless-adtk-detector/ The ADTK Anomaly Detector Plugin provides advanced time series anomaly detection for InfluxDB 3 Core using the ADTK (Anomaly Detection Toolkit) library. Apply statistical and machine learning-based detection methods to identify outliers, level shifts, volatility changes, and seasonal anomalies in your data. Features consensus-based detection requiring multiple detectors to agree before triggering alerts, reducing false positives. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type |Default | Description | |-----------------|------|--------|--------------------------------------------------------------------------------------------------| | `measurement` |string|required| Measurement to analyze for anomalies | | `field` |string|required| Numeric field to evaluate | | `detectors` |string|required| Dot-separated list of advanced ADTK detectors for different anomaly types | |`detector_params`|string|required| Base64-encoded JSON parameters for each detector | | `window` |string|required|Data analysis window with flexible scheduling. Format: `` (for example, “1h”, “30m”)| | `senders` |string|required| Dot-separated notification channels with multi-channel notification support | ### Advanced parameters | Parameter | Type |Default| Description | |------------------------|------|-------|-------------------------------------------------------------------------------------------| | `min_consensus` |number| 1 |Minimum detectors required to agree for consensus-based filtering to reduce false positives| |`min_condition_duration`|string| “0s” | Minimum duration for configurable anomaly persistence before alerting | ### Notification parameters | Parameter | Type |Default | Description | |----------------------|------|--------|-----------------------------------------------------------------| |`influxdb3_auth_token`|string|env var | InfluxDB 3 Core API token | | `notification_text` |string|template|Customizable notification template message with dynamic variables| | `notification_path` |string|“notify”| Notification endpoint path | | `port_override` |number| 8181 | InfluxDB port override | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [adtk\_anomaly\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/stateless_adtk_detector/adtk_anomaly_config_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ### Supported ADTK detectors | Detector | Description | Required Parameters | |----------------------|-------------------------------------|------------------------| |`GeneralizedESDTestAD`| Extreme Studentized Deviate test | `alpha` (optional) | |`InterQuartileRangeAD`| Detects outliers using IQR method | None | | `ThresholdAD` |Detects values above/below thresholds|`high`, `low` (optional)| | `QuantileAD` | Detects outliers based on quantiles |`low`, `high` (optional)| | `LevelShiftAD` | Detects sudden level changes | `window` (int) | | `VolatilityShiftAD` | Detects volatility changes | `window` (int) | | `PersistAD` | Detects persistent anomalous values | None | | `SeasonalAD` | Detects seasonal pattern deviations | None | ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Python packages**: * `adtk` (for anomaly detection) * `pandas` (for data manipulation) * `requests` (for HTTP notifications) * **Notification Sender Plugin** *(optional)*: Required if using the `senders` parameter. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package requests influxdb3 install package adtk influxdb3 install package pandas ``` 3. *(Optional)* For notifications, install the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) and create an HTTP trigger for it. ## Trigger setup ### Scheduled trigger Create a scheduled trigger for anomaly detection: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/stateless_adtk_detector/adtk_anomaly_detection_plugin.py" \ --trigger-spec "every:10m" \ --trigger-arguments "measurement=cpu,field=usage,detectors=QuantileAD.LevelShiftAD,detector_params=eyJRdWFudGlsZUFKIjogeyJsb3ciOiAwLjA1LCAiaGlnaCI6IDAuOTV9LCAiTGV2ZWxTaGlmdEFKIjogeyJ3aW5kb3ciOiA1fX0=,window=10m,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \ anomaly_detector ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Enable trigger ```bash influxdb3 enable trigger --database mydb anomaly_detector ``` ## Example usage ### Example 1: Quantile-based detection Detect outliers using quantile-based detection. This plugin analyzes existing time series data and sends notifications when anomalies are detected. ```bash # Base64 encode detector parameters: {"QuantileAD": {"low": 0.05, "high": 0.95}} echo '{"QuantileAD": {"low": 0.05, "high": 0.95}}' | base64 influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/stateless_adtk_detector/adtk_anomaly_detection_plugin.py" \ --trigger-spec "every:5m" \ --trigger-arguments "measurement=temperature,field=value,detectors=QuantileAD,detector_params=eyJRdWFudGlsZUFKIjogeyJsb3ciOiAwLjA1LCAiaGlnaCI6IDAuOTV9fQ==,window=1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \ temp_anomaly_detector ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Example 2: Multi-detector consensus Use multiple detectors with consensus requirement: ```bash # Base64 encode: {"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 10}} echo '{"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 10}}' | base64 influxdb3 create trigger \ --database monitoring \ --path "gh:influxdata/stateless_adtk_detector/adtk_anomaly_detection_plugin.py" \ --trigger-spec "every:15m" \ --trigger-arguments "measurement=cpu_metrics,field=utilization,detectors=QuantileAD.LevelShiftAD,detector_params=eyJRdWFudGlsZUFEIjogeyJsb3ciOiAwLjEsICJoaWdoIjogMC45fSwgIkxldmVsU2hpZnRBRCI6IHsid2luZG93IjogMTB9fQ==,min_consensus=2,window=30m,senders=discord,discord_webhook_url=$DISCORD_WEBHOOK_URL" \ cpu_consensus_detector ``` Set `DISCORD_WEBHOOK_URL` to your Discord incoming webhook URL. ### Volatility shift detection Monitor for sudden changes in data volatility: ```bash # Base64 encode: {"VolatilityShiftAD": {"window": 20}} echo '{"VolatilityShiftAD": {"window": 20}}' | base64 influxdb3 create trigger \ --database trading \ --path "gh:influxdata/stateless_adtk_detector/adtk_anomaly_detection_plugin.py" \ --trigger-spec "every:1m" \ --trigger-arguments "measurement=stock_prices,field=price,detectors=VolatilityShiftAD,detector_params=eyJWb2xhdGlsaXR5U2hpZnRBRCI6IHsid2luZG93IjogMjB9fQ==,window=1h,min_condition_duration=5m,senders=sms,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \ volatility_detector ``` ## Code overview ### Files * `adtk_anomaly_detection_plugin.py`: The main plugin code containing the scheduled handler for anomaly detection * `adtk_anomaly_config_scheduler.toml`: Example TOML configuration file ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'anomaly_detector'" ``` ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled anomaly detection tasks. Queries data within the specified window, applies ADTK detectors, and sends notifications for detected anomalies. Key operations: 1. Parses configuration and decodes detector parameters 2. Queries data from source measurement 3. Applies configured ADTK detectors 4. Evaluates consensus across detectors 5. Sends notifications when anomalies are confirmed ## Troubleshooting ### Common issues #### Issue: Detector parameter encoding errors **Solution**: Ensure detector\_params is valid Base64-encoded JSON. Use command line Base64 encoding: `echo '{"QuantileAD": {"low": 0.05}}' | base64`. Verify JSON structure matches detector requirements. #### Issue: False positive notifications **Solution**: Increase `min_consensus` to require more detectors to agree. Add `min_condition_duration` to require anomalies to persist. Adjust detector-specific thresholds in `detector_params`. #### Issue: Missing dependencies **Solution**: Install required packages: `adtk`, `pandas`, `requests`. Ensure the Notifier Plugin is installed for notifications. #### Issue: Data quality issues **Solution**: Verify sufficient data points in the specified window. Check for null values or data gaps that affect detection. Ensure field contains numeric data suitable for analysis. ### Base64 parameter encoding Generate properly encoded detector parameters: ```bash # Single detector echo '{"QuantileAD": {"low": 0.05, "high": 0.95}}' | base64 -w 0 # Multiple detectors echo '{"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 15}}' | base64 -w 0 # Threshold detector echo '{"ThresholdAD": {"high": 100, "low": 10}}' | base64 -w 0 ``` ### Message template variables Available variables for notification templates: * `$table`: Measurement name * `$field`: Field name with anomaly * `$value`: Anomalous value * `$detectors`: List of detecting methods * `$tags`: Tag values * `$timestamp`: Anomaly timestamp ### Detector configuration reference For detailed detector parameters and options, see the [ADTK documentation](https://adtk.readthedocs.io/en/stable/api/detectors.html). ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Stateless ADTK detector plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/stateless_adtk_detector) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[anomaly-detection](/influxdb3/core/tags/anomaly-detection/)[adtk](/influxdb3/core/tags/adtk/)[stateless](/influxdb3/core/tags/stateless/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Measurement to analyze for anomalies | | field | string | required | Numeric field to evaluate | | detectors | string | required | Dot-separated list of advanced ADTK detectors for different anomaly types | | detector_params | string | required | Base64-encoded JSON parameters for each detector | | window | string | required | Data analysis window with flexible scheduling. Format: (for example, “1h”, “30m”) | | senders | string | required | Dot-separated notification channels with multi-channel notification support | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | min_consensus | number | 1 | Minimum detectors required to agree for consensus-based filtering to reduce false positives | | min_condition_duration | string | “0s” | Minimum duration for configurable anomaly persistence before alerting | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | influxdb3_auth_token | string | env var | InfluxDB 3 Core API token | | notification_text | string | template | Customizable notification template message with dynamic variables | | notification_path | string | “notify” | Notification endpoint path | | port_override | number | 8181 | InfluxDB port override | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | | Detector | Description | Required Parameters | | --- | --- | --- | | Detector | Description | Required Parameters | | GeneralizedESDTestAD | Extreme Studentized Deviate test | alpha (optional) | | InterQuartileRangeAD | Detects outliers using IQR method | None | | ThresholdAD | Detects values above/below thresholds | high , low (optional) | | QuantileAD | Detects outliers based on quantiles | low , high (optional) | | LevelShiftAD | Detects sudden level changes | window (int) | | VolatilityShiftAD | Detects volatility changes | window (int) | | PersistAD | Detects persistent anomalous values | None | | SeasonalAD | Detects seasonal pattern deviations | None | --- # System metrics plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/system-metrics/ The System Metrics Plugin provides comprehensive system monitoring capabilities for InfluxDB 3 Core, collecting CPU, memory, disk, and network metrics from the host system. Monitor detailed performance insights including per-core CPU statistics, memory usage breakdowns, disk I/O performance, and network interface statistics. Features configurable metric collection with robust error handling and retry logic for reliable monitoring. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin’s `config_file_path` parameter. If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Optional parameters | Parameter | Type | Default | Description | |-----------------|-------|-----------|------------------------------------------------------------------------------| | `hostname` |string |`localhost`| Hostname to tag all metrics with for system identification | | `include_cpu` |boolean| `true` |Include comprehensive CPU metrics collection (overall and per-core statistics)| |`include_memory` |boolean| `true` | Include memory metrics collection (RAM usage, swap statistics, page faults) | | `include_disk` |boolean| `true` |Include disk metrics collection (partition usage, I/O statistics, performance)| |`include_network`|boolean| `true` | Include network metrics collection (interface statistics and error counts) | | `max_retries` |integer| `3` | Maximum retry attempts on failure with graceful error handling | *Note: This plugin has no required parameters. All parameters have sensible defaults.* ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. #### Example TOML configuration [system\_metrics\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/system_metrics/system_metrics_config_scheduler.toml) For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ## Software Requirements * **InfluxDB 3 Core**: with the Processing Engine enabled. * **Python packages**: * `psutil` (for system metrics collection) ### Installation steps 1. Start InfluxDB 3 Core with the Processing Engine enabled (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. Install required Python packages: ``` influxdb3 install package psutil ``` ## Trigger setup ### Basic Scheduled Trigger ```bash influxdb3 create trigger \ --database system_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:30s" \ system_metrics_trigger ``` ### Using Configuration File ```bash influxdb3 create trigger \ --database system_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:1m" \ --trigger-arguments config_file_path=system_metrics_config_scheduler.toml \ system_metrics_config_trigger ``` ### Custom Configuration ```bash influxdb3 create trigger \ --database system_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:30s" \ --trigger-arguments hostname=web-server-01,include_disk=false,max_retries=5 \ system_metrics_custom_trigger ``` ## Example usage ### Monitor Web Server Performance ```bash # Create trigger for web server monitoring every 15 seconds influxdb3 create trigger \ --database web_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:15s" \ --trigger-arguments hostname=web-server-01,include_network=true \ web_server_metrics ``` ### Database Server Monitoring ```bash # Focus on CPU and disk metrics for database server influxdb3 create trigger \ --database db_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:30s" \ --trigger-arguments hostname=db-primary,include_disk=true,include_cpu=true,include_network=false \ database_metrics ``` ### High-Frequency System Monitoring ```bash # Collect all metrics every 10 seconds with higher retry tolerance influxdb3 create trigger \ --database system_monitoring \ --path "gh:influxdata/system_metrics/system_metrics.py" \ --trigger-spec "every:10s" \ --trigger-arguments hostname=critical-server,max_retries=10 \ high_freq_metrics ``` ### Query collected metrics This plugin collects system metrics automatically. After the trigger runs, query to view the collected data: ```bash influxdb3 query \ --database system_monitoring \ "SELECT * FROM system_cpu WHERE time >= now() - interval '5 minutes' LIMIT 5" ``` **Expected output** \+——+——–+——-+——–+——+——–+——-+——–+——-+——-+————+——————+ | host | cpu | user | system | idle | iowait | nice | irq | load1 | load5 | load15 | time | +——+——–+——-+——–+——+——–+——-+——–+——-+——-+————+——————+ | srv1 | total | 12.5 | 5.3 | 81.2 | 0.8 | 0.0 | 0.2 | 0.85 | 0.92 | 0.88 | 2024-01-15 10:00 | | srv1 | total | 13.1 | 5.5 | 80.4 | 0.7 | 0.0 | 0.3 | 0.87 | 0.93 | 0.88 | 2024-01-15 10:01 | | srv1 | total | 11.8 | 5.1 | 82.0 | 0.9 | 0.0 | 0.2 | 0.83 | 0.91 | 0.88 | 2024-01-15 10:02 | | srv1 | total | 14.2 | 5.8 | 79.0 | 0.8 | 0.0 | 0.2 | 0.89 | 0.92 | 0.88 | 2024-01-15 10:03 | | srv1 | total | 12.9 | 5.4 | 80.6 | 0.9 | 0.0 | 0.2 | 0.86 | 0.92 | 0.88 | 2024-01-15 10:04 | +——+——–+——-+——–+——+——–+——-+——–+——-+——-+————+——————+ ## Code overview ### Main Functions #### `process_scheduled_call()` The main entry point for scheduled triggers. Collects system metrics based on configuration and writes them to InfluxDB. ``` def process_scheduled_call(influxdb3_local, call_time, args): # Parse configuration config = parse_config(args) # Collect metrics based on configuration if config['include_cpu']: collect_cpu_metrics(influxdb3_local, config['hostname']) if config['include_memory']: collect_memory_metrics(influxdb3_local, config['hostname']) # ... additional metric collections ``` ### Measurements and Fields #### system\_cpu Overall CPU statistics and metrics: * **Tags**: `host`, `cpu=total` * **Fields**: `user`, `system`, `idle`, `iowait`, `nice`, `irq`, `softirq`, `steal`, `guest`, `guest_nice`, `frequency_current`, `frequency_min`, `frequency_max`, `ctx_switches`, `interrupts`, `soft_interrupts`, `syscalls`, `load1`, `load5`, `load15` #### system\_cpu\_cores Per-core CPU statistics: * **Tags**: `host`, `core` (core number) * **Fields**: `usage`, `user`, `system`, `idle`, `iowait`, `nice`, `irq`, `softirq`, `steal`, `guest`, `guest_nice`, `frequency_current`, `frequency_min`, `frequency_max` #### system\_memory System memory statistics: * **Tags**: `host` * **Fields**: `total`, `available`, `used`, `free`, `active`, `inactive`, `buffers`, `cached`, `shared`, `slab`, `percent` #### system\_swap Swap memory statistics: * **Tags**: `host` * **Fields**: `total`, `used`, `free`, `percent`, `sin`, `sout` #### system\_memory\_faults Memory page fault information (when available): * **Tags**: `host` * **Fields**: `page_faults`, `major_faults`, `minor_faults`, `rss`, `vms`, `dirty`, `uss`, `pss` #### system\_disk\_usage Disk partition usage: * **Tags**: `host`, `device`, `mountpoint`, `fstype` * **Fields**: `total`, `used`, `free`, `percent` #### system\_disk\_io Disk I/O statistics: * **Tags**: `host`, `device` * **Fields**: `reads`, `writes`, `read_bytes`, `write_bytes`, `read_time`, `write_time`, `busy_time`, `read_merged_count`, `write_merged_count` #### system\_disk\_performance Calculated disk performance metrics: * **Tags**: `host`, `device` * **Fields**: `read_bytes_per_sec`, `write_bytes_per_sec`, `read_iops`, `write_iops`, `avg_read_latency_ms`, `avg_write_latency_ms`, `util_percent` #### system\_network Network interface statistics: * **Tags**: `host`, `interface` * **Fields**: `bytes_sent`, `bytes_recv`, `packets_sent`, `packets_recv`, `errin`, `errout`, `dropin`, `dropout` ## Troubleshooting ### Common issues #### Issue: Permission errors for disk I/O metrics **Solution**: The plugin will continue collecting other metrics even if some require elevated permissions. Run InfluxDB with appropriate permissions if disk I/O metrics are required. #### Issue: Missing psutil library **Solution**: Install the psutil package: ```bash influxdb3 install package psutil ``` #### Issue: High CPU usage from plugin **Solution**: Increase the trigger interval (for example, from `every:10s` to `every:30s`). Disable unnecessary metric types. Reduce the number of disk partitions monitored. ### Viewing Logs Logs are stored in the trigger’s database in the `system.processing_engine_logs` table: ```bash influxdb3 query \ --database YOUR_DATABASE \ "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'system_metrics_trigger' ORDER BY event_time DESC LIMIT 10" ``` ### Verifying Data Collection Check that metrics are being collected: ```bash # List all system metric measurements influxdb3 query \ --database system_monitoring \ "SHOW MEASUREMENTS WHERE measurement =~ /^system_/" # Check recent CPU metrics influxdb3 query \ --database system_monitoring \ "SELECT COUNT(*) FROM system_cpu WHERE time >= now() - interval '1 hour'" ``` ## Logging Logs are stored in the `_internal` database (or the database where the trigger is created) in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'" ``` Log columns: * **event\_time**: Timestamp of the log event * **trigger\_name**: Name of the trigger that generated the log * **log\_level**: Severity level (INFO, WARN, ERROR) * **log\_text**: Message describing the action or error ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [System metrics plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/system_metrics) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[monitoring](/influxdb3/core/tags/monitoring/)[system-metrics](/influxdb3/core/tags/system-metrics/)[performance](/influxdb3/core/tags/performance/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | hostname | string | localhost | Hostname to tag all metrics with for system identification | | include_cpu | boolean | true | Include comprehensive CPU metrics collection (overall and per-core statistics) | | include_memory | boolean | true | Include memory metrics collection (RAM usage, swap statistics, page faults) | | include_disk | boolean | true | Include disk metrics collection (partition usage, I/O statistics, performance) | | include_network | boolean | true | Include network metrics collection (interface statistics and error counts) | | max_retries | integer | 3 | Maximum retry attempts on failure with graceful error handling | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # Threshold deadman checks plugin Source: https://docs.influxdata.com/influxdb3/core/plugins/library/official/threshold-deadman-checks/ The Threshold Deadman Checks Plugin provides comprehensive monitoring capabilities for time series data in InfluxDB 3 Core, combining real-time threshold detection with deadman monitoring. Monitor field values against configurable thresholds, detect data absence patterns, and trigger multi-level alerts based on aggregated metrics. Features both scheduled batch monitoring and real-time data write monitoring with configurable trigger counts and severity levels. ## Configuration Plugin parameters may be specified as key-value pairs in the `--trigger-arguments` flag (CLI) or in the `trigger_arguments` field (API) when creating a trigger. ### Plugin metadata This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the [InfluxDB 3 Explorer](https://docs.influxdata.com/influxdb3/explorer/) UI to display and configure the plugin. ### Required parameters | Parameter | Type |Default | Description | |-------------|------|--------|-------------------------------------------------------------------------------| |`measurement`|string|required| Measurement to monitor for deadman alerts and aggregation-based conditions | | `senders` |string|required|Dot-separated notification channels with multi-channel notification integration| | `window` |string|required| Time window for periodic data presence checking | ### Data write trigger parameters | Parameter | Type |Default | Description | |------------------|------|--------|------------------------------------------------------------------------------------------------------| | `measurement` |string|required| Measurement to monitor for real-time threshold violations in dual monitoring mode | |`field_conditions`|string|required|Real-time threshold conditions with multi-level alerting (INFO, WARN, ERROR, CRITICAL severity levels)| | `senders` |string|required| Dot-separated notification channels with multi-channel notification integration | ### Threshold check parameters | Parameter | Type |Default| Description | |--------------------------|-------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`field_aggregation_values`|string | none |Multi-level aggregation conditions with aggregation support for avg, min, max, count, sum, median, stddev, first\_value, last\_value, var, and approx\_median values| | `deadman_check` |boolean| false | Enable deadman detection to monitor for data absence and missing data streams | | `interval` |string |“5min” | Configurable aggregation time interval for batch processing with performance optimization | | `trigger_count` |number | 1 | Configurable triggers requiring multiple consecutive failures before alerting | ### Notification parameters | Parameter | Type |Default | Description | |-----------------------------|------|--------|-----------------------------------------------------------------------------------------| | `influxdb3_auth_token` |string|env var | InfluxDB 3 Core API token with environment variable support | | `notification_deadman_text` |string|template| Customizable deadman alert template message with dynamic variables | |`notification_threshold_text`|string|template| Customizable threshold alert template message with dynamic variables | | `notification_text` |string|template|Customizable notification template message for data write triggers with dynamic variables| | `notification_path` |string|“notify”| Notification endpoint path with retry logic and exponential backoff | | `port_override` |number| 8181 | InfluxDB port override for notification delivery | ### TOML configuration | Parameter | Type |Default| Description | |------------------|------|-------|--------------------------------------------------------------------------------| |`config_file_path`|string| none |TOML config file path relative to `PLUGIN_DIR` (required for TOML configuration)| *To use a TOML configuration file, set the `PLUGIN_DIR` environment variable and specify the `config_file_path` in the trigger arguments.* This is in addition to the `--plugin-dir` flag when starting InfluxDB 3 Core. Example TOML configuration files provided: * [threshold\_deadman\_config\_scheduler.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/threshold_deadman_checks/threshold_deadman_config_scheduler.toml) - for scheduled triggers * [threshold\_deadman\_config\_data\_writes.toml](https://github.com/influxdata/influxdb3_plugins/blob/master/influxdata/threshold_deadman_checks/threshold_deadman_config_data_writes.toml) - for data write triggers For more information on using TOML configuration files, see the Using TOML Configuration Files section in the [influxdb3\_plugins/README.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README.md). ### Channel-specific configuration Notification channels require additional parameters based on the sender type (same as the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/)). ## Schema requirement The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing. ## Software requirements * **InfluxDB v3 Core/Enterprise**: with the Processing Engine enabled. * **Notification Sender Plugin for InfluxDB 3 Core**: This plugin is required for sending notifications. See the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/). ## Installation steps 1. **Start InfluxDB 3 Core with the Processing Engine enabled** (`--plugin-dir /path/to/plugins`): ``` influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins ``` 2. **Install required Python packages**: ``` influxdb3 install package requests ``` 3. **Optional**: For notifications, install and configure the [influxdata/notifier plugin](/influxdb3/core/plugins/library/official/notifier/) ## Trigger setup ### Scheduled trigger Create a trigger for periodic threshold and deadman checks: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "every:10m" \ --trigger-arguments "measurement=cpu,senders=slack,field_aggregation_values=temp:avg@>=30-ERROR,window=10m,trigger_count=3,deadman_check=true,slack_webhook_url=$SLACK_WEBHOOK_URL" \ threshold_scheduler ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Data write trigger Create a trigger for real-time threshold monitoring: ```bash influxdb3 create trigger \ --database mydb \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments "measurement=cpu,field_conditions=temp>30-WARN:status==ok-INFO,senders=slack,trigger_count=2,slack_webhook_url=$SLACK_WEBHOOK_URL" \ threshold_datawrite ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. ### Enable triggers ```bash influxdb3 enable trigger --database mydb threshold_scheduler influxdb3 enable trigger --database mydb threshold_datawrite ``` ## Example usage ### Example 1: Basic threshold monitoring Write test data and monitor for threshold violations: ```bash # Write test data influxdb3 write \ --database sensors \ "heartbeat,host=server1 status=1" influxdb3 write \ --database sensors \ "heartbeat,host=server1 status=0" # Create and enable the trigger influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "every:5m" \ --trigger-arguments "measurement=heartbeat,senders=slack,window=5m,deadman_check=true,slack_webhook_url=$SLACK_WEBHOOK_URL" \ heartbeat_monitor influxdb3 enable trigger --database sensors heartbeat_monitor # Query to verify data influxdb3 query \ --database sensors \ "SELECT * FROM heartbeat ORDER BY time DESC LIMIT 5" ``` Set `SLACK_WEBHOOK_URL` to your Slack incoming webhook URL. **Expected output** When no data is received within the window, a deadman alert is sent: “CRITICAL: No heartbeat data from heartbeat between 2025-06-01T10:00:00Z and 2025-06-01T10:05:00Z” ### Example 2: Deadman monitoring Monitor for data absence and alert when no data is received: ```bash influxdb3 create trigger \ --database sensors \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "every:15m" \ --trigger-arguments "measurement=heartbeat,senders=sms,window=10m,deadman_check=true,trigger_count=2,twilio_from_number=+1234567890,twilio_to_number=+0987654321,notification_deadman_text=CRITICAL: No heartbeat data from \$table between \$time_from and \$time_to" \ heartbeat_monitor ``` ### Multi-level threshold monitoring Monitor aggregated values with different severity levels: ```bash influxdb3 create trigger \ --database monitoring \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "every:5m" \ --trigger-arguments "measurement=system_metrics,senders=slack.discord,field_aggregation_values='cpu_usage:avg@>=80-WARN cpu_usage:avg@>=95-ERROR memory_usage:max@>=90-WARN',window=5m,interval=1min,trigger_count=3,slack_webhook_url=$SLACK_WEBHOOK_URL,discord_webhook_url=$DISCORD_WEBHOOK_URL" \ system_threshold_monitor ``` Set `SLACK_WEBHOOK_URL` and `DISCORD_WEBHOOK_URL` to your webhook URLs. ### Real-time field condition monitoring Monitor data writes for immediate threshold violations: ```bash influxdb3 create trigger \ --database applications \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "all_tables" \ --trigger-arguments "measurement=response_times,field_conditions=latency>500-WARN:latency>1000-ERROR:error_rate>0.05-CRITICAL,senders=http,trigger_count=1,http_webhook_url=$HTTP_WEBHOOK_URL,notification_text=[\$level] Application alert: \$field \$op_sym \$compare_val (actual: \$actual)" \ app_performance_monitor ``` Set `HTTP_WEBHOOK_URL` to your HTTP webhook endpoint. ### Combined monitoring Monitor both aggregation thresholds and deadman conditions: ```bash influxdb3 create trigger \ --database comprehensive \ --path "gh:influxdata/threshold_deadman_checks/threshold_deadman_checks_plugin.py" \ --trigger-spec "every:10m" \ --trigger-arguments "measurement=temperature_sensors,senders=whatsapp,field_aggregation_values='temperature:avg@>=35-WARN temperature:max@>=40-ERROR',window=15m,deadman_check=true,trigger_count=2,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \ comprehensive_sensor_monitor ``` ## Code overview ### Files * `threshold_deadman_checks_plugin.py`: The main plugin code containing handlers for scheduled and data write triggers * `threshold_deadman_config_scheduler.toml`: Example TOML configuration for scheduled triggers * `threshold_deadman_config_data_writes.toml`: Example TOML configuration for data write triggers ### Logging Logs are stored in the trigger’s database in the `system.processing_engine_logs` table. To view logs: ```bash influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'threshold_scheduler'" ``` ### Main functions #### `process_scheduled_call(influxdb3_local, call_time, args)` Handles scheduled threshold and deadman checks. Queries data within the specified window, evaluates aggregation-based conditions, and checks for data absence. #### `process_writes(influxdb3_local, table_batches, args)` Handles real-time threshold monitoring on data writes. Evaluates incoming data against configured field conditions with multi-level severity. ## Troubleshooting ### Common issues #### Issue: No alerts triggered **Solution**: Verify threshold values are appropriate for your data ranges. Check that notification channels are properly configured. Ensure the Notifier Plugin is installed and accessible. Review plugin logs for configuration errors. #### Issue: False positive alerts **Solution**: Increase `trigger_count` to require more consecutive failures. Adjust threshold values to be less sensitive. Consider longer aggregation intervals for noisy data. #### Issue: Missing deadman alerts **Solution**: Verify `deadman_check=true` is set in configuration. Check that the measurement name matches existing data. Ensure the time window is appropriate for your data frequency. #### Issue: Authentication issues **Solution**: Set `INFLUXDB3_AUTH_TOKEN` environment variable. Verify API token has required database permissions. Check Twilio credentials for SMS/WhatsApp notifications. ### Configuration formats **Aggregation conditions (scheduled)** * Format: `field:aggregation@operator value-level` * Example: `temp:avg@>=30-ERROR` * Multiple conditions: `"temp:avg@>=30-WARN humidity:min@<40-INFO"` **Field conditions (data write)** * Format: `field operator value-level` * Example: `temp>30-WARN:status==ok-INFO` * Supported operators: `>`, `<`, `>=`, `<=`, `==`, `!=` **Supported aggregations** * `avg`: Average value * `min`: Minimum value * `max`: Maximum value * `count`: Count of records * `sum`: Sum of values * `median`: Median value * `stddev`: Standard deviation * `first_value`: First value in time interval * `last_value`: Last value in time interval * `var`: Variance of values * `approx_median`: Approximate median (faster than exact median) ### Message template variables **Deadman notifications** * `$table`: Measurement name * `$time_from`: Start of checked period * `$time_to`: End of checked period **Threshold notifications (scheduled)** * `$level`: Alert severity level * `$table`: Measurement name * `$field`: Field name * `$aggregation`: Aggregation type * `$op_sym`: Operator symbol * `$compare_val`: Threshold value * `$actual`: Actual measured value * `$row`: Unique identifier **Threshold notifications (data write)** * `$level`: Alert severity level * `$field`: Field name * `$op_sym`: Operator symbol * `$compare_val`: Threshold value * `$actual`: Actual field value ### Row identification The `row` variable uniquely identifies alert contexts using format: `measurement:level:tag1=value1:tag2=value2` This ensures trigger counts are maintained independently for each unique combination of measurement, severity level, and tag values. ## Report an issue For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues). ## Find support for InfluxDB 3 Core The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. #### Related * [Threshold deadman checks plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/influxdata/threshold_deadman_checks) [plugins](/influxdb3/core/tags/plugins/)[processing engine](/influxdb3/core/tags/processing-engine/)[python](/influxdb3/core/tags/python/)[monitoring](/influxdb3/core/tags/monitoring/)[thresholds](/influxdb3/core/tags/thresholds/)[deadman](/influxdb3/core/tags/deadman/)[alerting](/influxdb3/core/tags/alerting/) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Measurement to monitor for deadman alerts and aggregation-based conditions | | senders | string | required | Dot-separated notification channels with multi-channel notification integration | | window | string | required | Time window for periodic data presence checking | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | measurement | string | required | Measurement to monitor for real-time threshold violations in dual monitoring mode | | field_conditions | string | required | Real-time threshold conditions with multi-level alerting (INFO, WARN, ERROR, CRITICAL severity levels) | | senders | string | required | Dot-separated notification channels with multi-channel notification integration | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | field_aggregation_values | string | none | Multi-level aggregation conditions with aggregation support for avg, min, max, count, sum, median, stddev, first_value, last_value, var, and approx_median values | | deadman_check | boolean | false | Enable deadman detection to monitor for data absence and missing data streams | | interval | string | “5min” | Configurable aggregation time interval for batch processing with performance optimization | | trigger_count | number | 1 | Configurable triggers requiring multiple consecutive failures before alerting | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | influxdb3_auth_token | string | env var | InfluxDB 3 Core API token with environment variable support | | notification_deadman_text | string | template | Customizable deadman alert template message with dynamic variables | | notification_threshold_text | string | template | Customizable threshold alert template message with dynamic variables | | notification_text | string | template | Customizable notification template message for data write triggers with dynamic variables | | notification_path | string | “notify” | Notification endpoint path with retry logic and exponential backoff | | port_override | number | 8181 | InfluxDB port override for notification delivery | | Parameter | Type | Default | Description | | --- | --- | --- | --- | | Parameter | Type | Default | Description | | config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) | --- # Processing engine Python API reference Source: https://docs.influxdata.com/influxdb3/core/plugins/python-api-reference/ The InfluxDB 3 processing engine provides a Python API that plugins use at runtime. Nothing in this API is importable from a plugin—the runtime injects the objects instead. InfluxDB passes `influxdb3_local` (an `InfluxDB3Local` instance) as the first argument to every trigger entry point and installs `LineBuilder` into Python builtins before the plugin runs, so both single-file and multi-file plugins can use them without an import. * [Trigger entry points](#trigger-entry-points) * [Log messages](#log-messages) * [Query data](#query-data) * [Write data](#write-data) * [Cache data](#cache-data) * [Plugin cancellation](#plugin-cancellation) * [LineBuilder](#linebuilder) * [TableBatch](#tablebatch) * [Exceptions](#exceptions) For usage patterns and examples, see [Extend plugins](/influxdb3/core/extend-plugin/). ## Trigger entry points A plugin defines one entry point that matches the trigger type it is attached to. You define the function; InfluxDB calls it when the trigger fires. Multi-file plugins must define the entry point in the plugin directory’s `__init__.py`. | Trigger type | Trigger specification | Entry point function | |----------------|-------------------------------------|-----------------------------------------------------| |Data write (WAL)| `table:TABLE_NAME` or `all_tables` | [`process_writes()`](#process_writes) | | Scheduled |`every:DURATION` or `cron:EXPRESSION`|[`process_scheduled_call()`](#process_scheduled_call)| | HTTP request | `request:REQUEST_PATH` | [`process_request()`](#process_request) | ### `process_writes()` ```python def process_writes( influxdb3_local, table_batches: Sequence[TableBatch], args: Mapping[str, str] | None = None, ) -> None ``` Entry point for data write (WAL) triggers. InfluxDB calls the function with the rows that were just written to the database, grouped by table. * `table_batches`: the written rows as a sequence of [`TableBatch`](#tablebatch) dictionaries. * `args`: trigger arguments as a string-to-string mapping. ### `process_scheduled_call()` ```python def process_scheduled_call( influxdb3_local, schedule_time: datetime, args: Mapping[str, str] | None = None, ) -> None ``` Entry point for scheduled triggers. * `schedule_time`: the trigger’s fire time as a naive `datetime`. The engine builds the value with `datetime.fromtimestamp()`, so it is expressed in the server’s local timezone and truncated to whole seconds. * `args`: trigger arguments as a string-to-string mapping. ### `process_request()` ```python def process_request( influxdb3_local, query_params: Mapping[str, str], request_headers: Mapping[str, str], request_body: bytes, args: Mapping[str, str] | None = None, ) ``` Entry point for HTTP request triggers. * `query_params`: URL query parameters as a string-to-string mapping. * `request_headers`: request headers as a string-to-string mapping. Header names are lowercased, and the client’s `Authorization` header is stripped before the plugin sees it. * `request_body`: the raw request bytes. * `args`: trigger arguments as a string-to-string mapping. #### Return value `process_request` returns an HTTP-style response in one of the following forms: * **A Flask-style response object**—duck-typed, not an actual `flask.Response`. The object must define a `__flask_response__()` method that returns `True`, a `status_code` attribute, a `headers` mapping, and a `get_data()` method that returns `str`. A genuine `flask.Response` is rejected: it does not define `__flask_response__`, and its `get_data()` returns bytes. * **A tuple** of `(body, status, headers)` following Flask conventions.`status` and `headers` are optional; `headers` may be the second element only when `status` is omitted. * **A bare string, dictionary, list, or iterator**, rendered with defaults: dictionaries and lists are JSON-encoded with `Content-Type: application/json`; strings and other iterables are concatenated with a `text/html` default content type. The status code defaults to `200` when not provided. Any other return value—`None`, or an object that is not a string, dictionary, list, or iterable—fails the request with status `500` and the error `Unsupported return type from Python function`. Returning `bytes` is accepted as an iterable but yields an empty body, because its items are integers; encode to `str` instead. ## Log messages ```python influxdb3_local.info(*args: object) -> None influxdb3_local.warn(*args: object) -> None influxdb3_local.error(*args: object) -> None ``` Each method converts its arguments to strings, joins them with spaces, and logs the result at the named level (`INFO`, `WARN`, or `ERROR`). All three levels are stored in the `system.processing_engine_logs` table, where you can [query them using SQL](/influxdb3/core/admin/query-system-data/#query-trigger-logs), and appear in `influxdb3 test` output. ## Query data ```python influxdb3_local.query( query: str, args: Mapping[str, str] | None = None, database: str | None = None, ) -> list[dict[str, Any]] ``` Executes a SQL query and returns a list of row dictionaries. `args` supplies values for named SQL parameters, referenced in the query with a leading `$`: ```python influxdb3_local.query( "SELECT host, usage FROM cpu WHERE host = $host", {"host": "host1"}, ) ``` Parameter values must be strings; passing an `int` or `float` raises `TypeError`. `database` selects which database to query and defaults to the database the trigger is attached to. Each row dictionary contains every column in the result schema: * Column values are native Python `int`, `float`, `bool`, or `str` values. * Timestamp columns are nanosecond timestamps represented as integers. * Dictionary-encoded columns (tags) are materialized as their string labels. * SQL `NULL` values are returned as `None`. Columns of any other Arrow type raise `ValueError`. Supported types are `Int64`, `UInt64`, `Float64`, `Boolean`, `Utf8`, `LargeUtf8`, `Timestamp` (nanosecond), and `Dictionary` of `Utf8`. Raises [`QueryError`](#exceptions) on execution failures, invalid SQL, or an invalid database name. ## Write data All write methods take a [`LineBuilder`](#linebuilder) line and raise an exception when the target database is `_internal`. `write` and `write_to_db` queue writes; queued writes are flushed once the plugin returns, so they land after any `write_sync` or `write_sync_to_db` calls the plugin made.`write_sync` and `write_sync_to_db` write synchronously through the write buffer while the plugin is still running. ### `write` ```python influxdb3_local.write(line: LineBuilder) -> None ``` Queues a line protocol write to the current database. ### `write_to_db` ```python influxdb3_local.write_to_db(db_name: str, line: LineBuilder) -> None ``` Queues a line protocol write to the named database. ### `write_sync` ```python influxdb3_local.write_sync(line: LineBuilder, no_sync: bool) -> None ``` Writes line protocol to the current database synchronously.`no_sync` is required; pass `no_sync=True` to skip waiting for WAL synchronization. Use [`write_sync_to_db`](#write_sync_to_db) to target a different database. ### `write_sync_to_db` ```python influxdb3_local.write_sync_to_db( db_name: str, line: LineBuilder, no_sync: bool, ) -> None ``` Writes line protocol to the named database synchronously.`no_sync` is required; pass `no_sync=True` to skip waiting for WAL synchronization. Use [`write_sync`](#write_sync) to write to the trigger’s database. ## Cache data ```python influxdb3_local.cache: Cache ``` The `influxdb3_local.cache` property provides an in-memory cache that persists values between plugin executions. The trigger-local cache (the default) is scoped to the database and trigger pair; the global cache is shared by every trigger in the process. Set `use_global=True` in cache calls to use the global cache. The server clears both caches on restart. Reading the `cache` property runs an expiry sweep, though the sweep only does work once per cleanup interval. Individual expired entries are dropped on read regardless. ### `cache.put()` ```python influxdb3_local.cache.put( key: str, value: Any, ttl: float | None = None, use_global: bool | None = None, ) -> None ``` Stores a Python object in the trigger-local cache or the global shared cache. `ttl` controls expiry in seconds. Values in test caches (`influxdb3 test`) default to a 30-minute TTL when not provided; production caches persist values indefinitely unless a `ttl` is set. Raises `ValueError` when `ttl` is negative, `NaN`, or too large to represent as a duration. ### `cache.get()` ```python influxdb3_local.cache.get( key: str, default: Any | None = None, use_global: bool | None = None, ) -> Any | None ``` Fetches a value from the trigger-local or global cache. Expired entries are evicted on read. Returns the stored value, the provided default, or `None` when the key is absent. ### `cache.delete()` ```python influxdb3_local.cache.delete( key: str, use_global: bool | None = None, ) -> bool ``` Removes a cached value. Returns `True` when the key existed in the selected cache. ## Plugin cancellation Once the current plugin run has been cancelled—the server is shutting down, or the trigger was disabled or deleted—the logging, write, and query methods raise `KeyboardInterrupt`. `KeyboardInterrupt` subclasses `BaseException` rather than `Exception`, so a plugin’s `except Exception` handler does not swallow it, and a long-running loop unwinds instead of hanging the shutdown or the disable. The message reads `influxdb3 is shutting down; aborting plugin execution` for every cancellation cause, including a plain trigger disable. The `cache` property and the cache methods do not check for cancellation and keep working. ## LineBuilder `LineBuilder` constructs InfluxDB line protocol in plugins. It handles line protocol escaping and nanosecond timestamps, and plugins can use it without an import. Construct a builder with `LineBuilder(measurement)`, then call the tag, field, and timestamp methods on the resulting instance. In this section, `line` is a `LineBuilder` instance. Tag and field methods return the same `LineBuilder` instance, so you can chain calls: ```python line = LineBuilder("weather") line.tag("location", "us-midwest").float64_field("temperature", 82.5) influxdb3_local.write(line) ``` Raises `InvalidMeasurementError` when the measurement name contains spaces. Tag and field keys that are empty or contain spaces, commas, or equals signs raise `InvalidKeyError`. | Method | Adds | |---------------------------|----------------------------------------------------------------| | `tag(key, value)` | A tag; the value is stringified | | `int64_field(key, value)` | A signed integer field | |`uint64_field(key, value)` | An unsigned integer field; negative values raise `ValueError` | |`float64_field(key, value)`|A float field; integral values are rendered with a trailing `.0`| |`string_field(key, value)` | A string field with quotes and backslashes escaped | | `bool_field(key, value)` | A boolean field, rendered as `t` or `f` | | `time_ns(timestamp_ns)` | The nanosecond timestamp for the line | | `build()` | Renders the line as line protocol | ### `line.build()` ```python line.build() -> str ``` When you call `build()` on a `LineBuilder` instance, it renders the accumulated measurement, tags, fields, and optional timestamp as a line protocol string.`build()` raises `InvalidLineError` when called without any fields. For format details, see the [line protocol reference](/influxdb3/core/reference/line-protocol/). ## TableBatch A batch of WAL rows for a single table, delivered to [`process_writes`](#process_writes). A `TableBatch` is a plain dictionary—read it with `table_batch["table_name"]` and `table_batch["rows"]`, not attribute access. | Key | Type | Description | |------------|------------------------------------|------------------------------| |`table_name`| `str` |The table the batch belongs to| | `rows` |`Sequence[MutableMapping[str, Any]]`| The written rows | Each row is itself a dictionary that holds every column in the table schema (tags, fields, and time) keyed by column name. Columns with no value for that row are `None`. Time columns are nanosecond integers. ## Exceptions | Exception | Raised | |-------------------------|----------------------------------------------------------------------------| | `InfluxDBError` | Base exception for `LineBuilder` errors | |`InvalidMeasurementError`| When the measurement name contains spaces | | `InvalidKeyError` |When a tag or field key is empty or contains spaces, commas, or equals signs| | `InvalidLineError` | When building line protocol fails—for example, no fields were added | | `QueryError` | By [`query`](#query-data) when a query fails or names an invalid database | ### Catching QueryError The `QueryError` class is defined by the engine’s native extension module, which a plugin cannot import, and the name is not injected into plugin globals or builtins.`except QueryError` therefore raises `NameError`. Catch `Exception` instead and inspect `type(err).__name__` to distinguish it: ```python try: results = influxdb3_local.query("SELECT * FROM cpu") except Exception as err: if type(err).__name__ == "QueryError": influxdb3_local.error("query failed:", err) ``` #### Related * [Extend plugins with API features and state management](/influxdb3/core/plugins/extend-plugin/) * [influxdb3 create trigger](/influxdb3/core/reference/cli/influxdb3/create/trigger/) * [influxdb3 test](/influxdb3/core/reference/cli/influxdb3/test/) * [Processing engine reference](/influxdb3/core/reference/processing-engine/) [processing engine](/influxdb3/core/tags/processing-engine/)[plugins](/influxdb3/core/tags/plugins/)[API](/influxdb3/core/tags/api/)[python](/influxdb3/core/tags/python/) | Trigger type | Trigger specification | Entry point function | | --- | --- | --- | | Trigger type | Trigger specification | Entry point function | | Data write (WAL) | table:TABLE_NAME or all_tables | process_writes() | | Scheduled | every:DURATION or cron:EXPRESSION | process_scheduled_call() | | HTTP request | request:REQUEST_PATH | process_request() | | Method | Adds | | --- | --- | | Method | Adds | | tag(key, value) | A tag; the value is stringified | | int64_field(key, value) | A signed integer field | | uint64_field(key, value) | An unsigned integer field; negative values raise ValueError | | float64_field(key, value) | A float field; integral values are rendered with a trailing .0 | | string_field(key, value) | A string field with quotes and backslashes escaped | | bool_field(key, value) | A boolean field, rendered as t or f | | time_ns(timestamp_ns) | The nanosecond timestamp for the line | | build() | Renders the line as line protocol | | Key | Type | Description | | --- | --- | --- | | Key | Type | Description | | table_name | str | The table the batch belongs to | | rows | Sequence[MutableMapping[str, Any]] | The written rows | | Exception | Raised | | --- | --- | | Exception | Raised | | InfluxDBError | Base exception for LineBuilder errors | | InvalidMeasurementError | When the measurement name contains spaces | | InvalidKeyError | When a tag or field key is empty or contains spaces, commas, or equals signs | | InvalidLineError | When building line protocol fails—for example, no fields were added | | QueryError | By query when a query fails or names an invalid database | --- # Query data in InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/query-data/ Learn to query data in InfluxDB 3 Core. ### [Execute queries](/influxdb3/core/query-data/execute-queries/) Use tools and libraries to query data from InfluxDB 3 Core. ### [Query data with SQL](/influxdb3/core/query-data/sql/) Learn to query data in InfluxDB 3 Core using SQL. ### [Query data with InfluxQL](/influxdb3/core/query-data/influxql/) Learn to use InfluxQL to query data in InfluxDB 3 Core. [query](/influxdb3/core/tags/query/) --- # Execute queries Source: https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/ Use tools and libraries to query data from an InfluxDB 3 Core database. InfluxDB client libraries and Flight clients can use the Flight+gRPC protocol to query with SQL or InfluxQL and retrieve data in the[Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html). HTTP clients can use the InfluxDB v1 `/query` REST API to query with InfluxQL and retrieve data in JSON format. Learn how to connect to InfluxDB and query your data using the following tools: ## [Use the v3 query API](/influxdb3/core/query-data/execute-queries/influxdb-v3-api/) Use SQL or InfluxQL and the InfluxDB v3 HTTP query API to query data in InfluxDB 3 Core. ```sh curl --get http://localhost:8181/api/v3/query_sql \ --header "Authorization: Token AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` [Read more ](/influxdb3/core/query-data/execute-queries/influxdb-v3-api/) ## [Use the influxdb3 CLI](/influxdb3/core/query-data/execute-queries/influxdb3-cli/) Use the `influxdb3 query` command to query data in InfluxDB 3 Core with SQL. ```sh influxdb3 query \ --database DATABASE_NAME \ "SELECT * FROM home" ``` [Read more ](/influxdb3/core/query-data/execute-queries/influxdb3-cli/) ## [Use the v1 query API and InfluxQL](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) Use the InfluxDB v1 HTTP query API to query data in InfluxDB 3 Core with InfluxQL. ```sh curl --get http://localhost:8181/query \ --header "Authorization: Token AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` [Read more ](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/)[influxql](/influxdb3/core/tags/influxql/) --- # Use the InfluxDB v1 HTTP query API and InfluxQL to query data Source: https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb-v1-api/ * InfluxQL Use the InfluxDB v1 HTTP query API to query data in InfluxDB 3 Core with InfluxQL. The examples below use **cURL** to send HTTP requests to the InfluxDB v1 HTTP API, but you can use any HTTP client. > [!Warning] > #### InfluxQL feature support > > InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. > This process is ongoing and some InfluxQL features are still being implemented. > For information about the current implementation status of InfluxQL features, > see [InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/). Use the v1 `/query` endpoint and the `GET` request method to query data with InfluxQL: ``` GET http://localhost:8181/query ``` ## Authenticate API requests InfluxDB 3 Core requires each API request to be authenticated with a[token](/influxdb3/core/admin/tokens/). With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. * [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) * [Authenticate with a token scheme](#authenticate-with-a-token-scheme) ### Authenticate with a username and password scheme With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use the InfluxDB 1.x convention of username and password to authenticate database reads by passing a [token](/influxdb3/core/admin/tokens/) as the `password` credential. When authenticating requests to the v1 API `/query` endpoint, InfluxDB 3 Core checks that the `password` (`p`) value is an authorized [token](/influxdb3/core/admin/tokens/) . InfluxDB 3 Core ignores the `username` (`u`) parameter in the request. Use one of the following authentication schemes with clients that support Basic authentication or query parameters: * [Basic authentication](#basic-authentication) * [Query string authentication](#query-string-authentication) #### Basic authentication Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/query` requests. When authenticating requests, InfluxDB 3 Core checks that the `password` part of the decoded credential is an authorized [token](/influxdb3/core/admin/tokens/) . InfluxDB 3 Core ignores the `username` part of the decoded credential. ##### Syntax ```http Authorization: Basic ``` Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. ##### Example The following example shows how to use cURL with the `Basic` authentication scheme: ```sh curl --get "http://localhost:8181/query" \ --user "any:DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` #### Query string authentication In the URL, pass the `p` query parameter to authenticate `/query` requests. When authenticating requests, InfluxDB 3 Core checks that the `p` (*password*) value is an authorized [token](/influxdb3/core/admin/tokens/) and ignores the `u` (*username*) parameter. ##### Syntax ```sh http://localhost:8181/query/?u=any&p=DATABASE_TOKEN ``` ##### Example The following example shows how to use cURL with query string authentication: ```sh curl --get "http://localhost:8181/query" \ --data-urlencode "p=DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` ### Authenticate with a token scheme Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a [token](/influxdb3/core/admin/tokens/) for authenticating v1 API `/query` requests. `Bearer` and `Token` are equivalent in InfluxDB 3 Core. The `Token` scheme is used in the InfluxDB 2.x API.`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). Support for one or the other may vary across InfluxDB API clients. #### Syntax ```http Authorization: Bearer DATABASE_TOKEN ``` ```http Authorization: Token DATABASE_TOKEN ``` #### Examples Use `Bearer` to authenticate a query request: ```sh curl --get "http://localhost:8181/query" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` Use `Token` to authenticate a query request: ```sh curl --get "http://localhost:8181/query" \ --header "Authorization: Token DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` ## Query parameters For InfluxDB 3 Core v1 API `/query` requests, set parameters as listed in the following table: | Parameter | Allowed in |Ignored| Value | |--------------|------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `chunked` |Query string|Honored|Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first.| |`chunked_size`|Query string|Honored| **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. | | `db` \* |Query string|Honored| Database name | | `epoch` |Query string|Honored| [Timestamp precision](#timestamp-precision) | | `p` |Query string|Honored| For [query string authentication](#query-string-authentication), a [token](/influxdb3/core/admin/tokens/) | `pretty` | Query string | Ignored | N/A`q` \* | Query string | Honored | URL-encoded InfluxQL query`rp` | Query string | Honored, but discouraged | Retention policy`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string`Authorization` | Header | Honored | `Bearer DATABASE_TOKEN`, `Token DATABASE_TOKEN`, or `Basic ` \* = Required ### Timestamp precision Use one of the following values for timestamp precision: * `ns`: nanoseconds * `us`: microseconds * `ms`: milliseconds * `s`: seconds * `m`: minutes * `h`: hours Replace the following configuration values: * `DATABASE_NAME`: the name of the [database](/influxdb3/core/admin/databases/) to query * `DATABASE_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## Return results as JSON or CSV By default, the `/query` endpoint returns results in **JSON**, but it can also return results in **CSV**. To return results as CSV, include the `Accept` header with the `application/csv` or `text/csv` MIME type: ```sh curl --get http://localhost:8181/query \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Accept: application/csv" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` #### Related * [Use compatibility APIs and client libraries to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/)[python](/influxdb3/core/tags/python/) | Parameter | Allowed in | Ignored | Value | | --- | --- | --- | --- | | Parameter | Allowed in | Ignored | Value | | chunked | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to true , InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. | | chunked_size | Query string | Honored | Requires chunked to be set to true . If set to a specific value, InfluxDB chunks responses by series or by this number of points. | | db * | Query string | Honored | Database name | | epoch | Query string | Honored | Timestamp precision | | p | Query string | Honored | For query string authentication , a token | --- # Use the InfluxDB v3 HTTP query API Source: https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb-v3-api/ * InfluxQL * SQL Use the InfluxDB 3 HTTP query API to query data in InfluxDB 3 Core. The API provides `GET` and `POST` endpoints for querying data and system information using SQL or InfluxQL. > [!Note] > #### Query using gRPC or HTTP > > InfluxDB 3 supports HTTP and Flight (gRPC) query APIs. > For more information about using Flight, see the [InfluxDB 3 (`influxdb3-`) client libraries](https://github.com/InfluxCommunity/). The examples below use **cURL** to send HTTP requests to the InfluxDB 3 HTTP API, but you can use any HTTP client. * [Query using SQL and the HTTP API](#query-using-sql-and-the-http-api) * [Query using InfluxQL and the HTTP API](#query-using-influxql-and-the-http-api) ## Query using SQL and the HTTP API Use the `/api/v3/query_sql` endpoint with the `GET` or `POST` request methods. * `GET`: Pass parameters in the URL query string (for simple queries) * `POST`: Pass parameters in a JSON object (for complex queries and readability in your code) Include the following parameters: * `q`: *(Required)* The **SQL** query to execute. * `db`: *(Required)* The database to execute the query against. * `params`: A JSON object containing parameters to be used in a *parameterized query*. * `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`). JSONL (`jsonl`) is preferred because it streams results back to the client.`pretty` is for human-readable output. Default is `json`. ### Example: Query passing URL-encoded parameters The following example sends an HTTP `GET` request with a URL-encoded SQL query: ```bash curl "http://localhost:8181/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5" \ --header "Authorization: Bearer AUTH_TOKEN" ``` ### Example: Query passing JSON parameters The following example sends an HTTP `POST` request with parameters in a JSON payload: ``` curl http://localhost:8181/api/v3/query_sql \ --header "Authorization: Bearer AUTH_TOKEN" --json '{"db": "server", "q": "select * from cpu limit 5"}' ``` ### Query system information Use the HTTP API `/api/v3/query_sql` endpoint to retrieve system information about your database server and table schemas in InfluxDB 3 Core. #### Examples > [!Note] > #### system\_ sample data > > In examples, tables with `"table_name":"system_` are user-created tables for CPU, memory, disk, > network, and other resource statistics collected and written > by the user–for example, using the `psutil` Python library or[Telegraf](/telegraf/v1/get-started/) to collect > and write system metrics to an InfluxDB 3 database. ##### Show tables The following example sends a `GET` request that executes a `show tables` query to retrieve all user-created tables (`"table_schema":"iox"`), system tables, and information schema tables for a database: ```bash curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" \ --header "Authorization: Bearer AUTH_TOKEN" ``` The response body contains the following JSONL: ```jsonl {"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"} {"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"} {"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"} ``` A table has one of the following `table_schema` values: * `iox`: tables created by the user of the database. * `system`: tables used by the system to show information about the running database server. Some of these tables show stored information such as configurations, while others, such as the `queries` table, hold ephemeral state in memory. * `information_schema`: views that show schema information for tables in the database. #### View column information for a table The following query sends a `POST` request that executes an SQL query to retrieve information about columns in the sample `system_swap` table schema: *Note: when you send a query in JSON, you must escape single quotes that surround field names.* ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'", "format": "jsonl" }' ``` The output is similar to the following: ```jsonl {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"percent","ordinal_position":2,"is_nullable":"YES","data_type":"Float64","numeric_precision":24,"numeric_precision_radix":2} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"} {"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"} ``` #### Recently executed queries To view recently executed queries, query the `queries` system table: ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM system.queries LIMIT 2", "format": "jsonl" }' ``` The output is similar to the following: ```jsonl {"id":"cdd63409-1822-4e65-8e3a-d274d553dbb3","phase":"success","issue_time":"2025-01-20T17:01:40.690067","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.032689S","permit_duration":"PT0.000202S","execute_duration":"PT0.000223S","end2end_duration":"PT0.033115S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false} {"id":"47f8d312-5e75-4db2-837a-6fcf94c09927","phase":"success","issue_time":"2025-01-20T17:02:32.627782","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.000583S","permit_duration":"PT0.000015S","execute_duration":"PT0.000063S","end2end_duration":"PT0.000662S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false} ``` ## Query using InfluxQL and the HTTP API Use the `/api/v3/query_influxql` endpoint with the `GET` or `POST` request methods. * `GET`: Pass parameters in the URL query string (for simple queries) * `POST`: Pass parameters in a JSON object (for complex queries and readability in your code) Include the following parameters: * `q`: *(Required)* The **InfluxQL** query to execute. * `db`: *(Required)* The database to execute the query against. * `params`: A JSON object containing parameters to be used in a *parameterized query*. * `format`: The format of the response (`json`, `jsonl`, `csv`, `pretty`, or `parquet`). JSONL (`jsonl`) is preferred because it streams results back to the client.`pretty` is for human-readable output. Default is `json`. ### Example: Query passing URL-encoded parameters The following example sends an HTTP `GET` request with a URL-encoded InfluxQL query: ```bash curl "http://localhost:8181/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5" \ --header "Authorization: Bearer AUTH_TOKEN" ``` ### Example: Query passing JSON parameters The following example sends an HTTP `POST` request with parameters in a JSON payload: ``` curl http://localhost:8181/api/v3/query_influxql \ --header "Authorization: Bearer AUTH_TOKEN" \ --json '{"db": "server", "q": "select * from cpu limit 5"}' ``` #### Related [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/)[sql](/influxdb3/core/tags/sql/)[python](/influxdb3/core/tags/python/) --- # Use the influxdb3 CLI to query data Source: https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb3-cli/ Use the [`influxdb3 query` command](/influxdb3/core/reference/cli/influxdb3/query/)to query data in InfluxDB 3 Core with SQL or InfluxQL. Provide the following with your command: * **Authorization token**: Your InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin) with read permissions on the database. Provide this using one of the following: * `--token` command option * `INFLUXDB3_AUTH_TOKEN` environment variable * **Database name**: The name of the database to query. Provide this using one of the following: * `-d`, `--database` command option * `INFLUXDB3_DATABASE_NAME` environment variable * **Query language** *(Optional)*: The query language of the query. Use the `-l`, `--language` option to specify one of the following query languages: * `sql` *(default)* * `influxql` * **Query**: SQL or InfluxQL query to execute. Provide the query in one of the following ways: * a string * the `--file` option and the path to a file that contains the query * from stdin #### SQL #### #### string #### ```bash influxdb3 query \ --token AUTH_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM home" ``` ```bash influxdb3 query \ --token AUTH_TOKEN \ --database DATABASE_NAME \ --file ./query.sql ``` ```bash cat ./query.sql | influxdb3 query --token AUTH_TOKEN --database DATABASE_NAME ``` #### string #### ```bash influxdb3 query \ --token AUTH_TOKEN \ --language influxql \ --database DATABASE_NAME \ "SELECT * FROM home" ``` ```bash influxdb3 query \ --token AUTH_TOKEN \ --language influxql \ --file ./query.influxql ``` ```bash cat ./query.influxql | influxdb3 query \ --token AUTH_TOKEN \ --language influxql \ --database DATABASE_NAME ``` In the examples above and below, replace the following: * `DATABASE_NAME`: Name of the database to query ## Output format The `influxdb3 query` command supports the following output formats: * `pretty` *(default)* * `json` * `jsonl` * `csv` * `parquet` *(must [output to a file](#output-query-results-to-a-parquet-file))* Use the `--format` flag to specify the output format: ```sh influxdb3 query \ --token AUTH_TOKEN \ --database DATABASE_NAME \ --format json \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ``` [](#view-example-pretty-formatted-results) View example pretty-formatted results ``` +----+------+-------------+------+---------------------+ | co | hum | room | temp | time | +----+------+-------------+------+---------------------+ | 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00 | | 0 | 35.9 | Kitchen | 21.0 | 2022-01-01T08:00:00 | | 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00 | | 0 | 36.2 | Kitchen | 23.0 | 2022-01-01T09:00:00 | | 0 | 36.0 | Living Room | 21.8 | 2022-01-01T10:00:00 | +----+------+-------------+------+---------------------+ ``` [](#view-example-json-formatted-results) View example JSON-formatted results ```json [{"co":0,"hum":35.9,"room":"Living Room","temp":21.1,"time":"2022-01-01T08:00:00"},{"co":0,"hum":35.9,"room":"Kitchen","temp":21.0,"time":"2022-01-01T08:00:00"},{"co":0,"hum":35.9,"room":"Living Room","temp":21.4,"time":"2022-01-01T09:00:00"},{"co":0,"hum":36.2,"room":"Kitchen","temp":23.0,"time":"2022-01-01T09:00:00"},{"co":0,"hum":36.0,"room":"Living Room","temp":21.8,"time":"2022-01-01T10:00:00"}] ``` [](#view-example-json-line-formatted-results) View example JSON-line-formatted results ```jsonl {"co":0,"hum":35.9,"room":"Living Room","temp":21.1,"time":"2022-01-01T08:00:00"} {"co":0,"hum":35.9,"room":"Kitchen","temp":21.0,"time":"2022-01-01T08:00:00"} {"co":0,"hum":35.9,"room":"Living Room","temp":21.4,"time":"2022-01-01T09:00:00"} {"co":0,"hum":36.2,"room":"Kitchen","temp":23.0,"time":"2022-01-01T09:00:00"} {"co":0,"hum":36.0,"room":"Living Room","temp":21.8,"time":"2022-01-01T10:00:00"} ``` [](#view-example-csv-formatted-results) View example CSV-formatted results ```csv co,hum,room,temp,time 0,35.9,Living Room,21.1,2022-01-01T08:00:00 0,35.9,Kitchen,21.0,2022-01-01T08:00:00 0,35.9,Living Room,21.4,2022-01-01T09:00:00 0,36.2,Kitchen,23.0,2022-01-01T09:00:00 0,36.0,Living Room,21.8,2022-01-01T10:00:00 ``` ## Output query results to a Parquet file To output query results to a Parquet file, provide the following options with the `influxdb3 query` command: * `--format`: `parquet` * `-o`, `--output`: the filepath to the Parquet file to store results in ```sh influxdb3 query \ --token AUTH_TOKEN \ --database DATABASE_NAME \ --format parquet \ --output path/to/results.parquet \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ``` #### Related * [influxdb3 query](/influxdb3/core/reference/cli/influxdb3/query/) * [SQL reference documentation](/influxdb3/core/reference/sql/) * [InfluxQL reference documentation](/influxdb3/core/reference/influxql/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/)[influxql](/influxdb3/core/tags/influxql/)[influxdb3](/influxdb3/core/tags/influxdb3/)[CLI](/influxdb3/core/tags/cli/) --- # Query data with InfluxQL Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/ Learn to query data in InfluxDB 3 Core using InfluxQL. * [Explore your schema with InfluxQL](#explore-your-schema-with-influxql) * [Perform a basic InfluxQL query](#perform-a-basic-influxql-query) * [Aggregate data with InfluxQL](#aggregate-data-with-influxql) * [Troubleshoot InfluxQL errors](#troubleshoot-influxql-errors) * [Use parameterized queries with InfluxQL](#use-parameterized-queries-with-influxql) ### [Explore your schema with InfluxQL](/influxdb3/core/query-data/influxql/explore-schema/) Use InfluxQL `SHOW` statements to return information about your data schema. ##### List measurements ```sql SHOW MEASUREMENTS ``` ##### List field keys in a measurement ```sql SHOW FIELD KEYS FROM "measurement" ``` ##### List tag keys in a measurement ```sql SHOW TAG KEYS FROM "measurement" ``` ##### List tag values for a specific tag key ```sql SHOW TAG VALUES FROM "measurement" WITH KEY = "tag-key" WHERE time > now() - 1d ``` [Read more ](/influxdb3/core/query-data/influxql/explore-schema/) ### [Perform a basic InfluxQL query](/influxdb3/core/query-data/influxql/basic-query/) A basic InfluxQL query that queries data from InfluxDB most commonly includes `SELECT`, `FROM`, and `WHERE` clauses. ```sql SELECT temp, room FROM home WHERE time >= now() - 1d ``` [Read more ](/influxdb3/core/query-data/influxql/basic-query/) ### [Aggregate data with InfluxQL](/influxdb3/core/query-data/influxql/aggregate-select/) Use InfluxQL aggregate and selector functions to perform aggregate operations on your time series data. ##### Aggregate fields by groups ```sql SELECT MEAN(temp) AS mean, FIRST(hum) as first, FROM home GROUP BY tag ``` ##### Aggregate by time-based intervals ```sql SELECT MEAN(temp), sum(hum), FROM home WHERE time >= now() - 24h GROUP BY time(1h),room ``` [Read more ](/influxdb3/core/query-data/influxql/aggregate-select/) ### [Troubleshoot InfluxQL errors](/influxdb3/core/query-data/influxql/troubleshoot/) Learn how to troubleshoot and fix common InfluxQL errors. ### [Use parameterized queries with InfluxQL](/influxdb3/core/query-data/influxql/parameterized-queries/) Use parameterized queries to prevent injection attacks and make queries more reusable. ```sql SELECT * FROM home WHERE time >= $min_time AND temp >= $min_temp AND room = $room ``` [Read more ](/influxdb3/core/query-data/influxql/parameterized-queries/) [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/) --- # Aggregate data with InfluxQL Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/aggregate-select/ An InfluxQL query that aggregates data includes the following clauses: \* Required * \* `SELECT`: Specify fields and calculations to output from a measurement or use the wildcard alias (`*`) to select all fields and tags from a measurement. * \* `FROM`: Specify the measurement to query data from. * `WHERE`: Only retrieve data that meets the specified conditions–for example, time is in a time range, contains specific tag values, or contains a field value outside specified thresholds. * `GROUP BY`: Group data by tag values and time intervals. > [!Note] > For simplicity, the term *“aggregate”* in this guide refers to applying > both aggregate and selector functions to a dataset. Learn how to apply aggregate operations to your queried data: * [Aggregate and selector functions](#aggregate-and-selector-functions) * [Aggregate functions](#aggregate-functions) * [Selector functions](#selector-functions) * [Example aggregate queries](#example-aggregate-queries) > [!Note] > #### InfluxDB v1 to InfluxDB 3 data model > > InfluxQL was designed around the InfluxDB v1 data model, but can still be used > to query data from InfluxDB 3 Core. When using the InfluxDB 3 Core > InfluxQL implementation, the data model is different in the following ways: > > * an InfluxDB v1 **database and retention policy** combination is combined > into a single InfluxDB 3 **database** entity. > * an InfluxDB v1 **measurement** is equivalent to an InfluxDB 3 **table**. ## Aggregate and selector functions Both aggregate and selector functions return a limited number of rows from each group. Aggregate functions return a single row, whereas some selector functions let you specify the number of rows to return from each group. For example, if you `GROUP BY room` and perform an aggregate operation in your `SELECT` clause, results include an aggregate value for each unique value of `room`. ### Aggregate functions Use **aggregate functions** to aggregate values in a specified field for each group and return a single row per group containing the aggregate field value. [View InfluxQL aggregate functions](/influxdb3/core/reference/influxql/functions/aggregates/) ##### Basic aggregate query ```sql SELECT MEAN(co) from home ``` ### Selector functions Use **selector functions** to “select” a value from a specified field. [View InfluxQL selector functions](/influxdb3/core/reference/influxql/functions/selectors/) ##### Basic selector query ```sql SELECT TOP(co, 3) from home ``` ## Example aggregate queries * [Perform an ungrouped aggregation](#perform-an-ungrouped-aggregation) * [Group and aggregate data](#group-and-aggregate-data) * [Downsample data by applying interval-based aggregates](#downsample-data-by-applying-interval-based-aggregates) > [!Note] > #### Sample data > > The following examples use the [Home sensor data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Perform an ungrouped aggregation To aggregate *all* queried values in a specified field: * Use aggregate or selector functions in your `SELECT` statement. * Do not include a `GROUP BY` clause to leave your data ungrouped. ```sql SELECT MEAN(co) AS "average co" FROM home ``` [](#view-example-results) View example results name: home |time| average co | |----|-----------------| | 0 |5.269230769230769| ### Group and aggregate data To apply aggregate or selector functions to grouped data: * Use aggregate or selector functions in your `SELECT` statement. * Include a `GROUP BY` clause with a comma-delimited list of tags to group by. Keep the following in mind when using `GROUP BY`: * `GROUP BY` can use column aliases that are defined in the `SELECT` clause. ```sql SELECT MEAN(temp) AS "average temp" FROM home GROUP BY room ``` [](#view-example-results) View example results name: home tags: room=Kitchen |time| average temp | |----|------------------| | 0 |22.623076923076926| name: home tags: room=Living Room |time| average temp | |----|-----------------| | 0 |22.16923076923077| #### Downsample data by applying interval-based aggregates A common use case when querying time series is downsampling data by applying aggregates to time-based groups. To group and aggregate data into time-based groups: * In your `SELECT` clause, apply [aggregate](/influxdb3/core/reference/influxql/functions/aggregates/)or [selector](/influxdb3/core/reference/influxql/functions/selectors/)functions to queried fields. * In your `WHERE` clause, include time bounds for the query. Interval-based aggregates produce a row for each specified time interval. If no time bounds are specified in the `WHERE` clause, the query uses the default time range (1970-01-01T00:00:00Z to now) and returns a row for each interval in that time range. * In your `GROUP BY` clause: * Use the [`time()` function](/influxdb3/core/reference/influxql/functions/date-time/#time)to specify the time interval to group by. * *Optional*: Specify other tags to group by. The following example retrieves unique combinations of time intervals and rooms with their minimum, maximum, and average temperatures. ```sql SELECT MAX(temp) AS "max temp", MIN(temp) AS "min temp", MEAN(temp) AS "average temp" FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T20:00:00Z' GROUP BY time(2h), room ``` [](#view-example-results-1) View example results name: home tags: room=Kitchen | time |max temp|min temp| average temp | |--------------------|--------|--------|------------------| |2022-01-01T08:00:00Z| 23 | 21 | 22 | |2022-01-01T10:00:00Z| 22.7 | 22.4 |22.549999999999997| |2022-01-01T12:00:00Z| 22.8 | 22.5 | 22.65 | |2022-01-01T14:00:00Z| 22.8 | 22.7 | 22.75 | |2022-01-01T16:00:00Z| 22.7 | 22.4 |22.549999999999997| |2022-01-01T18:00:00Z| 23.3 | 23.1 |23.200000000000003| |2022-01-01T20:00:00Z| 22.7 | 22.7 | 22.7 | name: home tags: room=Living Room | time |max temp|min temp| average temp | |--------------------|--------|--------|------------------| |2022-01-01T08:00:00Z| 21.4 | 21.1 | 21.25 | |2022-01-01T10:00:00Z| 22.2 | 21.8 | 22 | |2022-01-01T12:00:00Z| 22.4 | 22.2 |22.299999999999997| |2022-01-01T14:00:00Z| 22.3 | 22.3 | 22.3 | |2022-01-01T16:00:00Z| 22.6 | 22.4 | 22.5 | |2022-01-01T18:00:00Z| 22.8 | 22.5 | 22.65 | |2022-01-01T20:00:00Z| 22.2 | 22.2 | 22.2 | #### Related * [InfluxQL aggregate functions](/influxdb3/core/reference/influxql/functions/aggregates/) * [InfluxQL selector functions](/influxdb3/core/reference/influxql/functions/selectors/) [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/) | time | average co | | --- | --- | | time | average co | | 0 | 5.269230769230769 | | time | average temp | | --- | --- | | time | average temp | | 0 | 22.623076923076926 | | time | average temp | | --- | --- | | time | average temp | | 0 | 22.16923076923077 | | time | max temp | min temp | average temp | | --- | --- | --- | --- | | time | max temp | min temp | average temp | | 2022-01-01T08:00:00Z | 23 | 21 | 22 | | 2022-01-01T10:00:00Z | 22.7 | 22.4 | 22.549999999999997 | | 2022-01-01T12:00:00Z | 22.8 | 22.5 | 22.65 | | 2022-01-01T14:00:00Z | 22.8 | 22.7 | 22.75 | | 2022-01-01T16:00:00Z | 22.7 | 22.4 | 22.549999999999997 | | 2022-01-01T18:00:00Z | 23.3 | 23.1 | 23.200000000000003 | | 2022-01-01T20:00:00Z | 22.7 | 22.7 | 22.7 | | time | max temp | min temp | average temp | | --- | --- | --- | --- | | time | max temp | min temp | average temp | | 2022-01-01T08:00:00Z | 21.4 | 21.1 | 21.25 | | 2022-01-01T10:00:00Z | 22.2 | 21.8 | 22 | | 2022-01-01T12:00:00Z | 22.4 | 22.2 | 22.299999999999997 | | 2022-01-01T14:00:00Z | 22.3 | 22.3 | 22.3 | | 2022-01-01T16:00:00Z | 22.6 | 22.4 | 22.5 | | 2022-01-01T18:00:00Z | 22.8 | 22.5 | 22.65 | | 2022-01-01T20:00:00Z | 22.2 | 22.2 | 22.2 | --- # Perform a basic InfluxQL query Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/basic-query/ InfluxQL (Influx Query Language) is an SQL-like query language used to interact with InfluxDB and work with times series data. > [!Note] > #### InfluxDB v1 to InfluxDB 3 data model > > InfluxQL was designed around the InfluxDB v1 data model, but can still be used > to query data from InfluxDB 3 Core. When using the InfluxDB 3 Core > InfluxQL implementation, the data model is different in the following ways: > > * an InfluxDB v1 **database and retention policy** combination is combined > into a single InfluxDB 3 **database** entity. > * an InfluxDB v1 **measurement** is equivalent to an InfluxDB 3 **table**. A basic InfluxQL query that queries data from InfluxDB most commonly includes the following clauses: \* Required * \* `SELECT`: Specify fields, tags, and calculations to return from a [table](/influxdb3/core/reference/glossary/#table) or use the wildcard alias (`*`) to select all fields and tags from a table. It requires at least one[field key](/influxdb3/core/reference/glossary/#field-key) or the wildcard alias (`*`). For more information, see[Notable SELECT statement behaviors](/influxdb3/core/reference/influxql/select/#notable-select-statement-behaviors). * \* `FROM`: Specify the[table](/influxdb3/core/reference/glossary/#table) to query from. It requires one or more comma-delimited[measurement expressions](/influxdb3/core/reference/influxql/select/#measurement_expression). * `WHERE`: Filter data based on[field values](/influxdb3/core/reference/glossary/#field),[tag values](/influxdb3/core/reference/glossary/#tag), or[timestamps](/influxdb3/core/reference/glossary/#timestamp). Only return data that meets the specified conditions–for example, falls within a time range, contains specific tag values, or contains a field value outside a specified range. ```sql SELECT temp, hum, room FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` ## Result set If at least one row satisfies the query, InfluxDB 3 Core returns row data in the query result set. If a query uses a `GROUP BY` clause, the result set includes the following: * Columns listed in the query’s `SELECT` clause * A `time` column that contains the timestamp for the record or the group * An `iox::measurement` column that contains the record’s[table](/influxdb3/core/reference/glossary/#table) name * Columns listed in the query’s `GROUP BY` clause; each row in the result set contains the values used for grouping ### GROUP BY result columns If a query uses `GROUP BY` and the `WHERE` clause doesn’t filter by time, then groups are based on the[default time range](/influxdb3/core/reference/influxql/group-by/#default-time-range). ## Basic query examples * [Query data within time boundaries](#query-data-within-time-boundaries) * [Query data without time boundaries](#query-data-without-time-boundaries) * [Query specific fields and tags](#query-specific-fields-and-tags) * [Query fields based on tag values](#query-fields-based-on-tag-values) * [Query points based on field values](#query-points-based-on-field-values) * [Alias queried fields and tags](#alias-queried-fields-and-tags) > [!Note] > #### Sample data > > The following examples use the [Home sensor data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Query data within time boundaries * Use the `SELECT` clause to specify what tags and fields to return. Specify at least one field key. To return all tags and fields, use the wildcard alias (`*`). * Specify the [table](/influxdb3/core/reference/glossary/#table) to query in the `FROM` clause. * Specify time boundaries in the `WHERE` clause. Include time-based predicates that compare the value of the `time` column to a timestamp. Use the `AND` logical operator to chain multiple predicates together. ```sql SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' ``` Query time boundaries can be relative or absolute. [](#query-with-relative-time-boundaries) Query with relative time boundaries To query data from relative time boundaries, compare the value of the `time`column to a timestamp calculated by subtracting an interval from a timestamp. Use `now()` to return the timestamp for the current time (UTC). ##### Query all data from the last month ```sql SELECT * FROM home WHERE time >= now() - 30d ``` ##### Query one day of data from a week ago ```sql SELECT * FROM home WHERE time >= now() - 7d AND time <= now() - 6d ``` [](#query-with-absolute-time-boundaries) Query with absolute time boundaries To query data from absolute time boundaries, compare the value of the `time`column to a timestamp literal. Use the `AND` logical operator to chain together multiple predicates and define both start and stop boundaries for the query. ```sql SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` ### Query data without time boundaries To query data without time boundaries, do not include any time-based predicates in your `WHERE` clause. If a time range is not defined in the `WHERE` clause, the default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to *now*. > [!Warning] > Querying data *without time bounds* can return an unexpected amount of data. > The query may take a long time to complete and results may be truncated. ```sql SELECT * FROM home ``` ### Query specific fields and tags To query specific fields, include them in the `SELECT` clause. If querying multiple fields or tags, comma-delimit each. If a field or tag key includes special characters or spaces or is case-sensitive, wrap the key in *double-quotes*. ```sql SELECT time, room, temp, hum FROM home ``` ### Query fields based on tag values * In the `SELECT` clause, include fields you want to query and tags you want to base conditions on. * In the `WHERE` clause, include predicates that compare the tag identifier to a string literal. Use[logical operators](/influxdb3/core/reference/influxql/where/#logical-operators)to chain multiple predicates together and apply multiple conditions. ```sql SELECT * FROM home WHERE room = 'Kitchen' ``` ### Query points based on field values * In the `SELECT` clause, include fields you want to query. * In the `WHERE` clause, include predicates that compare the field identifier to a value or expression. Use[logical operators](/influxdb3/core/reference/influxql/where/#logical-operators)(`AND`, `OR`) to chain multiple predicates together and apply multiple conditions. ```sql SELECT co, time FROM home WHERE co >= 10 OR co <= -10 ``` ### Alias queried fields and tags To alias or rename fields and tags that you query, use the `AS` clause. After the tag, field, or expression you want to alias, pass `AS` followed by the alias name as an identifier (wrap in double quotes (`"`) if the alias includes spaces or special characters)–for example: ```sql SELECT temp AS temperature, hum AS "humidity (%)" FROM home ``` > [!Note] > When aliasing columns in **InfluxQL**, use the `AS` clause and an[identifier](/influxdb3/core/reference/influxql/#identifiers). When[aliasing columns in **SQL**](/influxdb3/core/query-data/sql/basic-query/#alias-queried-fields-and-tags), > you can use the `AS` clause to define the alias, but it isn’t necessary. [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/) --- # Explore your schema with InfluxQL Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/explore-schema/ Use InfluxQL `SHOW` statements to return information about your data schema. > [!Note] > #### InfluxDB v1 to InfluxDB 3 data model > > InfluxQL was designed around the InfluxDB v1 data model, but can still be used > to query data from InfluxDB 3 Core. When using the InfluxDB 3 Core > InfluxQL implementation, the data model is different in the following ways: > > * an InfluxDB v1 **database and retention policy** combination is combined > into a single InfluxDB 3 **database** entity. > * an InfluxDB v1 **measurement** is equivalent to an InfluxDB 3 **table**. * [List measurements in a database](#list-measurements-in-a-database) * [List measurements that contain specific tag key-value pairs](#list-measurements-that-contain-specific-tag-key-value-pairs) * [List measurements that match a regular expression](#list-measurements-that-match-a-regular-expression) * [List field keys in a measurement](#list-field-keys-in-a-measurement) * [List tag keys in a measurement](#list-tag-keys-in-a-measurement) * [List tag keys in measurements that contain a specific tag key-value pair](#list-tag-keys-in-measurements-that-contain-a-specific-tag-key-value-pair) * [List tag values for a specific tag key](#list-tag-values-for-a-specific-tag-key) * [List tag values for multiple tags](#list-tag-values-for-multiple-tags) * [List tag values for tags that match a regular expression](#list-tag-values-for-tags-that-match-a-regular-expression) * [List tag values associated with a specific tag key-value pair](#list-tag-values-associated-with-a-specific-tag-key-value-pair) > [!Note] > #### Sample data > > The following examples use data provided in [sample data sets](/influxdb3/core/reference/sample-data/). > To run the example queries and return identical results, follow the instructions > provided for each sample data set to write the data to your InfluxDB 3 Core > database. ## List measurements in a database Use [`SHOW MEASUREMENTS`](/influxdb3/core/reference/influxql/show/#show-measurements)to list measurements in your InfluxDB database. ```sql SHOW MEASUREMENTS ``` [](#view-example-output) View example output name: measurements | name | |-------------| | bitcoin | | home | |home\_actions| | numbers | | weather | ### List measurements that contain specific tag key-value pairs To return only measurements with specific tag key-value pairs, include a `WHERE`clause with tag key-value pairs to query for. ```sql SHOW MEASUREMENTS WHERE room = 'Kitchen' ``` [](#view-example-output-1) View example output name: measurements | name | |-------------| | home | |home\_actions| ### List measurements that match a regular expression To return only measurements with names that match a[regular expression](/influxdb3/core/reference/influxql/regular-expressions/), include a `WITH` clause that compares the `MEASUREMENT` to a regular expression. ```sql SHOW MEASUREMENTS WITH MEASUREMENT =~ /^home/ ``` [](#view-example-output-2) View example output name: measurements | name | |-------------| | home | |home\_actions| ## List field keys in a measurement Use [`SHOW FIELD KEYS`](/influxdb3/core/reference/influxql/show/#show-field-keys)to return all field keys in a measurement. Include a `FROM` clause to specify the measurement. If no measurement is specified, the query returns all field keys in the database. ```sql SHOW FIELD KEYS FROM home ``` [](#view-example-output-3) View example output name: home |fieldKey|fieldType| |--------|---------| | co | integer | | hum | float | | temp | float | ## List tag keys in a measurement Use [`SHOW TAG KEYS`](/influxdb3/core/reference/influxql/show/#show-field-keys)to return all tag keys in a measurement. Include a `FROM` clause to specify the measurement. If no measurement is specified, the query returns all tag keys in the database. ```sql SHOW TAG KEYS FROM home_actions ``` [](#view-example-output-4) View example output name: home\_actions |tagKey| |------| |action| |level | | room | ### List tag keys in measurements that contain a specific tag key-value pair To return all tag keys measurements that contain specific tag key-value pairs, include a `WHERE` clause with the tag key-value pairs to query for. ```sql SHOW TAG KEYS WHERE room = 'Kitchen' ``` [](#view-example-output-5) View example output name: home |tagKey| |------| | room | name: home\_actions |tagKey| |------| |action| |level | | room | ## List tag values for a specific tag key Use [`SHOW TAG VALUES`](/influxdb3/core/reference/influxql/show/#show-field-values)to return all values for specific tags in a measurement. * Include a `FROM` clause to specify one or more measurements to query. * Use the `WITH` clause to compare `KEY` to tag keys to list the values of. * Use the `WHERE` clause to restrict the search to a specific time range (default time range is the last day). ```sql SHOW TAG VALUES FROM weather WITH KEY = location ``` > [!Note] > #### Include a FROM clause > > We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES`statement that specifies 1-50 tables to query. > Without a `FROM` clause, the InfluxDB query engine must read data from all > tables and return unique tag values from each. > > Depending on the number of tables in your database and the number of unique tag > values in each table, excluding a `FROM` clause can result in poor query performance, > query timeouts, or unnecessary resource allocation that may affect other queries. [](#view-example-output-5) View example output name: weather | key | value | |--------|-------------| |location| Concord | |location| Hayward | |location|San Francisco| ### List tag values for multiple tags To return tag values for multiple specific tag keys, use the `IN` operator in the `WITH` clause to compare `KEY` to a list of tag keys. ```sql SHOW TAG VALUES FROM home_actions WITH KEY IN ("level", "action") ``` [](#view-example-output-6) View example output name: home\_actions | key |value| |------|-----| |action|alert| |action|cool | |level | ok | |level |warn | ### List tag values for tags that match a regular expression To return only tag values from tags keys that match a regular expression, use regular expression comparison operators in your `WITH` clause to compare `KEY`to the regular expression. ```sql SHOW TAG VALUES FROM home, home_actions WITH KEY =~ /oo/ ``` [](#view-example-output-7) View example output name: home |key | value | |----|-----------| |room| Kitchen | |room|Living Room| name: home\_actions |key | value | |----|-----------| |room| Kitchen | |room|Living Room| ### List tag values associated with a specific tag key-value pair To list tag values for tags associated with a specific tag key-value pair: * Use the `WITH` clause to identify what tag keys to return values for. * Include a `WHERE` clause that identifies the tag key-value pair to query for. The following example returns tag values for the `action` and `level` tags for points where the `room` tag value is `Kitchen`. ```sql SHOW TAG VALUES FROM home_actions WITH KEY IN ("action", "level") WHERE room = 'Kitchen' ``` [](#view-example-output-8) View example output name: home\_actions | key |value| |------|-----| |action|alert| |action|cool | |level | ok | |level |warn | #### Related * [InfluxQL SHOW statements](/influxdb3/core/reference/influxql/show/) [query](/influxdb3/core/tags/query/)[influxql](/influxdb3/core/tags/influxql/) | name | | --- | | name | | bitcoin | | home | | home_actions | | numbers | | weather | | name | | --- | | name | | home | | home_actions | | name | | --- | | name | | home | | home_actions | | fieldKey | fieldType | | --- | --- | | fieldKey | fieldType | | co | integer | | hum | float | | temp | float | | tagKey | | --- | | tagKey | | action | | level | | room | | tagKey | | --- | | tagKey | | room | | tagKey | | --- | | tagKey | | action | | level | | room | | key | value | | --- | --- | | key | value | | location | Concord | | location | Hayward | | location | San Francisco | | key | value | | --- | --- | | key | value | | action | alert | | action | cool | | level | ok | | level | warn | | key | value | | --- | --- | | key | value | | room | Kitchen | | room | Living Room | | key | value | | --- | --- | | key | value | | room | Kitchen | | room | Living Room | | key | value | | --- | --- | | key | value | | action | alert | | action | cool | | level | ok | | level | warn | --- # Use parameterized queries with InfluxQL Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/parameterized-queries/ Parameterized queries in InfluxDB 3 Core let you dynamically and safely change values in a query. If your application code allows user input to customize values or expressions in a query, use a parameterized query to make sure untrusted input is processed strictly as data and not executed as code. Parameterized queries: * help prevent injection attacks, which can occur if input is executed as code * help make queries more reusable > [!Note] > #### Prevent injection attacks > > For more information on security and query parameterization, > see the [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/\> SQL\_Injection\_Prevention\_Cheat\_Sheet.html#defense-option-1-prepared-statements-with-parameterized-queries). In InfluxDB 3, a parameterized query is an InfluxQL or SQL query that contains one or more named parameter placeholders–variables that represent input data. * [Use parameters in `WHERE` expressions](#use-parameters-in-where-expressions) * [Parameter data types](#parameter-data-types) * [Data type examples](#data-type-examples) * [Time expressions](#time-expressions) * [Not compatible with parameters](#not-compatible-with-parameters) * [Parameterize an SQL query](#parameterize-an-sql-query) * [Execute parameterized InfluxQL queries](#execute-parameterized-influxql-queries) * [Use the HTTP API](#use-the-http-api) * [Use InfluxDB Flight RPC clients](#use-influxdb-flight-rpc-clients) * [Client support for parameterized queries](#client-support-for-parameterized-queries) * [Not supported](#not-supported) > [!Note] > #### Parameters only supported in `WHERE` expressions > > InfluxDB 3 supports parameters in `WHERE` clause **predicate expressions**. > Parameter values must be one of the [allowed parameter data types](#parameter-data-types). > > If you use parameters in other expressions or clauses, > such as function arguments, `SELECT`, or `GROUP BY`, then your query might not work as you expect. ## Use parameters in `WHERE` expressions You can use parameters in `WHERE` clause **predicate expressions**-–for example, the following query contains a `$temp` parameter: ```sql SELECT * FROM measurement WHERE temp > $temp ``` When executing a query, you specify parameter name-value pairs. The value that you assign to a parameter must be one of the [parameter data types](#parameter-data-types). ```go {"temp": 22.0} ``` The InfluxDB Querier parses the query text with the parameter placeholders, and then generates query plans that replace the placeholders with the values that you provide. This separation of query structure from input data ensures that input is treated as one of the allowed [data types](#parameter-data-types) and not as executable code. ## Parameter data types A parameter value can be one of the following data types: * Null * Boolean * Unsigned integer (`u_int64`) * Integer (`int64`) * Double (`float64`) * String ### Data type examples ```js { "string": "Living Room", "double": 3.14, "unsigned_integer": 1234, "integer": -1234, "boolean": false, "null": Null, } ``` ### Time expressions To parameterize time bounds, substitute a parameter for a timestamp literal–for example: ```sql SELECT * FROM home WHERE time >= $min_time ``` For the parameter value, specify the timestamp literal as a string–for example: ```go // Assign a timestamp string literal to the min_time parameter. parameters := influxdb3.QueryParameters{ "min_time": "2022-01-01 00:00:00.00", } ``` InfluxDB executes the query as the following: ```sql SELECT * FROM home WHERE time >= '2022-01-01 00:00:00.00' ``` ### Not compatible with parameters If you use parameters for the following, your query might not work as you expect: * In clauses other than `WHERE`, such as `SELECT` or `GROUP BY` * As function arguments, such as `avg($temp)` * In place of identifiers, such as column or table names * In place of duration literals, such as `time > now() - $min_duration` ## Parameterize an SQL query > [!Note] > #### Sample data > > The following examples use the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. To use a parameterized query, do the following: 1. In your query text, use the `$parameter` syntax to reference a parameter name–for example, the following query contains `$room` and `$min_temp` parameter placeholders: ``` SELECT * FROM home WHERE time > now() - 7d AND temp >= $min_temp AND room = $room ``` 2. Provide a value for each parameter name. If you don’t assign a value for a parameter, InfluxDB returns an error. The syntax for providing parameter values depends on the client you use–for example: [Go](#) ``` // Define a QueryParameters struct--a map of parameters to input values. parameters := influxdb3.QueryParameters{ "room": "Kitchen", "min_temp": 20.0, } ``` After InfluxDB receives your request and parses the query, it executes the query as ```sql SELECT * FROM home WHERE time > now() - 7d AND temp >= 20.0 AND room = 'Kitchen' ``` ## Execute parameterized InfluxQL queries > [!Note] > #### Sample data > > The following examples use the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Use the HTTP API InfluxDB 3 Core provides the `/api/v3/query_influxql` HTTP API endpoint for executing InfluxQL queries with parameters. ``` POST /api/v3/query_influxql ``` Send a JSON object that contains `db` (database), `q` (query), and `params` (parameter name-value pairs) properties in the request body. The following example sends a parameterized InfluxQL query to the `/api/v3/query_influxql` endpoint: ```bash curl "http://localhost:8181/api/v3/query_influxql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "q": "SELECT * FROM home WHERE time >= $min_time AND temp >= $min_temp AND room = $room", "params": { "min_time": "2022-01-01T08:00:00Z", "min_temp": 22.0, "room": "Kitchen" } }' ``` Replace the following: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The response body contains query results in JSON format: ```json [ {"iox::measurement":"home","time":"2022-01-01T09:00:00","co":0,"hum":36.2,"room":"Kitchen","temp":23.0}, {"iox::measurement":"home","time":"2022-01-01T10:00:00","co":0,"hum":36.1,"room":"Kitchen","temp":22.7}, {"iox::measurement":"home","time":"2022-01-01T11:00:00","co":0,"hum":36.0,"room":"Kitchen","temp":22.4}, {"iox::measurement":"home","time":"2022-01-01T12:00:00","co":0,"hum":36.0,"room":"Kitchen","temp":22.5} ] ``` ### Use InfluxDB Flight RPC clients Using the InfluxDB 3 native Flight RPC protocol and supported clients, you can send a parameterized query and a list of parameter name-value pairs. InfluxDB Flight clients that support parameterized queries pass the parameter name-value pairs in a Flight ticket `params` field. The following examples show how to use client libraries to execute parameterized InfluxQL queries: [Go](#) ```go import ( "context" "fmt" "io" "os" "text/tabwriter" "time" "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters, options influxdb3.QueryOptions) error { url := os.Getenv("INFLUX_HOST") token := os.Getenv("INFLUX_TOKEN") database := os.Getenv("INFLUX_DATABASE") // Instantiate the influxdb3 client. client, err := influxdb3.New(influxdb3.ClientConfig{ Host: url, Token: token, Database: database, }) if err != nil { panic(err) } // Ensure the client is closed after the Query function finishes. defer func(client *influxdb3.Client) { err := client.Close() if err != nil { panic(err) } }(client) // Call the client's QueryWithParameters function. // Provide the query, parameters, and the InfluxQL QueryType option. iterator, err := client.QueryWithParameters(context.Background(), query, parameters, influxdb3.WithQueryType(options.QueryType)) // Create a buffer for storing rows as you process them. w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) w.Init(os.Stdout, 0, 8, 0, '\t', 0) fmt.Fprintf(w, "time\troom\tco\thum\ttemp\n") // Format and write each row to the buffer. // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) } w.Flush() return nil } func main() { // Use the $placeholder syntax in a query to reference parameter placeholders // for input data. // The following InfluxQL query contains the placeholders $room and $min_temp. query := ` SELECT * FROM home WHERE time > now() - 7d AND temp >= $min_temp AND room = $room` // Define a QueryParameters struct--a map of placeholder names to input values. parameters := influxdb3.QueryParameters{ "room": "Kitchen", "min_temp": 20.0, } Query(query, parameters, influxdb3.QueryOptions{ QueryType: influxdb3.InfluxQL, }) } ``` ## Client support for parameterized queries * Not all [InfluxDB 3 Flight clients](/influxdb3/core/reference/client-libraries/v3/) support parameterized queries. * InfluxDB doesn’t currently support parameterized queries or DataFusion prepared statements for Flight SQL or Flight SQL clients. * InfluxDB 3 SQL and InfluxQL parameterized queries aren’t supported in InfluxDB v1 and v2 clients. ## Not supported Currently, parameterized queries in InfluxDB 3 Core don’t provide the following: * support for DataFusion prepared statements * query caching, optimization, or performance benefits [query](/influxdb3/core/tags/query/)[security](/influxdb3/core/tags/security/)[influxql](/influxdb3/core/tags/influxql/) --- # Troubleshoot InfluxQL errors Source: https://docs.influxdata.com/influxdb3/core/query-data/influxql/troubleshoot/ Learn how to troubleshoot and fix common InfluxQL errors. > [!Note] > **Disclaimer:** This document does not contain an exhaustive list of all > possible InfluxQL errors. * [error: database name required](#error-database-name-required) * [error parsing query: found …, expected identifier at …](#error-parsing-query-found--expected-identifier-at-) * [error parsing query: mixing aggregate and non-aggregate queries is not supported](#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported) * [invalid operation: time and \*influxql.VarRef are not compatible](#invalid-operation-time-and-influxqlvarref-are-not-compatible) > [!Note] > #### InfluxDB v1 to InfluxDB 3 data model > > InfluxQL was designed around the InfluxDB v1 data model, but can still be used > to query data from InfluxDB 3 Core. When using the InfluxDB 3 Core > InfluxQL implementation, the data model is different in the following ways: > > * an InfluxDB v1 **database and retention policy** combination is combined > into a single InfluxDB 3 **database** entity. > * an InfluxDB v1 **measurement** is equivalent to an InfluxDB 3 **table**. ## error: database name required ``` error: database name required ``` ### Cause The `database name required` error occurs when certain[`SHOW` queries](/influxdb3/core/reference/influxql/show/)do not specify a [database](/influxdb3/core/reference/glossary/#database)in the query or with the query request. For example, the following `SHOW` query doesn’t specify the database and assumes the `db` is not specified in the `/query` API request: ```sql SHOW MEASUREMENTS ``` ### Solution To resolve this error, specify a database with your query request by doing one of the following: * Include an `ON` clause with the `SHOW` statement that specifies the database to query: ``` SHOW MEASUREMENTS ON DATABASE_NAME ``` * If using the [InfluxDB v1 query API](/influxdb3/core/api/query-data/#operation/GetV1ExecuteQuery), Include the `db` query parameter in your request: ``` curl --get http://localhost:8181/query \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW MEASUREMENTS" ``` **Related:**[InfluxQL `SHOW` statements](/influxdb3/core/reference/influxql/show/),[Explore your schema with InfluxQL](/influxdb3/core/query-data/influxql/explore-schema/) ## error parsing query: found …, expected identifier at … ``` error parsing query: found EXAMPLE, expected identifier at line 1, char 14 ``` ### Causes This error occurs when InfluxDB anticipates an identifier in a query but doesn’t find it. Identifiers are tokens that refer to database names, retention policy names, measurement names, field keys, and tag keys. This error is generally caused by one of the following: * [A required identifier is missing](#a-required-identifier-is-missing) * [A string literal is used instead of an identifier](#a-string-literal-is-used-instead-of-an-identifier) * [An InfluxQL keyword is used as an unquoted identifier](#an-influxql-keyword-is-used-as-an-unquoted-identifier) #### A required identifier is missing Some InfluxQL statements and clauses require identifiers to identify databases, measurements, tags, or fields. If the statement is missing a required identifier, the query returns the `expected identifier` error. For example, the following query omits the measurement name from the[`FROM` clause](/influxdb3/core/reference/influxql/select/#from-clause): ```sql SELECT * FROM WHERE color = 'blue' ``` ##### Solution Update the query to include the expected identifier in the `FROM` clause that identifies the measurement to query: ```sql SELECT * FROM measurement_name WHERE color = 'blue' ``` #### A string literal is used instead of an identifier In InfluxQL, string literals are wrapped in single quotes (`''`) while character sequences wrapped in double quotes (`""`) are parsed as identifiers. If you use single quotes to wrap an identifier, the identifier is parsed as a string literal and returns the `expected identifier` error. For example, the following query wraps the measurement name in single quotes: ```sql SELECT * FROM 'measurement-name' WHERE color = 'blue' ``` Results in the following error: ``` error parsing query: found measurement-name, expected identifier at line 1, char 14 ``` ##### Solution Update single-quoted identifiers to use double quotes so they are parsed as identifiers and not as string literals. ```sql SELECT * FROM "measurement-name" WHERE color = 'blue' ``` #### An InfluxQL keyword is used as an unquoted identifier [InfluxQL keyword](/influxdb3/core/reference/influxql/#keywords)are character sequences reserved for specific functionality in the InfluxQL syntax. It is possible to use a keyword as an identifier, but the identifier must be wrapped in double quotes (`""`). > [!Note] > While wrapping identifiers that are InfluxQL keywords in double quotes is an > acceptable workaround, for simplicity, you should avoid using[InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords)as identifiers. ```sql SELECT duration FROM runs ``` Returns the following error: ``` error parsing query: found DURATION, expected identifier, string, number, bool at line 1, char 8 ``` ##### Solution Double quote [InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords)when used as identifiers: ```sql SELECT "duration" FROM runs ``` **Related:**[InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords) ## error parsing query: mixing aggregate and non-aggregate queries is not supported ``` error parsing query: mixing aggregate and non-aggregate queries is not supported ``` ### Cause The `mixing aggregate and non-aggregate` error occurs when a `SELECT` statement includes both an [aggregate function](/influxdb3/core/reference/influxql/functions/aggregates/)and a standalone [field key](/influxdb3/core/reference/glossary/#field-key) or[tag key](/influxdb3/core/reference/glossary/#tag-key). Aggregate functions return a single calculated value per group and column and there is no obvious single value to return for any un-aggregated fields or tags. For example, the following example queries two fields from the `home`measurement–`temp` and `hum`. However, it only applies the aggregate function,`MEAN` to the `temp` field. ```sql SELECT MEAN(temp), hum FROM home ``` ### Solution To fix this error, apply an aggregate or selector function to each of the queried fields: ```sql SELECT MEAN(temp), MAX(hum) FROM home ``` **Related:**[InfluxQL functions](/influxdb3/core/reference/influxql/functions/),[Aggregate data with InfluxQL](/influxdb3/core/query-data/influxql/aggregate-select/) ## invalid operation: time and \*influxql.VarRef are not compatible ``` invalid operation: time and *influxql.VarRef are not compatible ``` ### Cause The `time and \*influxql.VarRef are not compatible` error occurs when date-time strings are double-quoted in a query. Date-time strings should be formatted as string literals and wrapped in single quotes (`''`). For example: ```sql SELECT temp FROM home WHERE time \>= "2022-01-01T08:00:00Z" AND time \<= "2022-01-01T00:20:00Z" ``` Returns the following error: ``` invalid operation: time and *influxql.VarRef are not compatible ``` ### Solution To fix the error, wrap RFC3339 timestamps in single quotes rather than double quotes. ```sql SELECT temp FROM home WHERE time \>= '2022-01-01T08:00:00Z' AND time \<= '2022-01-01T00:20:00Z' ``` **Related:**[Query data within time boundaries](/influxdb3/core/query-data/influxql/basic-query/#query-data-within-time-boundaries),[`WHERE` clause–Time ranges](/influxdb3/core/reference/influxql/where/#time-ranges),[InfluxQL time syntax](/influxdb3/core/reference/influxql/time-and-timezone/#time-syntax) --- # Query data with SQL Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/ Learn to query data in InfluxDB 3 Core using SQL. * [Explore your schema with SQL](#explore-your-schema-with-sql) * [Perform a basic SQL query](#perform-a-basic-sql-query) * [Aggregate data with SQL](#aggregate-data-with-sql) * [Cast values to different types](#cast-values-to-different-types) * [Compare values in SQL queries](#compare-values-in-sql-queries) * [Fill gaps in data](#fill-gaps-in-data) * [Use parameterized queries with SQL](#use-parameterized-queries-with-sql) ### [Explore your schema with SQL](/influxdb3/core/query-data/sql/explore-schema/) Use SQL to explore your data schema in your InfluxDB 3 Core database. ##### List tables ```sql SHOW TABLES ``` ##### List columns in a table ```sql SHOW COLUMNS IN table ``` [Read more ](/influxdb3/core/query-data/sql/explore-schema/) ### [Perform a basic SQL query](/influxdb3/core/query-data/sql/basic-query/) A basic SQL query that queries data from InfluxDB 3 Core most commonly includes `SELECT`, `FROM`, and `WHERE` clauses. ```sql SELECT temp, room FROM home WHERE time >= now() - INTERVAL '1 day' ``` [Read more ](/influxdb3/core/query-data/sql/basic-query/) ### [Aggregate data with SQL](/influxdb3/core/query-data/sql/aggregate-select/) Use aggregate and selector functions to perform aggregate operations on your time series data. ##### Aggregate fields by groups ```sql SELECT mean(field1) AS mean, selector_first(field2)['value'] as first, tag1 FROM home GROUP BY tag ``` ##### Aggregate by time-based intervals ```sql SELECT DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, mean(field1), sum(field2), tag1 FROM home GROUP BY 1, tag1 ``` [Read more ](/influxdb3/core/query-data/sql/aggregate-select/) ### [Cast values to different types](/influxdb3/core/query-data/sql/cast-types/) Use the `CAST` function or double-colon `::` casting shorthand syntax to cast a value to a specific type. ```sql -- CAST clause SELECT CAST(1234.5 AS BIGINT) -- Double-colon casting shorthand SELECT 1234.5::BIGINT ``` [Read more ](/influxdb3/core/query-data/sql/cast-types/) ### [Compare values in SQL queries](/influxdb3/core/query-data/sql/compare-values/) Use SQL window functions to compare values across different rows in your time series data. Learn how to calculate differences, percentage changes, and compare values at specific time intervals. ##### Calculate difference from previous value ```sql SELECT time, room, temp, temp - LAG(temp) OVER ( PARTITION BY room ORDER BY time ) AS temp_change FROM home ORDER BY room, time ``` [Read more ](/influxdb3/core/query-data/sql/compare-values/) ### [Fill gaps in data](/influxdb3/core/query-data/sql/fill-gaps/) Use [`date_bin_gapfill`](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill) with [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate) or [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf) to fill gaps of time where no data is returned. ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as time, room, interpolate(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` [Read more ](/influxdb3/core/query-data/sql/fill-gaps/) ### [Use parameterized queries with SQL](/influxdb3/core/query-data/sql/parameterized-queries/) Use parameterized queries to prevent injection attacks and make queries more reusable. ```sql SELECT * FROM home WHERE time >= $min_time AND temp >= $min_temp AND room = $room ``` [Read more ](/influxdb3/core/query-data/sql/parameterized-queries/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/) --- # Aggregate data with SQL Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/aggregate-select/ An SQL query that aggregates data includes the following clauses: \* Required * \* `SELECT`: Specify fields, tags, and calculations to output from a table or use the wildcard alias (`*`) to select all fields and tags from a table. * \* `FROM`: Specify the table to query data from. * `WHERE`: Only return rows that meets the specified conditions–for example, the time is within a time range, a tag has a specific value, or a field value is above or below a specified threshold. * `GROUP BY`: Group data that have the same values for specified columns and expressions (for example, an aggregate function result). > [!Note] > For simplicity, the verb, **“aggregate,”** in this guide refers to applying > both aggregate and selector functions to a dataset. Learn how to apply aggregate operations to your queried data: * [Aggregate and selector functions](#aggregate-and-selector-functions) * [Aggregate functions](#aggregate-functions) * [Selector functions](#selector-functions) * [Example aggregate queries](#example-aggregate-queries) ## Aggregate and selector functions Both aggregate and selector functions return a single row from each SQL group. For example, if you `GROUP BY room` and perform an aggregate operation in your `SELECT` clause, results include an aggregate value for each unique value of `room`. ### Aggregate functions Use **aggregate functions** to aggregate values in a specified column for each group and return a single row per group containing the aggregate value. [View SQL aggregate functions](/influxdb3/core/reference/sql/functions/aggregate/) ##### Basic aggregate query ```sql SELECT AVG(co) from home ``` ### Selector functions Use **selector functions** to “select” a value from a specified column. The available selector functions are designed to work with time series data. [View SQL selector functions](/influxdb3/core/reference/sql/functions/selector/) Each selector function returns a Rust *struct* (similar to a JSON object) representing a single time and value from the specified column in the each group. What time and value get returned depend on the logic in the selector function. For example, `selector_first` returns the value of specified column in the first row of the group. `selector_max` returns the maximum value of the specified column in the group. #### Selector struct schema The struct returned from a selector function has two properties: * **time**: `time` value in the selected row * **value**: value of the specified column in the selected row ```js {time: 2023-01-01T00:00:00Z, value: 72.1} ``` #### Use selector functions Each selector function has two arguments: * The first is the column to operate on. * The second is the time column to use in the selection logic. In your `SELECT` statement, execute a selector function and use bracket notation to reference properties of the [returned struct](#selector-struct-schema) to populate the column value: ```sql SELECT selector_first(temp, time)['time'] AS time, selector_first(temp, time)['value'] AS temp, room FROM home GROUP BY room ``` ## Example aggregate queries * [Perform an ungrouped aggregation](#perform-an-ungrouped-aggregation) * [Group and aggregate data](#group-and-aggregate-data) * [Downsample data by applying interval-based aggregates](#downsample-data-by-applying-interval-based-aggregates) * [Query rows based on aggregate values](#query-rows-based-on-aggregate-values) > [!Note] > #### Sample data > > The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Perform an ungrouped aggregation To aggregate *all* queried values in a specified column: * Use aggregate or selector functions in your `SELECT` statement. * Do not include a `GROUP BY` clause to leave your data ungrouped. ```sql SELECT avg(co) AS 'average co' from home ``` [](#view-example-results) View example results | average co | |-----------------| |5.269230769230769| ### Group and aggregate data To apply aggregate or selector functions to grouped data: * Use aggregate or selector functions in your `SELECT` statement. * Include columns to group by in your `SELECT` statement. * Include a `GROUP BY` clause with a comma-delimited list of columns and expressions to group by. Keep the following in mind when using `GROUP BY`: * `GROUP BY` can use column aliases that are defined in the `SELECT` clause. * `GROUP BY` won’t use an aliased value if the alias is the same as the original column name. `GROUP BY` will use the original value of the column, not the transformed, aliased value. ```sql SELECT room, avg(temp) AS 'average temp' FROM home GROUP BY room ``` [](#view-example-results) View example results | room | average temp | |-----------|------------------| |Living Room|22.16923076923077 | | Kitchen |22.623076923076926| #### Downsample data by applying interval-based aggregates A common use case when querying time series is downsampling data by applying aggregates to time-based groups. To group and aggregate data into time-based groups: * In your `SELECT` clause: * Use the [`DATE_BIN` function](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin)to calculate time intervals and output a column that contains the start of the interval nearest to the `time` timestamp in each row–for example, the following clause calculates two-hour intervals (originating at the Unix epoch) and returns a new `time` column that contains the start of the interval nearest to `home.time`: ``` SELECT DATE_BIN(INTERVAL '2 hours', time) AS time FROM home ... ``` Given a `time` value`2022-01-01T13:00:50.000Z`, the output `time` column contains`2022-01-01T12:00:00.000Z`. * Use [aggregate](/influxdb3/core/reference/sql/functions/aggregate/) or[selector](/influxdb3/core/reference/sql/functions/selector/) functions on specified columns. * In your `GROUP BY` clause: * Specify the `DATE_BIN(...)` column ordinal reference (`1`). This lets you group by the transformed `time` value and maintain the `time`column name. * Specify other columns (for example, `room`) that are specified in the`SELECT` clause and aren’t used in a selector function. ``` SELECT DATE_BIN(INTERVAL '2 hours', time) AS time ... GROUP BY 1, room ... ``` To reference the `DATE_BIN(...)` result column by *name* in the `GROUP BY`clause, assign an alias other than “time” in the `SELECT` clause–for example: ``` SELECT DATE_BIN(INTERVAL '2 hours', time) AS _time FROM home ... GROUP BY _time, room ``` * Include an `ORDER BY` clause with columns to sort by. The following example retrieves unique combinations of time intervals and rooms with their minimum, maximum, and average temperatures: ```sql SELECT DATE_BIN(INTERVAL '2 hours', time) AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', avg(temp) AS 'average temp' FROM home GROUP BY 1, room ORDER BY room, 1 ``` [](#view-example-results) View example results | time | room |max temp|min temp| average temp | |--------------------|-----------|--------|--------|------------------| |2022-01-01T08:00:00Z| Kitchen | 23 | 21 | 22 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | 22.4 |22.549999999999997| |2022-01-01T12:00:00Z| Kitchen | 22.8 | 22.5 | 22.65 | |2022-01-01T14:00:00Z| Kitchen | 22.8 | 22.7 | 22.75 | |2022-01-01T16:00:00Z| Kitchen | 22.7 | 22.4 |22.549999999999997| |2022-01-01T18:00:00Z| Kitchen | 23.3 | 23.1 |23.200000000000003| |2022-01-01T20:00:00Z| Kitchen | 22.7 | 22.7 | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.4 | 21.1 | 21.25 | |2022-01-01T10:00:00Z|Living Room| 22.2 | 21.8 | 22 | |2022-01-01T12:00:00Z|Living Room| 22.4 | 22.2 |22.299999999999997| |2022-01-01T14:00:00Z|Living Room| 22.3 | 22.3 | 22.3 | |2022-01-01T16:00:00Z|Living Room| 22.6 | 22.4 | 22.5 | |2022-01-01T18:00:00Z|Living Room| 22.8 | 22.5 | 22.65 | |2022-01-01T20:00:00Z|Living Room| 22.2 | 22.2 | 22.2 | > [!Note] > #### GROUP BY time > > In the `GROUP BY` clause, the name “time” always refers to the `time` column > in the source table. If you want to reference a calculated time column by name, > use an alias different from “time” or use the column ordinal–for example: > > #### Column alias #### > > ``` > SELECT > DATE_BIN(INTERVAL '2 hours', time) AS _time, > room, > selector_max(temp, time)['value'] AS 'max temp', > selector_min(temp, time)['value'] AS 'min temp', > avg(temp) AS 'average temp' > FROM home > GROUP BY _time, room > ORDER BY room, _time > ``` > > ``` > SELECT > DATE_BIN(INTERVAL '2 hours', time) AS time, > room, > selector_max(temp, time)['value'] AS 'max temp', > selector_min(temp, time)['value'] AS 'min temp', > avg(temp) AS 'average temp' > FROM home > GROUP BY 1, room > ORDER BY room, 1 > ``` ### Query rows based on aggregate values To query data based on values after an aggregate operation, include a `HAVING`clause with defined predicate conditions such as a value threshold. Predicates in the `WHERE` clause are applied *before* data is aggregated. Predicates in the `HAVING` clause are applied *after* data is aggregated. ```sql SELECT room, avg(co) AS 'average co' FROM home GROUP BY room HAVING "average co" > 5 ``` [](#view-example-results) View example results | room | average co | |-------|------------------| |Kitchen|6.6923076923076925| #### Related * [SQL aggregate functions](/influxdb3/core/reference/sql/functions/aggregate/) * [SQL selector functions](/influxdb3/core/reference/sql/functions/selector/) * [GROUP BY clause](/influxdb3/core/reference/sql/group-by/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/) | average co | | --- | | average co | | 5.269230769230769 | | room | average temp | | --- | --- | | room | average temp | | Living Room | 22.16923076923077 | | Kitchen | 22.623076923076926 | | time | room | max temp | min temp | average temp | | --- | --- | --- | --- | --- | | time | room | max temp | min temp | average temp | | 2022-01-01T08:00:00Z | Kitchen | 23 | 21 | 22 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | 22.4 | 22.549999999999997 | | 2022-01-01T12:00:00Z | Kitchen | 22.8 | 22.5 | 22.65 | | 2022-01-01T14:00:00Z | Kitchen | 22.8 | 22.7 | 22.75 | | 2022-01-01T16:00:00Z | Kitchen | 22.7 | 22.4 | 22.549999999999997 | | 2022-01-01T18:00:00Z | Kitchen | 23.3 | 23.1 | 23.200000000000003 | | 2022-01-01T20:00:00Z | Kitchen | 22.7 | 22.7 | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.4 | 21.1 | 21.25 | | 2022-01-01T10:00:00Z | Living Room | 22.2 | 21.8 | 22 | | 2022-01-01T12:00:00Z | Living Room | 22.4 | 22.2 | 22.299999999999997 | | 2022-01-01T14:00:00Z | Living Room | 22.3 | 22.3 | 22.3 | | 2022-01-01T16:00:00Z | Living Room | 22.6 | 22.4 | 22.5 | | 2022-01-01T18:00:00Z | Living Room | 22.8 | 22.5 | 22.65 | | 2022-01-01T20:00:00Z | Living Room | 22.2 | 22.2 | 22.2 | | room | average co | | --- | --- | | room | average co | | Kitchen | 6.6923076923076925 | --- # Perform a basic SQL query Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/basic-query/ The InfluxDB SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)query engine which provides an SQL syntax similar to other relational query languages. A basic SQL query that queries data from InfluxDB 3 Core most commonly includes the following clauses: \* Required * \* `SELECT`: Specify fields, tags, and calculations to output from a table or use the wildcard alias (`*`) to select all fields and tags from a table. * \* `FROM`: Specify the table to query data from. * `WHERE`: Only return rows that meets the specified conditions–for example, the time is within a time range, a tag has a specific value, or a field value is above or below a specified threshold. ```sql SELECT temp, hum, room FROM home WHERE time \>= '2022-01-01T08:00:00Z' AND time \<= '2022-01-01T20:00:00Z' ``` ## Result set If at least one row satisfies the query, InfluxDB 3 Core returns row data in the query result set. An SQL query result set includes columns listed in the query’s `SELECT` statement. ## Basic query examples * [Query data within time boundaries](#query-data-within-time-boundaries) * [Query data without time boundaries](#query-data-without-time-boundaries) * [Query specific fields and tags](#query-specific-fields-and-tags) * [Query fields based on tag values](#query-fields-based-on-tag-values) * [Query points based on field values](#query-points-based-on-field-values) * [Alias queried fields and tags](#alias-queried-fields-and-tags) > [!Note] > #### Sample data > > The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Query data within time boundaries * Use the `SELECT` clause to specify what tags and fields to return. To return all tags and fields, use the wildcard alias (`*`). * Specify the table to query in the `FROM` clause. * Specify time boundaries in the `WHERE` clause. Include time-based predicates that compare the value of the `time` column to a timestamp. Use the `AND` logical operator to chain multiple predicates together. ```sql SELECT \* FROM home WHERE time \>= '2022-01-01T08:00:00Z' AND time \<= '2022-01-01T12:00:00Z' ``` Query time boundaries can be relative or absolute. [](#query-with-relative-time-boundaries) Query with relative time boundaries To query data from relative time boundaries, compare the value of the `time`column to a timestamp calculated by subtracting an interval from a timestamp. Use `now()` to return the timestamp for the current time (UTC). ##### Query all data from the last month ```sql SELECT * FROM home WHERE time >= now() - INTERVAL '1 month' ``` ##### Query one day of data data from a week ago ```sql SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' AND time <= now() - INTERVAL '6 days' ``` [](#query-with-absolute-time-boundaries) Query with absolute time boundaries To query data from absolute time boundaries, compare the value of the `time` column to a timestamp literal. Use the `AND` logical operator to chain together multiple predicates and define both start and stop boundaries for the query. ```sql SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` [](#query-data-using-a-time-zone-offset) Query data using a time zone offset To query data using a time zone offset, use the[`AT TIME ZONE` operator](/influxdb3/core/reference/sql/operators/other/#at-time-zone)to apply a time zone offset to timestamps in the `WHERE` clause. > [!Note] > Timestamp types in InfluxDB always represent a UTC time. `AT TIME ZONE` returns > a UTC timestamp adjusted for the offset of the specified time zone. > Timestamps in the `time` column are not updated. > If you need to display the timestamps in your current timezone, this should be > handled client-side. ```sql SELECT * FROM home WHERE time >= '2022-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AND time <= '2022-01-01 12:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' ``` ### Query data without time boundaries To query data without time boundaries, do not include any time-based predicates in your `WHERE` clause. > [!Warning] > Querying data *without time bounds* can return an unexpected amount of data. > The query may take a long time to complete and results may be truncated. ```sql SELECT * FROM home ``` ### Query specific fields and tags To query specific fields, include them in the `SELECT` clause. If querying multiple fields or tags, comma-delimit each. If a field or tag key includes special characters or spaces or is case-sensitive, wrap the key in *double-quotes*. ```sql SELECT time, room, temp, hum FROM home ``` ### Query fields based on tag values * Include the fields you want to query and the tags you want to base conditions on in the `SELECT` clause. * Include predicates in the `WHERE` clause that compare the tag identifier to a string literal. Use [logical operators](/influxdb3/core/reference/sql/operators/logical/) to chain multiple predicates together and apply multiple conditions. ```sql SELECT * FROM home WHERE room = 'Kitchen' ``` ### Query points based on field values * In the `SELECT` clause, include fields you want to query. * In the `WHERE` clause, include predicates that compare the field identifier to a value or expression. Use [logical operators](/influxdb3/core/reference/sql/where/#logical-operators) (`AND`, `OR`) to chain multiple predicates together and apply multiple conditions. ```sql SELECT co, time FROM home WHERE co >= 10 OR co <= -10 ``` ### Alias queried fields and tags To alias or rename fields and tags that you query, pass a string literal after the field or tag identifier in the `SELECT` clause. You can use the `AS` clause to define the alias, but it isn’t necessary. The following queries are functionally the same: ```sql SELECT temp 'temperature', hum 'humidity' FROM home SELECT temp AS 'temperature', hum AS 'humidity' FROM home ``` [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/) --- # Cast values to different types Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/cast-types/ Use the `CAST` function or double-colon `::` casting shorthand syntax to cast a value to a specific type. ```sql -- CAST function SELECT CAST(1234.5 AS BIGINT) -- Double-colon casting shorthand SELECT 1234.5::BIGINT ``` * [Cast to a string type](#cast-to-a-string-type) * [Cast to numeric types](#cast-to-numeric-types) * [Float](#cast-to-a-float) * [Integer](#cast-to-an-integer) * [Unsigned integer](#cast-to-an-unsigned-integer) * [Cast to a boolean type](#cast-to-a-boolean-type) * [Cast to a timestamp type](#cast-to-a-timestamp-type) Casting operations can be performed on a column expression or a literal value. For example, the following query uses the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data)and: * Casts all values in the `time` column to integers (Unix nanosecond timestamps). * Casts the literal string value `'1234'` to a 64-bit float for each row. #### :: shorthand #### ```sql SELECT time::BIGINT AS unix_time, '1234'::DOUBLE AS string_to_float FROM home LIMIT 5 ``` ```sql SELECT CAST(time AS BIGINT) AS unix_time, CAST('1234' AS DOUBLE) AS string_to_float FROM home LIMIT 5 ``` | unix\_time |string\_to\_float| |-------------------|-----------------| |1641024000000000000| 1234 | |1641027600000000000| 1234 | |1641031200000000000| 1234 | |1641034800000000000| 1234 | |1641038400000000000| 1234 | ## Cast to a string type Use the `STRING`, `CHAR`, `VARCHAR`, or `TEXT` type in a casting operation to cast a value to a string. #### :: shorthand #### ```sql value::STRING value::CHAR value::VARCHAR value::TEXT ``` ```sql CAST(value AS STRING) CAST(value AS CHAR) CAST(value AS VARCHAR) CAST(value AS TEXT) ``` SQL supports casting the following to a string value: * **Floats** * **Integers** * **Unsigned integers** * **Booleans** * **Timestamps** ## Cast to numeric types The InfluxDB SQL implementation supports 64-bit floats (`DOUBLE`), integers (`BIGINT`), and unsigned integers (`BIGINT UNSIGNED`). ### Cast to a float Use the `DOUBLE` type in a casting operation to cast a value to a 64-bit float. #### :: shorthand #### ```sql value::DOUBLE ``` ```sql CAST(value AS DOUBLE) ``` SQL supports casting the following to a float value: * **Strings**: Returns the float equivalent of the numeric string (`[0-9]`). The following string patterns are also supported: * Scientific notation (`'123.4E+10'`) * Infinity (`'±Inf'`) * NaN (`'NaN'`) * **Integers** * **Unsigned integers** ### Cast to an integer Use the `BIGINT` type in a casting operation to cast a value to a 64-bit signed integer. #### :: shorthand #### ```sql value::BIGINT ``` ```sql CAST(value AS BIGINT) ``` SQL supports casting the following to an integer: * **Strings**: Returns the integer equivalent of the numeric string (`[0-9]`). * **Floats**: Truncates the float value at the decimal. * **Unsigned integers**: Returns the signed integer equivalent of the unsigned integer. * **Booleans**: Returns `1` for `true` and `0` for `false`. * **Timestamps**: Returns the equivalent[nanosecond epoch timestamp](/influxdb3/core/reference/glossary/#unix-timestamp). ### Cast to an unsigned integer Use the `BIGINT UNSIGNED` type in a casting operation to cast a value to a 64-bit unsigned integer. #### :: shorthand #### ```sql value::BIGINT UNSIGNED ``` ```sql CAST(value AS BIGINT UNSIGNED) ``` SQL supports casting the following to an unsigned integer: * **Strings**: Returns the unsigned integer equivalent of the numeric string (`[0-9]`). * **Floats**: Truncates the float value at the decimal. * **Integers**: Returns the unsigned integer equivalent of the signed integer. * **Booleans**: Returns `1` for `true` and `0` for `false`. * **Timestamps**: Returns the equivalent[nanosecond epoch timestamp](/influxdb3/core/reference/glossary/#unix-timestamp). ## Cast to a boolean type Use the `BOOLEAN` type in a casting operation to cast a value to a boolean. #### :: shorthand #### ```sql value::BOOLEAN ``` ```sql CAST(value AS BOOLEAN) ``` SQL supports casting the following to a boolean: * **Strings** * Return `true`: * `'true'` *(case-insensitive)* * `'t'`, *(case-insensitive)* * `'1'` * Return `false`: * `'false'` *(case-insensitive)* * `'f'` *(case-insensitive)* * `'0'` * **Integers** * Returns `true`: positive non-zero integer * Returns `false`: `0` * **Unsigned integers** * Returns `true`: non-zero unsigned integer * Returns `false`: `0` ## Cast to a timestamp type Use the `TIMESTAMP` type in a casting operation to cast a value to a timestamp. #### :: shorthand #### ```sql value::TIMESTAMP ``` ```sql CAST(value AS TIMESTAMP) ``` SQL supports casting the following to a timestamp: * **Strings**: Returns the timestamp equivalent of the string value. The following RFC3339 and RFC339-like string patterns are supported: * `YYYY-MM-DDT00:00:00.000Z` * `YYYY-MM-DDT00:00:00.000-00:00` * `YYYY-MM-DD 00:00:00.000-00:00` * `YYYY-MM-DDT00:00:00Z` * `YYYY-MM-DD 00:00:00.000` * `YYYY-MM-DD 00:00:00` * `YYYY-MM-DD` * **Integers**: Parses the integer as a Unix *second* timestamp and returns the equivalent timestamp. * **Unsigned integers**: Parses the unsigned integer as a Unix nanosecond timestamp and returns the equivalent timestamp. > [!Note] > #### Cast Unix nanosecond timestamps to a timestamp type > > To cast a Unix nanosecond timestamp to a timestamp type, first cast the numeric > value to an unsigned integer (`BIGINT UNSIGNED`) and then a timestamp. > You can also use the [`to_timestamp_nanos`](/influxdb3/core/reference/sql/functions/time-and-date/\> #to\_timestamp\_nanos) > function. > > #### :: shorthand #### > > ``` > 1704067200000000000::BIGINT UNSIGNED::TIMESTAMP > ``` > > ``` > CAST(CAST(1704067200000000000 AS BIGINT UNSIGNED) AS TIMESTAMP) > ``` > > ``` > to_timestamp_nanos(1704067200000000000) > ``` ### Timestamp functions You can also use the following SQL functions to cast a value to a timestamp type: * [`to_timestamp`](/influxdb3/core/reference/sql/functions/time-and-date/#to_timestamp) * [`to_timestamp_millis`](/influxdb3/core/reference/sql/functions/time-and-date/#to_timestamp_millis) * [`to_timestamp_micros`](/influxdb3/core/reference/sql/functions/time-and-date/#to_timestamp_micros) * [`to_timestamp_nanos`](/influxdb3/core/reference/sql/functions/time-and-date/#to_timestamp_nanos) * [`to_timestamp_seconds`](/influxdb3/core/reference/sql/functions/time-and-date/#to_timestamp_seconds) * [to\_unixtime](/influxdb3/core/reference/sql/functions/time-and-date/#to_unixtime) #### Related * [SQL data types](/influxdb3/core/reference/sql/data-types/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/) | unix_time | string_to_float | | --- | --- | | unix_time | string_to_float | | 1641024000000000000 | 1234 | | 1641027600000000000 | 1234 | | 1641031200000000000 | 1234 | | 1641034800000000000 | 1234 | | 1641038400000000000 | 1234 | --- # Compare values in SQL queries Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/compare-values/ Use [SQL window functions](/influxdb3/core/reference/sql/functions/window/) to compare values across different rows in your time series data. Window functions like [`LAG`](/influxdb3/core/reference/sql/functions/window/#lag) and [`LEAD`](/influxdb3/core/reference/sql/functions/window/#lead) let you access values from previous or subsequent rows without using self-joins, making it easy to calculate changes over time. Common use cases for comparing values include: * Calculating the difference between the current value and a previous value * Computing rate of change or percentage change * Detecting significant changes or anomalies * Comparing values at specific time intervals * Handling counter metrics that reset to zero **To compare values across rows:** 1. Use a [window function](/influxdb3/core/reference/sql/functions/window/) such as `LAG` or `LEAD` with an `OVER` clause. 2. Include a `PARTITION BY` clause to group data by tags (like `room` or `sensor_id`). 3. Include an `ORDER BY` clause to define the order for comparisons (typically by `time`). 4. Use arithmetic operators to calculate differences, ratios, or percentage changes. ## Examples of comparing values > [!Note] > #### Sample data > > The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. * [Calculate the difference from the previous value](#calculate-the-difference-from-the-previous-value) * [Calculate the percentage change](#calculate-the-percentage-change) * [Compare values at regular intervals](#compare-values-at-regular-intervals) * [Compare values with exact time offsets](#compare-values-with-exact-time-offsets) * [Handle counter metrics and resets](#handle-counter-metrics-and-resets) * [Calculate non-negative differences (counter rate)](#calculate-non-negative-differences-counter-rate) * [Calculate cumulative counter increase](#calculate-cumulative-counter-increase) * [Aggregate counter increases by time interval](#aggregate-counter-increases-by-time-interval) ### Calculate the difference from the previous value Use the `LAG` function to access the value from the previous row and calculate the difference. This is useful for detecting changes over time. ```sql SELECT time, room, temp, temp - LAG(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS temp_change FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|temp\_change| |-------------------|-----------|----|------------| |2022-01-01T08:00:00| Kitchen |21.0| NULL | |2022-01-01T09:00:00| Kitchen |23.0| 2.0 | |2022-01-01T10:00:00| Kitchen |22.7| \-0.3 | |2022-01-01T08:00:00|Living Room|21.1| NULL | |2022-01-01T09:00:00|Living Room|21.4| 0.3 | |2022-01-01T10:00:00|Living Room|21.8| 0.4 | The first row in each partition returns `NULL` for `temp_change` because there’s no previous value. To use a default value instead of `NULL`, provide a third argument to `LAG`: ```sql LAG(temp, 1, 0) -- Returns 0 if no previous value exists ``` ### Calculate the percentage change Calculate the percentage change between the current value and a previous value by dividing the difference by the previous value. ```sql SELECT time, room, temp, ROUND( ((temp - LAG(temp, 1) OVER (PARTITION BY room ORDER BY time)) / LAG(temp, 1) OVER (PARTITION BY room ORDER BY time)) * 100, 2 ) AS percent_change FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|percent\_change| |-------------------|-----------|----|---------------| |2022-01-01T08:00:00| Kitchen |21.0| NULL | |2022-01-01T09:00:00| Kitchen |23.0| 9.52 | |2022-01-01T10:00:00| Kitchen |22.7| \-1.30 | |2022-01-01T08:00:00|Living Room|21.1| NULL | |2022-01-01T09:00:00|Living Room|21.4| 1.42 | |2022-01-01T10:00:00|Living Room|21.8| 1.87 | ### Compare values at regular intervals For regularly spaced time series data (like hourly readings), use `LAG` with an offset parameter to compare values from a specific number of rows back. The following query compares each temperature reading with the reading from one hour earlier (assuming hourly data): ```sql SELECT time, room, temp, LAG(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS temp_1h_ago, temp - LAG(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS hourly_change FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T12:00:00Z' ORDER BY room, time ``` | time | room |temp|temp\_1h\_ago|hourly\_change| |-------------------|-----------|----|-------------|--------------| |2022-01-01T08:00:00| Kitchen |21.0| NULL | NULL | |2022-01-01T09:00:00| Kitchen |23.0| 21.0 | 2.0 | |2022-01-01T10:00:00| Kitchen |22.7| 23.0 | \-0.3 | |2022-01-01T11:00:00| Kitchen |22.4| 22.7 | \-0.3 | |2022-01-01T08:00:00|Living Room|21.1| NULL | NULL | |2022-01-01T09:00:00|Living Room|21.4| 21.1 | 0.3 | |2022-01-01T10:00:00|Living Room|21.8| 21.4 | 0.4 | |2022-01-01T11:00:00|Living Room|22.2| 21.8 | 0.4 | ### Compare values with exact time offsets For irregularly spaced time series data or when you need to compare values from an exact time offset (like exactly 1 hour ago, not just the previous row), use a self-join with interval arithmetic. ```sql SELECT current.time, current.room, current.temp AS current_temp, previous.temp AS temp_1h_ago, current.temp - previous.temp AS hourly_diff FROM home AS current LEFT JOIN home AS previous ON current.room = previous.room AND previous.time = current.time - INTERVAL '1 hour' WHERE current.time >= '2022-01-01T08:00:00Z' AND current.time < '2022-01-01T12:00:00Z' ORDER BY current.room, current.time ``` | time | room |current\_temp|temp\_1h\_ago|hourly\_diff| |-------------------|-----------|-------------|-------------|------------| |2022-01-01T08:00:00| Kitchen | 21.0 | NULL | NULL | |2022-01-01T09:00:00| Kitchen | 23.0 | 21.0 | 2.0 | |2022-01-01T10:00:00| Kitchen | 22.7 | 23.0 | \-0.3 | |2022-01-01T11:00:00| Kitchen | 22.4 | 22.7 | \-0.3 | |2022-01-01T08:00:00|Living Room| 21.1 | NULL | NULL | |2022-01-01T09:00:00|Living Room| 21.4 | 21.1 | 0.3 | |2022-01-01T10:00:00|Living Room| 21.8 | 21.4 | 0.4 | |2022-01-01T11:00:00|Living Room| 22.2 | 21.8 | 0.4 | This self-join approach works when: * Your data points don’t fall at regular intervals * You need to compare against a specific time offset regardless of when the previous data point occurred * You want to ensure the comparison is against a value from exactly 1 hour ago (or any other specific interval) ## Handle counter metrics and resets Counter metrics track cumulative values that increase over time, such as total requests, bytes transferred, or errors. Unlike gauge metrics (which can go up or down), counters typically only increase, though they may reset to zero when a service restarts. Use [`GREATEST`](/influxdb3/core/reference/sql/functions/conditional/#greatest) with `LAG` to handle counter resets by treating negative differences as zero. > [!Note] > #### InfluxDB 3 SQL and counter metrics > > InfluxDB 3 SQL doesn’t provide built-in equivalents to Flux’s `increase()`or InfluxQL’s `NON_NEGATIVE_DIFFERENCE()` functions. > Use the patterns shown below to achieve similar results. ### Calculate non-negative differences (counter rate) Calculate the increase between consecutive counter readings, treating negative differences (counter resets) as zero. ```sql SELECT time, host, requests, LAG(requests) OVER (PARTITION BY host ORDER BY time) AS prev_requests, GREATEST( requests - LAG(requests) OVER (PARTITION BY host ORDER BY time), 0 ) AS requests_increase FROM metrics WHERE host = 'server1' ORDER BY time ``` | time | host |requests|prev\_requests|requests\_increase| |-------------------|-------|--------|--------------|------------------| |2024-01-01T00:00:00|server1| 1000 | NULL | 0 | |2024-01-01T01:00:00|server1| 1250 | 1000 | 250 | |2024-01-01T02:00:00|server1| 1600 | 1250 | 350 | |2024-01-01T03:00:00|server1| 50 | 1600 | 0 | |2024-01-01T04:00:00|server1| 300 | 50 | 250 | `LAG(requests)` retrieves the previous counter value, `requests - LAG(requests)` calculates the difference, and `GREATEST(..., 0)` returns 0 for negative differences (counter resets).`PARTITION BY host` ensures comparisons are only within the same host. ### Calculate cumulative counter increase Calculate the total increase in a counter over time, handling resets. Use a Common Table Expression (CTE) to first calculate the differences, then sum them. ```sql WITH counter_diffs AS ( SELECT time, host, requests, GREATEST( requests - LAG(requests) OVER (PARTITION BY host ORDER BY time), 0 ) AS requests_increase FROM metrics WHERE host = 'server1' ) SELECT time, host, requests, SUM(requests_increase) OVER (PARTITION BY host ORDER BY time) AS cumulative_increase FROM counter_diffs ORDER BY time ``` | time | host |requests|cumulative\_increase| |-------------------|-------|--------|--------------------| |2024-01-01T00:00:00|server1| 1000 | 0 | |2024-01-01T01:00:00|server1| 1250 | 250 | |2024-01-01T02:00:00|server1| 1600 | 600 | |2024-01-01T03:00:00|server1| 50 | 600 | |2024-01-01T04:00:00|server1| 300 | 850 | The CTE computes non-negative differences for each row, then `SUM(requests_increase) OVER (...)` creates a running total. The cumulative increase continues to grow despite the counter reset at 03:00. ### Aggregate counter increases by time interval Calculate the total increase in a counter for each time interval (for example, hourly totals). ```sql WITH counter_diffs AS ( SELECT DATE_BIN(INTERVAL '1 hour', time) AS time_bucket, host, requests, GREATEST( requests - LAG(requests) OVER (PARTITION BY host ORDER BY time), 0 ) AS requests_increase FROM metrics ) SELECT time_bucket, host, SUM(requests_increase) AS total_increase FROM counter_diffs WHERE requests_increase > 0 GROUP BY time_bucket, host ORDER BY host, time_bucket ``` | time\_bucket | host |total\_increase| |-------------------|-------|---------------| |2024-01-01T01:00:00|server1| 250 | |2024-01-01T02:00:00|server1| 350 | |2024-01-01T04:00:00|server1| 250 | |2024-01-01T01:00:00|server2| 400 | |2024-01-01T02:00:00|server2| 500 | |2024-01-01T03:00:00|server2| 300 | |2024-01-01T04:00:00|server2| 400 | The CTE calculates differences for each row.`DATE_BIN()` assigns each timestamp to a 1-hour interval, `SUM(requests_increase)` aggregates all increases within each interval, and `WHERE requests_increase > 0` filters out zero increases (first row and counter resets). #### Related * [SQL window functions](/influxdb3/core/reference/sql/functions/window/) * [Aggregate data with SQL](/influxdb3/core/query-data/sql/aggregate-select/) [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/)[window functions](/influxdb3/core/tags/window-functions/) | time | room | temp | temp_change | | --- | --- | --- | --- | | time | room | temp | temp_change | | 2022-01-01T08:00:00 | Kitchen | 21.0 | NULL | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 2.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | -0.3 | | 2022-01-01T08:00:00 | Living Room | 21.1 | NULL | | 2022-01-01T09:00:00 | Living Room | 21.4 | 0.3 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 0.4 | | time | room | temp | percent_change | | --- | --- | --- | --- | | time | room | temp | percent_change | | 2022-01-01T08:00:00 | Kitchen | 21.0 | NULL | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 9.52 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | -1.30 | | 2022-01-01T08:00:00 | Living Room | 21.1 | NULL | | 2022-01-01T09:00:00 | Living Room | 21.4 | 1.42 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 1.87 | | time | room | temp | temp_1h_ago | hourly_change | | --- | --- | --- | --- | --- | | time | room | temp | temp_1h_ago | hourly_change | | 2022-01-01T08:00:00 | Kitchen | 21.0 | NULL | NULL | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 21.0 | 2.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 23.0 | -0.3 | | 2022-01-01T11:00:00 | Kitchen | 22.4 | 22.7 | -0.3 | | 2022-01-01T08:00:00 | Living Room | 21.1 | NULL | NULL | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.1 | 0.3 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 21.4 | 0.4 | | 2022-01-01T11:00:00 | Living Room | 22.2 | 21.8 | 0.4 | | time | room | current_temp | temp_1h_ago | hourly_diff | | --- | --- | --- | --- | --- | | time | room | current_temp | temp_1h_ago | hourly_diff | | 2022-01-01T08:00:00 | Kitchen | 21.0 | NULL | NULL | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 21.0 | 2.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 23.0 | -0.3 | | 2022-01-01T11:00:00 | Kitchen | 22.4 | 22.7 | -0.3 | | 2022-01-01T08:00:00 | Living Room | 21.1 | NULL | NULL | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.1 | 0.3 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 21.4 | 0.4 | | 2022-01-01T11:00:00 | Living Room | 22.2 | 21.8 | 0.4 | | time | host | requests | prev_requests | requests_increase | | --- | --- | --- | --- | --- | | time | host | requests | prev_requests | requests_increase | | 2024-01-01T00:00:00 | server1 | 1000 | NULL | 0 | | 2024-01-01T01:00:00 | server1 | 1250 | 1000 | 250 | | 2024-01-01T02:00:00 | server1 | 1600 | 1250 | 350 | | 2024-01-01T03:00:00 | server1 | 50 | 1600 | 0 | | 2024-01-01T04:00:00 | server1 | 300 | 50 | 250 | | time | host | requests | cumulative_increase | | --- | --- | --- | --- | | time | host | requests | cumulative_increase | | 2024-01-01T00:00:00 | server1 | 1000 | 0 | | 2024-01-01T01:00:00 | server1 | 1250 | 250 | | 2024-01-01T02:00:00 | server1 | 1600 | 600 | | 2024-01-01T03:00:00 | server1 | 50 | 600 | | 2024-01-01T04:00:00 | server1 | 300 | 850 | | time_bucket | host | total_increase | | --- | --- | --- | | time_bucket | host | total_increase | | 2024-01-01T01:00:00 | server1 | 250 | | 2024-01-01T02:00:00 | server1 | 350 | | 2024-01-01T04:00:00 | server1 | 250 | | 2024-01-01T01:00:00 | server2 | 400 | | 2024-01-01T02:00:00 | server2 | 500 | | 2024-01-01T03:00:00 | server2 | 300 | | 2024-01-01T04:00:00 | server2 | 400 | --- # Explore your schema with SQL Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/explore-schema/ Use SQL to explore your data schema in your InfluxDB 3 Core database. ## List tables in a database Use `SHOW TABLES` to list tables in your InfluxDB database. ```sql SHOW TABLES ``` [](#view-example-output) View example output Tables listed with the `table_schema` of `iox` are tables. Tables with `system` or `information_schema` table schemas are system tables that store internal metadata. |table\_catalog| table\_schema |table\_name |table\_type| |--------------|-------------------|------------|-----------| | public | iox | home |BASE TABLE | | public | iox | noaa |BASE TABLE | | public | system | queries |BASE TABLE | | public |information\_schema| tables | VIEW | | public |information\_schema| views | VIEW | | public |information\_schema| columns | VIEW | | public |information\_schema|df\_settings| VIEW | ## List columns in a table Use the `SHOW COLUMNS` statement to view what columns are in a table. Use the `IN` clause to specify the table. ```sql SHOW COLUMNS IN home ``` [](#view-example-output) View example output |table\_catalog|table\_schema|table\_name|column\_name| data\_type |is\_nullable| |--------------|-------------|-----------|------------|---------------------------|------------| | public | iox | home | co | Int64 | YES | | public | iox | home | hum | Float64 | YES | | public | iox | home | room | Dictionary(Int32, Utf8) | YES | | public | iox | home | temp | Float64 | YES | | public | iox | home | time |Timestamp(Nanosecond, None)| NO | [query](/influxdb3/core/tags/query/)[sql](/influxdb3/core/tags/sql/) | table_catalog | table_schema | table_name | table_type | | --- | --- | --- | --- | | table_catalog | table_schema | table_name | table_type | | public | iox | home | BASE TABLE | | public | iox | noaa | BASE TABLE | | public | system | queries | BASE TABLE | | public | information_schema | tables | VIEW | | public | information_schema | views | VIEW | | public | information_schema | columns | VIEW | | public | information_schema | df_settings | VIEW | | table_catalog | table_schema | table_name | column_name | data_type | is_nullable | | --- | --- | --- | --- | --- | --- | | table_catalog | table_schema | table_name | column_name | data_type | is_nullable | | public | iox | home | co | Int64 | YES | | public | iox | home | hum | Float64 | YES | | public | iox | home | room | Dictionary(Int32, Utf8) | YES | | public | iox | home | temp | Float64 | YES | | public | iox | home | time | Timestamp(Nanosecond, None) | NO | --- # Fill gaps in data Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/fill-gaps/ Use [`date_bin_gapfill`](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill)with [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate)or [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf) to fill gaps of time where no data is returned. Gap-filling SQL queries handle missing data in time series data by filling in gaps with interpolated values or by carrying forward the last available observation. **To fill gaps in data:** 1. Use the `date_bin_gapfill` function to window your data into time-based groups and apply an [aggregate function](/influxdb3/core/reference/sql/functions/aggregate/)to each window. If no data exists in a window, `date_bin_gapfill` inserts a new row with the starting timestamp of the window, all columns in the`GROUP BY` clause populated, and null values for the queried fields. 2. Use either `interpolate` or `locf` to fill the inserted null values in the specified column. * **interpolate**: fills null values by interpolating values between non-null values. * **locf**: fills null values by carrying the last observed value forward. > [!Note] > The expression passed to `interpolate` or `locf` must use an[aggregate function](/influxdb3/core/reference/sql/functions/aggregate/). 3. Include a `WHERE` clause that sets upper and lower time bounds. For example: ```sql WHERE time \>= '2022-01-01T08:00:00Z' AND time \<= '2022-01-01T10:00:00Z' ``` ## Example of filling gaps in data The following examples use the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data)to show how to use `date_bin_gapfill` and the different results of `interplate`and `locf`. #### interpolate #### ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as time, room, interpolate(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` | time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 22 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 22.85 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.25 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.6 | |2022-01-01T10:00:00Z|Living Room| 21.8 | ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as time, room, locf(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` | time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 21 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 23 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.1 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.4 | |2022-01-01T10:00:00Z|Living Room| 21.8 | | time | room | AVG(home.temp) | | --- | --- | --- | | time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 22 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 22.85 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.25 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.6 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | time | room | AVG(home.temp) | | --- | --- | --- | | time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 21 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 23 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.1 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.4 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | --- # Use parameterized queries with SQL Source: https://docs.influxdata.com/influxdb3/core/query-data/sql/parameterized-queries/ Parameterized queries in InfluxDB 3 Core let you dynamically and safely change values in a query. If your application code allows user input to customize values or expressions in a query, use a parameterized query to make sure untrusted input is processed strictly as data and not executed as code. Parameterized queries: * help prevent injection attacks, which can occur if input is executed as code * help make queries more reusable > [!Note] > #### Prevent injection attacks > > For more information on security and query parameterization, > see the [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html#defense-option-1-prepared-statements-with-parameterized-queries). In InfluxDB 3, a parameterized query is an InfluxQL or SQL query that contains one or more named parameter placeholders–variables that represent input data. * [Use parameters in `WHERE` expressions](#use-parameters-in-where-expressions) * [Parameter data types](#parameter-data-types) * [Data type examples](#data-type-examples) * [Time expressions](#time-expressions) * [Not compatible with parameters](#not-compatible-with-parameters) * [Parameterize an SQL query](#parameterize-an-sql-query) * [Execute parameterized SQL queries](#execute-parameterized-sql-queries) * [Use the HTTP API](#use-the-http-api) * [Use InfluxDB Flight RPC clients](#use-influxdb-flight-rpc-clients) * [Client support for parameterized queries](#client-support-for-parameterized-queries) * [Not supported](#not-supported) > [!Note] > #### Parameters only supported in `WHERE` expressions > > InfluxDB 3 supports parameters in `WHERE` clause **predicate expressions**. > Parameter values must be one of the [allowed parameter data types](#parameter-data-types). > > If you use parameters in other expressions or clauses, > such as function arguments, `SELECT`, or `GROUP BY`, then your query might not work as you expect. ## Use parameters in `WHERE` expressions You can use parameters in `WHERE` clause **predicate expressions**-–for example, the following query contains a `$temp` parameter: ```sql SELECT * FROM measurement WHERE temp > $temp ``` When executing a query, you specify parameter name-value pairs. The value that you assign to a parameter must be one of the [parameter data types](#parameter-data-types). ```go {"temp": 22.0} ``` The InfluxDB Querier parses the query text with the parameter placeholders, and then generates query plans that replace the placeholders with the values that you provide. This separation of query structure from input data ensures that input is treated as one of the allowed [data types](#parameter-data-types) and not as executable code. ## Parameter data types A parameter value can be one of the following data types: * Null * Boolean * Unsigned integer (`u_int64`) * Integer (`int64`) * Double (`float64`) * String ### Data type examples ```js { "string": "Living Room", "double": 3.14, "unsigned_integer": 1234, "integer": -1234, "boolean": false, "null": Null, } ``` ### Time expressions To parameterize time bounds, substitute a parameter for a timestamp literal–for example: ```sql SELECT * FROM home WHERE time >= $min_time ``` For the parameter value, specify the timestamp literal as a string–for example: ```go // Assign a timestamp string literal to the min_time parameter. parameters := influxdb3.QueryParameters{ "min_time": "2022-01-01 00:00:00.00", } ``` InfluxDB executes the query as the following: ```sql SELECT * FROM home WHERE time >= '2022-01-01 00:00:00.00' ``` ### Not compatible with parameters If you use parameters for the following, your query might not work as you expect: * In clauses other than `WHERE`, such as `SELECT` or `GROUP BY` * As function arguments, such as `avg($temp)` * In place of identifiers, such as column or table names * In place of duration literals, such as `INTERVAL $minutes` ## Parameterize an SQL query > [!Note] > #### Sample data > > The following examples use the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. To use a parameterized query, do the following: 1. In your query text, use the `$parameter` syntax to reference a parameter name–for example, the following query contains `$room` and `$min_temp` parameter placeholders: ``` SELECT * FROM home WHERE time > now() - INTERVAL '7 days' AND temp >= $min_temp AND room = $room ``` 2. Provide a value for each parameter name. If you don’t assign a value for a parameter, InfluxDB returns an error. The syntax for providing parameter values depends on the client you use–for example: [Go](#) ``` // Define a QueryParameters struct--a map of parameters to input values. parameters := influxdb3.QueryParameters{ "room": "Kitchen", "min_temp": 20.0, } ``` After InfluxDB receives your request and parses the query, it executes the query as ```sql SELECT * FROM home WHERE time > now() - INTERVAL '7 days' AND temp >= 20.0 AND room = 'Kitchen' ``` ## Execute parameterized SQL queries > [!Note] > #### Sample data > > The following examples use the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). > To run the example queries and return results,[write the sample data](/influxdb3/core/reference/sample-data/#write-the-home-sensor-data-to-influxdb)to your InfluxDB 3 Core database before running the example queries. ### Use the HTTP API InfluxDB 3 Core provides the `/api/v3/query_sql` HTTP API endpoint for executing SQL queries with parameters. ``` POST /api/v3/query_sql ``` Send a JSON object that contains `db` (database), `q` (query), and `params` (parameter name-value pairs) properties in the request body. The following example sends a parameterized SQL query to the `/api/v3/query_sql` endpoint: ```bash curl "http://localhost:8181/api/v3/query_sql" \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "db": "DATABASE_NAME", "q": "SELECT * FROM home WHERE time >= $min_time AND temp >= $min_temp AND room = $room", "params": { "min_time": "2022-01-01T08:00:00Z", "min_temp": 22.0, "room": "Kitchen" } }' ``` Replace the following: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: your [token](/influxdb3/core/admin/tokens/) The response body contains query results in JSON format: ```json [ {"co":0,"hum":36.2,"room":"Kitchen","temp":23.0,"time":"2022-01-01T09:00:00"}, {"co":0,"hum":36.1,"room":"Kitchen","temp":22.7,"time":"2022-01-01T10:00:00"}, {"co":0,"hum":36.0,"room":"Kitchen","temp":22.4,"time":"2022-01-01T11:00:00"}, {"co":0,"hum":36.0,"room":"Kitchen","temp":22.5,"time":"2022-01-01T12:00:00"} ] ``` ### Use InfluxDB Flight RPC clients Using the InfluxDB 3 native Flight RPC protocol and supported clients, you can send a parameterized query and a list of parameter name-value pairs. InfluxDB Flight clients that support parameterized queries pass the parameter name-value pairs in a Flight ticket `params` field. The following examples show how to use client libraries to execute parameterized SQL queries: [Go](#) ```go import ( "context" "fmt" "io" "os" "text/tabwriter" "time" "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters) error { url := os.Getenv("INFLUX_HOST") token := os.Getenv("INFLUX_TOKEN") database := os.Getenv("INFLUX_DATABASE") // Instantiate the influxdb3 client. client, err := influxdb3.New(influxdb3.ClientConfig{ Host: url, Token: token, Database: database, }) if err != nil { panic(err) } // Ensure the client is closed after the Query function finishes. defer func(client *influxdb3.Client) { err := client.Close() if err != nil { panic(err) } }(client) // Call the client's QueryWithParameters function. // Provide the query and parameters. The default QueryType is SQL. iterator, err := client.QueryWithParameters(context.Background(), query, parameters) // Create a buffer for storing rows as you process them. w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) w.Init(os.Stdout, 0, 8, 0, '\t', 0) fmt.Fprintf(w, "time\troom\tco\thum\ttemp\n") // Format and write each row to the buffer. // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) } w.Flush() return nil } func main() { // Use the $placeholder syntax in a query to reference parameter placeholders // for input data. // The following SQL query contains the placeholders $room and $min_temp. query := ` SELECT * FROM home WHERE time > now() - INTERVAL '7 days' AND temp >= $min_temp AND room = $room` // Define a QueryParameters struct--a map of placeholder names to input values. parameters := influxdb3.QueryParameters{ "room": "Kitchen", "min_temp": 20.0, } } ``` ## Client support for parameterized queries * Not all [InfluxDB 3 Flight clients](/influxdb3/core/reference/client-libraries/v3/) support parameterized queries. * InfluxDB doesn’t currently support parameterized queries or DataFusion prepared statements for Flight SQL or Flight SQL clients. * InfluxDB 3 SQL and InfluxQL parameterized queries aren’t supported in InfluxDB v1 and v2 clients. ## Not supported Currently, parameterized queries in InfluxDB 3 Core don’t provide the following: * support for DataFusion prepared statements * query caching, optimization, or performance benefits [query](/influxdb3/core/tags/query/)[security](/influxdb3/core/tags/security/)[sql](/influxdb3/core/tags/sql/) --- # InfluxDB 3 Core reference documentation Source: https://docs.influxdata.com/influxdb3/core/reference/ ### [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) InfluxDB 3 Core lets you customize your server configuration by using `influxdb3 serve` command options or by setting environment variables. ### [Command line tools](/influxdb3/core/reference/cli/) View command line tools used to manage and interact with InfluxDB 3 Core. ### [Line protocol reference](/influxdb3/core/reference/line-protocol/) InfluxDB 3 Core uses line protocol to write data points. It is a text-based format that provides the table, tag set, field set, and timestamp of a data point. ### [Processing engine reference](/influxdb3/core/reference/processing-engine/) The InfluxDB 3 Processing engine is an embedded Python virtual machine that runs inside InfluxDB 3 Core to execute Python code in response to triggers you define without requiring external application servers or middleware. ### [SQL reference documentation](/influxdb3/core/reference/sql/) Learn the SQL syntax and structure used to query InfluxDB. ### [InfluxQL reference documentation](/influxdb3/core/reference/influxql/) InfluxQL is an SQL-like query language for interacting with data in InfluxDB. ### [API client libraries](/influxdb3/core/reference/client-libraries/) InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. View the list of available client libraries. ### [InfluxDB 3 Core internals](/influxdb3/core/reference/internals/) Learn about InfluxDb 3 Core internal systems and mechanisms. ### [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/) Learn about naming restrictions and conventions for databases, tables, tags, fields, and other identifiers in InfluxDB 3 Core. ### [Usage telemetry](/influxdb3/core/reference/telemetry/) InfluxData collects telemetry data to help improve the InfluxDB 3 Core. Learn what data InfluxDB 3 Core collects and sends to InfluxData, how it’s used, and how you can opt out. ### [Glossary](/influxdb3/core/reference/glossary/) Terms related to InfluxData products and platforms. ### [Sample data](/influxdb3/core/reference/sample-data/) Sample datasets are used throughout the the InfluxDB 3 Core documentation to demonstrate functionality. Use the following sample datasets to replicate provided examples. ### [InfluxDB HTTP API](/influxdb3/core/reference/api/) The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for interactions with InfluxDB. --- # InfluxDB HTTP API Source: https://docs.influxdata.com/influxdb3/core/reference/api/ This page has moved to [InfluxDB HTTP API](/influxdb3/core/api/). --- # Command line tools Source: https://docs.influxdata.com/influxdb3/core/reference/cli/ View command line tools used to run, manage, and interact with InfluxDB 3 Core: ### [influxdb3](/influxdb3/core/reference/cli/influxdb3/) The `influxdb3` CLI runs and interacts with the InfluxDB 3 Core server. --- # influxdb3 CLI Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/ The `influxdb3` CLI runs and interacts with the InfluxDB 3 Core server. ## Usage ```bash influxdb3 [GLOBAL-OPTIONS] [COMMAND] ``` ## Commands | Command | Description | |-----------------------------------------------------------|------------------------------| | [create](/influxdb3/core/reference/cli/influxdb3/create/) | Create resources | | [debug](/influxdb3/core/reference/cli/influxdb3/debug/) | Diagnostic tools | | [delete](/influxdb3/core/reference/cli/influxdb3/delete/) | Delete resources | |[disable](/influxdb3/core/reference/cli/influxdb3/disable/)| Disable resources | | [enable](/influxdb3/core/reference/cli/influxdb3/enable/) | Enable resources | |[install](/influxdb3/core/reference/cli/influxdb3/install/)| Install plugins | | [query](/influxdb3/core/reference/cli/influxdb3/query/) | Query InfluxDB 3 Core | | [serve](/influxdb3/core/reference/cli/influxdb3/serve/) |Run the InfluxDB 3 Core server| | [show](/influxdb3/core/reference/cli/influxdb3/show/) | List resources | | [test](/influxdb3/core/reference/cli/influxdb3/test/) | Test plugins | | [update](/influxdb3/core/reference/cli/influxdb3/update/) | Update resources | | [write](/influxdb3/core/reference/cli/influxdb3/write/) | Write to InfluxDB 3 Core | ## Global options |Option| | Description | |------|------------|-----------------------------------------------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information including runtime configuration options| | `-V` |`--version` | Print version | For advanced global configuration options (including `--num-io-threads` and other runtime settings), see [Configuration options](/influxdb3/core/reference/config-options/#global-configuration-options). ## Quick-Start Mode For development, testing, and home use, you can start InfluxDB 3 Core by running `influxdb3` without the `serve` subcommand or any configuration parameters. The system automatically generates required values: * **`node-id`**: `{hostname}-node` (fallback: `primary-node`) * **`object-store`**: `file` * **`data-dir`**: `~/.influxdb` The system displays warning messages showing the auto-generated identifiers: ``` Using auto-generated node id: mylaptop-node. For production deployments, explicitly set --node-id ``` > [!Important] > #### Production deployments > > Quick-start mode is designed for development and testing environments. > For production deployments, use explicit configuration with the `serve` subcommand > and specify all required parameters as shown in the [Examples](#examples) below. **Configuration precedence**: CLI flags \> environment variables \> auto-generated defaults For more information about quick-start mode, see [Get started](/influxdb3/core/get-started/setup/#quick-start-mode-development). ## Examples In the examples below, replace`my-host-01`: with a unique identifier for your InfluxDB 3 Core server. ### Quick-start InfluxDB 3 server ```bash # Zero-config startup influxdb3 # Override specific defaults influxdb3 --object-store memory # Use environment variables to override defaults INFLUXDB3_NODE_ID=my-node influxdb3 ``` ### Run the InfluxDB 3 server ```bash influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 ``` ### Run the InfluxDB 3 server with custom IO threads ```bash influxdb3 --num-io-threads=8 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 ``` ### Display short-form help for all commands ```bash influxdb3 -h ``` ### Display long-form help for all commands ```bash influxdb3 --help ``` ### Run the InfluxDB 3 Core server with extra verbose logging ```bash influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 \ --verbose ``` ### Run InfluxDB 3 Core with debug logging using LOG\_FILTER ```bash LOG_FILTER=debug influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 ``` | Command | Description | | --- | --- | | Command | Description | | create | Create resources | | debug | Diagnostic tools | | delete | Delete resources | | disable | Disable resources | | enable | Enable resources | | install | Install plugins | | query | Query InfluxDB 3 Core | | serve | Run the InfluxDB 3 Core server | | show | List resources | | test | Test plugins | | update | Update resources | | write | Write to InfluxDB 3 Core | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information including runtime configuration options | | -V | --version | Print version | --- # influxdb3 create Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/ The `influxdb3 create` command creates a resource such as a database or authentication token. ## Usage ```bash influxdb3 create ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------------------------|----------------------------------------------| | [database](/influxdb3/core/reference/cli/influxdb3/create/database/) | Create a new database | | [last\_cache](/influxdb3/core/reference/cli/influxdb3/create/last_cache/) | Create a new last value cache | |[distinct\_cache](/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/)| Create a new distinct value cache | | [table](/influxdb3/core/reference/cli/influxdb3/create/table/) | Create a new table in a database | | [token](/influxdb3/core/reference/cli/influxdb3/create/token/) | Create a new authentication token | | [trigger](/influxdb3/core/reference/cli/influxdb3/create/trigger/) |Create a new trigger for the processing engine| | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | database | Create a new database | | last_cache | Create a new last value cache | | distinct_cache | Create a new distinct value cache | | table | Create a new table in a database | | token | Create a new authentication token | | trigger | Create a new trigger for the processing engine | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 create database Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/database/ The `influxdb3 create database` command creates a new database in your InfluxDB 3 Core instance. Provide a database name and, optionally, specify connection settings and authentication credentials using flags or environment variables. ## Usage ```bash # Syntax influxdb3 create database [OPTIONS] ``` ## Arguments * **`DATABASE_NAME`**: The name of the database to create. Valid database names are alphanumeric and start with a letter or number. Dashes (-) and underscores (\_) are allowed. You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environment variable. ## Options |Option| | Description | |------|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | |`--retention-period`|Database [retention period](/influxdb3/core/reference/glossary/#retention-period) ([duration](/influxdb3/core/reference/glossary/#duration) value, for example: `30d`, `24h`, `1h`)| | | `--token` | Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | `--tls-no-verify` | Disable TLS certificate verification. **Not recommended in production.** Useful for testing with self-signed certificates | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables instead of providing CLI options directly: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples The following examples show how to create a database. In the examples below, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token ### Create a database (default) Creates a database using settings from environment variables and defaults. ```bash influxdb3 create database DATABASE_NAME ``` ### Create a database with an authentication token Creates a database using the specified arguments. Flags override their associated environment variables. ```bash influxdb3 create database --token AUTH_TOKEN DATABASE_NAME ``` ### Create a database with a retention period Creates a database with a 30-day retention period. Data older than 30 days will not be queryable. ```bash influxdb3 create database --retention-period 30d DATABASE_NAME ``` ### Create a database with infinite retention Creates a database with no retention period (data never expires). ```bash influxdb3 create database --retention-period none DATABASE_NAME ``` ### Create a database with a 90-day retention period Creates a database with a 90-day retention period using an authentication token. ```bash influxdb3 create database \ --retention-period 90d \ --token AUTH_TOKEN \ DATABASE_NAME ``` ### Create a database with a 1-year retention period Creates a database with a 1-year retention period. ```bash influxdb3 create database --retention-period 1y DATABASE_NAME ``` ### Create a database with a combined duration Creates a database with a retention period of 30 days and 12 hours. ```bash influxdb3 create database --retention-period 30d12h DATABASE_NAME ``` ## Retention period duration formats Retention periods are specified as [duration](/influxdb3/core/reference/glossary/#duration)values using a numeric value plus a duration unit. ### Valid duration units |Unit| Description | |----|---------------| |`h` | hour | |`d` | day | |`w` | week | |`mo`|month (30 days)| |`y` |year (365 days)| > [!Note] > Minute (`m`) and second (`s`) units are not supported for retention periods. > [!Warning] > #### Retention period constraints > > * **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). > * **Zero-duration periods**: Setting a retention period to `0` (for example,`0d` or `0h`) is allowed but marks all data for immediate deletion at query time.*This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention.* > * **Infinite retention**: Use `none` to set an infinite retention period. ### Example duration values * `1h` - 1 hour * `24h` - 24 hours * `7d` - 7 days * `4w` - 4 weeks * `30d` - 30 days * `1mo` - 1 month (30 days) * `90d` - 90 days * `1y` - 1 year (365 days) * `none` - infinite (data never expires) You can combine units: `30d12h` (30.5 days), `1y6mo` (545 days) For complete details about retention periods, see[Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/). #### Related * [Create a database](/influxdb3/core/admin/databases/create/) * [Create database API](/influxdb3/core/api/database/#operation/PostConfigureDatabase) * [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/) | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --retention-period | Database retention period ( duration value, for example: 30d , 24h , 1h ) | | | --token | Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification. Not recommended in production. Useful for testing with self-signed certificates | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | | Unit | Description | | --- | --- | | Unit | Description | | h | hour | | d | day | | w | week | | mo | month (30 days) | | y | year (365 days) | --- # influxdb3 create distinct_cache Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/ The `influxdb3 create distinct_cache` command creates a new distinct value cache for a specific table and column set in your InfluxDB 3 Core instance. Use this command to configure a cache that tracks unique values in specified columns. You must provide the database, token, table, and columns. Optionally, you can specify a name for the cache. ## Usage ```bash influxdb3 create distinct_cache [OPTIONS] \ --database \ --token --table
\ --columns \ [CACHE_NAME] ``` ## Arguments * **`CACHE_NAME`**: *(Optional)* A name to assign to the cache. If omitted, the CLI generates a name automatically. ## Options |Option| | Description | |------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-t` | `--table` | *(Required)* Table to create the cache for | | | `--columns` |*(Required)* Comma-separated list of columns to cache distinct values for–for example: `col1,col2,col3` (see [Metadata cache hierarchy](#metadata-cache-hierarchy))| | |`--max-cardinality`| Maximum number of distinct value combinations to hold in the cache | | | `--max-age` | Maximum age of an entry in the cache entered as a human-readable duration–for example: `30d`, `24h` | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | `--tls-no-verify` | Disable TLS certificate verification. **Not recommended in production.** Useful for testing with self-signed certificates | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | > [!Important] > #### Metadata cache hierarchy > > The distinct value cache has a hierarchical structure with a level for each specified column. > The order specified in the `--columns` option determines the order of levels, > from top-to-bottom, of the cache hierarchy. ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Prerequisites Before creating a distinct value cache, make sure you: 1. [Create a database](/influxdb3/core/reference/cli/influxdb3/create/database/) 2. [Create a table](/influxdb3/core/reference/cli/influxdb3/create/table/) that includes the columns you want to cache 3. Have a valid authentication token ## Examples Before running the following commands, replace the placeholder values with your own: * `DATABASE_NAME`: The database name * `TABLE_NAME`: The name of the table to cache values from * `CACHE_NAME`: The name of the distinct value cache to create * `COLUMN_NAME`: The column to cache distinct values from You can also set environment variables (such as `INFLUXDB3_AUTH_TOKEN`) instead of passing options inline. ### Create a distinct cache for one column Track unique values from a single column. This setup is useful for testing or simple use cases. ```bash influxdb3 create distinct_cache \ --database DATABASE_NAME \ --table TABLE_NAME \ --column COLUMN_NAME \ CACHE_NAME ``` ### Create a hierarchical cache with constraints Create a distinct value cache for multiple columns. The following example tracks unique combinations of `room` and `sensor_id`, and sets limits on the number of entries and their maximum age. ```bash influxdb3 create distinct_cache \ --database my_test_db \ --table my_sensor_table \ --columns room,sensor_id \ --max-cardinality 1000 \ --max-age 30d \ my_sensor_distinct_cache ``` ## Common pitfalls * `--column` is not valid. Use `--columns`. * Tokens must be included explicitly unless set via `INFLUXDB3_AUTH_TOKEN` * Table and column names must already exist or be recognized by the engine | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -t | --table | ( Required ) Table to create the cache for | | | --columns | ( Required ) Comma-separated list of columns to cache distinct values for–for example: col1,col2,col3 (see Metadata cache hierarchy ) | | | --max-cardinality | Maximum number of distinct value combinations to hold in the cache | | | --max-age | Maximum age of an entry in the cache entered as a human-readable duration–for example: 30d , 24h | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification. Not recommended in production. Useful for testing with self-signed certificates | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 create last_cache Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/last_cache/ The `influxdb3 create last_cache` command creates a last value cache, which stores the most recent values for specified columns in a table. Use this to efficiently retrieve the latest values based on key column combinations. ## Usage ```bash influxdb3 create last_cache [OPTIONS] \ --database DATABASE_NAME \ --table TABLE_NAME \ --token AUTH_TOKEN \ CACHE_NAME ``` ## Arguments * **CACHE\_NAME**: *(Optional)* Name for the cache. If omitted, InfluxDB automatically generates one. ## Options |Option| | Description | |------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-t` | `--table` | *(Required)* Table to create the cache for | | | `--key-columns` | Comma-separated list of columns to use as keys in the cache–for example: `foo,bar,baz` | | |`--value-columns`| Comma-separated list of columns to store as values in the cache–for example: `foo,bar,baz` | | | `--count` | Number of entries per unique key column combination to store in the cache (default `1`) | | | `--ttl` |Cache entries’ time-to-live (TTL) in [Humantime form](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)–for example: `10s`, `1min 30sec`, `3 hours` (default `4 hours`)| | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`| Disable TLS certificate verification. **Not recommended in production.** Useful for testing with self-signed certificates | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables as substitutes for CLI options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Prerequisites Before creating a last value cache, ensure you’ve done the following: * Create a [database](/influxdb3/core/reference/cli/influxdb3/create/database/). * Create a [table](/influxdb3/core/reference/cli/influxdb3/create/table/) with the columns you want to cache. * Have a valid authentication token. ## Examples A last value cache stores the most recent values from specified columns in a table. ### Create a basic last value cache for one column The following example shows how to track the most recent value for a single key (the last temperature for each room): ```bash influxdb3 create last_cache \ --database DATABASE_NAME \ --table my_sensor_table \ --token AUTH_TOKEN \ --key-columns room \ --value-columns temp \ my_temp_cache ``` ### Create a last value cache with multiple keys and values The following example shows how to: * Use multiple columns as a composite key * Track several values per key combination * Set a cache entry limit with `--count` * Configure automatic expiry with `--ttl` ```bash influxdb3 create last_cache \ --database DATABASE_NAME \ --table my_sensor_table \ --token AUTH_TOKEN \ --key-columns room,sensor_id \ --value-columns temp,hum \ --count 10 \ --ttl 1h \ my_sensor_cache ``` ## Usage notes * Define the table schema to include all specified key and value columns. * Pass tokens using `--token`, unless you’ve set one through an environment variable. * Specify `--count` and `--ttl` to override the defaults; otherwise, the system uses default values. | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -t | --table | ( Required ) Table to create the cache for | | | --key-columns | Comma-separated list of columns to use as keys in the cache–for example: foo,bar,baz | | | --value-columns | Comma-separated list of columns to store as values in the cache–for example: foo,bar,baz | | | --count | Number of entries per unique key column combination to store in the cache (default 1 ) | | | --ttl | Cache entries’ time-to-live (TTL) in Humantime form –for example: 10s , 1min 30sec , 3 hours (default 4 hours ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification. Not recommended in production. Useful for testing with self-signed certificates | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 create table Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/table/ The `influxdb3 create table` command creates a new table in a specified database. Tables must include at least one tag column and can optionally include field columns with defined data types. > [!Note] > InfluxDB automatically creates tables when you write line protocol data. Use this command > only if you need to define a custom schema or apply a custom partition template before > writing data. ## Usage ```bash # Syntax influxdb3 create table [OPTIONS] \ --tags [...] \ --database \ --token \ ``` ## Arguments * **TABLE\_NAME**: The name of the table to create. ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | | `--tags` | *(Required)* Comma-separated list of tag columns to include in the table | | | `--fields` | Comma-separated list of field columns and their types to include in the table | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | > [!Important] > #### Tag and field naming requirements > > Tag and field keys are alphanumeric and must start with a letter or number. > They can contain dashes (`-`) and underscores (`_`). ### Option environment variables You can use the following environment variables to set options instead of passing them via CLI flags: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples In the examples below, replace the following: * `DATABASE_NAME`: The database name * `AUTH_TOKEN`: The authentication token * `TABLE_NAME`: A name for the new table ### Create an empty table ```bash influxdb3 create table \ --tags tag1,tag2,tag3 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME ``` ### Create a table with tag and field columns ```bash influxdb3 create table \ --tags room,sensor_id \ --fields temp:float64,hum:float64,co:int64 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME ``` ### Verification Use the `SHOW TABLES` query to verify that the table was created successfully: ```bash influxdb3 query \ --database my_test_db \ --token AUTH_TOKEN \ "SHOW TABLES" Example output: +---------------+--------------------+----------------------------+------------+ | table_catalog | table_schema | table_name | table_type | +---------------+--------------------+----------------------------+------------+ | public | iox | my_sensor_table | BASE TABLE | | public | system | distinct_caches | BASE TABLE | | public | system | last_caches | BASE TABLE | | public | system | parquet_files | BASE TABLE | +---------------+--------------------+----------------------------+------------+ ``` > [!Note] > `SHOW TABLES` is an SQL query. It isn’t supported in InfluxQL. | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | | --tags | ( Required ) Comma-separated list of tag columns to include in the table | | | --fields | Comma-separated list of field columns and their types to include in the table | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 create token Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/token/ The `influxdb3 create token` command creates a new authentication token. This returns the raw token string. Use it to authenticate future CLI commands and API requests. > [!Important] > InfluxDB displays the raw token string only once. Be sure to copy and securely store it. ## Usage ```bash influxdb3 create token ``` ## Commands | Command | Description | | |------------------------------------------------------------------------|-----------------------------------------------------------------------|---| |[`--admin`](/influxdb3/core/reference/cli/influxdb3/create/token/admin/)|Create an operator or named admin token for the InfluxDB 3 Core server.| | ## Options |Option| | Description | |------|------------|-------------------------------| | | `--admin` | Create an admin token | | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Command | Description | | | --- | --- | --- | | Command | Description | | | --admin | Create an operator or named admin token for the InfluxDB 3 Core server. | | | Option | | Description | | --- | --- | --- | | Option | | Description | | | --admin | Create an admin token | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 create token --admin Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/token/admin/ Create an operator token or named admin token. ## Usage ``` influxdb3 create token --admin [OPTIONS] ``` ## Options | Option | Description | |---------------|-------------------------------------------------------------------------------------------------------------| |`--regenerate` | Regenerates the operator token. Requires `--token` and the current operator token | | `--name` | Name of the token | | `--expiry` | Expires in `duration`–for example, 10d for 10 days 1y for 1 year | | `--host` |The host URL of the running InfluxDB 3 server [env: `INFLUXDB3_HOST_URL=`] [default: `http://127.0.0.1:8181`]| | `--token` | An existing admin token for the InfluxDB 3 server | | `--tls-ca` | An optional arg to use a custom ca for useful for testing with self signed certs | | `--format` | Output format for token [possible values: `json`, `text`] | | `--offline` | Generate token without connecting to server (for automation) | |`--output-file`| File path to save the token (required with `--offline`) | |`-h`, `--help` | Print help information | | `--help-all` | Print more detailed help information | ## Examples * [Create an operator token](#create-an-operator-token) * [Use the operator token to create a named admin token](#use-the-operator-token-to-create-a-named-admin-token) * [Use the token to create a database](#use-the-token-to-create-a-database) * [Generate an offline admin token](#generate-an-offline-admin-token) ### Create an operator token The operator token is a special token that has full administrative privileges on the InfluxDB server and doesn’t expire. The first admin token you create becomes the operator token for the instance. You can create an operator token using the `--admin` flag without any additional options. ```bash influxdb3 create token --admin ``` The output is the raw token string you can use to authenticate future CLI commands and API requests. For CLI commands, use the `--token` option or the `INFLUXDB3_AUTH_TOKEN` environment variable to pass the token string. ### Use the operator token to create a named admin token ```bash influxdb3 create token \ --admin \ --token OPERATOR_TOKEN \ --name TOKEN_NAME \ --expiry DURATION ``` Replace the following: * `OPERATOR_TOKEN`: Your operator token for the server * `TOKEN_NAME`: Name for your new admin token * `DURATION`: Duration for the token to remain valid, in [humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format (for example, `10d` for 10 days or `1y` for 1 year). ### Use the token to create a database ```bash influxdb3 create database \ --token ADMIN_TOKEN \ DATABASE_NAME ``` Replace the following: * `ADMIN_TOKEN`: Your InfluxDB admin token * `DATABASE_NAME`: Name for your new database > [!Note] > #### Use CLI environment variables > > Set the token as an environment variable to simplify repeated CLI commands: > > ``` > export INFLUXDB3_AUTH_TOKEN=ADMIN_TOKEN > ``` ### Generate an offline admin token Generate an offline admin token file to use if no tokens exist when the server starts. Once started, you can interact with the server using the provided token. Offline admin tokens are designed to help with automated deployments. Include the following options: * `--offline` *(Required)* * `--output-file` *(Required)* * `--name` *(default is `_admin`)* * `--expiry` *(Optional)* ```bash influxdb3 create token --admin \ --name TOKEN_NAME \ --expiry DURATION \ --offline \ --output-file path/to/admin-token.json ``` Replace the following: * `TOKEN_NAME`: Name for your offline admin token * `DURATION`: Duration for the token to remain valid, in [humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format (for example, `10d` for 10 days or `1y` for 1 year). * `path/to/admin-token.json`: File path to use for the generated token file [](#view-example-offline-admin-token-file) View example offline admin token file ```json { "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...", "name": "example-admin-token", "expiry_millis": 1756400061529 } ``` | Option | Description | | --- | --- | | Option | Description | | --regenerate | Regenerates the operator token. Requires --token and the current operator token | | --name | Name of the token | | --expiry | Expires in duration –for example, 10d for 10 days 1y for 1 year | | --host | The host URL of the running InfluxDB 3 server [env: INFLUXDB3_HOST_URL= ] [default: http://127.0.0.1:8181 ] | | --token | An existing admin token for the InfluxDB 3 server | | --tls-ca | An optional arg to use a custom ca for useful for testing with self signed certs | | --format | Output format for token [possible values: json , text ] | | --offline | Generate token without connecting to server (for automation) | | --output-file | File path to save the token (required with --offline ) | | -h , --help | Print help information | | --help-all | Print more detailed help information | --- # influxdb3 create trigger Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/trigger/ The `influxdb3 create trigger` command creates a new trigger for the processing engine. ## Usage ```bash # Syntax influxdb3 create trigger [OPTIONS] \ --database \ --token \ --plugin-filename \ --trigger-spec \ ``` ## Arguments * **TRIGGER\_NAME**: A name for the new trigger. ## Options |Option| | Description | |------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-p` | `--path` |Path to plugin file or directory (single `.py` file or directory containing `__init__.py` for multifile plugins). Can be local path (with `--upload`) or server path. Replaces `--plugin-filename`.| | | `--upload` | Upload local plugin files to the server. Requires admin token. Use with `--path` to specify local files. | | | `--plugin-filename` | *(Deprecated: use `--path` instead)* Name of the file, stored in the server’s `plugin-dir`, that contains the Python plugin code to run | | | `--trigger-spec` | Trigger specification: `table:`, `all_tables`, `every:`, `cron:`, or `request:` | | |`--trigger-arguments`| Additional arguments for the trigger, in the format `key=value`, separated by commas (for example, `arg1=val1,arg2=val2`) | | | `--disabled` | Create the trigger in disabled state | | | `--error-behavior` | Error handling behavior: `log`, `retry`, or `disable` | | |`--run-asynchronous` | Run the trigger asynchronously, allowing multiple triggers to run simultaneously (default is synchronous) | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | `--tls-no-verify` | Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Reference a plugin from GitHub To fetch a plugin remotely instead of downloading it locally, prefix the plugin path with `gh:`. The path after the prefix is appended to the configured `--plugin-repo`–for example: ``` gh:examples/wal_plugin/wal_plugin.py ``` Despite the name, `gh:` doesn’t require GitHub or a Git repository–`--plugin-repo` accepts any HTTP/HTTPS URL that serves raw plugin files. By default, `gh:`-prefixed plugins resolve against the [`influxdata/influxdb3_plugins`](https://github.com/influxdata/influxdb3_plugins) repository at `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/`. For example, `gh:examples/wal_plugin/wal_plugin.py` resolves to `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/examples/wal_plugin/wal_plugin.py`. To reference plugins from a different repository, set the `--plugin-repo` server option (or the `INFLUXDB3_PLUGIN_REPO` environment variable) to a raw content URL base path. For more information, see the [`plugin-repo` config option](/influxdb3/core/reference/config-options/#plugin-repo). InfluxDB fetches the plugin over HTTP when the trigger is created (to validate it), and again each time the trigger starts–for example, on server startup or when re-enabled. If the fetch fails, `influxdb3 create trigger` returns an error with the HTTP status code and URL: ``` error fetching plugin from repository: 404 Not Found https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/not_found.py ``` Unlike local plugins, `gh:`-prefixed plugins aren’t automatically reloaded when the source changes–disable and re-enable the trigger to fetch updates. Only single-file plugins are supported with the `gh:` prefix; multi-file plugin directories must be uploaded locally with `--upload`. ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples The following examples show how to use the `influxdb3 create trigger` command to create triggers in different scenarios. * [Create a trigger for a specific table](#create-a-trigger-for-a-specific-table) * [Create a trigger for all tables](#create-a-trigger-for-all-tables) * [Create a trigger with a schedule](#create-a-trigger-with-a-schedule) * [Create a trigger for HTTP requests](#create-a-trigger-for-http-requests) * [Create a trigger with a multifile plugin](#create-a-trigger-with-a-multifile-plugin) * [Upload and create a trigger with a local plugin](#upload-and-create-a-trigger-with-a-local-plugin) * [Create a trigger with additional arguments](#create-a-trigger-with-additional-arguments) * [Create a disabled trigger](#create-a-disabled-trigger) * [Create a trigger with error handling](#create-a-trigger-with-error-handling) Replace the following placeholders with your values: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `PLUGIN_FILENAME`: Python plugin filename * `TRIGGER_NAME`: Name of the trigger to create * `TABLE_NAME`: Name of the table to trigger on ### Create a trigger for a specific table Create a trigger that processes data from a specific table. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename PLUGIN_FILENAME \ --trigger-spec table:TABLE_NAME \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/core/plugins/#create-a-data-write-plugin) interface. ### Create a trigger for all tables Create a trigger that applies to all tables in the specified database. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec all_tables \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/core/plugins/#create-a-data-write-plugin) interface. This is useful when you want a trigger to apply to any table in the database, regardless of name. ### Create a trigger with a schedule Create a trigger that runs at a specific interval using a duration. Supported duration units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years). Maximum interval is 1 year. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec every:5m \ TRIGGER_NAME ``` Create a trigger that runs based on a cron schedule using extended 6-field cron format. The cron expression follows the format: ``` second minute hour day_of_month month day_of_week ``` Fields: * **second**: 0-59 * **minute**: 0-59 * **hour**: 0-23 * **day\_of\_month**: 1-31 * **month**: 1-12 or JAN-DEC * **day\_of\_week**: 0-7 (0 or 7 is Sunday) or SUN-SAT Example: Run at 6:00 AM every weekday (Monday-Friday): ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec "cron:0 0 6 * * 1-5" \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [scheduled plugin](/influxdb3/core/plugins/#create-a-scheduled-plugin) interface. ### Create a trigger for HTTP requests Create a trigger that provides an API endpoint and processes HTTP requests. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename PLUGIN_FILENAME \ --trigger-spec request:REQUEST_PATH \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [HTTP request plugin](/influxdb3/core/plugins/#create-an-http-request-plugin) interface. ### Create a trigger with a multifile plugin Create a trigger using a plugin organized in multiple files. The plugin directory must contain an `__init__.py` file. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "my_complex_plugin" \ --trigger-spec "every:5m" \ TRIGGER_NAME ``` The `--path` points to a directory in the server’s `plugin-dir` with the following structure: ``` my_complex_plugin/ ├── __init__.py # Required entry point ├── processors.py # Supporting modules └── utils.py ``` For more information about multifile plugins, see [Create your plugin file](/influxdb3/core/plugins/#create-your-plugin-file). ### Upload and create a trigger with a local plugin Upload plugin files from your local machine and create a trigger in a single command. Requires admin token. ```bash # Upload single-file plugin influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "/local/path/to/plugin.py" \ --upload \ --trigger-spec "every:1m" \ TRIGGER_NAME # Upload multifile plugin directory influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "/local/path/to/plugin-dir" \ --upload \ --trigger-spec "table:TABLE_NAME" \ TRIGGER_NAME ``` The `--upload` flag transfers local files to the server’s plugin directory. This is useful for: * Local plugin development and testing * Deploying plugins without SSH access * Automating plugin deployment For more information, see [Upload plugins from local machine](/influxdb3/core/plugins/#upload-plugins-from-local-machine). ### Create a trigger with additional arguments ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --trigger-arguments arg1=value1,arg2=value2 \ TRIGGER_NAME ``` ### Create a disabled trigger Create a trigger in a disabled state. ```bash influxdb3 create trigger \ --disabled \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ TRIGGER_NAME ``` Creating a trigger in a disabled state prevents it from running immediately. You can enable it later when you’re ready to activate it. ### Create a trigger with error handling Log the error to the service output and the `system.processing_engine_logs` table: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior log \ TRIGGER_NAME ``` Rerun the trigger if it fails: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior retry \ TRIGGER_NAME ``` Disable the trigger if it fails: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior disable \ TRIGGER_NAME ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -p | --path | Path to plugin file or directory (single .py file or directory containing __init__.py for multifile plugins). Can be local path (with --upload ) or server path. Replaces --plugin-filename . | | | --upload | Upload local plugin files to the server. Requires admin token. Use with --path to specify local files. | | | --plugin-filename | (Deprecated: use --path instead) Name of the file, stored in the server’s plugin-dir , that contains the Python plugin code to run | | | --trigger-spec | Trigger specification: table: , all_tables , every: , cron: , or request: | | | --trigger-arguments | Additional arguments for the trigger, in the format key=value , separated by commas (for example, arg1=val1,arg2=val2 ) | | | --disabled | Create the trigger in disabled state | | | --error-behavior | Error handling behavior: log , retry , or disable | | | --run-asynchronous | Run the trigger asynchronously, allowing multiple triggers to run simultaneously (default is synchronous) | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 debug Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/debug/ The `influxdb3 debug` command includes diagnostic tools for troubleshooting your InfluxDB 3 Core deployment. ## Usage ```bash influxdb3 debug ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------------------------------|----------------------------------------------| |[object-store-check](/influxdb3/core/reference/cli/influxdb3/debug/object-store-check/)| Validate object store compatibility | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | object-store-check | Validate object store compatibility | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 debug object-store-check Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/debug/object-store-check/ The `influxdb3 debug object-store-check` command validates that an object store correctly implements the semantic operations that InfluxDB 3 Core relies on. It writes synthetic test objects to `/oscheck-/` and reports any compatibility violations. This command connects directly to the object store and does not require a running InfluxDB 3 Core server. ## Usage ```bash influxdb3 debug object-store-check [OPTIONS] ``` ## Options |Option| | Description |Required| |------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|--------| | | `--object-store ` | Object store type. Valid values: `s3`, `google`, `azure`, `file`, `memory` | Yes | | | `--bucket ` | Object store bucket name. Required for `s3`, `google`, and `azure` object store types. | Varies | | | `--aws-endpoint ` | Custom AWS or S3-compatible endpoint URL | No | | | `--aws-access-key-id ` | AWS access key ID | No | | |`--aws-secret-access-key `| AWS secret access key | No | | | `--aws-allow-http` | Allow non-HTTPS connections to the object store | No | | | `--aws-default-region ` | AWS region | No | | | `--check-prefix ` | Prefix for synthetic test objects. The command writes to `/oscheck-/`. | No | | | `--probe-prefix ` |Read-only prefix to replay catalog loader operations against. Use this option to diagnose failures with an existing catalog without writing new data.| No | | `-h` | `--help` | Print help information | No | | | `--help-all` | Print detailed help information | No | ## Examples ### Check a MinIO (S3-compatible) object store Replace the following: * `MINIO_USERNAME`: your MinIO username * `MINIO_PASSWORD`: your MinIO password ```bash influxdb3 debug object-store-check \ --object-store s3 \ --bucket influxdb3 \ --aws-endpoint http://localhost:9000 \ --aws-access-key-id MINIO_USERNAME \ --aws-secret-access-key MINIO_PASSWORD \ --aws-allow-http \ --check-prefix oscheck ``` ### Probe an existing catalog prefix (read-only) Use `--probe-prefix` with your actual cluster ID to diagnose catalog load failures without writing any data to the object store. ```bash influxdb3 debug object-store-check \ --object-store s3 \ --bucket influxdb3 \ --aws-endpoint http://localhost:9000 \ --aws-access-key-id MINIO_USERNAME \ --aws-secret-access-key MINIO_PASSWORD \ --aws-allow-http \ --probe-prefix my-cluster-id ``` | Option | | Description | Required | | --- | --- | --- | --- | | Option | | Description | Required | | | --object-store | Object store type. Valid values: s3 , google , azure , file , memory | Yes | | | --bucket | Object store bucket name. Required for s3 , google , and azure object store types. | Varies | | | --aws-endpoint | Custom AWS or S3-compatible endpoint URL | No | | | --aws-access-key-id | AWS access key ID | No | | | --aws-secret-access-key | AWS secret access key | No | | | --aws-allow-http | Allow non-HTTPS connections to the object store | No | | | --aws-default-region | AWS region | No | | | --check-prefix | Prefix for synthetic test objects. The command writes to /oscheck-/ . | No | | | --probe-prefix | Read-only prefix to replay catalog loader operations against. Use this option to diagnose failures with an existing catalog without writing new data. | No | | -h | --help | Print help information | No | | | --help-all | Print detailed help information | No | --- # influxdb3 delete Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/ The `influxdb3 delete` command deletes a resource such as a cache, a database, or a table. ## Usage ```bash influxdb3 delete ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------------------------|----------------------------------------------| | [database](/influxdb3/core/reference/cli/influxdb3/delete/database/) | Delete a database | | [last\_cache](/influxdb3/core/reference/cli/influxdb3/delete/last_cache/) | Delete a last value cache | |[distinct\_cache](/influxdb3/core/reference/cli/influxdb3/delete/distinct_cache/)| Delete a metadata cache | | [table](/influxdb3/core/reference/cli/influxdb3/delete/table/) | Delete a table from a database | | [token](/influxdb3/core/reference/cli/influxdb3/delete/token/) |Delete an authorization token from the server | | [trigger](/influxdb3/core/reference/cli/influxdb3/delete/trigger/) | Delete a trigger for the processing engine | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | database | Delete a database | | last_cache | Delete a last value cache | | distinct_cache | Delete a metadata cache | | table | Delete a table from a database | | token | Delete an authorization token from the server | | trigger | Delete a trigger for the processing engine | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 delete database Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/database/ The `influxdb3 delete database` command deletes a database. ## Usage ```bash # Syntax influxdb3 delete database [OPTIONS] ``` ## Arguments * **DATABASE\_NAME**: The name of the database to delete. Valid database names are alphanumeric and start with a letter or number. Dashes (`-`) and underscores (`_`) are allowed. Environment variable: `INFLUXDB3_DATABASE_NAME` ## Options |Option| | Description | |------|-----------------|--------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | | `--hard-delete` |When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery| | | `--token` | Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Delete a database](#delete-a-database) * [Delete a database while specifying the token inline](#delete-a-database-while-specifying-the-token-inline) * [Hard delete a database immediately](#hard-delete-a-database-immediately) * [Hard delete a database at a specific time](#hard-delete-a-database-at-a-specific-time) In the examples below, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token ### Delete a database ```bash influxdb3 delete database DATABASE_NAME ``` ### Delete a database while specifying the token inline ```bash influxdb3 delete database --token AUTH_TOKEN DATABASE_NAME ``` ### Hard delete a database immediately Permanently delete a database and all its data immediately without the ability to recover. ```bash influxdb3 delete database --hard-delete now DATABASE_NAME ``` ### Hard delete a database at a specific time Schedule a database for permanent deletion at a specific timestamp. ```bash influxdb3 delete database --hard-delete "2024-01-01T00:00:00Z" DATABASE_NAME ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --hard-delete | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery | | | --token | Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 delete distinct_cache Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/distinct_cache/ The `influxdb3 delete distinct_cache` command deletes a distinct value cache. ## Usage ```bash influxdb3 delete distinct_cache [OPTIONS] \ --database \ --table
\ [CACHE_NAME] ``` ## Arguments * **CACHE\_NAME**: *(Optional)* Name of the cache to delete. ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-t` | `--table` | *(Required)* Table to delete the cache for | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples ### Delete a distinct value cache ```bash influxdb3 delete distinct_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ CACHE_NAME ``` In the example above, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `TABLE_NAME`: Table name * `CACHE_NAME`: Name of the distinct value cache to delete | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -t | --table | ( Required ) Table to delete the cache for | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 delete last_cache Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/last_cache/ The `influxdb3 delete last_cache` command deletes a last value cache. ## Usage ```bash influxdb3 delete last_cache [OPTIONS] --database --table
[CACHE_NAME] ``` ## Arguments * **CACHE\_NAME**: *(Optional)* Name of the cache to delete. ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-t` | `--table` | *(Required)* Table to delete the cache from | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples ### Delete a last value cache ```bash influxdb3 delete last_cache \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --table TABLE_NAME \ CACHE_NAME ``` In the example above, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `TABLE_NAME`: Table name * `CACHE_NAME`: Name of the last value cache to delete | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -t | --table | ( Required ) Table to delete the cache from | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 delete table Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/table/ The `influxdb3 delete table` command deletes a table from a database. ## Usage ```bash # Syntax influxdb3 delete table [OPTIONS] --database ``` ## Arguments * **TABLE\_NAME**: The name of the table to delete. ## Options |Option| | Description | |------|-----------------|--------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--hard-delete` |When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery| | | `--token` | *(Required)* Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples In the examples below, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `TABLE_NAME`: Name of the table to delete ### Delete a table ```bash influxdb3 delete table \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TABLE_NAME ``` ### Hard delete a table immediately Permanently delete a table and all its data immediately without the ability to recover. ```bash influxdb3 delete table \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --hard-delete now \ TABLE_NAME ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --hard-delete | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery | | | --token | ( Required ) Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 delete token Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/token/ The `influxdb3 delete token` command deletes an authorization token from the InfluxDB 3 Core server. ## Usage ```bash # Syntax influxdb3 delete token [OPTIONS] ``` ## Options | Option | Description |Default| Environment | |-----------------|-------------------------------------------------------------------------------------------------------------|-------|-------------------------| | `--token` | *(Required)* The token for authentication with the InfluxDB 3 Core server | | `INFLUXDB3_AUTH_TOKEN` | | `--token-name` | *(Required)* The name of the token to be deleted | | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | `INFLUXDB3_TLS_CA` | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| |`INFLUXDB3_TLS_NO_VERIFY`| | `-h`, `--help` | Print help information | | | | `--help-all` | Print detailed help information | | | ## Examples In the examples below, replace the following: * `AUTH_TOKEN`: Authentication token with permission to delete tokens * `TOKEN_TO_DELETE`: Name of the token to delete ### Delete a token by name ```bash influxdb3 delete token --token-name TOKEN_TO_DELETE --token AUTH_TOKEN ``` ### Show help for the command ```bash influxdb3 delete token --help ``` #### Related * [Manage tokens](/influxdb3/core/admin/tokens/) * [InfluxDB /api/v3 Token API reference](/influxdb3/core/api/v3/#tag/Token) [cli](/influxdb3/core/tags/cli/) | Option | Description | Default | Environment | | --- | --- | --- | --- | | Option | Description | Default | Environment | | --token | ( Required ) The token for authentication with the InfluxDB 3 Core server | | INFLUXDB3_AUTH_TOKEN | | --token-name | ( Required ) The name of the token to be deleted | | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | INFLUXDB3_TLS_CA | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | INFLUXDB3_TLS_NO_VERIFY | | -h , --help | Print help information | | | | --help-all | Print detailed help information | | | --- # influxdb3 delete trigger Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/delete/trigger/ The `influxdb3 delete trigger` command deletes a processing engine trigger. ## Usage ```bash # Syntax influxdb3 delete trigger [OPTIONS] --database ``` ## Arguments * **TRIGGER\_NAME**: The name of the trigger to delete. ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | | `--force` | Force delete even if the trigger is active | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Delete a trigger](#delete-a-trigger) * [Force delete an active trigger](#force-delete-an-active-trigger) In the examples below, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `TRIGGER_NAME`: Name of the trigger to delete ### Delete a trigger ```bash influxdb3 delete trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TRIGGER_NAME ``` ### Force delete an active trigger ```bash influxdb3 delete trigger \ --force \ --database DATABASE_NAME \ --token AUTH_TOKEN \ TRIGGER_NAME ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | | --force | Force delete even if the trigger is active | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 disable Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/disable/ The `influxdb3 disable` command disables resources such as a trigger. ## Usage ```bash influxdb3 disable ``` ## Subcommands | Subcommand | Description | |-------------------------------------------------------------------|----------------------------------------------| |[trigger](/influxdb3/core/reference/cli/influxdb3/disable/trigger/)| Disables a plugin trigger | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | trigger | Disables a plugin trigger | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 disable trigger Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/disable/trigger/ The `influxdb3 disable trigger` command disables a plugin trigger. ## Usage ```bash influxdb3 disable trigger [OPTIONS] --database ``` ## Arguments: * **TRIGGER\_NAME**: Name of the trigger to disable ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 enable Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/enable/ The `influxdb3 enable` command enables resources such as a trigger. ## Usage ```bash influxdb3 enable ``` ## Subcommands | Subcommand | Description | |------------------------------------------------------------------|----------------------------------------------| |[trigger](/influxdb3/core/reference/cli/influxdb3/enable/trigger/)| Enable a trigger to enable plugin execution | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | trigger | Enable a trigger to enable plugin execution | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 enable trigger Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/enable/trigger/ The `influxdb3 enable trigger` command enables a trigger to enable plugin execution. ## Usage ```bash influxdb3 enable trigger [OPTIONS] --database ``` ## Arguments: * **TRIGGER\_NAME**: Name of the trigger to enable ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 install Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/install/ The `influxdb3 install` command and its subcommands manage Python package installations for the InfluxDB 3 Core processing engine. ## Usage ```bash influxdb3 install ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------------|-----------------------------------------------------| |[`package`](/influxdb3/core/reference/cli/influxdb3/install/package/)|Install Python packages for processing engine plugins| | `help` | Print command help or the help of a subcommand | ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | package | Install Python packages for processing engine plugins | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 install package Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/install/package/ The `influxdb3 install package` command installs Python packages within the plugin environment for use in [InfluxDB 3 Core processing engine plugins](/influxdb3/core/process/). Use this command to add external dependencies that your plugins require, such as data processing libraries, notification tools, or forecasting packages. ## Usage ```bash # Syntax influxdb3 install package [OPTIONS] [PACKAGES]... ``` ## Arguments * **`[PACKAGES]...`**: One or more package names to install (space-separated) ## Options | Option | Description | Default | Environment Variable | |-----------------------------------------------|-------------------------------------------------------------------------------------------------------------|-----------------------|---------------------------| | `-H`, `--host ` | The host URL of the running InfluxDB 3 Core server |`http://127.0.0.1:8181`| `INFLUXDB3_HOST_URL` | | `--token ` | The token for authentication with the InfluxDB 3 Core server | | `INFLUXDB3_AUTH_TOKEN` | | `--plugin-dir ` | Location of the plugins directory | `/plugins` | `INFLUXDB3_PLUGIN_DIR` | |`--virtual-env-location `| Custom virtual environment location | | `VIRTUAL_ENV` | | `--package-manager ` | Package manager to use: `discover`, `pip`, `uv`, or `disabled` | `discover` |`INFLUXDB3_PACKAGE_MANAGER`| | `--plugin-repo ` | Plugin repository URL | | `INFLUXDB3_PLUGIN_REPO` | | `-r`, `--requirements ` | Path to a `requirements.txt` file | | | | `--tls-ca ` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | `INFLUXDB3_TLS_CA` | | `--tls-no-verify` |Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `INFLUXDB3_TLS_NO_VERIFY` | | `-h`, `--help` | Print help information | | | | `--help-all` | Print detailed help information | | | ## Examples ### Install a single package ```bash influxdb3 install package pandas ``` ### Install multiple packages ```bash influxdb3 install package pint pandas requests ``` ### Install packages from a requirements file ```bash influxdb3 install package -r requirements.txt ``` ### Install packages with custom host and authentication ```bash influxdb3 install package \ --host http://localhost:8181 \ --token AUTH_TOKEN \ pint pandas ``` Replace `AUTH_TOKEN` with your [admin token](/influxdb3/core/admin/tokens/)for your InfluxDB 3 Core instance. ### Install packages with a specific package manager ```bash influxdb3 install package \ --package-manager uv \ prophet adtk ``` ### Install packages with a custom CA certificate ```bash influxdb3 install package \ --tls-ca /path/to/ca-cert.pem \ requests ``` ## Package management ### Package manager selection By default (`--package-manager discover`), the CLI automatically detects and uses the best available package manager: 1. **uv** (preferred): Faster package installation 2. **pip** (fallback): Standard Python package manager ### Virtual environment The CLI manages a virtual environment for plugin packages to avoid conflicts with system Python packages. You can customize the virtual environment location with `--virtual-env-location` or the `VIRTUAL_ENV` environment variable. ### Security mode If your InfluxDB 3 Core server was started with [`--package-manager disabled`](/influxdb3/core/reference/config-options/#package-manager), the `influxdb3 install package` command is blocked for security and compliance requirements. When attempting to install packages with this command while the server has package installation disabled, the command fails with a `403 Forbidden` error: ``` Package installation has been disabled. Contact your administrator for more information. ``` The server’s `--package-manager disabled` setting is designed for: * **Enterprise security requirements**: Prevent arbitrary package installation * **Compliance environments**: Control exactly which packages are available * **Air-gapped deployments**: Pre-install all dependencies before deployment * **Multi-tenant scenarios**: Prevent tenants from installing potentially malicious packages In these environments, administrators must pre-install all required Python packages into the server’s virtual environment before starting InfluxDB 3 Core. For more information, see the [`package-manager`](/influxdb3/core/reference/config-options/#package-manager) configuration option. ### Troubleshooting If package installation fails: * **Check if package installation is disabled**: If you receive a `403 Forbidden` error, contact your administrator. Package installation may be disabled on your InfluxDB 3 Core instance. * **Verify network connectivity**: Ensure your InfluxDB 3 Core instance can reach PyPI or your custom package repository * **Check package names**: Verify package names are correct and available in the package repository * **Review logs**: Check InfluxDB 3 Core server logs for detailed error messages * **Test with pip**: Try installing the package directly with `pip` to verify it’s available * **Use requirements file**: For complex dependencies, use a `requirements.txt` file with version pinning * **Check Docker disk space** (Docker environments only): If running InfluxDB 3 Core in Docker and seeing “No space left on device” errors, free up disk space: ``` # Check Docker disk usage docker system df # Remove unused images and build cache docker image prune -af docker buildx prune -af ``` #### Related * [Processing engine and Python plugins](/influxdb3/core/plugins/) [cli](/influxdb3/core/tags/cli/)[processing engine](/influxdb3/core/tags/processing-engine/)[plugins](/influxdb3/core/tags/plugins/) | Option | Description | Default | Environment Variable | | --- | --- | --- | --- | | Option | Description | Default | Environment Variable | | -H , --host | The host URL of the running InfluxDB 3 Core server | http://127.0.0.1:8181 | INFLUXDB3_HOST_URL | | --token | The token for authentication with the InfluxDB 3 Core server | | INFLUXDB3_AUTH_TOKEN | | --plugin-dir | Location of the plugins directory | /plugins | INFLUXDB3_PLUGIN_DIR | | --virtual-env-location | Custom virtual environment location | | VIRTUAL_ENV | | --package-manager | Package manager to use: discover , pip , uv , or disabled | discover | INFLUXDB3_PACKAGE_MANAGER | | --plugin-repo | Plugin repository URL | | INFLUXDB3_PLUGIN_REPO | | -r , --requirements | Path to a requirements.txt file | | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | INFLUXDB3_TLS_CA | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | INFLUXDB3_TLS_NO_VERIFY | | -h , --help | Print help information | | | | --help-all | Print detailed help information | | | --- # influxdb3 query Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/query/ The `influxdb3 query` command executes a query against a running InfluxDB 3 Core server. ## Usage ```bash influxdb3 query [OPTIONS] --database [QUERY]... ``` ##### Aliases `query`, `q` ## Arguments * **QUERY**: The query to execute. Provide the query in one of the following ways: * a string * a path to a file that contains the query using the `--file` option * from stdin ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-l` | `--language` | Query language of the query string (`sql` *(default)* or `influxql`) | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, `parquet`) | | `-o` | `--output` | Output query results to the specified file | | `-f` | `--file` | A file that contains the query to execute | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Query data using SQL](#query-data-using-sql) * [Query data using InfluxQL](#query-data-using-influxql) * [Query data and return JSON-formatted results](#query-data-and-return-json-formatted-results) * [Query data and write results to a file](#query-data-and-write-results-to-a-file) In the examples below, replace`DATABASE_NAME`: with the name of the database to query. ### Query data using SQL #### string #### ```bash influxdb3 query \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'SELECT * FROM home' ``` ```bash influxdb3 query \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./query.sql ``` ```bash cat ./query.sql | influxdb3 query \ --database DATABASE_NAME \ --token AUTH_TOKEN \ ``` ### Query data using InfluxQL #### string #### ```bash influxdb3 query \ --language influxql \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'SELECT * FROM home' ``` ```bash influxdb3 query \ --language influxql \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./query.influxql ``` ```bash cat ./query.influxql | influxdb3 query \ --language influxql \ --database DATABASE_NAME \ --token AUTH_TOKEN ``` ### Query data and return JSON-formatted results #### string #### ```bash influxdb3 query \ --format json \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'SELECT * FROM home' ``` ```bash influxdb3 query \ --format json \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./query.sql ``` ```bash cat ./query.sql | influxdb3 query \ --format json \ --database DATABASE_NAME \ --token AUTH_TOKEN \ ``` ### Query data and write results to a file #### string #### ```bash influxdb3 query \ --output /path/to/results.txt \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'SELECT * FROM home' ``` ```bash influxdb3 query \ --output /path/to/results.txt \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./query.sql ``` ```bash cat ./query.sql | influxdb3 query \ --output /path/to/results.txt \ --database DATABASE_NAME \ --token AUTH_TOKEN ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -l | --language | Query language of the query string ( sql (default) or influxql ) | | | --format | Output format ( pretty (default) , json , jsonl , csv , parquet ) | | -o | --output | Output query results to the specified file | | -f | --file | A file that contains the query to execute | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 serve Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/serve/ The `influxdb3 serve` command starts the InfluxDB 3 Core server. ## Usage ```bash influxdb3 serve [OPTIONS] ``` ## Required Parameters * **node-id**: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store. * **object-store**: Determines where time series data is stored. * Other object store parameters depending on the selected `object-store` type. > [!Note] > `--node-id` supports alphanumeric strings with optional hyphens. > [!Important] > #### Global configuration options > > Some configuration options (like [`--num-io-threads`](/influxdb3/core/reference/config-options/#num-io-threads)) are **global** and must be specified **before** the `serve` command: > > ``` > influxdb3 --num-io-threads=8 serve --node-id=node0 --object-store=file --verbose > ``` > > See [Global configuration options](/influxdb3/core/reference/config-options/#global-configuration-options) for the complete list. ## Options |Option| | Description | |------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | \* | `--node-id` | *See [configuration options](/influxdb3/core/reference/config-options/#node-id)* | | \* | `--object-store` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store)* | | | `--admin-token-recovery-http-bind` | *See [configuration options](/influxdb3/core/reference/config-options/#admin-token-recovery-http-bind)* | | | `--admin-token-recovery-tcp-listener-file-path` | *See [configuration options](/influxdb3/core/reference/config-options/#admin-token-recovery-tcp-listener-file-path)* | | | `--admin-token-file` | *See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-file)* | | | `--aws-access-key-id` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-access-key-id)* | | | `--aws-allow-http` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-allow-http)* | | | `--aws-credentials-file` | *See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-credentials-file)* | | | `--aws-default-region` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-default-region)* | | | `--aws-endpoint` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-endpoint)* | | | `--aws-secret-access-key` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-secret-access-key)* | | | `--aws-session-token` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-session-token)* | | | `--aws-skip-signature` | *See [configuration options](/influxdb3/core/reference/config-options/#aws-skip-signature)* | | | `--azure-allow-http` | *See [configuration options](/influxdb3/enterprise/reference/config-options/#azure-allow-http)* | | | `--azure-endpoint` | *See [configuration options](/influxdb3/core/reference/config-options/#azure-endpoint)* | | | `--azure-storage-access-key` | *See [configuration options](/influxdb3/core/reference/config-options/#azure-storage-access-key)* | | | `--azure-storage-account` | *See [configuration options](/influxdb3/core/reference/config-options/#azure-storage-account)* | | | `--bucket` | *See [configuration options](/influxdb3/core/reference/config-options/#bucket)* | | | `--data-dir` | *See [configuration options](/influxdb3/core/reference/config-options/#data-dir)* | | | `--datafusion-config` | *See [configuration options](/influxdb3/core/reference/config-options/#datafusion-config)* | | | `--datafusion-max-parquet-fanout` | *See [configuration options](/influxdb3/core/reference/config-options/#datafusion-max-parquet-fanout)* | | | `--datafusion-num-threads` | *See [configuration options](/influxdb3/core/reference/config-options/#datafusion-num-threads)* | | | `--datafusion-runtime-disable-lifo-slot` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-event-interval` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-global-queue-interval` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-max-blocking-threads` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-max-io-events-per-tick` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-thread-keep-alive` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-thread-priority` | Development-only Tokio runtime configuration | | | `--datafusion-runtime-type` | Development-only Tokio runtime configuration | | | `--datafusion-use-cached-parquet-loader` | *See [configuration options](/influxdb3/core/reference/config-options/#datafusion-use-cached-parquet-loader)* | | | `--delete-grace-period` | *See [configuration options](/influxdb3/core/reference/config-options/#delete-grace-period)* | | | `--disable-authz` | *See [configuration options](/influxdb3/core/reference/config-options/#disable-authz)* | | | `--disable-file-cache` | *See [configuration options](/influxdb3/core/reference/config-options/#disable-file-cache)* | | | `--distinct-cache-eviction-interval` | *See [configuration options](/influxdb3/core/reference/config-options/#distinct-cache-eviction-interval)* | | | `--exec-mem-pool-size` | *See [configuration options](/influxdb3/core/reference/config-options/#exec-mem-pool-size)* | | | `--force-snapshot-mem-size` | *See [configuration options](/influxdb3/core/reference/config-options/#force-snapshot-mem-size)* | | | `--gen1-duration` | *See [configuration options](/influxdb3/core/reference/config-options/#gen1-duration)* | | | `--gen1-lookback-duration` | *See [configuration options](/influxdb3/core/reference/config-options/#gen1-lookback-duration)* | | | `--google-service-account` | *See [configuration options](/influxdb3/core/reference/config-options/#google-service-account)* | | | `--hard-delete-default-duration` | *See [configuration options](/influxdb3/core/reference/config-options/#hard-delete-default-duration)* | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | | | `--http-bind` | *See [configuration options](/influxdb3/core/reference/config-options/#http-bind)* | | | `--last-cache-eviction-interval` | *See [configuration options](/influxdb3/core/reference/config-options/#last-cache-eviction-interval)* | | | `--log-destination` | *See [configuration options](/influxdb3/core/reference/config-options/#log-destination)* | | | `--log-filter` | *See [configuration options](/influxdb3/core/reference/config-options/#log-filter)* | | | `--log-format` | *See [configuration options](/influxdb3/core/reference/config-options/#log-format)* | | | `--max-concurrent-queries` | *See [configuration options](/influxdb3/core/reference/config-options/#max-concurrent-queries)* | | | `--max-http-request-size` | *See [configuration options](/influxdb3/core/reference/config-options/#max-http-request-size)* | | | `--object-store-connection-limit` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store-connection-limit)* | | | `--object-store-http2-max-frame-size` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store-http2-max-frame-size)* | | | `--object-store-http2-only` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store-http2-only)* | | | `--object-store-max-retries` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store-max-retries)* | | | `--object-store-retry-timeout` | *See [configuration options](/influxdb3/core/reference/config-options/#object-store-retry-timeout)* | | | `--package-manager` | *See [configuration options](/influxdb3/core/reference/config-options/#package-manager)* | | | `--parquet-mem-cache-prune-interval` | *See [configuration options](/influxdb3/core/reference/config-options/#parquet-mem-cache-prune-interval)* | | | `--parquet-mem-cache-prune-percentage` | *See [configuration options](/influxdb3/core/reference/config-options/#parquet-mem-cache-prune-percentage)* | | | `--file-cache-recency` | *See [configuration options](/influxdb3/core/reference/config-options/#file-cache-recency)* | | | `--file-cache-size` | *See [configuration options](/influxdb3/core/reference/config-options/#file-cache-size)* | | | `--plugin-dir` | *See [configuration options](/influxdb3/core/reference/config-options/#plugin-dir)* | | | `--plugin-repo` | *See [configuration options](/influxdb3/core/reference/config-options/#plugin-repo)* | | | `--preemptive-cache-age` | *See [configuration options](/influxdb3/core/reference/config-options/#preemptive-cache-age)* | | | `--query-file-limit` | *See [configuration options](/influxdb3/core/reference/config-options/#query-file-limit)* | | | `--query-log-max-entries` | *See [configuration options](/influxdb3/core/reference/config-options/#query-log-max-entries)* | | | `--restrict-plugin-triggers-to` | *See [configuration options](/influxdb3/core/reference/config-options/#restrict-plugin-triggers-to)* | | | `--retention-check-interval` | *See [configuration options](/influxdb3/core/reference/config-options/#retention-check-interval)* | | | `--snapshotted-wal-files-to-keep` | *See [configuration options](/influxdb3/core/reference/config-options/#snapshotted-wal-files-to-keep)* | | | `--table-index-cache-concurrency-limit` | *See [configuration options](/influxdb3/core/reference/config-options/#table-index-cache-concurrency-limit)* | | | `--table-index-cache-max-entries` | *See [configuration options](/influxdb3/core/reference/config-options/#table-index-cache-max-entries)* | | | `--tcp-listener-file-path` | *See [configuration options](/influxdb3/core/reference/config-options/#tcp-listener-file-path)* | | | `--disable-telemetry-upload` | *See [configuration options](/influxdb3/core/reference/config-options/#disable-telemetry-upload)* | | | `--telemetry-endpoint` | *See [configuration options](/influxdb3/core/reference/config-options/#telemetry-endpoint)* | | | `--tls-cert` | *See [configuration options](/influxdb3/core/reference/config-options/#tls-cert)* | | | `--tls-key` | *See [configuration options](/influxdb3/core/reference/config-options/#tls-key)* | | | `--tls-minimum-version` | *See [configuration options](/influxdb3/core/reference/config-options/#tls-minimum-version)* | | | `--traces-exporter` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-exporter)* | | | `--traces-exporter-jaeger-agent-host` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-exporter-jaeger-agent-host)* | | | `--traces-exporter-jaeger-agent-port` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-exporter-jaeger-agent-port)* | | | `--traces-exporter-jaeger-service-name` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-exporter-jaeger-service-name)* | | |`--traces-exporter-jaeger-trace-context-header-name`|*See [configuration options](/influxdb3/core/reference/config-options/#traces-exporter-jaeger-trace-context-header-name)*| | | `--traces-jaeger-debug-name` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-jaeger-debug-name)* | | | `--traces-jaeger-max-msgs-per-second` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-jaeger-max-msgs-per-second)* | | | `--traces-jaeger-tags` | *See [configuration options](/influxdb3/core/reference/config-options/#traces-jaeger-tags)* | | | `--virtual-env-location` | *See [configuration options](/influxdb3/core/reference/config-options/#virtual-env-location)* | | | `--wal-flush-interval` | *See [configuration options](/influxdb3/core/reference/config-options/#wal-flush-interval)* | | | `--wal-max-buffered-writes` | *See [configuration options](/influxdb3/core/reference/config-options/#wal-max-buffered-writes)* | | | `--wal-replay-concurrency-limit` | *See [configuration options](/influxdb3/core/reference/config-options/#wal-replay-concurrency-limit)* | | | `--wal-replay-fail-on-error` | *See [configuration options](/influxdb3/core/reference/config-options/#wal-replay-fail-on-error)* | | | `--wal-files-per-snapshot` | *See [configuration options](/influxdb3/core/reference/config-options/#wal-files-per-snapshot)* | | | `--without-auth` | *See [configuration options](/influxdb3/core/reference/config-options/#without-auth)* | ### Option environment variables You can use environment variables to define most `influxdb3 serve` options. For more information, see[Configuration options](/influxdb3/core/reference/config-options/). ## Quick-Start Mode For development, testing, and home use, you can start InfluxDB 3 Core by running `influxdb3` without the `serve` subcommand or any configuration parameters. The system automatically generates required values: * **`node-id`**: `{hostname}-node` (fallback: `primary-node`) * **`object-store`**: `file` * **`data-dir`**: `~/.influxdb` The system displays warning messages showing the auto-generated identifiers: ``` Using auto-generated node id: mylaptop-node. For production deployments, explicitly set --node-id ``` ### Quick-start examples ```bash # Zero-config startup influxdb3 # Override specific defaults influxdb3 --object-store memory # Use environment variables to override defaults INFLUXDB3_NODE_ID=my-node influxdb3 ``` > [!Important] > #### Production deployments > > Quick-start mode is designed for development and testing environments. > For production deployments, use explicit configuration with the `serve` subcommand > and specify all required parameters as shown in the [Examples](#examples) below. **Configuration precedence**: CLI flags \> environment variables \> auto-generated defaults For more information about quick-start mode, see [Get started](/influxdb3/core/get-started/setup/#quick-start-mode-development). ## Examples * [Run the InfluxDB 3 server](#run-the-influxdb-3-server) * [Run the InfluxDB 3 server with extra verbose logging](#run-the-influxdb-3-server-with-extra-verbose-logging) * [Run InfluxDB 3 with debug logging using LOG\_FILTER](#run-influxdb-3-with-debug-logging-using-log_filter) In the examples below, replace`my-host-01`: with a unique string that identifies your InfluxDB 3 Core server. ### Run the InfluxDB 3 server ```bash influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 ``` ### Run the InfluxDB 3 server with extra verbose logging ```bash influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 --verbose ``` ### Run InfluxDB 3 with debug logging using LOG\_FILTER ```bash LOG_FILTER=debug influxdb3 serve \ --object-store file \ --data-dir ~/.influxdb3 \ --node-id my-host-01 ``` ## Troubleshooting ### Common Issues * **Error: “Failed to connect to object store”** Verify your `--object-store` setting and ensure all required parameters for that storage type are provided. * **Permission errors when using S3, Google Cloud, or Azure storage** Check that your authentication credentials are correct and have sufficient permissions. #### Related * [InfluxDB 3 Core configuration options](/influxdb3/core/reference/config-options/) | Option | | Description | | --- | --- | --- | | Option | | Description | | * | --node-id | See configuration options | | * | --object-store | See configuration options | | | --admin-token-recovery-http-bind | See configuration options | | | --admin-token-recovery-tcp-listener-file-path | See configuration options | | | --admin-token-file | See configuration options | | | --aws-access-key-id | See configuration options | | | --aws-allow-http | See configuration options | | | --aws-credentials-file | See configuration options | | | --aws-default-region | See configuration options | | | --aws-endpoint | See configuration options | | | --aws-secret-access-key | See configuration options | | | --aws-session-token | See configuration options | | | --aws-skip-signature | See configuration options | | | --azure-allow-http | See configuration options | | | --azure-endpoint | See configuration options | | | --azure-storage-access-key | See configuration options | | | --azure-storage-account | See configuration options | | | --bucket | See configuration options | | | --data-dir | See configuration options | | | --datafusion-config | See configuration options | | | --datafusion-max-parquet-fanout | See configuration options | | | --datafusion-num-threads | See configuration options | | | --datafusion-runtime-disable-lifo-slot | Development-only Tokio runtime configuration | | | --datafusion-runtime-event-interval | Development-only Tokio runtime configuration | | | --datafusion-runtime-global-queue-interval | Development-only Tokio runtime configuration | | | --datafusion-runtime-max-blocking-threads | Development-only Tokio runtime configuration | | | --datafusion-runtime-max-io-events-per-tick | Development-only Tokio runtime configuration | | | --datafusion-runtime-thread-keep-alive | Development-only Tokio runtime configuration | | | --datafusion-runtime-thread-priority | Development-only Tokio runtime configuration | | | --datafusion-runtime-type | Development-only Tokio runtime configuration | | | --datafusion-use-cached-parquet-loader | See configuration options | | | --delete-grace-period | See configuration options | | | --disable-authz | See configuration options | | | --disable-file-cache | See configuration options | | | --distinct-cache-eviction-interval | See configuration options | | | --exec-mem-pool-size | See configuration options | | | --force-snapshot-mem-size | See configuration options | | | --gen1-duration | See configuration options | | | --gen1-lookback-duration | See configuration options | | | --google-service-account | See configuration options | | | --hard-delete-default-duration | See configuration options | | -h | --help | Print help information | | | --help-all | Print detailed help information | | | --http-bind | See configuration options | | | --last-cache-eviction-interval | See configuration options | | | --log-destination | See configuration options | | | --log-filter | See configuration options | | | --log-format | See configuration options | | | --max-concurrent-queries | See configuration options | | | --max-http-request-size | See configuration options | | | --object-store-connection-limit | See configuration options | | | --object-store-http2-max-frame-size | See configuration options | | | --object-store-http2-only | See configuration options | | | --object-store-max-retries | See configuration options | | | --object-store-retry-timeout | See configuration options | | | --package-manager | See configuration options | | | --parquet-mem-cache-prune-interval | See configuration options | | | --parquet-mem-cache-prune-percentage | See configuration options | | | --file-cache-recency | See configuration options | | | --file-cache-size | See configuration options | | | --plugin-dir | See configuration options | | | --plugin-repo | See configuration options | | | --preemptive-cache-age | See configuration options | | | --query-file-limit | See configuration options | | | --query-log-max-entries | See configuration options | | | --restrict-plugin-triggers-to | See configuration options | | | --retention-check-interval | See configuration options | | | --snapshotted-wal-files-to-keep | See configuration options | | | --table-index-cache-concurrency-limit | See configuration options | | | --table-index-cache-max-entries | See configuration options | | | --tcp-listener-file-path | See configuration options | | | --disable-telemetry-upload | See configuration options | | | --telemetry-endpoint | See configuration options | | | --tls-cert | See configuration options | | | --tls-key | See configuration options | | | --tls-minimum-version | See configuration options | | | --traces-exporter | See configuration options | | | --traces-exporter-jaeger-agent-host | See configuration options | | | --traces-exporter-jaeger-agent-port | See configuration options | | | --traces-exporter-jaeger-service-name | See configuration options | | | --traces-exporter-jaeger-trace-context-header-name | See configuration options | | | --traces-jaeger-debug-name | See configuration options | | | --traces-jaeger-max-msgs-per-second | See configuration options | | | --traces-jaeger-tags | See configuration options | | | --virtual-env-location | See configuration options | | | --wal-flush-interval | See configuration options | | | --wal-max-buffered-writes | See configuration options | | | --wal-replay-concurrency-limit | See configuration options | | | --wal-replay-fail-on-error | See configuration options | | | --wal-files-per-snapshot | See configuration options | | | --without-auth | See configuration options | --- # influxdb3 show Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/ The `influxdb3 show` command lists resources in your InfluxDB 3 Core server. ## Usage ```bash influxdb3 show ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------------|----------------------------------------------| |[databases](/influxdb3/core/reference/cli/influxdb3/show/databases/)| List database | | [plugins](/influxdb3/core/reference/cli/influxdb3/show/plugins/) | List loaded plugins | | [system](/influxdb3/core/reference/cli/influxdb3/show/system/) | Display system table data | | [tokens](/influxdb3/core/reference/cli/influxdb3/show/tokens/) | List authentication tokens | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | databases | List database | | plugins | List loaded plugins | | system | Display system table data | | tokens | List authentication tokens | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 show databases Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/databases/ The `influxdb3 show databases` command lists databases in your InfluxDB 3 Core server. ## Usage ```bash influxdb3 show databases [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | | `--token` | *(Required)* Authentication token | | |`--show-deleted` | Include databases marked as deleted in the output | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [List all databases](#list-all-databases) * [List all databases, including deleted databases](#list-all-databases-including-deleted-databases) * [List databases in JSON-formatted output](#list-databases-in-json-formatted-output) ### List all databases ```bash influxdb3 show databases ``` ### List all databases, including deleted databases ```bash influxdb3 show databases --show-deleted ``` ### List databases in JSON-formatted output ```bash influxdb3 show databases --format json ``` ### List databases in Parquet format output [Parquet](https://parquet.apache.org/) is a binary format. Use the `--output` option to specify the file where you want to save the Parquet data. ``` influxdb3 show databases --format parquet \ --output /Users/me/databases.parquet ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --token | ( Required ) Authentication token | | | --show-deleted | Include databases marked as deleted in the output | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 show plugins Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/plugins/ The `influxdb3 show plugins` command lists loaded Processing Engine plugins in your InfluxDB 3 Core server. ## Usage ```bash influxdb3 show plugins [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | | `--token` | *(Required)* Authentication token | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--output` | Path where to save output when using the `parquet` format | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Output The command returns information about loaded plugin files: * **plugin\_name**: Name of a trigger using this plugin * **file\_name**: Plugin filename * **file\_path**: Full server path to the plugin file * **size\_bytes**: File size in bytes * **last\_modified**: Last modification timestamp (milliseconds since epoch) > [!Note] > This command queries the `system.plugin_files` table in the `_internal` database. > For more advanced queries and filtering, see [Query system data](/influxdb3/core/admin/query-system-data/). ## Examples * [List all plugins](#list-all-plugins) * [List plugins in different output formats](#list-plugins-in-different-output-formats) * [Output plugins to a Parquet file](#output-plugins-to-a-parquet-file) ### List all plugins ```bash influxdb3 show plugins ``` ### List plugins in different output formats You can specify the output format using the `--format` option: ```bash # JSON format influxdb3 show plugins --format json # JSON Lines format influxdb3 show plugins --format jsonl # CSV format influxdb3 show plugins --format csv ``` ### Output plugins to a Parquet file [Parquet](https://parquet.apache.org/) is a binary format. Use the `--output` option to specify the file where you want to save the Parquet data. ```bash influxdb3 show plugins \ --format parquet \ --output /Users/me/plugins.parquet ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --token | ( Required ) Authentication token | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --output | Path where to save output when using the parquet format | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 show retention Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/retention/ The `influxdb3 show retention` command displays effective retention periods for tables in your InfluxDB 3 Core server. ## Usage ```bash # Syntax influxdb3 show retention [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | | `--token` | *(Required)* Authentication token | | | `--database` | Filter retention information by database name | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Show retention for all tables](#show-retention-for-all-tables) * [Show retention for a specific database](#show-retention-for-a-specific-database) * [Show retention in JSON format](#show-retention-in-json-format) * [Export retention data to Parquet format](#export-retention-data-to-parquet-format) In the examples below, replace `AUTH_TOKEN` with your authentication token. ### Show retention for all tables ```bash influxdb3 show retention \ --host http://localhost:8181 \ --token AUTH_TOKEN ``` ### Show retention for a specific database ```bash influxdb3 show retention \ --host http://localhost:8181 \ --token AUTH_TOKEN \ --database mydb ``` ### Show retention in JSON format ```bash influxdb3 show retention \ --host http://localhost:8181 \ --token AUTH_TOKEN \ --format json ``` ### Export retention data to Parquet format [Parquet](https://parquet.apache.org/) is a binary format. When using the `parquet` format, data is written to standard output by default. Use output redirection or the `--output` option to save the data to a file. ```bash influxdb3 show retention \ --host http://localhost:8181 \ --token AUTH_TOKEN \ --format parquet \ --output retention-data.parquet ``` ## Output The command displays the following information for each table: * **Database**: The database name * **Table**: The table name * **Retention**: The *effective* retention period in human-readable format (for example, “7d” for 7 days, “24h” for 24 hours, “infinite” for no retention) * **Source**: Where the retention is defined (`table`, `database`, or `infinite`) ### Example output ``` Database | Table | Retention | Source ---------|-------------|-----------|---------- mydb | cpu | 7d | database mydb | mem | 24h | table mydb | disk | infinite | infinite ``` Tables with table-level retention policies override the database-level retention. Tables without explicit retention policies inherit the database retention or have infinite retention if none is set. | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --token | ( Required ) Authentication token | | | --database | Filter retention information by database name | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 show system Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/system/ The `influxdb3 show system` command displays data from InfluxDB 3 Core system tables. ## Usage ``` influxdb3 show system [OPTIONS] --database ``` ##### Aliases `system`, `s` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------------------------|----------------------------------------------| | [summary](/influxdb3/core/reference/cli/influxdb3/show/system/summary) | Summarize system table data | | [table](/influxdb3/core/reference/cli/influxdb3/show/system/table/) |Retrieve entries from a specific system table | |[table-list](/influxdb3/core/reference/cli/influxdb3/show/system/table-list/)| List available system tables | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-----------------------------------------------------------------------------------| | `-H` | `--host` |Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`)| | `-d` |`--database`| *(Required)* Name of the database to operate on | | | `--token` | Authentication token | | `-h` | `--help` | Print help information | | |`--help-all`| Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`|`--database`| | `INFLUXDB3_AUTH_TOKEN` | `--token` | | Subcommand | Description | | --- | --- | | Subcommand | Description | | summary | Summarize system table data | | table | Retrieve entries from a specific system table | | table-list | List available system tables | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | Authentication token | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | --- # influxdb3 show system summary Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/system/summary/ The `influxdb3 show system summary` command returns a summary of various types of system table data. ## Usage ```bash influxdb3 show system --database summary [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-l` | `--limit` | Maximum number of entries from each table to display (default is `10`, `0` indicates no limit) | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ## Examples * [Summarize system table data](#summarize-system-table-data) * [Summarize system table data in JSON-formatted output](#summarize-system-table-data-in-json-formatted-output) In the examples below, replace`DATABASE_NAME` with the name of the database to operate on. ### Summarize system table data ```bash influxdb3 show system --database DATABASE_NAME summary ``` ### Summarize system table data in JSON-formatted output ```bash influxdb3 show system --database DATABASE_NAME summary --format json ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -l | --limit | Maximum number of entries from each table to display (default is 10 , 0 indicates no limit) | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 show system table-list Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/system/table-list/ The `influxdb3 show system table-list` command lists available system tables. ## Usage ```bash influxdb3 show system --database table-list [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ## Examples * [List system tables](#list-system-tables) * [List system tables in JSON-formatted output](#list-system-tables-in-json-formatted-output) In the examples below, replace`DATABASE_NAME` with the name of the database to operate on. ### List system tables ```bash influxdb3 show system --database DATABASE_NAME summary ``` ### List system tables in JSON-formatted output ```bash influxdb3 show system --database DATABASE_NAME summary --format json ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 show system table Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/system/table/ The `influxdb3 show system table` command queries data from a system table. ## Usage ```bash influxdb3 show system --database table [OPTIONS] ``` ## Arguments * **SYSTEM\_TABLE**: the system table to query ## Options |Option| | Description | |------|-----------------|--------------------------------------------------------------------------------------------------------------| | `-l` | `--limit` | Maximum number of tables entries to display (default is `10`, `0` indicates no limit) | | `-o` | `--order-by` | Order by the specified columns | | `-s` | `--select` | Select specific columns from the system table | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification. (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ## Examples * [Query a system table](#query-a-system-table) * [Query specific columns from a system table](#query-specific-columns-from-a-system-table) * [Query a system table and order by a specific column](#query-a-system-table-and-order-by-a-specific-column) * [Query a system table and return JSON-formatted output](#query-a-system-table-and-return-json-formatted-output) In the examples below, replace`DATABASE_NAME` with the name of the database to operate on. ### Query a system table ```bash # Query the parquet_files system table influxdb3 show system --database DATABASE_NAME table parquet_files ``` ### Query specific columns from a system table ```bash # Select specific columns from the parquet_files system table influxdb3 show system \ --database DATABASE_NAME \ table \ --select table_name,size_bytes,row_count \ parquet_files ``` ### Query a system table and order by a specific column ```bash influxdb3 show system \ --database DATABASE_NAME \ table \ --order-by size_bytes,row_count \ parquet_files ``` ### Query a system table and return JSON-formatted output ```bash influxdb3 show system \ --database DATABASE_NAME \ table \ --format json \ parquet_files ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -l | --limit | Maximum number of tables entries to display (default is 10 , 0 indicates no limit) | | -o | --order-by | Order by the specified columns | | -s | --select | Select specific columns from the system table | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification. ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 show tokens Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/show/tokens/ The `influxdb3 show tokens` command lists authentication tokens in your InfluxDB 3 Core server. ## Usage ```bash influxdb3 show tokens [OPTIONS] ``` ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | | `--token` | *(Required)* Authentication token | | | `--format` | Output format (`pretty` *(default)*, `json`, `jsonl`, `csv`, or `parquet`) | | | `--output` | Path where to save output when using the `parquet` format | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [List all tokens](#list-all-tokens) * [List tokens in different output formats](#list-tokens-in-different-output-formats) * [Output tokens to a Parquet file](#output-tokens-to-a-parquet-file) ### List all tokens ```bash influxdb3 show tokens ``` ### List tokens in different output formats You can specify the output format using the `--format` option: ```bash # JSON format influxdb3 show tokens --format json # JSON Lines format influxdb3 show tokens --format jsonl # CSV format influxdb3 show tokens --format csv ``` ### Output tokens to a Parquet file [Parquet](https://parquet.apache.org/) is a binary format. Use the `--output` option to specify the file where you want to save the Parquet data. ```bash influxdb3 show tokens \ --format parquet \ --output /Users/me/tokens.parquet ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | | --token | ( Required ) Authentication token | | | --format | Output format ( pretty (default) , json , jsonl , csv , or parquet ) | | | --output | Path where to save output when using the parquet format | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 test Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/test/ The `influxdb3 test` command tests InfluxDB 3 resources, such as plugins. ## Usage ```bash influxdb3 test ``` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------------------|----------------------------------------------| |[wal\_plugin](/influxdb3/core/reference/cli/influxdb3/test/wal_plugin/)| Test a write-ahead log (WAL) plugin | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | wal_plugin | Test a write-ahead log (WAL) plugin | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 test schedule_plugin Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/test/schedule_plugin/ The `influxdb3 test schedule_plugin` command tests a schedule plugin. Use this command to verify plugin behavior without creating a trigger. ## Usage ```bash influxdb3 test schedule_plugin [OPTIONS] --database ``` ## Arguments * **FILENAME**: Path to the plugin file. Use the absolute path or the path relative to the current working directory, such as `/.py`. ## Options |Option| Flag | Description | |------|-------------------|----------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | URL of the running InfluxDB 3 Core server
(default: `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database you want to test the plugin against | | | `--token` | *(Required)* Authentication token | | |`--input-arguments`|Comma-separated list of `key=value` pairs to pass as plugin input arguments (for example, `key1=val1,key2=val2`)| | | `--schedule` | Cron schedule to simulate when testing the plugin
(default: `* * * * *`) | | | `--cache-name` | Optional cache name to associate with the test | | | `--tls-ca` | Path to a custom TLS certificate authority for self-signed certs | | | `--tls-no-verify` | Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Show basic help information | | | `--help-all` | Show all available help options | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable |Corresponding Option| |-------------------------|--------------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | | `INFLUXDB3_TLS_CA` | `--tls-ca` | |`INFLUXDB3_TLS_NO_VERIFY`| `--tls-no-verify` | ## Examples In the examples below, replace the following: * `DATABASE_NAME`: Your target database * `AUTH_TOKEN`: Your authentication token * `PLUGIN_DIR`: the path to the plugin directory you provided when starting the server * `FILENAME`: Plugin file name ### Test a schedule plugin ```bash influxdb3 test schedule_plugin \ --database DATABASE_NAME \ --token AUTH_TOKEN \ PLUGIN_DIR/FILENAME.py ``` ### Test with input arguments and a custom cron schedule You can pass input arguments to your plugin as key-value pairs and specify a custom cron schedule (using Quartz cron syntax with six fields): ```bash influxdb3 test schedule_plugin \ --host http://localhost:8182 \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --input-arguments threshold=10,unit=seconds \ --schedule "0 0 * * * ?" \ PLUGIN_DIR/FILENAME.py ``` * Pass plugin parameters using `--input-arguments` as comma-separated key=value pairs. * Use `--schedule` to set the plugin’s execution time with a Quartz cron expression. For example, “0 0 \* \* \* ?” runs the plugin at the start of every hour. | Option | Flag | Description | | --- | --- | --- | | Option | Flag | Description | | -H | --host | URL of the running InfluxDB 3 Core server (default: http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database you want to test the plugin against | | | --token | ( Required ) Authentication token | | | --input-arguments | Comma-separated list of key=value pairs to pass as plugin input arguments (for example, key1=val1,key2=val2 ) | | | --schedule | Cron schedule to simulate when testing the plugin (default: * * * * * ) | | | --cache-name | Optional cache name to associate with the test | | | --tls-ca | Path to a custom TLS certificate authority for self-signed certs | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Show basic help information | | | --help-all | Show all available help options | | Environment Variable | Corresponding Option | | --- | --- | | Environment Variable | Corresponding Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_CA | --tls-ca | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 test wal_plugin Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/test/wal_plugin/ The `influxdb3 test wal_plugin` command tests a write-ahead log (WAL) plugin. ## Usage ```bash influxdb3 test wal_plugin [OPTIONS] --database ``` ## Arguments * **PLUGIN\_NAME**: The name of the plugin file on the server–for example:`/.py` ## Options |Option| | Description | |------|-------------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | | `--lp` | Line protocol to use as input | | | `--file` | Line protocol file to use as input | | |`--input-arguments`| Comma-separated list of `key=value` pairs to pass as plugin input arguments | | | `--cache-name` | Name of the cache to use in the test | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | `--tls-no-verify` |Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | | `INFLUXDB3_TLS_CA` | `--tls-ca` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Test a WAL plugin](#test-a-wal-plugin) * [Test a WAL plugin with a line protocol string](#test-a-wal-plugin-with-a-line-protocol-string) * [Test a WAL plugin with a file containing line protocol](#test-a-wal-plugin-with-a-file-containing-line-protocol) * [Test a WAL plugin using input arguments](#test-a-wal-plugin-using-input-arguments) In the examples below, replace the following: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `PLUGIN_DIR`: Plugin directory name * `PLUGIN_NAME`: Plugin file name ### Test a WAL plugin ```bash influxdb3 test wal_plugin \ --database DATABASE_NAME \ --token AUTH_TOKEN \ PLUGIN_DIR/PLUGIN_NAME.py ``` ### Test a WAL plugin with a line protocol string ```bash influxdb3 test wal_plugin \ --lp 'home,room=Kitchen temp=21.0,hum=35.9,co=0i' \ --database DATABASE_NAME \ --token AUTH_TOKEN \ PLUGIN_DIR/PLUGIN_NAME.py ``` ### Test a WAL plugin with a file containing line protocol ```bash influxdb3 test wal_plugin \ --file PLUGIN_DIR/PLUGIN_NAME_test/input-file.lp` --database DATABASE_NAME \ --token AUTH_TOKEN \ PLUGIN_DIR/PLUGIN_NAME.py ``` ### Test a WAL plugin using input arguments ```bash influxdb3 test wal_plugin \ --input-arguments arg1=foo,arg2=baz \ --database DATABASE_NAME \ --token AUTH_TOKEN \ PLUGIN_DIR/PLUGIN_NAME.py ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | | --lp | Line protocol to use as input | | | --file | Line protocol file to use as input | | | --input-arguments | Comma-separated list of key=value pairs to pass as plugin input arguments | | | --cache-name | Name of the cache to use in the test | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_CA | --tls-ca | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 update Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/update/ The `influxdb3 update` command updates resources in your InfluxDB 3 Core instance. ## Usage ```bash influxdb3 update ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------------|----------------------------------------------| |[database](/influxdb3/core/reference/cli/influxdb3/update/database/)| Update a database | | [trigger](/influxdb3/core/reference/cli/influxdb3/update/trigger/) | Update a trigger | | help |Print command help or the help of a subcommand| ## Options |Option| | Description | |------|------------|-------------------------------| | `-h` | `--help` | Print help information | | |`--help-all`|Print detailed help information| | Subcommand | Description | | --- | --- | | Subcommand | Description | | database | Update a database | | trigger | Update a trigger | | help | Print command help or the help of a subcommand | | Option | | Description | | --- | --- | --- | | Option | | Description | | -h | --help | Print help information | | | --help-all | Print detailed help information | --- # influxdb3 update database Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/update/database/ The `influxdb3 update database` command updates an existing database in your InfluxDB 3 Core instance. > [!Note] > InfluxDB 3 Core does not support updating database retention periods. > Retention periods can only be set when [creating a database](/influxdb3/core/admin/databases/create/)and cannot be changed afterward. ## Usage ```bash influxdb3 update database [OPTIONS] --database ``` ## Arguments * **`DATABASE_NAME`**: (Required) The name of the database to update. You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environment variable. ## Options |Option| | Description | |------|-----------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | The name of the database to update | | | `--token` | Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify`|Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables instead of providing CLI options directly: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | | `INFLUXDB3_TLS_CA` | `--tls-ca` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | The name of the database to update | | | --token | Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_CA | --tls-ca | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 update trigger Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/update/trigger/ The `influxdb3 update trigger` command updates an existing trigger in your InfluxDB 3 Core instance. Use this command to update trigger plugin code, configuration, or behavior without recreating the trigger. This preserves trigger history and configuration while allowing you to iterate on plugin development. ## Usage ```bash influxdb3 update trigger [OPTIONS] \ --database \ --trigger-name ``` ## Arguments * **`DATABASE_NAME`**: (Required) The name of the database containing the trigger. * **`TRIGGER_NAME`**: (Required) The name of the trigger to update. ## Options |Option| | Description | |------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database containing the trigger | | | `--trigger-name` | *(Required)* Name of the trigger to update | | `-p` | `--path` |Path to plugin file or directory (single `.py` file or directory containing `__init__.py` for multifile plugins). Can be local path (with `--upload`) or server path.| | | `--upload` | Upload local plugin files to the server. Requires admin token. Use with `--path` to specify local files. | | |`--trigger-arguments`| Additional arguments for the trigger, in the format `key=value`, separated by commas (for example, `arg1=val1,arg2=val2`) | | | `--disabled` | Set the trigger state to disabled | | | `--enabled` | Set the trigger state to enabled | | | `--error-behavior` | Error handling behavior: `log`, `retry`, or `disable` | | | `--token` | Authentication token | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | `--tls-no-verify` | Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables instead of providing CLI options directly: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | | `INFLUXDB3_TLS_CA` | `--tls-ca` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples The following examples show how to update triggers in different scenarios. * [Update trigger plugin code](#update-trigger-plugin-code) * [Upload and update with a local plugin](#upload-and-update-with-a-local-plugin) * [Update trigger arguments](#update-trigger-arguments) * [Enable or disable a trigger](#enable-or-disable-a-trigger) * [Update error handling behavior](#update-error-handling-behavior) Replace the following placeholders with your values: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `TRIGGER_NAME`: Name of the trigger to update ### Update trigger plugin code Update a trigger to use modified plugin code from the server’s plugin directory. ```bash influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --path "my_plugin.py" \ --token AUTH_TOKEN ``` ### Upload and update with a local plugin Upload new plugin code from your local machine and update the trigger in a single operation. Requires admin token. ```bash # Upload single-file plugin influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --path "/local/path/to/updated_plugin.py" \ --upload \ --token AUTH_TOKEN # Upload multifile plugin directory influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --path "/local/path/to/plugin_directory" \ --upload \ --token AUTH_TOKEN ``` The `--upload` flag transfers local files to the server’s plugin directory, making it easy to iterate on plugin development without manual file copying. ### Update trigger arguments Modify the arguments passed to a trigger’s plugin code. ```bash influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --trigger-arguments threshold=100,window=5m \ --token AUTH_TOKEN ``` ### Enable or disable a trigger Change the trigger’s enabled state without modifying other configuration. ```bash # Disable a trigger influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --disabled \ --token AUTH_TOKEN # Enable a trigger influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --enabled \ --token AUTH_TOKEN ``` ### Update error handling behavior Change how the trigger responds to errors. ```bash # Log errors without retrying influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --error-behavior log \ --token AUTH_TOKEN # Retry on errors influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --error-behavior retry \ --token AUTH_TOKEN # Disable trigger on error influxdb3 update trigger \ --database DATABASE_NAME \ --trigger-name TRIGGER_NAME \ --error-behavior disable \ --token AUTH_TOKEN ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database containing the trigger | | | --trigger-name | ( Required ) Name of the trigger to update | | -p | --path | Path to plugin file or directory (single .py file or directory containing __init__.py for multifile plugins). Can be local path (with --upload ) or server path. | | | --upload | Upload local plugin files to the server. Requires admin token. Use with --path to specify local files. | | | --trigger-arguments | Additional arguments for the trigger, in the format key=value , separated by commas (for example, arg1=val1,arg2=val2 ) | | | --disabled | Set the trigger state to disabled | | | --enabled | Set the trigger state to enabled | | | --error-behavior | Error handling behavior: log , retry , or disable | | | --token | Authentication token | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_CA | --tls-ca | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # influxdb3 write Source: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/write/ The `influxdb3 write` command writes data to your InfluxDB 3 Core server. ## Usage ```bash influxdb3 write [OPTIONS] --database [LINE_PROTOCOL]... ``` ##### Aliases `write`, `w` ## Arguments * **LINE\_PROTOCOL**: The line protocol to write to InfluxDB 3 Core. Provide the line protocol in one of the following ways: * a string * a path to a file that contains the line protocol using the `--file` option * from stdin ## Options |Option| | Description | |------|------------------|-------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-f` | `--file` | A file that contains line protocol to write | | |`--accept-partial`| Accept partial writes | | | `--no-sync` | Do not wait for WAL sync before acknowledging the write request | | | `--precision` | Precision of data timestamps (`ns`, `us`, `ms`, or `s`) | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | |`--tls-no-verify` |Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates)| | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples * [Write line protocol to your InfluxDB 3 server](#write-line-protocol-to-your-influxdb-3-server) * [Write line protocol and accept partial writes](#write-line-protocol-and-accept-partial-writes) * [Write line protocol with specific timestamp precision](#write-line-protocol-with-specific-timestamp-precision) * [Write line protocol and immediately return a response](#write-line-protocol-and-immediately-return-a-response) In the examples below, replace the following: * `DATABASE_NAME`: the name of the database to query * `AUTH_TOKEN`: Authentication token ### Write line protocol to your InfluxDB 3 server #### string #### ```bash influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000' ``` ```bash influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./data.lp ``` ```bash cat ./data.lp | influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN ``` ### Write line protocol and accept partial writes #### string #### ```bash influxdb3 write \ --accept-partial \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000' ``` ```bash influxdb3 write \ --accept-partial \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./data.lp ``` ```bash cat ./data.lp | influxdb3 write \ --accept-partial \ --database DATABASE_NAME \ --token AUTH_TOKEN ``` ### Write line protocol with specific timestamp precision By default, in CLI and HTTP API write requests, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision. To avoid any ambiguity, specify the `--precision {ns|us|ms|s}` option: ```bash influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --precision s \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 ' ``` ### Write line protocol and immediately return a response By default, InfluxDB 3 Core waits to respond to write requests until the written data is flushed from the Write-Ahead Log (WAL) to object storage (every 1s by default). Use the `--no-sync` option to immediately return a response without waiting for the WAL to flush. This improves perceived write response times, but may hide certain types of write errors–for example: malformed line protocol or type conflicts. > [!Tip] > Only use `--no-sync` when low write latency is more important than guaranteed data durability. > Avoid using this option for critical or irreplaceable data, as it increases the risk of silent data loss. ```bash influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --no-sync \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000' ``` | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -f | --file | A file that contains line protocol to write | | | --accept-partial | Accept partial writes | | | --no-sync | Do not wait for WAL sync before acknowledging the write request | | | --precision | Precision of data timestamps ( ns , us , ms , or s ) | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify | --- # InfluxDB API client libraries Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/ InfluxDB client libraries are language-specific packages that integrate with InfluxDB APIs. ### [Apache Arrow Flight RPC clients](/influxdb3/core/reference/client-libraries/flight/) Flight clients are language-specific drivers that can interact with Flight servers using the Arrow in-memory format and the Flight RPC framework. View the list of available clients. ### [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) InfluxDB 3 client libraries use InfluxDB HTTP APIs to write data and use [Flight clients](/influxdb3/core/reference/client-libraries/flight-sql) to execute SQL and InfluxQL queries. View the list of available client libraries. ### [InfluxDB v2 API client libraries](/influxdb3/core/reference/client-libraries/v2/) InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/api/buckets-v2-compatible/). View the list of available client libraries. ### [InfluxDB v1 client libraries](/influxdb3/core/reference/client-libraries/v1/) InfluxDB v1 client libraries use the InfluxDB 1.7 API and should be fully compatible with InfluxDB 1.5+. View the list of available client libraries. [client libraries](/influxdb3/core/tags/client-libraries/)[API](/influxdb3/core/tags/api/)[developer tools](/influxdb3/core/tags/developer-tools/) --- # Apache Arrow Flight RPC clients Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/ Flight RPC and Flight SQL clients are language-specific drivers that interact with databases using the Arrow in-memory format and the Flight RPC protocol. Apache Arrow Flight RPC and Flight SQL protocols define APIs for servers and clients. > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) for integrating InfluxDB 3 with your application code. > Client libraries wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/client-libraries), and processing data stored in InfluxDB 3 Core. **Flight RPC clients** can use SQL or InfluxQL to query data stored in an InfluxDB 3 Core database. Using InfluxDB 3’s IOx-specific Flight RPC protocol, clients send a single `DoGet()` request to authenticate, query, and retrieve data. **Flight SQL clients** use the [Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) for querying an SQL database server. They can use SQL to query data stored in an InfluxDB 3 Core database, but they can’t use InfuxQL. > [!Important] > #### Flight SQL requires HTTP/2 > > Flight SQL uses gRPC, which requires **HTTP/2**. > If you connect to InfluxDB 3 Core through a proxy (such as HAProxy, nginx, or a load balancer), > verify that your proxy is configured to support HTTP/2. > Without HTTP/2 support, Flight SQL connections will fail. Clients are maintained by Apache Arrow projects or third-parties. For specifics about a Flight client, see the client’s GitHub repository. ### [C# .NET Flight client](/influxdb3/core/reference/client-libraries/flight/csharp-flight/) The C# .NET Flight client integrates with C# .NET scripts and applications to query data stored in InfluxDB. ### [Go Flight client](/influxdb3/core/reference/client-libraries/flight/go-flight/) The Go Flight client integrates with Go scripts and applications to query data stored in InfluxDB. ### [Java Flight SQL package](/influxdb3/core/reference/client-libraries/flight/java-flightsql/) The Java Flight SQL client integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL. ```java public class Query { public static void main(String[] args) { String query = "SELECT * FROM home"; Location location = Location.forGrpcTls(HOST, 443); CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN)); BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE); FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() { @Override public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) { outgoingHeaders.insert(DATABASE_FIELD, DATABASE_NAME); } }; FlightClient client = FlightClient.builder(allocator, location) .intercept(f) .build(); FlightSqlClient sqlClient = new FlightSqlClient(client); FlightInfo flightInfo = sqlClient.execute(query, auth); } } ``` ### [Python Flight client](/influxdb3/core/reference/client-libraries/flight/python-flight/) The Python Flight client integrates with Python scripts and applications to query data stored in InfluxDB. ``` from pyarrow.flight import FlightClient, Ticket, FlightCallOptions import json import pandas import tabulate # Downsampling query groups data into 2-hour bins sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', avg(temp) AS 'average temp' FROM home GROUP BY 1, room ORDER BY room, 1""" flight_ticket = Ticket(json.dumps({ "namespace_name": "DATABASE_NAME", "sql_query": sql, "query_type": "sql" })) token = (b"authorization", bytes(f"Bearer AUTH_TOKEN".encode('utf-8'))) options = FlightCallOptions(headers=[token]) client = FlightClient(f"grpc+tls://localhost:8181:443") reader = client.do_get(flight_ticket, options) arrow_table = reader.read_all() ``` ### [Python Flight SQL DBAPI client](/influxdb3/core/reference/client-libraries/flight/python-flightsql-dbapi/) The Python `flightsql-dbapi` library uses SQL and the Flight SQL protocol to query data stored in an InfluxDB Core database. [client libraries](/influxdb3/core/tags/client-libraries/)[Flight RPC](/influxdb3/core/tags/flight-rpc/)[Flight SQL](/influxdb3/core/tags/flight-sql/) --- # C# .NET Flight client Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/csharp-flight/ [Apache Arrow for C# .NET](https://github.com/apache/arrow/blob/main/csharp/README.md) integrates with C# .NET scripts and applications to query data stored in InfluxDB. For more information, see the [C# client example on GitHub](https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample). > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using the [`influxdb3-csharp` C# client library](/influxdb3/core/reference/client-libraries/v3/csharp/) for integrating InfluxDB 3 with your C# application code. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/api-client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/), and processing data stored in InfluxDB 3 Core. > Client libraries can query using SQL or InfluxQL. [gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # Go Flight client Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/go-flight/ [Apache Arrow for Go](https://pkg.go.dev/github.com/apache/arrow/go/v12) integrates with Go scripts and applications to query data stored in InfluxDB. > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using the [`influxdb3-go` Go client library](/influxdb3/core/reference/client-libraries/v3/go/) for integrating InfluxDB 3 with your Go application code. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/api-client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/), and processing data stored in InfluxDB 3 Core. > Client libraries can query using SQL or InfluxQL. ## Flight SQL client ### Example query using Flight SQL The following example shows how to use the Arrow Flight SQL client for Go to query an InfluxDB 3 Core database: 1. In your editor, open a new file named `query.go` and enter the following sample code: ``` package main import ( "context" "crypto/x509" "encoding/json" "fmt" "os" "github.com/apache/arrow/go/v14/arrow/flight/flightsql" "google.golang.org/grpc" "google.golang.org/grpc/credentials" "google.golang.org/grpc/metadata" ) func dbQuery(ctx context.Context) error { url := "localhost:8181:443" // INFLUX_TOKEN is an environment variable you created for your database READ token token := os.Getenv("INFLUX_TOKEN") database := "get-started" // Create a gRPC transport pool, err := x509.SystemCertPool() if err != nil { return fmt.Errorf("x509: %s", err) } transport := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(pool, "")) opts := []grpc.DialOption{ transport, } // Create query client client, err := flightsql.NewClient(url, nil, nil, opts...) if err != nil { return fmt.Errorf("flightsql: %s", err) } ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token) ctx = metadata.AppendToOutgoingContext(ctx, "database", database) // Execute query query := `SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z'` info, err := client.Execute(ctx, query) if err != nil { return fmt.Errorf("flightsql flight info: %s", err) } reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket) if err != nil { return fmt.Errorf("flightsql do get: %s", err) } // Print results as JSON for reader.Next() { record := reader.Record() b, err := json.MarshalIndent(record, "", " ") if err != nil { return err } fmt.Println("RECORD BATCH") fmt.Println(string(b)) if err := reader.Err(); err != nil { return fmt.Errorf("flightsql reader: %s", err) } } return nil } func main() { if err := dbQuery(context.Background()); err != nil { fmt.Fprintf(os.Stderr, "error: %v\n", err) os.Exit(1) } } ``` The sample does the following: 1. Imports the following packages: * `context` * `crypto/x509` * `encoding/json` * `fmt` * `os` * `github.com/apache/arrow/go/v14/arrow/flight/flightsql` * `google.golang.org/grpc` * `google.golang.org/grpc/credentials` * `google.golang.org/grpc/metadata` 2. Creates a `dbQuery` function that does the following: 1. Defines variables for InfluxDB credentials. * **`url`**: InfluxDB 3 Core cluster hostname and port (`:443`) *(no protocol)* * **`database`**: the name of the InfluxDB 3 Core database to query * **`token`**: a [database token](/influxdb3/core/admin/tokens/database/) with read permission on the specified database.*For security reasons, we recommend setting this as an environment variable rather than including the raw token string.* 2. Defines an `opts` options list that includes a gRPC transport for communicating with InfluxDB over the *gRPC+TLS* protocol. 3. Calls the `flightsql.NewClient()` method with `url` and `opts` to create a new Flight SQL client. 4. Appends the following InfluxDB credentials as key-value pairs to the outgoing context: * **`authorization`**: Bearer \ * **`database`**: Database name 5. Defines the SQL query to execute. 6. Calls the `client.execute()` method to send the query request. 7. Calls the `client.doGet()` method with the *ticket* from the query response to retrieve result data from the endpoint. 8. Creates a reader to read the Arrow table returned by the endpoint and print the results as JSON. 3. Creates a `main` module function that executes the `dbQuery` function. 2. Enter the following commands to install all the necessary packages and run the program to query InfluxDB 3 Core: ``` go get ./... go run ./query.go ``` [](#view-program-output) View program output ```text RECORD BATCH [ { "co": 0, "hum": 35.9, "room": "Kitchen", "temp": 21, "time": "2022-01-01 08:00:00" }, { "co": 0, "hum": 36.2, "room": "Kitchen", "temp": 23, "time": "2022-01-01 09:00:00" }, { "co": 0, "hum": 36.1, "room": "Kitchen", "temp": 22.7, "time": "2022-01-01 10:00:00" }, { "co": 0, "hum": 36, "room": "Kitchen", "temp": 22.4, "time": "2022-01-01 11:00:00" }, { "co": 0, "hum": 36, "room": "Kitchen", "temp": 22.5, "time": "2022-01-01 12:00:00" }, ... ] ``` For more information, see the [Go Arrow Flight Client documentation](https://pkg.go.dev/github.com/apache/arrow/go/v14/arrow/flight#Client). #### Related * [Go client library for InfluxDB 3](/influxdb3/core/reference/client-libraries/v3/go/) [Flight client](/influxdb3/core/tags/flight-client/)[Go](/influxdb3/core/tags/go/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # Java Flight SQL package Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/java-flightsql/ [Apache Arrow Flight SQL for Java](https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html) integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL. > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using the [`influxdb3-java` Java client library](/influxdb3/core/reference/client-libraries/v3/java/) for integrating InfluxDB 3 with your Java application code. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/api-client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/), and processing data stored in InfluxDB 3 Core. > Client libraries can query using SQL or InfluxQL. * [Get started using the Java Flight SQL client to query InfluxDB](#get-started-using-the-java-flight-sql-client-to-query-influxdb) * [Set up InfluxDB](#set-up-influxdb) * [Install prerequisites](#install-prerequisites) * [Create the FlightQuery class](#create-the-flightquery-class) * [Create a query client](#create-a-query-client) * [Execute a query](#execute-a-query) * [Retrieve and process Arrow data](#retrieve-and-process-arrow-data) * [Run the application](#run-the-application) * [Troubleshoot Arrow Flight requests](#troubleshoot-arrow-flight-requests) ## Get started using the Java Flight SQL client to query InfluxDB Write a Java class for a Flight SQL client that connects to InfluxDB 3 Core, executes an SQL query, and retrieves data stored in an InfluxDB 3 Core database. The example uses the [Apache Arrow Java implementation (`org.apache.arrow`)](https://arrow.apache.org/docs/java/index.html) for interacting with Flight database servers like InfluxDB 3. * **`org.apache.arrow`**: Provides classes and methods for integrating Java applications with Apache Arrow data and protocols. * **`org.apache.arrow.flight.sql`**: Provides classes and methods for interacting with Flight database servers using Arrow Flight RPC and Flight SQL. 1. [Set up InfluxDB](#set-up-influxdb) 2. [Install prerequisites](#install-prerequisites) 3. [Create the FlightQuery class](#create-the-flightquery-class) 4. [Create a query client](#create-a-query-client) 5. [Execute a query](#execute-a-query) 6. [Retrieve and process Arrow data](#retrieve-and-process-arrow-data) To clone or download the example application that you can run with Docker, see the [InfluxCommunity/ArrowFlightClient\_Query\_Examples repository](https://github.com/InfluxCommunity/ArrowFlightClient_Query_Examples) on GitHub. ### Set up InfluxDB To configure the application for querying InfluxDB 3 Core, you’ll need the following InfluxDB resources: * InfluxDB 3 Core **database** * InfluxDB 3 Core **database token** with *read* permission to the database If you don’t already have a database token and a database, see how to [set up InfluxDB](/influxdb3/core/get-started/setup/). If you don’t already have data to query, see how to[write data](/influxdb3/core/get-started/write/) to a database. ### Install prerequisites The following uses Docker and Maven to build and run the Java application and avoid platform-specific dependency problems. The example `Dockerfile` installs compatible versions of Maven and Java JDK in the Docker container, and then runs the Maven commands to download dependencies and compile the application. Follow the instructions to download and install Docker for your system: * **macOS**: [Install Docker for macOS](https://docs.docker.com/desktop/install/mac-install/) * **Linux**: [Install Docker for Linux](https://docs.docker.com/desktop/install/linux-install/) [](#view-the-dockerfile) View the Dockerfile ```dockerfile # Use the official Maven image as the base image FROM maven:3.8.3-openjdk-11 AS build # Set the working directory WORKDIR /app # Copy the pom.xml file into the container COPY pom.xml . # Download and cache dependencies RUN mvn dependency:go-offline # Copy the rest of the source code into the container COPY src/ ./src/ # Compile the source code and copy dependencies RUN mvn compile dependency:copy-dependencies # Use the official OpenJDK image as the runtime base image FROM openjdk:11-jre-slim # Set the working directory WORKDIR /app # Copy the compiled classes and dependencies from the build stage COPY --from=build /app/target/classes ./classes COPY --from=build /app/target/dependency ./dependency # Set ARGs for --build-arg options passed in the build command ARG DATABASE_FIELD ARG DATABASE_NAME ARG HOST ARG TOKEN # Set run-time ENVs from ARGs ENV DATABASE_FIELD=${DATABASE_FIELD} ENV DATABASE_NAME=${DATABASE_NAME} ENV HOST=${HOST} ENV TOKEN=${TOKEN} # Set the entrypoint to run your Java application ENTRYPOINT ["java", "-cp", "classes:dependency/*", "com.influxdb.examples.FlightExamples"] ``` [](#view-the-maven-pomxml) View the Maven pom.xml ```xml 4.0.0 com.influxdb examples 1.0-SNAPSHOT org.apache.maven.plugins maven-jar-plugin 3.2.0 true lib/ com.influxdb.examples.FlightExamples org.apache.maven.plugins maven-help-plugin 3.2.0 org.apache.maven.plugins maven-shade-plugin 3.4.1 shade true false *:* META-INF/*.SF META-INF/*.DSA META-INF/*.RSA 1.8 1.8 org.apache.arrow flight-sql 11.0.0 io.netty netty-all 4.1.74.Final org.slf4j slf4j-simple 1.7.30 ``` ### Create the FlightQuery class [](#view-flightqueryjava) View FlightQuery.java ``` package com.influxdb.examples; import org.apache.arrow.flight.auth2.BearerCredentialWriter; import org.apache.arrow.flight.CallHeaders; import org.apache.arrow.flight.CallStatus; import org.apache.arrow.flight.grpc.CredentialCallOption; import org.apache.arrow.flight.Location; import org.apache.arrow.flight.FlightClient; import org.apache.arrow.flight.FlightClientMiddleware; import org.apache.arrow.flight.FlightInfo; import org.apache.arrow.flight.FlightStream; import org.apache.arrow.flight.sql.FlightSqlClient; import org.apache.arrow.flight.Ticket; import org.apache.arrow.memory.BufferAllocator; import org.apache.arrow.memory.RootAllocator; import org.apache.arrow.vector.VectorSchemaRoot; public class FlightQuery { /* Get server credentials from environment variables */ public static final String DATABASE_NAME = System.getenv("DATABASE_NAME"); public static final String HOST = System.getenv("HOST"); public static final String TOKEN = System.getenv("TOKEN"); public static void main() { System.out.println("Query InfluxDB with the Java Flight SQL Client"); // Create an interceptor that injects header metadata (database name) in every request. FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() { @Override public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) { outgoingHeaders.insert("database", DATABASE_NAME); } @Override public void onHeadersReceived(CallHeaders incomingHeaders) { } @Override public void onCallCompleted(CallStatus status) { } }; // Create a gRPC+TLS channel URI with HOST and port 443. Location location = Location.forGrpcTls(HOST, 443); // Set the allowed memory. BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE); // Create a client with the allocator and gRPC channel. FlightClient client = FlightClient.builder(allocator, location) .intercept(f) .build(); System.out.println("client" + client); FlightSqlClient sqlClient = new FlightSqlClient(client); System.out.println("sqlClient: " + sqlClient); // Define the SQL query to execute. String query = "SELECT * FROM home"; /* Construct a bearer credential using TOKEN. Construct a credentials option using the bearer credential. */ CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN)); /* Execute the query. If successful, execute returns a FlightInfo object that contains metadata and an endpoints list. Each endpoint contains the following: - A list of addresses where you can retrieve the data. - A `ticket` value that identifies the data to retrieve. */ FlightInfo flightInfo = sqlClient.execute(query, auth); // Extract the Flight ticket from the response. Ticket ticket = flightInfo.getEndpoints().get(0).getTicket(); // Pass the ticket to request the Arrow stream data from the endpoint. final FlightStream stream = sqlClient.getStream(ticket, auth); // Process all the Arrow stream data. while (stream.next()) { try { // Get the current vector data from the stream. final VectorSchemaRoot root = stream.getRoot(); System.out.println(root.contentToTSVString()); } catch (Exception e) { // Handle exceptions. System.out.println("Error executing FlightSqlClient: " + e.getMessage()); } } try { // Close the stream and release resources. stream.close(); } catch (Exception e) { // Handle exceptions. System.out.println("Error closing stream: " + e.getMessage()); } try { // Close the client sqlClient.close(); } catch (Exception e) { // Handle exceptions. System.out.println("Error closing client: " + e.getMessage()); } } } ``` 1. In your `/src/main/java` directory, create the `com/influxdb/examples` subdirectories for the `com.influxdb.examples` package. 2. In the `examples` directory from the preceding step, create the `FlightQuery.java` class file. You should have the following directory structure: ``` PROJECT_ROOT └──src └──main └──java └──com └──influxdb └──examples └──FlightQuery.java ``` 3. In `FlightQuery.java`: 1. Add the package name: ``` package com.influxdb.examples; ``` 2. Add `import` statements for the following packages. You’ll use classes and methods from these packages in the remaining steps: * `org.apache.arrow.flight.auth2.BearerCredentialWriter` * `org.apache.arrow.flight.CallHeaders` * `org.apache.arrow.flight.CallStatus` * `org.apache.arrow.flight.grpc.CredentialCallOption` * `org.apache.arrow.flight.Location` * `org.apache.arrow.flight.FlightClient` * `org.apache.arrow.flight.FlightClientMiddleware` * `org.apache.arrow.flight.FlightInfo` * `org.apache.arrow.flight.FlightStream` * `org.apache.arrow.flight.sql.FlightSqlClient` * `org.apache.arrow.flight.Ticket` * `org.apache.arrow.memory.BufferAllocator` * `org.apache.arrow.memory.RootAllocator` * `org.apache.arrow.vector.VectorSchemaRoot` 3. Create a `FlightQuery` class. 4. In the `FlightQuery` class: 1. Define constants for server credentials. * `DATABASE_NAME` * `HOST` * `TOKEN` *The example `Dockerfile` defines environment variables for these credentials.* 2. Create a `main()` method. ### Create a query client In the `FlightQuery.main()` method, do the following to create an SQL client that can connect to `HOST` and `DATABASE_NAME`: 1. Construct a *gRPC+TLS* channel URI with `HOST` and port `443` for communicating with a [gRPC server over TLS](https://grpc.io/docs/guides/auth/#with-server-authentication-ssltls-4). 2. Instantiate `FlightClientMiddleware` and define an event callback that inserts the following Flight request metadata header property: ``` { "database": "DATABASE_NAME" } ``` 3. Instantiate a `BufferAllocator` that sets the memory allowed for the client. 4. Create a `FlightClient` with the allocator and gRPC channel. 5. Instantiate a `FlightSqlClient` that wraps the `FlightClient` instance. ### Execute a query In the `FlightQuery.main` method: 1. Instantiate a `CredentialCallOption` with `TOKEN` as a *bearer* credential. The result is a credential object that you’ll pass in each request to the server. 2. Define a string that contains the SQL query to execute–for example: ``` String query = "SELECT * FROM home"; ``` 3. Call the `FlightSqlClient.execute` method with the SQL query and the `CredentialCallOption`. 4. If successful, the `FlightSqlClient.execute` method responds with a `FlightInfo` object that contains metadata and an `endpoints: [...]` list. Each endpoint contains the following: * A list of addresses where you can retrieve the data. * A `ticket` value that identifies the data to retrieve. 5. Extract the ticket from the response. ### Retrieve and process Arrow data In the `FlightQuery.main()` method, do the following to retrieve the data stream described in the `FlightInfo` response: 1. Call the `FlightSqlClient.getStream` method with the *ticket* and the `CredentialCallOption` to fetch the [Arrow stream](https://arrow.apache.org/docs/format/CStreamInterface.html). 2. Call the `FlightStream.getRoot` method to get the current vector data from the stream. 3. Process the data and handle exceptions. The example converts the vector data into tab-separated values and prints the result to `System.out`. For more examples using Java to work with Arrow data, see the [Apache Arrow Java Cookbook](https://arrow.apache.org/cookbook/java/). 4. Finally, close the stream and client. ### Run the application Follow these steps to build and run the application using Docker: 1. Copy the `Dockerfile` and `pom.xml` to your project root directory. 2. Open a terminal in your project root directory. 3. In your terminal, run the `docker build` command and pass `--build-arg` flags for the server credentials: * **`DATABASE_NAME`**: your [InfluxDB 3 Core database](/influxdb3/core/admin/databases/) * **`HOST`**: your InfluxDB 3 Core hostname (URL without the “https://”) * **`TOKEN`**: your [InfluxDB 3 Core database token](/influxdb3/core/get-started/setup/) with *read* permission to the database ``` docker build \ --build-arg DATABASE_NAME=INFLUX_DATABASE \ --build-arg HOST=localhost:8181\ --build-arg TOKEN=INFLUX_TOKEN \ -t javaflight . ``` The command builds a Docker image named `javaflight`. 4. To run the application in a new Docker container, enter the following command: ``` docker run javaflight ``` The output is the query data in TSV-format. ## Troubleshoot Arrow Flight requests For the list of Arrow Flight error response codes, see the [Arrow Flight RPC documentation](https://arrow.apache.org/docs/format/Flight.html#error-handling). #### Related * [Java client library for InfluxDB 3](/influxdb3/core/reference/client-libraries/v3/java/) [Flight client](/influxdb3/core/tags/flight-client/)[Java](/influxdb3/core/tags/java/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/) --- # Python Flight client Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/python-flight/ [Apache Arrow Python bindings](https://arrow.apache.org/docs/python/index.html) integrate with Python scripts and applications to query data stored in InfluxDB. > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using the [`influxdb3-python` Python client library](/influxdb3/core/reference/client-libraries/v3/python/) for integrating InfluxDB 3 with your Python application code. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/api-client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/), and processing data stored in InfluxDB 3 Core. > Client libraries can query using SQL or InfluxQL. The following examples show how to use the `pyarrow.flight` and `pandas` Python modules to query and format data stored in an InfluxDB 3 Core database: [SQL](#sql-python)[InfluxQL](#influxql-python) ``` # Using pyarrow>=12.0.0 FlightClient from pyarrow.flight import FlightClient, Ticket, FlightCallOptions import json import pandas import tabulate # Downsampling query groups data into 2-hour bins sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time) AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', avg(temp) AS 'average temp' FROM home GROUP BY 1, room ORDER BY room, 1""" flight_ticket = Ticket(json.dumps({ "namespace_name": "DATABASE_NAME", "sql_query": sql, "query_type": "sql" })) token = (b"authorization", bytes(f"Bearer DATABASE_TOKEN".encode('utf-8'))) options = FlightCallOptions(headers=[token]) client = FlightClient(f"grpc+tls://localhost:8181:443") reader = client.do_get(flight_ticket, options) arrow_table = reader.read_all() # Use pyarrow and pandas to view and analyze data data_frame = arrow_table.to_pandas() print(data_frame.to_markdown()) ``` ``` # Using pyarrow>=12.0.0 FlightClient from pyarrow.flight import FlightClient, Ticket, FlightCallOptions import json import pandas import tabulate # Downsampling query groups data into 2-hour bins influxql=""" SELECT FIRST(temp) FROM home WHERE room = 'kitchen' AND time >= now() - 100d AND time <= now() - 10d GROUP BY time(2h)""" flight_ticket = Ticket(json.dumps({ "namespace_name": "DATABASE_NAME", "sql_query": influxql, "query_type": "influxql" })) token = (b"authorization", bytes(f"Bearer DATABASE_TOKEN".encode('utf-8'))) options = FlightCallOptions(headers=[token]) client = FlightClient(f"grpc+tls://localhost:8181:443") reader = client.do_get(flight_ticket, options) arrow_table = reader.read_all() # Use pyarrow and pandas to view and analyze data data_frame = arrow_table.to_pandas() print(data_frame.to_markdown()) ``` Replace the following: * `DATABASE_NAME`: your InfluxDB 3 Core database * `DATABASE_TOKEN`: a [database token](/influxdb3/core/admin/tokens/database/)with sufficient permissions to the specified database [Flight client](/influxdb3/core/tags/flight-client/)[Python](/influxdb3/core/tags/python/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # Python Flight SQL DBAPI client Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/flight/python-flightsql-dbapi/ The [Python `flightsql-dbapi` Flight SQL DBAPI library](https://github.com/influxdata/flightsql-dbapi) integrates with Python applications using SQL to query data stored in an InfluxDB 3 Core database. The `flightsql-dbapi` library uses the [Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) to query and retrieve data. > [!Note] > #### Use InfluxDB 3 client libraries > > We recommend using the [`influxdb3-python` Python client library](/influxdb3/core/reference/client-libraries/v3/python/) for integrating InfluxDB 3 with your Python application code. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) wrap Apache Arrow Flight clients > and provide convenient methods for [writing](/influxdb3/core/write-data/api-client-libraries/), [querying](/influxdb3/core/query-data/execute-queries/), and processing data stored in InfluxDB 3 Core. > Client libraries can query using SQL or InfluxQL. ## Installation The [`flightsql-dbapi`](https://github.com/influxdata/flightsql-dbapi) Flight SQL library for Python provides a[DB API 2](https://peps.python.org/pep-0249/) interface and[SQLAlchemy](https://www.sqlalchemy.org/) dialect for[Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html). Installing `flightsql-dbapi` also installs the [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you’ll use for working with Arrow data. In your terminal, use `pip` to install `flightsql-dbapi`: ```sh pip install flightsql-dbapi ``` ## Importing the module The `flightsql-dbapi` package provides the `flightsql` module. From the module, import the `FlightSQLClient` class method: ```py from flightsql import FlightSQLClient ``` * `flightsql.FlightSQLClient` class: an interface for [initializing a client](#initialize-a-client) and interacting with a Flight SQL server. ## API reference * [Class FlightSQLClient](#class-flightsqlclient) * [Syntax](#syntax) * [Initialize a client](#initialize-a-client) * [Instance methods](#instance-methods) * [FlightSQLClient.execute](#flightsqlclientexecute) * [Syntax](#execute-query-syntax) * [Example](#execute-query-example) * [FlightSQLClient.do\_get](#flightsqlclientdo_get) * [Syntax](#retrieve-data-syntax) * [Example](#retrieve-data-example) ## Class FlightSQLClient Provides an interface for [initializing a client](#initialize-a-client) and interacting with a Flight SQL server. ### Syntax ```py __init__(self, host=None, token=None, metadata=None, features=None) ``` Initializes and returns a `FlightSQLClient` instance for interacting with the server. ## Initialize a client The following example shows how to use Python with `flightsql-dbapi`and the *DB API 2* interface to instantiate a Flight SQL client configured for an InfluxDB database. ```py from flightsql import FlightSQLClient # Instantiate a FlightSQLClient configured for a database client = FlightSQLClient(host='localhost:8181', token='DATABASE_TOKEN', metadata={'database': 'DATABASE_NAME'}, features={'metadata-reflection': 'true'}) ``` Replace the following: * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with read permissions on the databases you want to query * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) ### Instance methods ### FlightSQLClient.execute Sends a Flight SQL RPC request to execute the specified SQL Query. #### Syntax ```py execute(query: str, call_options: Optional[FlightSQLCallOptions] = None) ``` #### Example ```py # Execute the query info = client.execute("SELECT * FROM home") ``` The response contains a `flight.FlightInfo` object that contains metadata and an `endpoints: [...]` list. Each endpoint contains the following: * A list of addresses where you can retrieve query result data. * A `ticket` value that identifies the data to [retrieve](#retrieve-data-example). ### FlightSQLClient.do\_get Passes a Flight ticket (obtained from a `FlightSQLClient.execute` response) and retrieves Arrow data identified by the ticket. Returns a `pyarrow.flight.FlightStreamReader` for streaming the data. #### Syntax ``` do_get(ticket, call_options: Optional[FlightSQLCallOptions] = None) ``` #### Example The following sample shows how to use Python with `flightsql-dbapi` and `pyarrow` to query InfluxDB and retrieve data. ```py from flightsql import FlightSQLClient # Instantiate a FlightSQLClient configured for a database client = FlightSQLClient(host='localhost:8181', token='DATABASE_TOKEN', metadata={'database': 'DATABASE_NAME'}, features={'metadata-reflection': 'true'}) # Execute the query to retrieve FlightInfo info = client.execute("SELECT * FROM home") # Extract the token for retrieving data ticket = info.endpoints[0].ticket # Use the ticket to request the Arrow data stream. # Return a FlightStreamReader for streaming the results. reader = client.do_get(ticket) # Read all data to a pyarrow.Table table = reader.read_all() print(table) ``` `do_get(ticket)` returns a [`pyarrow.flight.FlightStreamReader`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightStreamReader.html) for streaming Arrow [record batches](https://arrow.apache.org/docs/python/data.html#record-batches). To read data from the stream, call one of the following `FlightStreamReader` methods: * `read_all()`: Read all record batches as a [`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html). * `read_chunk()`: Read the next RecordBatch and metadata. * `read_pandas()`: Read all record batches and convert them to a [`pandas.DataFrame`](https://pandas.pydata.org/docs/reference/frame.html). [Flight client](/influxdb3/core/tags/flight-client/)[Python](/influxdb3/core/tags/python/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/) --- # InfluxDB v1 client libraries Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v1/ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. Client libraries for InfluxDB v1 work with the InfluxDB 1.7 API and should be fully compatible with InfluxDB 1.5+. > [!Note] > Upgrade to InfluxDB 3 to use new client libraries compatible with InfluxDB write APIs, SQL, and InfluxQL. For more information, see [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/). Functionality varies among client libraries. For specifics about a client library, see the library’s GitHub repository. ## C++ * [influxdb-cxx](https://github.com/offa/influxdb-cxx) ## Elixir * [Instream (instream)](https://github.com/mneudert/instream) ## Erlang * [Erlang InfluxDB UDP Writer](https://github.com/palkan/influx_udp) * [InfluxDB line encoder](https://github.com/Pouriya-Jahanbakhsh/influxdb_encoderl) ## Go * [InfluxDB Client](https://github.com/influxdata/influxdb1-client) ## Haskell * [influxdb-haskell](https://github.com/maoe/influxdb-haskell) ## Java * [influxdb-java](https://github.com/influxdb/influxdb-java) * [Alpakka InfluxDB](https://doc.akka.io/docs/alpakka/current/influxdb.html) * [JFlux](https://github.com/nickRm/jflux) ## JavaScript/Node.js * [node-influx](https://github.com/node-influx/node-influx) ## Lisp * [CL-INFLUXDB](https://github.com/mmaul/cl-influxdb) ## MATLAB * [influxdb-matlab](https://github.com/EnricSala/influxdb-matlab) ## .Net * [InfluxDB.Client.Net](https://github.com/AdysTech/InfluxDB.Client.Net) * Supports .Net and .Net Core * [InfluxData.Net](https://github.com/pootzko/InfluxData.Net) * [InfluxDB Client for .NET](https://github.com/MikaelGRA/InfluxDB.Client) * [InfluxClient](https://github.com/danesparza/InfluxClient) ## Perl * [AnyEvent::InfluxDB](https://github.com/ajgb/anyevent-influxdb) * [InfluxDB-LineProtocol](http://search.cpan.org/~domm/InfluxDB-LineProtocol/) * [InfluxDB::HTTP](https://github.com/raphaelthomas/InfluxDB-HTTP) ## PHP * [influxdb-php](https://github.com/influxdb/influxdb-php) * [InfluxDB PHP SDK (influxdb-php-sdk)](https://github.com/corley/influxdb-php-sdk) ## Python * [InfluxDB-Python (influxdb-python)](https://github.com/influxdb/influxdb-python) R ---------- * [influxdbr](https://cran.r-project.org/web/packages/influxdbr/) ## Ruby * [influxdb-ruby](https://github.com/influxdb/influxdb-ruby) * [Influxer (influxer)](https://github.com/palkan/influxer) ## Rust * [Flux (flux)](https://crates.io/crates/flux) * [Influent (influent)](https://crates.io/crates/influent) ## Scala * [scala-influxdb-client](https://github.com/paulgoldbaum/scala-influxdb-client) * [chronicler](https://github.com/fsanaulla/chronicler) * [Alpakka InfluxDB](https://doc.akka.io/docs/alpakka/current/influxdb.html) ## Sensu * [sensu-influxdb-extension](https://github.com/jhrv/sensu-influxdb-extension) ## SNMP agent * [SnmpCollector (snmpcollector)](https://github.com/toni-moreno/snmpcollector) * A full featured Generic SNMP data collector with Web Administration Interface for InfluxDB. [client libraries](/influxdb3/core/tags/client-libraries/)[API](/influxdb3/core/tags/api/)[developer tools](/influxdb3/core/tags/developer-tools/) --- # InfluxDB v2 API client libraries Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query*stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/)are available that integrate with your code to write and query data stored > in InfluxDB 3 Core. > > InfluxDB 3 supports many different tools for [**writing**](/influxdb3/core/write-data/)and [**querying**](/influxdb3/core/query-data/) data.[**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use)to interact with InfluxDB 3 Core. ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/api/buckets-v2-compatible/). Functionality varies among client libraries. InfluxDB client libraries are maintained by the InfluxDB community. For specifics about a client library, see the library’s GitHub repository. * [Arduino](https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino) *– contributed by [tobiasschuerg](https://github.com/tobiasschuerg)* * [C#](https://github.com/influxdata/influxdb-client-csharp) * [Dart](https://github.com/influxdata/influxdb-client-dart) * [Go](/influxdb3/core/reference/client-libraries/v2/go/) * [Java](https://github.com/influxdata/influxdb-client-java) * [JavaScript](/influxdb3/core/reference/client-libraries/v2/javascript/) * [Kotlin](https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin) * [PHP](https://github.com/influxdata/influxdb-client-php) * [Python](/influxdb3/core/reference/client-libraries/v2/python/) * [R](https://github.com/influxdata/influxdb-client-r) * [Ruby](https://github.com/influxdata/influxdb-client-ruby) * [Scala](https://github.com/influxdata/influxdb-client-java/tree/master/client-scala) * [Swift](https://github.com/influxdata/influxdb-client-swift) [client libraries](/influxdb3/core/tags/client-libraries/)[API](/influxdb3/core/tags/api/)[developer tools](/influxdb3/core/tags/developer-tools/) --- # Arduino client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/arduino/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Arduino is an open source hardware and software platform used for building electronics projects. The documentation for this client library is available on GitHub. [Arduino InfluxDB client](https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino) --- # C# client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/csharp/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. C# is a general-purpose object-oriented programming language. The documentation for this client library is available on GitHub. [C# InfluxDB client](https://github.com/influxdata/influxdb-client-csharp) --- # Dart client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/dart/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Dart is a programming language created for quick application development for both web and mobile apps. The documentation for this client library is available on GitHub. [Dart InfluxDB client](https://github.com/influxdata/influxdb-client-dart) --- # InfluxDB v2 Go client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/go/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to write data to an InfluxDB 3 Core database. This guide presumes some familiarity with Go and InfluxDB. If just getting started, see [Get started with InfluxDB](/influxdb3/core/get-started/). ## Before you begin 1. [Install Go 1.13 or later](https://golang.org/doc/install). 2. Add the client package your to your project dependencies. ``` # Add InfluxDB Go client package to your project go.mod go get github.com/influxdata/influxdb-client-go/v2 ``` 3. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to your InfluxDB 3 Core cluster, contact your InfluxData account representative. ## Boilerplate for the InfluxDB Go Client Library Use the Go library to write and query data from InfluxDB. 1. In your Go program, import the necessary packages and specify the entry point of your executable program. ``` package main import ( "context" "fmt" "time" "github.com/influxdata/influxdb-client-go/v2" ) ``` 2. Define variables for your InfluxDB [database](/influxdb3/core/admin/databases/) (bucket), organization (required, but ignored), and [database token](/influxdb3/core/admin/tokens/#database-tokens). ``` bucket := "DATABASE_NAME" org := "ignored" token := "DATABASE_TOKEN" // Store the URL of your InfluxDB instance url := "https://localhost:8181" ``` 3. Create the the InfluxDB Go client and pass in the `url` and `token` parameters. ``` client := influxdb2.NewClient(url, token) ``` 4. Create a **write client** with the `WriteAPIBlocking` method and pass in the `org` and `bucket` parameters. ``` writeAPI := client.WriteAPIBlocking(org, bucket) ``` ## Write data to InfluxDB with Go Use the Go library to write data to InfluxDB. 1. Create a [point](/influxdb3/core/reference/glossary/#point) and write it to InfluxDB using the `WritePoint` method of the API writer struct. 2. Close the client to flush all pending writes and finish. ``` p := influxdb2.NewPoint("stat", map[string]string{"unit": "temperature"}, map[string]interface{}{"avg": 24.5, "max": 45}, time.Now()) writeAPI.WritePoint(context.Background(), p) client.Close() ``` ### Complete example write script ```go package main import ( "context" "fmt" "time" "github.com/influxdata/influxdb-client-go/v2" ) func main() { bucket := "DATABASE_NAME" org := "ignored" token := "DATABASE_TOKEN" // Store the URL of your InfluxDB instance url := "https://localhost:8181" // Create new client with default option for server url authenticate by token client := influxdb2.NewClient(url, token) // User blocking write client for writes to desired bucket writeAPI := client.WriteAPIBlocking(org, bucket) // Create point using full params constructor p := influxdb2.NewPoint("stat", map[string]string{"unit": "temperature"}, map[string]interface{}{"avg": 24.5, "max": 45}, time.Now()) // Write point immediately writeAPI.WritePoint(context.Background(), p) // Ensures background processes finishes client.Close() } ``` [client libraries](/influxdb3/core/tags/client-libraries/)[Go](/influxdb3/core/tags/go/) --- # Java client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/java/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Java is one of the oldest and most popular class-based, object-oriented programming languages. The documentation for this client library is available on GitHub. [Java InfluxDB client](https://github.com/influxdata/influxdb-client-java) --- # JavaScript client library for the InfluxDB v2 API Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/javascript/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB 3 Core cluster. ### [JavaScript for browsers](/influxdb3/core/reference/client-libraries/v2/javascript/browser/) Use the InfluxDB v2 JavaScript client library in browsers and front-end clients to write data to an InfluxDB Core database. ### [Node.js](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/) The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) for Node.js integrates with the InfluxDB v2 API to write data to an InfluxDB Core database. [client libraries](/influxdb3/core/tags/client-libraries/)[JavaScript](/influxdb3/core/tags/javascript/)[NodeJS](/influxdb3/core/tags/nodejs/) --- # InfluxDB v2 JavaScript client library for web browsers Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/javascript/browser/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an InfluxDB 3 Core database. This library supports both front-end and server-side environments and provides the following distributions: * ECMAScript modules (ESM) and CommonJS modules (CJS) * Bundled ESM * Bundled UMD This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. If you’re just getting started with InfluxDB, see [Get started with InfluxDB](/influxdb/v2/get-started/). > [!Warning] > ### Tokens in production applications > > The examples below configure the authentication token in source code for demonstration purposes only. > To protect your data, take the following steps: 1. Avoid sending tokens to public clients such as web browsers and mobile apps. Regard any application secret sent to client devices as public and not confidential. 2. Use short-lived, [**read-only tokens**](/influxdb/v2/reference/cli/influx/auth/create/#create-a-read-only-authentication-token) whenever possible to prevent unauthorized writes and deletes. * [Before you begin](#before-you-begin) * [Use with module bundlers](#use-with-module-bundlers) * [Use bundled distributions with browsers and module loaders](#use-bundled-distributions-with-browsers-and-module-loaders) * [Get started with the example app](#get-started-with-the-example-app) ## Before you begin 1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app. 2. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to your InfluxDB 3 Core cluster, contact your InfluxData account representative. ## Use with module bundlers If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`. ## Use bundled distributions with browsers and module loaders 1. Configure InfluxDB properties for your script. ``` ``` 2. Import modules from the latest client library browser distribution.`@influxdata/influxdb-client-browser` exports bundled ESM and UMD syntaxes. [ESM](#import-esm)[UMD](#import-umd) ``` ``` ``` ``` After you’ve imported the client library, you’re ready to [get started writing data with the example app](#get-started-with-the-example-app). ## Get started with the example app The client library includes an example browser app that writes to your InfluxDB instance. 1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repository. 2. Navigate to the `examples` directory: ``` cd examples ``` 3. Update `./env_browser.js` with your InfluxDB 3 Core cluster URL, your database name as `bucket`, an arbitrary string as `org`, and your database token. 4. Run the following command to start the application at [http://localhost:3001/examples/index.html]() ``` npm run browser ``` `index.html` loads the `env_browser.js` configuration, the client library ESM modules, and the application in your browser. For more examples, see how to [write data using the JavaScript client library for Node.js](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/). #### Related * [Write data with the InfluxDB v2 JavaScript client library](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/) [client libraries](/influxdb3/core/tags/client-libraries/)[JavaScript](/influxdb3/core/tags/javascript/) --- # Node.js JavaScript client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)integrates with the InfluxDB v2 API to write data from Node.js and browser applications to an InfluxDB 3 Core database. ## Use the client library in a Node.js application ### [Install the InfluxDB v2 JavaScript client library](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/install/) Install the Node.js JavaScript client library to write data to an InfluxDB Core database. ### [Write data](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/) The InfluxDB v2 JavaScript client library integrates with Node.js applications to write data to the InfluxDB v2 API. [client libraries](/influxdb3/core/tags/client-libraries/)[JavaScript](/influxdb3/core/tags/javascript/)[NodeJS](/influxdb3/core/tags/nodejs/) --- # Install the InfluxDB v2 JavaScript client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/install/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. ## Install Node.js 1. Install [Node.js](https://nodejs.org/en/download/package-manager/). 2. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to your InfluxDB 3 Core cluster, contact your InfluxData account representative. 3. In your terminal, create a directory for your Node.js project and change to it. ``` mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. * `npm`: the package manager included with Node.js * `-y`: uses defaults for the package and bypasses prompts ``` npm init -y ``` ## Install TypeScript Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project: 1. Install TypeScript and type definitions for Node.js. ``` npm i -g typescript && npm i --save-dev @types/node ``` 2. Enter the following command to create a TypeScript configuration (`tsconfig.json`) with default values: ``` tsc --init ``` 3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. ``` tsc --watch ``` ## Install dependencies Use the `@influxdata/influxdb-client` JavaScript client library to write data in InfluxDB 3 Core. Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data: ```sh npm i --save @influxdata/influxdb-client ``` The `@influxdata/influxdb-client-apis` client library package won’t work with InfluxDB 3 Core. It only works with InfluxDB v2 management APIs. ## Configure credentials The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for accessing your InfluxDB properties from environment variables or from `env.js`. The examples use these properties to interact with the InfluxDB API. Set environment variables or update `env.js` with your InfluxDB [database](/influxdb3/core/admin/databases/), organization (required, but ignored), [database token](/influxdb3/core/admin/tokens/#database-tokens), and cluster URL. ```sh export INFLUX_URL=https://localhost:8181 export INFLUX_TOKEN=DATABASE_TOKEN export INFLUX_ORG=ORG_ID export INFLUX_DATABASE=DATABASE_NAME ``` Replace the following: * **`DATABASE_TOKEN`**: InfluxDB database token * **`ORG_ID`**: An arbitrary string (InfluxDB ignores this credential, but the client library requires it) * **`DATABASE_NAME`**: InfluxDB database name ## Next steps Once you’ve installed the client library and configured credentials, you’re ready to [write data](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/) to InfluxDB. [Write data](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/) [client libraries](/influxdb3/core/tags/client-libraries/)[JavaScript](/influxdb3/core/tags/javascript/) --- # Write data with the InfluxDB v2 JavaScript client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/write/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. The JavaScript client library includes the following convenient features for writing data to InfluxDB: * Apply default tags to data points. * Buffer points into batches to optimize data transfer. * Automatically retry requests on failure. * Set an optional HTTP proxy address for your network. ### Before you begin * [Install the client library and other dependencies](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/install/). ### Write data with the client library 1. Instantiate a client by calling the `new InfluxDB()` constructor with your InfluxDB URL and database token (environment variables you already set in the [Install section](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/install/)). ``` import {InfluxDB, Point} from '@influxdata/influxdb-client' const influxDB = new InfluxDB({url: process.env.INFLUX_URL, token: process.env.INFLUX_TOKEN}) ``` 2. Use the `getWriteApi()` method of the client to create a **write client**. Provide your InfluxDB organization ID and database name. ``` const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, process.env.INFLUX_DATABASE) ``` 3. To apply one or more [tags](/influxdb3/core/reference/glossary/#tag) to all points, use the `useDefaultTags()` method. Provide tags as an object of key/value pairs. ``` writeApi.useDefaultTags({region: 'west'}) ``` 4. Use the `Point()` constructor to create a [point](/influxdb3/core/reference/glossary/#point). 1. Call the constructor and provide a [measurement](/influxdb3/core/reference/glossary/#measurement). 2. To add one or more tags, chain the `tag()` method to the constructor. Provide a `name` and `value`. 3. To add a field of type `float`, chain the `floatField()` method to the constructor. Provide a `name` and `value`. ``` const point1 = new Point('temperature') .tag('sensor_id', 'TLM010') .floatField('value', 24.0) ``` 5. Use the `writePoint()` method to write the point to your InfluxDB bucket. Finally, use the `close()` method to flush all pending writes. The example logs the new data point followed by “WRITE FINISHED” to stdout. ``` writeApi.writePoint(point1) writeApi.close().then(() => { console.log('WRITE FINISHED') }) ``` ### Complete example ```js 'use strict' /** @module write * Writes a data point to InfluxDB using the JavaScript client library with Node.js. **/ import {InfluxDB, Point} from '@influxdata/influxdb-client' /** * Instantiate the InfluxDB client * with a configuration object. **/ const influxDB = new InfluxDB({url: process.env.INFLUX_URL, token: process.env.INFLUX_TOKEN}) /** * Create a write client from the getWriteApi method. * Provide your org and database. **/ const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, process.env.INFLUX_DATABASE) /** * Apply default tags to all points. **/ writeApi.useDefaultTags({region: 'west'}) /** * Create a point and write it to the buffer. **/ const point1 = new Point('temperature') .tag('sensor_id', 'TLM01') .floatField('value', 24.0) console.log(` ${point1}`) writeApi.writePoint(point1) /** * Flush pending writes and close writeApi. **/ writeApi.close().then(() => { console.log('WRITE FINISHED') }) ``` In your terminal with [environment variables or `env.js` set](/influxdb3/core/reference/client-libraries/v2/javascript/nodejs/install/#configure-credentials), run the following command to execute the JavaScript file: ```sh node write.js ``` ### Response codes *For information about **InfluxDB API response codes**, see[InfluxDB API Write documentation](/influxdb3/core/api/write-data/#operation/PostWrite).* #### Related * [Troubleshoot issues writing data](/influxdb3/core/write-data/troubleshoot/) [client libraries](/influxdb3/core/tags/client-libraries/)[JavaScript](/influxdb3/core/tags/javascript/) --- # Kotlin client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/kotlin/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Kotlin is an open source programming language that runs on the Java Virtual Machine (JVM). The documentation for this client library is available on GitHub. [Kotlin InfluxDB client](https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin) --- # PHP client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/php/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. PHP is a popular general-purpose scripting language primarily used for web development. The documentation for this client library is available on GitHub. [PHP InfluxDB client](https://github.com/influxdata/influxdb-client-php) --- # Python client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/python/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Use the [InfluxDB Python client library](https://github.com/influxdata/influxdb-client-python) to integrate InfluxDB into Python scripts and applications. This guide presumes some familiarity with Python and InfluxDB. If just getting started, see [Get started with InfluxDB](/influxdb3/core/get-started/). ## Before you begin You’ll need the following prerequisites: 1. Install the InfluxDB Python library: ``` pip install influxdb-client ``` 2. InfluxDB Cloud Dedicated cluster URL using the HTTPS protocol–for example: ``` https://localhost:8181 ``` 3. Name of the [database](/influxdb3/core/admin/databases/) to write to. 4. InfluxDB [database token](/influxdb3/core/admin/tokens/#database-tokens)with permission to write to the database.*For security reasons, we recommend setting an environment variable to store your token and avoid exposing the raw token value in your script.* ## Write data to InfluxDB with Python Follow the steps to write [line protocol](/influxdb3/core/reference/syntax/line-protocol/) data to an InfluxDB Cloud Dedicated database. 1. In your editor, create a file for your Python program–for example: `write.py`. 2. In the file, import the InfluxDB client library. ``` import influxdb_client from influxdb_client.client.write_api import SYNCHRONOUS import os ``` 3. Define variables for your [database name](/influxdb3/core/admin/databases/), organization (required, but ignored), and [database token](/influxdb3/core/admin/tokens/#database-tokens). ``` database = "DATABASE_NAME" org = "ignored" # INFLUX_TOKEN is an environment variable you created for your database WRITE token token = os.getenv('INFLUX_TOKEN') url="https://localhost:8181" ``` 4. To instantiate the client, call the `influxdb_client.InfluxDBClient()` method with the following keyword arguments: `url`, `org`, and `token`. ``` client = influxdb_client.InfluxDBClient( url=url, token=token, org=org ) ``` The `InfluxDBClient` object has a `write_api` method used for configuration. 5. Instantiate a **write client** by calling the `client.write_api()` method with write configuration options. ``` write_api = client.write_api(write_options=SYNCHRONOUS) ``` 6. Create a [point](/influxdb3/core/reference/glossary/#point) object and write it to InfluxDB using the `write` method of the API writer object. The write method requires three parameters: `bucket`, `org`, and `record`. ``` p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) write_api.write(bucket=database, org=org, record=p) ``` ### Complete example write script ```python import influxdb_client from influxdb_client.client.write_api import SYNCHRONOUS import os database = "DATABASE_NAME" org = "ignored" # INFLUX_TOKEN is an environment variable you created for your database WRITE token token = os.getenv('INFLUX_TOKEN') url="https://localhost:8181" client = influxdb_client.InfluxDBClient( url=url, token=token, org=org ) # Write script write_api = client.write_api(write_options=SYNCHRONOUS) p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) write_api.write(bucket=database, org=org, record=p) ``` ## Query data from InfluxDB with Python The InfluxDB v2 Python client can’t query InfluxDB Cloud Dedicated. To query your dedicated instance, use a Python [Flight SQL client with gRPC](/influxdb3/core/reference/client-libraries/flight-sql/). [client libraries](/influxdb3/core/tags/client-libraries/)[python](/influxdb3/core/tags/python/) --- # R package client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/r/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. R is a programming language and software environment for statistical analysis, reporting, and graphical representation primarily used in data science. The documentation for this client library is available on GitHub. [R InfluxDB client](https://github.com/influxdata/influxdb-client-r) --- # Ruby client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/ruby/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Ruby is a highly flexible, open-source, object-oriented programming language. The documentation for this client library is available on GitHub. [Ruby InfluxDB client](https://github.com/influxdata/influxdb-client-ruby) --- # Scala client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/scala/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Scala is a general-purpose programming language that supports both object-oriented and functional programming. The documentation for this client library is available on GitHub. [Scala InfluxDB client](https://github.com/influxdata/influxdb-client-java/tree/master/client-scala) --- # Swift client library Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v2/swift/ > [!Warning] > #### Use InfluxDB 3 clients to query > > InfluxDB 3 supports [compatibility endpoints for *writing data*](/influxdb3/core/write-data/compatibility-apis/) using InfluxDB v2 and v1 tools. However, the `/api/v2/query` API endpoint and associated tooling, such as InfluxDB v2 client libraries and the `influx` CLI, *can’t query* data stored in InfluxDB 3 Core. > > [InfluxDB 3 client libraries](/influxdb3/core/reference/client-libraries/v3/) are available that integrate with your code to write and query data stored in InfluxDB 3 Core. > > [**Compare tools you can use**](/influxdb3/core/get-started/#tools-to-use) to interact with InfluxDB 3 Core. Swift is a programming language created by Apple for building applications across multiple Apple platforms. The documentation for this client library is available on GitHub. [Swift InfluxDB client](https://github.com/influxdata/influxdb-client-swift) --- # InfluxDB 3 API client libraries Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/ ## Client libraries for InfluxDB 3 InfluxDB 3 client libraries are language-specific packages that work with and integrate with your application to write to and query data in InfluxDB 3 Core. InfluxData and the user community maintain client libraries for developers who want to take advantage of: * Idioms for InfluxDB requests, responses, and errors. * Common patterns in a familiar programming language. * Faster development and less boilerplate code. InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs. They can be used to construct line protocol data and transform data from other formats to line protocol. InfluxDB 3 client libraries can query InfluxDB 3 using the Flight protocol to execute SQL and InfluxQL queries, request database information, and retrieve data stored in InfluxDB 3 Core. Additional features may vary among client libraries. For specifics about a client library, see the library’s GitHub repository. InfluxDB 3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity). ### [C# .NET](https://github.com/InfluxCommunity/influxdb3-csharp) The InfluxDB 3 `influxdb3-csharp` C# .NET client library integrates with C# .NET scripts and applications to write and query data stored in an InfluxDB Core database. ### [Go](/influxdb3/core/reference/client-libraries/v3/go/) The InfluxDB 3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an InfluxDB 3 Core database. ### [Java](/influxdb3/core/reference/client-libraries/v3/java/) The InfluxDB 3 `influxdb3-java` Java client library integrates with application code to write and query data stored in an InfluxDB Core database. ### [JavaScript](https://github.com/InfluxCommunity/influxdb3-js) The InfluxDB 3 `influxdb3-js` JavaScript client library integrates with JavaScript scripts and applications to write and query data stored in an InfluxDB Core database. ### [Python](/influxdb3/core/reference/client-libraries/v3/python/) The InfluxDB 3 `influxdb3-python` Python client library integrates with Python scripts and applications to write and query data stored in an InfluxDB Core database. ``` # Example: Write and query data # Write sensor data in batches from a CSV file to a database client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time', tag_columns=["room"]) # Execute a query and retrieve data from the last 90 days table = client.query( '''SELECT * FROM home WHERE time >= now() - INTERVAL '90 days' ORDER BY time''') # This script assumes the client object is correctly configured # with your database name, token, and host URL. # After the script runs, the table variable contains the data # formatted as a PyArrow table. ``` ### [Rust](https://github.com/InfluxCommunity/influxdb3-rust) The InfluxDB 3 `influxdb3-rust` Rust client library integrates with Rust applications to write and query data stored in an InfluxDB Core database. [client libraries](/influxdb3/core/tags/client-libraries/)[API](/influxdb3/core/tags/api/)[developer tools](/influxdb3/core/tags/developer-tools/) --- # C# .NET client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/csharp/ The InfluxDB 3 [`influxdb3-csharp` C# .NET client library](https://github.com/InfluxCommunity/influxdb3-csharp) integrates with C# .NET scripts and applications to write and query data stored in an InfluxDB 3 Core database. **Latest version:**[v1.9.0](/influxdb3/core/reference/client-libraries/v3/csharp/release-notes/)(2026-06-11) The documentation for this client library is available on GitHub. [InfluxDB 3 C# .NET client library](https://github.com/InfluxCommunity/influxdb3-csharp) [gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-csharp release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/csharp/release-notes/ ## v1.9.0 ### Features 1. [#269](https://github.com/InfluxCommunity/influxdb3-csharp/pull/269): Add partial writes support and default writes to the V2 API endpoint. * `NoSync` requires `UseV2Api=false` and the V3 API endpoint. * `AcceptPartial` applies only when writes are sent to the V3 API endpoint and is ignored when using the V2 API endpoint. See [Partial writes](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/#partial-writes) for more. ## v1.8.0 ### Features 1. [#227](https://github.com/InfluxCommunity/influxdb3-csharp/pull/227): Add example for write with interceptors. ## v1.7.0 ### Features 1. [#220](https://github.com/InfluxCommunity/influxdb3-csharp/pull/220): Add InfluxDB 3 Core/Enterprise structured errors handling. * CI updates ## v1.6.0 ### Features 1. [#193](https://github.com/InfluxCommunity/influxdb3-csharp/pull/193): Add option to disable gRPC query response compression: * New query option (`QueryOptions.DisableGrpcCompression`) added: `true` value disables gRPC response compression. Default value: `false` (compression enabled). * Also configurable via connection string query parameter (`disableGrpcCompression`). * Also configurable via environment variable (`INFLUX_DISABLE_GRPC_COMPRESSION`). ## v1.5.0 ### Features 1. [#175](https://github.com/InfluxCommunity/influxdb3-csharp/pull/175): Add QueryTimeout and WriteTimeout to ClientConfig. 2. [#179](https://github.com/InfluxCommunity/influxdb3-csharp/pull/179): Allows create ClientConfig from ClientConfig(string connectionString) and ClientConfig(IDictionary env) * CI updates ## v1.4.0 ### Features 1. [#174](https://github.com/InfluxCommunity/influxdb3-csharp/pull/174): Support passing HttpClient to InfluxDBClient. * CI updates ## v1.3.0 ### Features 1. [#164](https://github.com/InfluxCommunity/influxdb3-csharp/pull/164): Add function to get InfluxDB version. 2. [#168](https://github.com/InfluxCommunity/influxdb3-csharp/pull/168): Run integration tests against a locally started InfluxDB 3 Core server. ## v1.2.0 ### Features 1. [#155](https://github.com/InfluxCommunity/influxdb3-csharp/pull/155): Allows setting grpc options. 2. [#157](https://github.com/InfluxCommunity/influxdb3-csharp/pull/157): Fix: always clone `DefaultOptions` to keep it immutable. 3. [#158](https://github.com/InfluxCommunity/influxdb3-csharp/pull/158): Support fast writes without waiting for WAL persistence: * New write option (`WriteOptions.NoSync`) added: `true` value means faster write but without the confirmation that the data was persisted. Default value: `false`. * **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!** * Also configurable via connection string query parameter (`writeNoSync`). * Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`). * Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`,`"second"` ( in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`). ## v1.1.0 ### Features 1. [#153](https://github.com/InfluxCommunity/influxdb3-csharp/pull/153): Add custom SSL root certificate support. * New configuration items: * `SslRootsFilePath` * `DisableCertificateRevocationListCheck` * **Disclaimer:** Using custom SSL root certificate configurations is recommended for development and testing purposes only. For production deployments, ensure custom certificates are added to the operating system’s trusted certificate store. ## v1.0.0 ### Features 1. [#132](https://github.com/InfluxCommunity/influxdb3-csharp/pull/132): Respect iox::column\_type::field metadata when mapping query results into values. * iox::column\_type::field::integer: =\> Long * iox::column\_type::field::uinteger: =\> Long * iox::column\_type::field::float: =\> Double * iox::column\_type::field::string: =\> String * iox::column\_type::field::boolean: =\> Boolean ## v0.8.0 ### Features 1.[#118](https://github.com/InfluxCommunity/influxdb3-csharp/pull/118): Simplify getting response headers and status code from `InfluxDBApiException`. Includes example runnable through `Examples/General`. ## v0.7.0 ### Migration Notice * `InfluxDBClient` constructor with connection options has new option `authScheme` with `null` default value: ``` - public InfluxDBClient(string host, string token, string? organization = null, string? database = null); + public InfluxDBClient(string host, string token, string? organization = null, string? database = null, string? authScheme = null) ``` This new option is used for Edge (OSS) authentication. ### Features 1. [#101](https://github.com/InfluxCommunity/influxdb3-csharp/pull/101): Add standard `user-agent` header to all calls. 2. [#111](https://github.com/InfluxCommunity/influxdb3-csharp/pull/111): Add InfluxDB Edge (OSS) authentication support. ### Bug Fixes 1. [#110](https://github.com/InfluxCommunity/influxdb3-csharp/pull/110): InfluxDB Edge (OSS) error handling. ## v0.6.0 ### Features 1. [#90](https://github.com/InfluxCommunity/influxdb3-csharp/pull/90): Custom `HTTP/gRPC` headers can be specified globally by config or per request ## v0.5.0 ### Features 1. [#71](https://github.com/InfluxCommunity/influxdb3-csharp/pull/71): Add support for named query parameters ### Others 1. [#80](https://github.com/InfluxCommunity/influxdb3-csharp/pull/80): Use net8.0 as a default target framework in Tests and Examples ## v0.4.0 ### Features 1. [#66](https://github.com/InfluxCommunity/influxdb3-csharp/pull/66): Default Tags for Writes ## v0.3.0 ### Features 1. [#36](https://github.com/InfluxCommunity/influxdb3-csharp/pull/46): Add client creation from connection string and environment variables. 2. [#52](https://github.com/InfluxCommunity/influxdb3-csharp/pull/52): Add structured query support ### Docs 1. [#52](https://github.com/InfluxCommunity/influxdb3-csharp/pull/52): Add downsampling example ## v0.2.0 ### Features 1. [#33](https://github.com/InfluxCommunity/influxdb3-csharp/pull/33): Add GZIP support 2. [#34](https://github.com/InfluxCommunity/influxdb3-csharp/pull/34): Add HTTP proxy and custom HTTP headers support ### Breaking Changes 1. [#35](https://github.com/InfluxCommunity/influxdb3-csharp/pull/35): Renamed config types and some options ## v0.1.0 * initial release of new client version --- # Go client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/go/ The InfluxDB 3 [`influxdb3-go` Go client library](https://github.com/InfluxCommunity/influxdb3-go) integrates with Go scripts and applications to write and query data stored in an InfluxDB 3 Core database. **Latest version:**[v2.17.0](/influxdb3/core/reference/client-libraries/v3/go/release-notes/)(2026-07-01) ## Installation ```sh go get github.com/InfluxCommunity/influxdb3-go/v2 ``` ## Importing the package The `influxdb3-go` client library module provides the `influxdb3` package. Import the package: ```go import ( "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) ``` ## API reference ### Function `New` Create a client to interact with InfluxDB. #### Syntax ```go New(config ClientConfig) ``` Initializes and returns a `influxdb3.Client` instance with the following: * Configuration and functions for writing to the database. * A `*flight.Client` and functions for querying the database. #### Parameters * **`config`**: A `ClientConfig` struct with the following configuration properties: * **`Host`** (string): the InfluxDB 3 Core server URL * **`Token`** (string): a database token string * **`Database`** (string): the database to use for writing and querying. * **`Organization`** (string): *Optional*. The organization name or ID. * **`HTTPClient`** (`*http.Client`): *Optional*. Specifies a custom HTTP client, TLS configuration, or timeout to use. * **`WriteOptions`** (`*WriteOptions`): *Optional*. Options passed to the write client for writing to the database. * **`Headers`** (`http.Header`): *Optional*. Headers to include in all requests. #### Examples ##### Create an InfluxDB client ```go package main import ( "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func main() { client, err := influxdb3.New(influxdb3.ClientConfig{ Host: "https://localhost:8181", Token: "DATABASE_TOKEN", Database: "DATABASE_NAME", }) defer func(client *influxdb3.Client) { err := client.Close() if err != nil { panic(err) } }(client) if(err != nil) { panic(err) } } ``` Replace the following configuration values: * `DATABASE_NAME`: the name of the InfluxDB [database](/influxdb3/core/admin/databases/) to query * `DATABASE_TOKEN`: an InfluxDB [database token](/influxdb3/core/admin/tokens/#database-tokens)with *read* permission on the specified database ## Class influxdb3.Client ### Function `Client.Query()` Query data from InfluxDB 3 using SQL. #### Syntax ```go client.Query(ctx context.Context, query string) ``` Sends a Flight query request with SQL to InfluxDB. Returns the following: * A custom iterator (\*QueryIterator) for accessing query result data and metadata. * An error, if any. #### Parameters * **`ctx`** (`context.Context`): the context to use for the request * **`query`** (string): the SQL query to execute. #### Examples ##### Query using SQL ```go query := `SELECT * FROM home WHERE time >= '2022-01-02T08:00:00Z' AND time <= '2022-01-02T20:00:00Z'` iterator, err := client.Query(context.Background(), query) ``` ### Function `Client.QueryWithOptions()` Query data from InfluxDB 3 with query options such as **query type** for querying with InfluxQL. #### Syntax ```go client.QueryWithOptions(ctx context.Context, options *QueryOptions, query string) ``` Sends a query request with the specified query options to InfluxDB. Returns the following: * A custom iterator (\*QueryIterator) for accessing query result data and metadata. * An error, if any. #### Parameters * **`ctx`** (`context.Context`): the context to use for the request * **`options`**: query options (query type, optional database) * **`query`** (string): the SQL or InfluxQL query to execute. #### Examples ##### Query using InfluxQL ```go query := `SELECT * FROM home WHERE time >= 1641124000s AND time <= 1641124000s + 8h` queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL} iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query) ``` [Flight client](/influxdb3/core/tags/flight-client/)[go](/influxdb3/core/tags/go/)[InfluxQL](/influxdb3/core/tags/influxql/)[SQL](/influxdb3/core/tags/sql/)[Flight](/influxdb3/core/tags/flight/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-go release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/go/release-notes/ ## v2.17.0 * CI updates ### Dependencies 1. [#268](https://github.com/InfluxCommunity/influxdb3-go/pull/268): Upgrade Google gRPC to 1.82.0. ## v2.16.0 ### Dependencies 1. [#261](https://github.com/InfluxCommunity/influxdb3-go/pull/261): Upgrade dependencies. ## v2.15.0 ### Bug Fixes 1. [#258](https://github.com/InfluxCommunity/influxdb3-go/pull/258): Restores write behavior changed in 2.14 by defaulting writes to the V2 API endpoint. * All InfluxDB 3 products now work with default write settings. * Write option `NoSync` requires `UseV2Api=false` and the V3 API endpoint. `AcceptPartial` applies only when writes are sent to the V3 API endpoint and is ignored otherwise. ## v2.14.0 ### BREAKING CHANGES 1. [#245](https://github.com/InfluxCommunity/influxdb3-go/pull/245): Adds `UseV2Api` write option and fixes partial writes support introduced in [#234](https://github.com/InfluxCommunity/influxdb3-go/pull/234). Users of InfluxDB Clustered version must set this option to `true` for writing. ### Features 1. [#227](https://github.com/InfluxCommunity/influxdb3-go/pull/227): Support custom tag order via `WithTagOrder` write option. See [Sort tags by priority](https://docs.influxdata.com/influxdb3/enterprise/write-data/best-practices/schema-design/#sort-tags-by-query-priority) for more. * Point and struct writes now use custom line protocol marshaling in this client; dependency on `github.com/influxdata/line-protocol/v2` will be dropped in a future release. * Direct use of `lineprotocol.Precision` is deprecated; prefer `influxdb3.Precision` constants. 2. [#234](https://github.com/InfluxCommunity/influxdb3-go/pull/234): Support partial writes via `AcceptPartial` write option. See [Partial writes](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/#partial-writes) for more. 3. [#238](https://github.com/InfluxCommunity/influxdb3-go/pull/238): Support `arrow.NULL` data type in query response iterator. ### Dependencies 1. [#249](https://github.com/InfluxCommunity/influxdb3-go/pull/249): Requires Go 1.25 or newer. ## v2.13.0 ### Features 1. [#223](https://github.com/InfluxCommunity/influxdb3-go/pull/223): Support passing middleware functions to the Flight client. ## v2.12.0 ### Features 1. [#209](https://github.com/InfluxCommunity/influxdb3-go/pull/209): Document the global nature of gRPC compression in README.md ### Bug Fixes 1. [#213](https://github.com/InfluxCommunity/influxdb3-go/pull/213): Fixed InfluxDB 3 Core/Enterprise write error deserialization. ### Dependencies 1. Minimum supported Go version is now 1.24 as required by `google.golang.org/grpc` v1.76.0 - see [grpc-go#8509](https://github.com/grpc/grpc-go/issues/8509) ## v2.11.0 * CI updates ### Features 1. [192](https://github.com/InfluxCommunity/influxdb3-go/pull/192): Add clearer timeout parameters. * The `ClientConfig` property `Timeout` is now deprecated. * In `ClientConfig` a new property `WriteTimeout` supersedes it. * In `ClientConfig` the new property `QueryTimeout` sets a default context deadline to be used with all queries. * New environment variables `INFLUXDB_WRITE_TIMEOUT` and `INFLUXDB_QUERY_TIMEOUT` are added. ### Bug Fixes 1. [#193](https://github.com/InfluxCommunity/influxdb3-go/pull/193): Use `influxdb3_test` package in the documentation examples to enforce public API usage. ## v2.10.0 ### Features 1. [#189](https://github.com/InfluxCommunity/influxdb3-go/pull/189): Add transparent gRPC compression support. * CI updates ## v2.9.0 ### Features 1. [#169](https://github.com/InfluxCommunity/influxdb3-go/pull/169): Support user-defined type converter function for writes points. 2. [#171](https://github.com/InfluxCommunity/influxdb3-go/pull/171): Add function to get InfluxDB version. 3. [#176](https://github.com/InfluxCommunity/influxdb3-go/pull/176): Add comment warning null when calling getMeasurement function. 4. [#174](https://github.com/InfluxCommunity/influxdb3-go/pull/174): Run integration tests against a locally started InfluxDB 3 Core server. ## v2.8.0 ### Features 1. [#159](https://github.com/InfluxCommunity/influxdb3-go/pull/159): Support fast writes without waiting for WAL persistence: * New write option (`WriteOptions.NoSync`) added: `true` value means faster write but without the confirmation that the data was persisted. Default value: `false`. * **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!** * Also configurable via connection string query parameter (`writeNoSync`). * Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`). * Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`, `"second"` ( in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`). ### Bug Fixes 1. [#164](https://github.com/InfluxCommunity/influxdb3-go/pull/164): Updates * Go version to 1.23.9 * `golang.org/x/net` to v0.38.0 2. [#166](https://github.com/InfluxCommunity/influxdb3-go/pull/166): Upgrades dependency `apache/arrow/go` to `apache/arrow-go` v18. ## v2.7.0 ### Bug Fixes 1. [#158](https://github.com/InfluxCommunity/influxdb3-go/pull/158): Refactor Batcher and LPBatcher: * Fields and methods using `capacity` renamed to `initialCapacity`. * Log messages when buffer data is not being emitted are simplified. * `SetCapacity` methods on both structures are now deprecated. * `WithCapacity` and `WithBufferCapacity` options are now deprecated. ## v2.6.0 ### Features 1. [#155](https://github.com/InfluxCommunity/influxdb3-go/pull/155): Batcher warnings when buffer data is not being automatically emitted changed to level `Debug` in slog. ## v2.5.0 ### Features 1. [#146](https://github.com/InfluxCommunity/influxdb3-go/pull/146): Add error field to QueryIterator to hold first possible error encountered when retrieving records from the flight Reader. 2. [#147](https://github.com/InfluxCommunity/influxdb3-go/pull/147): Ability to pass `grpc.CallOption` functions to the underlying flight Client. 3. [#149](https://github.com/InfluxCommunity/influxdb3-go/pull/149): Add default configuration for the built-in HTTP client and expose new configurable parameters: * `Timeout` - The overall time limit for requests made by the Client. A negative value means no timeout. Default value: 10 seconds. * `IdleConnectionTimeout` - Maximum time an idle connection will remain idle before closing itself. A negative value means no timeout. Default value: 90 seconds. * `MaxIdleConnections` - Maximum number of idle connections. It sets both `transport.MaxIdleConn` and`transport.MaxIdleConnsPerHost` to the same value. A negative value means no limit. Default value: 100. 4. [#154](https://github.com/InfluxCommunity/influxdb3-go/pull/154): Export functions `NewQueryIterator` and`NewPointValueIterator` to simplify testing. ## v2.4.0 ### Features 1. [#141](https://github.com/InfluxCommunity/influxdb3-go/pull/141): Add proxy and custom SSL root certificate support. ## v2.3.0 ### Features 1. [#131](https://github.com/InfluxCommunity/influxdb3-go/pull/131): Add new PointValueIterator based on google guidelines [Guidelines](https://github.com/googleapis/google-cloud-go/wiki/Iterator-Guidelines) ## v2.2.0 ### Bug fixes 1. [#134](https://github.com/InfluxCommunity/influxdb3-go/pull/134): Reduce minimal Go version to 1.22, remove unnecessary toolchain constraints. ## v2.1.0 ### Bug fixes 1. [#127](https://github.com/InfluxCommunity/influxdb3-go/pull/127): LPBatcher now returns first line of the internal buffer when the line length exceeds the batch size. ## v2.0.0 ### Breaking Changes :warning: **This is a breaking change release.** > > > Previously, the Query API did not respect the metadata type for columns returned from InfluxDB v3. This release fixes this issue. As a result, the type of some columns may differ from previous versions. For example, the timestamp column will now be `time.Time` instead of `arrow.Timestamp`. > > Update steps: 1. Update library: `go get github.com/InfluxCommunity/influxdb3-go/v2/influxdb3` 2. Update import path in Go files to `github.com/InfluxCommunity/influxdb3-go/v2/influxdb3`. ### Features 1. [#114](https://github.com/InfluxCommunity/influxdb3-go/pull/114): Query API respects metadata types for columns returned from InfluxDB v3. Tags are mapped as a “string”, timestamp as “time.Time”, and fields as their respective types: * iox::column\_type::field::integer: =\> int64 * iox::column\_type::field::uinteger: =\> uint64 * iox::column\_type::field::float: =\> float64 * iox::column\_type::field::string: =\> string * iox::column\_type::field::boolean: =\> bool ## v1.0.0 :warning: **The v1.0.0 release had a malformed module path regarding the [Go Module Requirements](https://go.dev/ref/mod#major-version-suffixes). For a Go Module project, you need to use version 2 of the client.** ### Breaking Changes :warning: **This is a breaking change release.** > > > Previously, the Query API did not respect the metadata type for columns returned from InfluxDB v3. This release fixes this issue. As a result, the type of some columns may differ from previous versions. For example, the timestamp column will now be `time.Time` instead of `arrow.Timestamp`. > > ### Features 1. [#114](https://github.com/InfluxCommunity/influxdb3-go/pull/114): Query API respects metadata types for columns returned from InfluxDB v3. Tags are mapped as a “string”, timestamp as “time.Time”, and fields as their respective types: * iox::column\_type::field::integer: =\> int64 * iox::column\_type::field::uinteger: =\> uint64 * iox::column\_type::field::float: =\> float64 * iox::column\_type::field::string: =\> string * iox::column\_type::field::boolean: =\> bool ## v0.14.0 ### Features 1. [#112](https://github.com/InfluxCommunity/influxdb3-go/pull/112): Adds `LPBatcher` for lineprotocol batching following the model of the Point `Batcher`. ### Bug Fixes 1. [#113](https://github.com/InfluxCommunity/influxdb3-go/pull/113): Honor struct tags on WriteData, avoid panic for unexported fields ## v0.13.0 ### Features 1. [#108](https://github.com/InfluxCommunity/influxdb3-go/pull/108): Allow Request.GetBody to be set when writing gzipped data to make calls more resilient. 2. [#111](https://github.com/InfluxCommunity/influxdb3-go/pull/111): Support tabs in tag values. ## v0.12.0 ### Features 1. [#107](https://github.com/InfluxCommunity/influxdb3-go/pull/107): Add `Batcher` to simplify the process of writing data in batches. ## v0.11.0 ### Bug Fixes 1. [#105](https://github.com/InfluxCommunity/influxdb3-go/pull/105): Support newlines in tag values. 2. [#106](https://github.com/InfluxCommunity/influxdb3-go/pull/106): Close `resp.Body` after HTTP error response is encountered. ## v0.10.0 ### Features 1. [#100](https://github.com/InfluxCommunity/influxdb3-go/pull/100): Expose HTTP Response headers in `ServerError` ### Bug Fixes 1. [#94](https://github.com/InfluxCommunity/influxdb3-go/pull/94): Resource leak from unclosed `Response` 2. [#97](https://github.com/InfluxCommunity/influxdb3-go/pull/97): Style and performance improvements discovered by `golangci-lint` 3. [#98](https://github.com/InfluxCommunity/influxdb3-go/pull/98): Cloud Dedicated database creation ignores the name given by an argument * CI updates ## v0.9.0 ### Features 1. [#87](https://github.com/InfluxCommunity/influxdb3-go/pull/87): Add Cloud Dedicated database creation support 2. [#91](https://github.com/InfluxCommunity/influxdb3-go/pull/91): Add Edge (OSS) authentication support. ### Bug Fixes 1. [#89](https://github.com/InfluxCommunity/influxdb3-go/pull/89): InfluxDB Edge (OSS) error handling ## v0.8.0 ### Features 1. [#85](https://github.com/InfluxCommunity/influxdb3-go/pull/85): Add standard `user-agent` header to gRPC requests. 2. [#86](https://github.com/InfluxCommunity/influxdb3-go/pull/86): Add Serverless bucket creation support ## v0.7.0 ### Features 1. [#74](https://github.com/InfluxCommunity/influxdb3-go/pull/74): Use `log/slog` to print debug information instead of `fmt.Printf` 2. [#76](https://github.com/InfluxCommunity/influxdb3-go/pull/76): Add custom headers support for queries (gRPC requests) ### Bug Fixes 1. [#71](https://github.com/InfluxCommunity/influxdb3-go/pull/71): Rename `FlightSQL` constant to `SQL` ### Others 1. [#68](https://github.com/InfluxCommunity/influxdb3-go/pull/68): Upgrade Go version to 1.22. ## v0.6.0 ### Features 1. [#56](https://github.com/InfluxCommunity/influxdb3-go/pull/56): Add support for named query parameters ### Bug Fixes 1. [#59](https://github.com/InfluxCommunity/influxdb3-go/pull/59): Export Default Tags from package ## v0.5.0 ### Features 1. [#50](https://github.com/InfluxCommunity/influxdb3-go/pull/50): Default Tags for Writes ## v0.4.0 ### Features 1. [#45](https://github.com/InfluxCommunity/influxdb3-go/pull/45): Add structured query support ### Docs 1. [#45](https://github.com/InfluxCommunity/influxdb3-go/pull/45): Add downsampling example ## v0.3.0 ### Features 1. [#36](https://github.com/InfluxCommunity/influxdb3-go/pull/36): Add client creation from connection string and environment variables. ### Bug Fixes 1. [#37](https://github.com/InfluxCommunity/influxdb3-go/pull/37): `runtime error` for iterating Arrow Record without rows ## v0.2.0 ### Features 1. [#30](https://github.com/InfluxCommunity/influxdb3-go/pull/30): Add custom HTTP headers support ### Breaking Changes 1. [#31](https://github.com/InfluxCommunity/influxdb3-go/pull/31): Changed package to `influxdb3`. Renamed config types and some options. ## v0.1.0 * initial release of new client version * write using v2 api * query using SQL * query using influxQL --- # Java client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/java/ The InfluxDB 3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates with Java application code to write and query data stored in InfluxDB 3 Core. **Latest version:**[v1.10.0](/influxdb3/core/reference/client-libraries/v3/java/release-notes/)(2026-06-11) InfluxDB client libraries provide configurable batch writing of data to InfluxDB 3 Core. Use client libraries to construct line protocol data, transform data from other formats to line protocol, and batch write line protocol data to InfluxDB HTTP APIs. InfluxDB 3 client libraries can query InfluxDB 3 Core using SQL or InfluxQL. The `influxdb3-java` Java client library wraps the Apache Arrow `org.apache.arrow.flight.FlightClient`in a convenient InfluxDB 3 interface for executing SQL and InfluxQL queries, requesting server metadata, and retrieving data from InfluxDB 3 Core using the Flight protocol with gRPC. * [Installation](#installation) * [Using Maven](#using-maven) * [Using Gradle](#using-gradle) * [Importing the client](#importing-the-client) * [API reference](#api-reference) * [Classes](#classes) * [InfluxDBClient interface](#influxdbclient-interface) * [Initialize with credential parameters](#initialize-with-credential-parameters) * [InfluxDBClient instance methods](#influxdbclient-instance-methods) * [InfluxDBClient.writePoint](#influxdbclientwritepoint) * [InfluxDBClient.query](#influxdbclientquery) #### Example: write and query data The following example shows how to use `influxdb3-java` to write and query data stored in InfluxDB 3 Core. ``` package com.influxdata.demo; import com.influxdb.v3.client.InfluxDBClient; import com.influxdb.v3.client.Point; import com.influxdb.v3.client.query.QueryOptions; import com.influxdb.v3.client.query.QueryType; import java.time.Instant; import java.util.stream.Stream; public class HelloInfluxDB { private static final String HOST_URL = "https://localhost:8181"; // your cluster URL private static final String DATABASE = "DATABASE_NAME"; // your InfluxDB database name private static final char[] TOKEN = System.getenv("DATABASE_TOKEN"); // a local environment variable that stores your database token // Create a client instance that writes and queries data in your database. public static void main(String[] args) { // Instantiate the client with your InfluxDB credentials try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, TOKEN, DATABASE)) { writeData(client); queryData(client); } catch (Exception e) { System.err.println("An error occurred while connecting to InfluxDB!"); e.printStackTrace(); } } // Use the Point class to construct time series data. private static void writeData(InfluxDBClient client) { Point point = Point.measurement("temperature") .setTag("location", "London") .setField("value", 30.01) .setTimestamp(Instant.now().minusSeconds(10)); try { client.writePoint(point); System.out.println("Data is written to the database."); } catch (Exception e) { System.err.println("Failed to write data to the database."); e.printStackTrace(); } } // Use SQL to query the most recent 10 measurements private static void queryData(InfluxDBClient client) { System.out.printf("--------------------------------------------------------%n"); System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time"); System.out.printf("--------------------------------------------------------%n"); String sql = "select time,location,value from temperature order by time desc limit 10"; try (Stream stream = client.query(sql)) { stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0])); } catch (Exception e) { System.err.println("Failed to query data from the database."); e.printStackTrace(); } } } ``` Source: [suyashcjoshi/SimpleJavaInfluxDB](https://github.com/suyashcjoshi/SimpleJavaInfluxDB/) on GitHub Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core[database](/influxdb3/core/admin/databases/) to read and write data to * `DATABASE_TOKEN`: a local environment variable that stores your[token](/influxdb3/core/admin/tokens/database/)–the token must have read and write permissions on the specified database. ### Run the example to write and query data 1. Build an executable JAR for the project–for example, using Maven: ``` mvn package ``` 2. In your terminal, run the `java` command to write and query data in your database: ``` java \ --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED \ -jar target/PROJECT_NAME.jar ``` Include the following in your command: * [`--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED`](https://arrow.apache.org/docs/java/install.html#id3): with Java version 9 or later and Apache Arrow version 16 or later, exposes JDK internals for Arrow. For more options, see the [Apache Arrow Java install documentation](https://arrow.apache.org/docs/java/install.html). * `-jar target/PROJECT_NAME.jar`: your `.jar` file to run. The output is the newly written data from your InfluxDB 3 Core database. ## Installation Include `com.influxdb.influxdb3-java` in your project dependencies. #### Maven pom.xml #### ```xml com.influxdb influxdb3-java RELEASE ``` ```groovy dependencies { implementation group: 'com.influxdb', name: 'influxdb3-java', version: 'latest.release' } ``` ## Importing the client The `influxdb3-java` client library package provides`com.influxdb.v3.client` classes for constructing, writing, and querying data stored in InfluxDB 3 Core. ## API reference * [Interface InfluxDBClient](#interface-influxdbclient) * [Initialize with credential parameters](#initialize-with-credential-parameters) * [InfluxDBClient instance methods](#influxdbclient-instance-methods) * [InfluxDBClient.writePoint](#influxdbclientwritepoint) * [InfluxDBClient.query](#influxdbclientquery) ## InfluxDBClient interface `InfluxDBClient` provides an interface for interacting with InfluxDB APIs for writing and querying data. The `InfluxDBClient.getInstance` constructor initializes and returns a client instance with the following: * A *write client* configured for writing to the database. * An Arrow *Flight client* configured for querying the database. To initialize a client, call `getInstance` and pass your credentials as one of the following types: * [parameters](#initialize-with-credential-parameters) * a [`ClientConfig`](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/config/ClientConfig.java) * a [database connection string](#initialize-using-a-database-connection-string) ### Initialize with credential parameters ```java static InfluxDBClient getInstance(@Nonnull final String host, @Nullable final char[] token, @Nullable final String database) ``` * `host` (string): The host URL of the InfluxDB instance. * `database` (string): The [database](/influxdb3/core/admin/databases/) to use for writing and querying. * `token` (char array): A [database token](/influxdb3/core/admin/tokens/database/) with read/write permissions. #### Example: initialize with credential parameters ```java package com.influxdata.demo; import com.influxdb.v3.client.InfluxDBClient; import com.influxdb.v3.client.Point; import com.influxdb.v3.client.query.QueryOptions; import com.influxdb.v3.client.query.QueryType; import java.time.Instant; import java.util.stream.Stream; public class HelloInfluxDB { private static final String HOST_URL = "https://localhost:8181"; private static final String DATABASE = "DATABASE_NAME"; private static final char[] TOKEN = System.getenv("DATABASE_TOKEN"); // Create a client instance, and then write and query data in InfluxDB. public static void main(String[] args) { try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, DATABASE_TOKEN, DATABASE)) { writeData(client); queryData(client); } catch (Exception e) { System.err.println("An error occurred while connecting to InfluxDB!"); e.printStackTrace(); } } } ``` Replace the following: * `DATABASE_NAME`: your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: a[database token](/influxdb3/core/admin/tokens/database/) that has the necessary permissions on the specified database. #### Default tags To include default [tags](/influxdb3/core/reference/glossary/#tag) in all written data, pass a `Map` of tag keys and values. ```java InfluxDBClient getInstance(@Nonnull final String host, @Nullable final char[] token, @Nullable final String database, @Nullable Map defaultTags) ``` ### Initialize using a database connection string ```java "https://localhost:8181" + "?token=DATABASE_TOKEN&database=DATABASE_NAME" ``` Replace the following: * `DATABASE_NAME`: your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: a[database token](/influxdb3/core/admin/tokens/database/) that has the necessary permissions on the specified database. ### InfluxDBClient instance methods #### InfluxDBClient.writePoint To write points as line protocol to a database: 1. [Initialize the `client`](#initialize-with-credential-parameters)–your token must have write permission on the specified database. 2. Use the `com.influxdb.v3.client.Point` class to create time series data. 3. Call the `client.writePoint()` method to write points as line protocol in your database. ``` // Use the Point class to construct time series data. // Call client.writePoint to write the point in your database. private static void writeData(InfluxDBClient client) { Point point = Point.measurement("temperature") .setTag("location", "London") .setField("value", 30.01) .setTimestamp(Instant.now().minusSeconds(10)); try { client.writePoint(point); System.out.println("Data written to the database."); } catch (Exception e) { System.err.println("Failed to write data to the database."); e.printStackTrace(); } } ``` #### InfluxDBClient.query To query data and process the results: 1. [Initialize the `client`](#initialize-with-credential-parameters)–the token must have read permission on the database you want to query. 2. Call `client.query()` and provide your SQL query as a string. 3. Use the result stream’s built-in iterator to process row data. ``` // Query the latest 10 measurements using SQL private static void queryData(InfluxDBClient client) { System.out.printf("--------------------------------------------------------%n"); System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time"); System.out.printf("--------------------------------------------------------%n"); String sql = "select time,location,value from temperature order by time desc limit 10"; try (Stream stream = client.query(sql)) { stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0])); } catch (Exception e) { System.err.println("Failed to query data from the database."); e.printStackTrace(); } } ``` [View the InfluxDB 3 Java client library](https://github.com/InfluxCommunity/influxdb3-java/) [Flight client](/influxdb3/core/tags/flight-client/)[Java](/influxdb3/core/tags/java/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-java release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/java/release-notes/ ## v1.10.0 ### Features 1. [#388](https://github.com/InfluxCommunity/influxdb3-java/pull/388): Adds partial writes support and defaults writes to the V2 API endpoint. * `noSync` requires `useV2Api=false` and the V3 API endpoint. * `acceptPartial` applies only when writes are sent to the V3 API endpoint and is ignored when using the V2 API endpoint. * See [Partial writes](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/#partial-writes) for more. ### Bug Fixes 1. [#384](https://github.com/InfluxCommunity/influxdb3-java/pull/384): Always set `precision` to `nanosecond` when writing Points. ## v1.9.0 ### Features 1. [#360](https://github.com/InfluxCommunity/influxdb3-java/pull/360): Support passing interceptors to the Flight client. 2. [#363](https://github.com/InfluxCommunity/influxdb3-java/pull/363): Support custom tag order via `tagOrder` write option. See [Sort tags by priority](https://docs.influxdata.com/influxdb3/enterprise/write-data/best-practices/schema-design/#sort-tags-by-query-priority) for more. ## v1.8.0 ### Features 1. [#352](https://github.com/InfluxCommunity/influxdb3-java/pull/352): Upgrade Arrow Flight client dependencies. ### Bug Fixes 1. [#351](https://github.com/InfluxCommunity/influxdb3-java/pull/351): Enterprise/Core structured errors handling. * CI updates ## v1.7.0 ### Bug Fixes 1. [#317](https://github.com/InfluxCommunity/influxdb3-java/pull/317): Fix Arrow memory leak when stream close fails due to thread interrupts. 2. [#318](https://github.com/InfluxCommunity/influxdb3-java/pull/318): Explicit releasing of the VectorSchemaRoot. ## v1.6.0 ### Features 1. [#306](https://github.com/InfluxCommunity/influxdb3-java/pull/306): Improve closing of Arrow `FlightStream`. ### Bug Fixes 1. [#310](https://github.com/InfluxCommunity/influxdb3-java/pull/310): Ensure `QueryOptions` objects are left unchanged within the `queryData` implementation. ## v1.5.0 ### Features 1. [#289](https://github.com/InfluxCommunity/influxdb3-java/pull/289) Add the possibility to disable gRPC compression via the `disableGRPCCompression` parameter in the `ClientConfig`. * CI updates ## v1.4.0 ### Features 1. [#265](https://github.com/InfluxCommunity/influxdb3-java/pull/265) Add more precise timeout properties to `ClientConfig`. 1. Current property `timeout` is deprecated, as it applies only to the Write API and can be confusing to some users. 2. Two new properties are added, along with getters and similar setters in the `ClientConfig.Builder`. 1. `writeTimeout` - a `java.time.Duration` that applies only to the Write API. 2. `queryTimeout` - a `java.time.Duration` used to calculate deadlines when using the Query API. 3. These properties can also be defined when creating a client using environment variables. Respectively: 1. `INFLUX_WRITE_TIMEOUT` - a positive integer. The time unit is in seconds. 2. `INFLUX_QUERY_TIMEOUT` - a positive integer. The time unit is in seconds. 4. These properties can also be defined when creating a client using system properties. Respectively: 1. `influx.writeTimeout` - a positive integer. The time unit is in seconds. 2. `influx.queryTimeout` - a positive integer. The time unit is in seconds. * CI updates ## v1.3.0 ### Features 1. [#250](https://github.com/InfluxCommunity/influxdb3-java/pull/250) Upgrade Netty version to 4.2.3.Final. 2. [#251](https://github.com/InfluxCommunity/influxdb3-java/pull/251) Add comment warning null when calling getMeasurement function. 3. [#252](https://github.com/InfluxCommunity/influxdb3-java/pull/252) Run integration tests against a locally started InfluxDB 3 Core server. ### Documentation 1. [#253](https://github.com/InfluxCommunity/influxdb3-java/pull/253) New Durable example showing client reuse for better resource management. ## v1.2.0 ### Features 1. [#209](https://github.com/InfluxCommunity/influxdb3-java/pull/209) Add query function returning row as map. 2. [#238](https://github.com/InfluxCommunity/influxdb3-java/pull/238): Support fast writes without waiting for WAL persistence: * New write option (`WriteOptions.noSync`) added: `true` value means faster write but without the confirmation that the data was persisted. Default value: `false`. * **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!** * Also configurable via connection string query parameter (`writeNoSync`). * Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`). * Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`,`"second"` ( in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`). 3. [#241](https://github.com/InfluxCommunity/influxdb3-java/pull/241): Some default options will be used from a getter. 4. [#243](https://github.com/InfluxCommunity/influxdb3-java/pull/243): Add function to get InfluxDB version. ### Bug Fixes 1. [\#239](https://github.com/InfluxCommunity/influxdb3-java/pull/239): Use write options from `ClientConfig` in`InfluxDBClientImpl` write methods: ``` public void writeRecord(@Nullable final String record); public void writeRecords(@Nonnull final List records); public void writePoint(@Nullable final Point point); public void writePoints(@Nonnull final List points); ``` ## v1.1.0 ### Features 1. [#229](https://github.com/InfluxCommunity/influxdb3-java/pull/229): Support proxy and custom ssl root certificates 2. [#232](https://github.com/InfluxCommunity/influxdb3-java/pull/232): Allow set rpc max message size through maxInboundMessageSize in ClientConfig 3. [#233](https://github.com/InfluxCommunity/influxdb3-java/pull/233): More detailed documentation about timestamp handling for query and write functions 4. [#236](https://github.com/InfluxCommunity/influxdb3-java/pull/236): Supports Java 21. ## v1.0.0 ### Features 1. [#200](https://github.com/InfluxCommunity/influxdb3-java/pull/200): Respect iox::column\_type::field metadata when mapping query results into values. * iox::column\_type::field::integer: =\> Long * iox::column\_type::field::uinteger: =\> Long * iox::column\_type::field::float: =\> Double * iox::column\_type::field::string: =\> String * iox::column\_type::field::boolean: =\> Boolean ### Dependencies 1. [#202](https://github.com/InfluxCommunity/influxdb3-java/pull/202): Migrate from `flight-grpc` to `flight-core` package. ## v0.9.0 ### Features 1. [#158](https://github.com/InfluxCommunity/influxdb3-java/pull/158): Add InfluxDB Edge (OSS) authentication support. 2. [#163](https://github.com/InfluxCommunity/influxdb3-java/pull/163): Introduces `InfluxDBApiHttpException` to facilitate write retries and error recovery. ### Bug Fixes 1. [#148](https://github.com/InfluxCommunity/influxdb3-java/pull/148): InfluxDB Edge (OSS) error handling 2. [#153](https://github.com/InfluxCommunity/influxdb3-java/pull/153): Parsing timestamp columns ## v0.8.0 ### Features 1. [#144](https://github.com/InfluxCommunity/influxdb3-java/pull/133): user-agent header is updated for both REST and gRPC calls. ## v0.7.0 ### Features 1. [\#107](https://github.com/InfluxCommunity/influxdb3-java/pull/107): Custom headers are also supported for the query (gRPC request) ``` ClientConfig config = new ClientConfig.Builder() .host("https://us-east-1-1.aws.cloud2.influxdata.com") .token("my-token".toCharArray()) .database("my-database") .headers(Map.of("X-Tracing-Id", "123")) .build(); try (InfluxDBClient client = InfluxDBClient.getInstance(config)) { // // your code here // } catch (Exception e) { throw new RuntimeException(e); } ``` 2. [\#108](https://github.com/InfluxCommunity/influxdb3-java/pull/108): Custom headers can be specified per request (query/write): ``` ClientConfig config = new ClientConfig.Builder() .host("https://us-east-1-1.aws.cloud2.influxdata.com") .token("my-token".toCharArray()) .database("my-database") .build(); try (InfluxDBClient client = InfluxDBClient.getInstance(config)) { // // Write with custom headers // WriteOptions writeOptions = new WriteOptions( Map.of("X-Tracing-Id", "852") ); client.writeRecord("mem,tag=one value=1.0", writeOptions); // // Query with custom headers // QueryOptions queryOptions = new QueryOptions( Map.of("X-Tracing-Id", "852") ); Stream rows = client.query("select * from cpu", queryOptions); } catch (Exception e) { throw new RuntimeException(e); } ``` ## v0.6.0 ### Features 1. [#94](https://github.com/InfluxCommunity/influxdb3-java/pull/94): Add support for named query parameters ## v0.5.1 Resync artifacts with Maven Central. ## v0.5.0 ### Features 1. [#78](https://github.com/InfluxCommunity/influxdb3-java/pull/78): Default Tags can be used when writing points. ### Bug Fixes 1. [#77](https://github.com/InfluxCommunity/influxdb3-java/pull/77): Serialize InfluxDB response to `PointValues` ## v0.4.0 ### Features 1. [#41](https://github.com/InfluxCommunity/influxdb3-java/pull/41): Add structured query support ## v0.3.1 ### Bug Fixes 1. [#55](https://github.com/InfluxCommunity/influxdb3-java/pull/55): Iteration over more Arrow streams ## v0.3.0 ### Features 1. [#40](https://github.com/InfluxCommunity/influxdb3-java/pull/40): Add client creation from connection string, environment variables or system properties. ## v0.2.0 ### Features 1. [#27](https://github.com/InfluxCommunity/influxdb3-java/pull/27): Add GZIP support 2. [#30](https://github.com/InfluxCommunity/influxdb3-java/pull/30): Add HTTP proxy and custom headers support ### Breaking Changes 1. [#31](https://github.com/InfluxCommunity/influxdb3-java/pull/31): Renamed config types and some options ## v0.1.0 * initial release of new client version --- # JavaScript client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/javascript/ The InfluxDB 3 [`influxdb3-js` JavaScript client library](https://github.com/InfluxCommunity/influxdb3-js) integrates with JavaScript scripts and applications to write and query data stored in an InfluxDB 3 Core database. **Latest version:**[v2.3.0](/influxdb3/core/reference/client-libraries/v3/javascript/release-notes/)(2026-06-11) The documentation for this client library is available on GitHub. [InfluxDB 3 JavaScript client library](https://github.com/InfluxCommunity/influxdb3-js) [Flight client](/influxdb3/core/tags/flight-client/)[JavaScript](/influxdb3/core/tags/javascript/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-js release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/javascript/release-notes/ ## v2.3.0 ### Features 1. [#790](https://github.com/InfluxCommunity/influxdb3-js/pull/790): When setting Point timestamp to `new Date()`, the timestamp sent to the servers will be converted to the precision set in `WriteOptions`. 2. [#796](https://github.com/InfluxCommunity/influxdb3-js/pull/796): Adds partial write support and API endpoint selection for writes. * Writes use the V2 API endpoint by default. * `noSync` requires the V3 API endpoint; `acceptPartial` applies only to the V3 API endpoint and is ignored when using the V2 API endpoint. * See [Partial writes](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/#partial-writes) for more. ### Build 1. [#775](https://github.com/InfluxCommunity/influxdb3-js/pull/775): Upgrade typescript to 6.0.3. ## v2.2.0 ### Features 1. [#707](https://github.com/InfluxCommunity/influxdb3-js/pull/707): Support passing interceptor functions to the Flight client. 2. [#711](https://github.com/InfluxCommunity/influxdb3-js/pull/711): Support custom tag order via `tagOrder` write option. See [Sort tags by priority](https://docs.influxdata.com/influxdb3/enterprise/write-data/best-practices/schema-design/#sort-tags-by-query-priority) for more. ## v2.1.0 ### Bugfix 1. [#688](https://github.com/InfluxCommunity/influxdb3-js/pull/688): InfluxDB 3 Core/Enterprise write errors details handling. ## v2.0.0 > > > :warning: **Breaking Changes**: Node v18 support is dropped because it is end of life. > > ### Features 1. [#622](https://github.com/InfluxCommunity/influxdb3-js/pull/622): * Deprecated ConnectionOptions.timeout. * Added ConnectionOptions.queryTimeout and ConnectionOptions.writeTimeout. * Added QueryOptions.timeout and WriteOptions.timeout. * Users can pass timeout directly to the query and write functions. * CI updates ### Docs 1. [#645](https://github.com/InfluxCommunity/influxdb3-js/pull/645): Document gRPC compression. ## v1.4.0 * CI updates ## v1.3.0 ### Features 1. [#585](https://github.com/InfluxCommunity/influxdb3-js/pull/585): Add function to get InfluxDB version. 2. [#588](https://github.com/InfluxCommunity/influxdb3-js/pull/588): Support grpc options available via [@grpc/grpc-js](https://github.com/grpc/grpc-node/blob/master/packages/grpc-js/README.md#supported-channel-options). * New client option (`grpcOptions`) added. Accepts key-value pairs available via @grpc/grpc-js. * New queryOptions option (`grpcOptions`) added. Accepts key-value pairs available via @grpc/grpc-js. * Configurable also with the environment variable (`INFLUXDB_GRPC_OPTIONS`) which takes a comma separated list of key-value pairs. * See new example `clientWithGrpcOptions.ts`. * Not supported in browser API. 3. [#591](https://github.com/InfluxCommunity/influxdb3-js/pull/591): Add comment warning null when calling getMeasurement function. 4. [#592](https://github.com/InfluxCommunity/influxdb3-js/pull/592): Run integration tests against a locally started InfluxDB 3 Core server. ## v1.2.0 ### Features 1. [#574](https://github.com/InfluxCommunity/influxdb3-js/pull/574): Support fast writes without waiting for WAL persistence: * New write option (`WriteOptions.noSync`) added: `true` value means faster write but without the confirmation that the data was persisted. Default value: `false`. * **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!** * Also configurable via connection string query parameter (`writeNoSync`). * Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`). * Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`,`"second"` (in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`). ### Bugfix 1. [#570](https://github.com/InfluxCommunity/influxdb3-js/pull/570): Fixes the bug that makes query results duplicate rows [#553](https://github.com/InfluxCommunity/influxdb3-js/issues/553). 2. [#575](https://github.com/InfluxCommunity/influxdb3-js/pull/575): Upgrades build ecmascript to `es2023` ## v1.1.0 ### Features 1. [#545](https://github.com/InfluxCommunity/influxdb3-js/pull/545): Sets the correct versions for the client-browser package. ## v1.0.0 ### Features 1. [#491](https://github.com/InfluxCommunity/influxdb3-js/pull/491): Respect iox::column\_type::field metadata when mapping query results into values. * iox::column\_type::field::integer: =\> number * iox::column\_type::field::uinteger: =\> number * iox::column\_type::field::float: =\> number * iox::column\_type::field::string: =\> string * iox::column\_type::field::boolean: =\> boolean 2. [499](https://github.com/InfluxCommunity/influxdb3-js/pull/499): Migrate to new doc library ## v0.12.0 ### Bugfix 1. [437](https://github.com/InfluxCommunity/influxdb3-js/pull/437): Simplify iterating over Arrow’s batches in `QueryAPI` ## v0.11.0 ### Features 1. [410](https://github.com/InfluxCommunity/influxdb3-js/pull/410): Accepts HTTP responses with 2xx status codes as a success for writes. ## v0.10.0 ### Features 1. [369](https://github.com/InfluxCommunity/influxdb3-js/pull/369): Propagates headers from HTTP response to HttpError when an error is returned from the server. 2. [377](https://github.com/InfluxCommunity/influxdb3-js/pull/377): Add InfluxDB Edge (OSS) authentication support. ### Bugfix 1. [376](https://github.com/InfluxCommunity/influxdb3-js/pull/376): Handle InfluxDB Edge (OSS) errors better. ## v0.9.0 ### Features 1. [319](https://github.com/InfluxCommunity/influxdb3-js/pull/319): Adds standard `user-agent` header to calls. ## v0.8.0 ### Breaking Changes 1. [293](https://github.com/InfluxCommunity/influxdb3-js/pull/293): The Query API now uses a `QueryOptions` structure in `client.query()` methods. The `queryType` and `queryParams` values are now wrapped inside of it. QueryOptions also support adding custom headers. Query parameters are changed from type `Map` to type `Record`. ### Features 1. [293](https://github.com/InfluxCommunity/influxdb3-js/pull/293): `QueryOptions` also support adding custom headers. ## v0.7.0 ### Features 1. [#256](https://github.com/InfluxCommunity/influxdb3-js/pull/256): Adds support for named query parameters ## v0.6.0 ### Bugfix 1. [#221](https://github.com/InfluxCommunity/influxdb3-js/issues/221): Client options processing ## v0.5.0 ### Features 1. [#183](https://github.com/InfluxCommunity/influxdb3-js/pull/183): Default Tags for Writes ## v0.4.1 ### Bugfix 1. [#164](https://github.com/InfluxCommunity/influxdb3-js/issues/164): Query infinite wait state ## v0.4.0 ### Features 1. [#157](https://github.com/InfluxCommunity/influxdb3-js/pull/157): Add client instantiation from connection string and environment variables ## v0.3.1 Fixed package distribution files. The distribution files were not being included in the npm package. ## v0.3.0 ### Features 1. [#89](https://github.com/InfluxCommunity/influxdb3-js/pull/89): Add structured query support ### Docs 1. [#89](https://github.com/InfluxCommunity/influxdb3-js/pull/89): Add downsampling example ## v0.2.0 ### Features 1. [#52](https://github.com/InfluxCommunity/influxdb3-js/pull/52): Add support for browser environment ### Docs 1. [#52](https://github.com/InfluxCommunity/influxdb3-js/pull/52): Improve examples ## v0.1.0 * initial release of new client version * write using v2 api * query using FlightSQL * query using InfluxQl --- # Python client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/python/ * influxdb3-python v0.10.0 The InfluxDB 3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)integrates InfluxDB 3 Core write and query operations with Python scripts and applications. **Latest version:**[v0.20.0](/influxdb3/core/reference/client-libraries/v3/python/release-notes/)(2026-06-11) InfluxDB client libraries provide configurable batch writing of data to InfluxDB 3 Core. Client libraries can be used to construct line protocol data, transform data from other formats to line protocol, and batch write line protocol data to InfluxDB HTTP APIs. InfluxDB 3 client libraries can query InfluxDB 3 Core using SQL or InfluxQL. The `influxdb3-python` Python client library wraps the Apache Arrow `pyarrow.flight` client in a convenient InfluxDB 3 interface for executing SQL and InfluxQL queries, requesting server metadata, and retrieving data from InfluxDB 3 Core using the Flight protocol with gRPC. > [!Note] > Code samples in this page use the [Get started home sensor sample data](/influxdb3/core/reference/sample-data/#get-started-home-sensor-data). * [Installation](#installation) * [Importing the module](#importing-the-module) * [API reference](#api-reference) * [Classes](#classes) * [Class InfluxDBClient3](#class-influxdbclient3) * [Parameters](#parameters) * [Writing modes](#writing-modes) * [InfluxDBClient3 instance methods](#influxdbclient3-instance-methods) * [InfluxDBClient3.write](#influxdbclient3write) * [InfluxDBClient3.write\_file](#influxdbclient3write_file) * [InfluxDBClient3.query](#influxdbclient3query) * [InfluxDBClient3.close](#influxdbclient3close) * [Class Point](#class-point) * [Class WriteOptions](#class-writeoptions) * [Parameters](#parameters-4) * [Functions](#functions) * [Function write\_client\_options(\*\*kwargs)](#function-write_client_optionskwargs) * [Function flight\_client\_options(\*\*kwargs)](#function-flight_client_optionskwargs) * [Constants](#constants) * [Exceptions](#exceptions) ## Installation Install the client library and dependencies using `pip`: ```bash pip install influxdb3-python ``` ## Importing the module The `influxdb3-python` client library package provides the `influxdb_client_3`module. Import the module: ```python import influxdb_client_3 ``` Import specific class methods from the module: ```python from influxdb_client_3 import InfluxDBClient3, Point, WriteOptions ``` * [`influxdb_client_3.InfluxDBClient3`](#class-influxdbclient3): a class for interacting with InfluxDB * [`influxdb_client_3.Point`](#class-point): a class for constructing a time series data point * `influxdb_client_3.WriteOptions`: a class for configuring client write options ## API reference The `influxdb_client_3` module includes the following classes and functions. * [Classes](#classes) * [Functions](#functions) * [Constants](#constants) * [Exceptions](#exceptions) ## Classes * [Class InfluxDBClient3](#class-influxdbclient3) * [Parameters](#parameters) * [Writing modes](#writing-modes) * [InfluxDBClient3 instance methods](#influxdbclient3-instance-methods) * [InfluxDBClient3.write](#influxdbclient3write) * [InfluxDBClient3.write\_file](#influxdbclient3write_file) * [InfluxDBClient3.query](#influxdbclient3query) * [InfluxDBClient3.close](#influxdbclient3close) * [Class Point](#class-point) * [Class WriteOptions](#class-writeoptions) * [Parameters](#parameters-4) ## Class InfluxDBClient3 Provides an interface for interacting with InfluxDB APIs for writing and querying data. The `InfluxDBClient3` constructor initializes and returns a client instance with the following: * A singleton *write client* configured for writing to the database. * A singleton *Flight client* configured for querying the database. ### Parameters * **`host`** (string): The host URL of the InfluxDB instance. * **`database`** (string): The database to use for writing and querying. * **`token`** (string): A database token with read/write permissions. * *Optional* **`write_client_options`** (dict): Options to use when writing to InfluxDB. If `None`, writes are [synchronous](#synchronous-writing). * *Optional* **`flight_client_options`** (dict): Options to use when querying InfluxDB. ### Writing modes When writing data, the client uses one of the following modes: * [Synchronous writing](#synchronous-writing) * [Batch writing](#batch-writing) * Asynchronous writing: Deprecated #### Synchronous writing Default. When no `write_client_options` are provided during the initialization of `InfluxDBClient3`, writes are synchronous. When writing data in synchronous mode, the client immediately tries to write the provided data to InfluxDB, doesn’t retry failed requests, and doesn’t invoke response callbacks. ##### Example: initialize a client with synchronous (non-batch) defaults The following example initializes a client for writing and querying data in an InfluxDB 3 Core database. Given that `write_client_options` isn’t specified, the client uses the default [synchronous writing](#synchronous-writing) mode. ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with read/write permissions on the specified database To explicitly specify synchronous mode, create a client with `write_options=SYNCHRONOUS`–for example: ```python from influxdb_client_3 import InfluxDBClient3, write_client_options, SYNCHRONOUS wco = write_client_options(write_options=SYNCHRONOUS) client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", write_client_options=wco, flight_client_options=None) ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database #### Batch writing Batch writing is particularly useful for efficient bulk data operations. Options include setting batch size, flush intervals, retry intervals, and more. Batch writing groups multiple writes into a single request to InfluxDB. In batching mode, the client adds the record or records to a batch, and then schedules the batch for writing to InfluxDB. The client writes the batch to InfluxDB after reaching `write_client_options.batch_size` or `write_client_options.flush_interval`. If a write fails, the client reschedules the write according to the `write_client_options` retry options. ##### Configuring write client options Use `WriteOptions` and `write_client_options` to configure batch writing and response handling for the client: 1. Instantiate `WriteOptions`. To use batch defaults, call the constructor without specifying parameters. 2. Call `write_client_options` and use the `write_options` parameter to specify the `WriteOptions` instance from the preceding step. Specify callback parameters (success, error, and retry) to invoke functions on success or error. 3. Instantiate `InfluxDBClient3` and use the `write_client_options` parameter to specify the `dict` output from the preceding step. ##### Example: initialize a client using batch defaults and callbacks The following example shows how to use batch mode with defaults and specify callback functions for the response status (success, error, or retryable error). ```python from influxdb_client_3 import(InfluxDBClient3, write_client_options, WriteOptions, InfluxDBError) status = None # Define callbacks for write responses def success(self, data: str): status = "Success writing batch: data: {data}" assert status.startswith('Success'), f"Expected {status} to be success" def error(self, data: str, err: InfluxDBError): status = f"Error writing batch: config: {self}, data: {data}, error: {err}" assert status.startswith('Success'), f"Expected {status} to be success" def retry(self, data: str, err: InfluxDBError): status = f"Retry error writing batch: config: {self}, data: {data}, error: {err}" assert status.startswith('Success'), f"Expected {status} to be success" # Instantiate WriteOptions for batching write_options = WriteOptions() wco = write_client_options(success_callback=success, error_callback=error, retry_callback=retry, write_options=write_options) # Use the with...as statement to ensure the file is properly closed and resources # are released. with InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", write_client_options=wco) as client: client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time', tag_columns=["room"], write_precision='s') ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database ### InfluxDBClient3 instance methods ### InfluxDBClient3.write Writes a record or a list of records to InfluxDB. #### Parameters * **`record`** (*record* or list): A record or list of records to write. A record can be a `Point` object, a dict that represents a point, a line protocol string, or a `DataFrame`. * **`database`** (string): The database to write to. Default is to write to the database specified for the client. * \*\*`**kwargs`\*\*: Additional write options–for example: * **`write_precision`** (string): *Optional*. Default is `"ns"`. Specifies the [precision](/influxdb3/core/reference/glossary/#precision) (`"ms"`, `"s"`, `"us"`, `"ns"`) for timestamps in `record`. * **`write_client_options`** (dict): *Optional*. Specifies callback functions and options for [batch writing](#batch-writing) mode. To generate the `dict`, use the [`write_client_options` function](#function-write_client_optionskwargs). #### Example: write a line protocol string ```python from influxdb_client_3 import InfluxDBClient3 point = "home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641024000" client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") client.write(record=point, write_precision="s") ``` The following sample code executes an SQL query to retrieve the point: ```python # Execute an SQL query table = client.query(query='''SELECT room FROM home WHERE temp=21.1 AND time=from_unixtime(1641024000)''') # table is a pyarrow.Table room = table[0][0] assert f"{room}" == 'Living Room', f"Expected {room} to be Living Room" ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database #### Example: write data using points The `influxdb_client_3.Point` class provides an interface for constructing a data point for a measurement and setting fields, tags, and the timestamp for the point. The following example shows how to create a `Point` object, and then write the data to InfluxDB. ```python from influxdb_client_3 import Point, InfluxDBClient3 point = Point("home").tag("room", "Kitchen").field("temp", 21.5).field("hum", .25) client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") client.write(point) ``` The following sample code executes an InfluxQL query to retrieve the written data: ```python # Execute an InfluxQL query table = client.query(query='''SELECT DISTINCT(temp) as val FROM home WHERE temp > 21.0 AND time >= now() - 10m''', language="influxql") # table is a pyarrow.Table df = table.to_pandas() assert 21.5 in df['val'].values, f"Expected value in {df['val']}" ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database ##### Example: write data using a dict `InfluxDBClient3` can serialize a dictionary object into line protocol. If you pass a `dict` to `InfluxDBClient3.write`, the client expects the `dict` to have the following *point* attributes: * **measurement** (string): the measurement name * **tags** (dict): a dictionary of tag key-value pairs * **fields** (dict): a dictionary of field key-value pairs * **time**: the [timestamp](/influxdb3/core/reference/glossary/#timestamp) for the record The following example shows how to define a `dict` that represents a point, and then write the data to InfluxDB. ```python from influxdb_client_3 import InfluxDBClient3 # Using point dictionary structure points = { "measurement": "home", "tags": {"room": "Kitchen", "sensor": "K001"}, "fields": {"temp": 72.2, "hum": 36.9, "co": 4}, "time": 1641067200 } client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") client.write(record=points, write_precision="s") ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database ### InfluxDBClient3.write\_file Writes data from a file to InfluxDB. Execution is synchronous. #### Parameters * **`file`** (string): A path to a file containing records to write to InfluxDB. The filename must end with one of the following supported extensions. For more information about encoding and formatting data, see the documentation for each supported format: * `.feather`: [Feather](https://arrow.apache.org/docs/python/feather.html) * `.parquet`: [Parquet](https://arrow.apache.org/docs/python/parquet.html) * `.csv`: [Comma-separated values](https://arrow.apache.org/docs/python/csv.html) * `.json`: [JSON](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html) * `.orc`: [ORC](https://arrow.apache.org/docs/python/orc.html) * **`measurement_name`** (string): Defines the measurement name for records in the file. The specified value takes precedence over `measurement` and `iox::measurement` columns in the file. If no value is specified for the parameter, and a `measurement` column exists in the file, the `measurement` column value is used for the measurement name. If no value is specified for the parameter, and no `measurement` column exists, the `iox::measurement` column value is used for the measurement name. * **`tag_columns`** (list): Tag column names. Columns not included in the list and not specified by another parameter are assumed to be fields. * **`timestamp_column`** (string): The name of the column that contains timestamps. Default is `'time'`. * **`database`** (`str`): The database to write to. Default is to write to the database specified for the client. * **`file_parser_options`** (callable): A function for providing additional arguments to the file parser. * **`**kwargs`**: Additional options to pass to the `WriteAPI`–for example: * **`write_precision`** (string): *Optional*. Default is `"ns"`. Specifies the [precision](/influxdb3/core/reference/glossary/#precision) (`"ms"`, `"s"`, `"us"`, `"ns"`) for timestamps in `record`. * **`write_client_options`** (dict): *Optional*. Specifies callback functions and options for [batch writing](#batch-writing) mode. To generate the `dict`, use the [`write_client_options` function](#function-write_client_optionskwargs). #### Example: use batch options when writing file data The following example shows how to specify customized write options for batching, retries, and response callbacks, and how to write data from CSV and JSON files to InfluxDB: ```python from influxdb_client_3 import(InfluxDBClient3, write_client_options, WritePrecision, WriteOptions, InfluxDBError) # Define the result object result = { 'config': None, 'status': None, 'data': None, 'error': None } # Define callbacks for write responses def success_callback(self, data: str): result['config'] = self result['status'] = 'success' result['data'] = data assert result['data'] != None, f"Expected {result['data']}" print("Successfully wrote data: {result['data']}") def error_callback(self, data: str, exception: InfluxDBError): result['config'] = self result['status'] = 'error' result['data'] = data result['error'] = exception assert result['status'] == "success", f"Expected {result['error']} to be success for {result['config']}" def retry_callback(self, data: str, exception: InfluxDBError): result['config'] = self result['status'] = 'retry_error' result['data'] = data result['error'] = exception assert result['status'] == "success", f"Expected {result['status']} to be success for {result['config']}" write_options = WriteOptions(batch_size=500, flush_interval=10_000, jitter_interval=2_000, retry_interval=5_000, max_retries=5, max_retry_delay=30_000, exponential_base=2) wco = write_client_options(success_callback=success_callback, error_callback=error_callback, retry_callback=retry_callback, write_options=write_options) with InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", write_client_options=wco) as client: client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time', tag_columns=["room"], write_precision='s') client.write_file(file='./data/home-sensor-data.json', timestamp_column='time', tag_columns=["room"], write_precision='s') ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with write permissions on the specified database ### InfluxDBClient3.query Sends a Flight request to execute the specified SQL or InfluxQL query. Returns all data in the query result as an Arrow table ([`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html) instance). #### Parameters * **`query`** (string): the SQL or InfluxQL to execute. * **`language`** (string): the query language used in the `query` parameter–`"sql"` or `"influxql"`. Default is `"sql"`. * **`mode`** (string): Specifies the output to return from the [`pyarrow.flight.FlightStreamReader`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightStreamReader.html#pyarrow.flight.FlightStreamReader). Default is `"all"`. * `all`: Read the entire contents of the stream and return it as a [`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html). * `chunk`: Read the next message (a `FlightStreamChunk`) and return `data` and `app_metadata`. Returns `null` if there are no more messages. * `pandas`: Read the contents of the stream and return it as a [`pandas.DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/frame.html). * `reader`: Convert the `FlightStreamReader` into a [`pyarrow.RecordBatchReader`](https://arrow.apache.org/docs/python/generated/pyarrow.RecordBatchReader.html#pyarrow-recordbatchreader). * `schema`: Return the schema for all record batches in the stream. * **`**kwargs`**: [`FlightCallOptions`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightCallOptions.html#pyarrow.flight.FlightCallOptions) #### Example: query using SQL ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") table = client.query("SELECT * from home WHERE time >= now() - INTERVAL '90 days'") # Filter columns. print(table.select(['room', 'temp'])) # Use PyArrow to aggregate data. print(table.group_by('hum').aggregate([])) ``` In the examples, replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with read permission on the specified database #### Example: query using InfluxQL ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") query = "SELECT * from home WHERE time >= -90d" table = client.query(query=query, language="influxql") # Filter columns. print(table.select(['room', 'temp'])) ``` ##### Example: read all data from the stream and return a pandas DataFrame ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") query = "SELECT * from home WHERE time >= now() - INTERVAL '90 days'" pd = client.query(query=query, mode="pandas") # Print the pandas DataFrame formatted as a Markdown table. print(pd.to_markdown()) ``` ##### Example: view the schema for all batches in the stream ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") table = client.query("""SELECT * from home WHERE time >= now() - INTERVAL '90 days'""") # View the table schema. print(table.schema) ``` ##### Example: retrieve the result schema and no data ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") query = "SELECT * from home WHERE time >= now() - INTERVAL '90 days'" schema = client.query(query=query, mode="schema") print(schema) ``` ##### Specify a timeout Pass `timeout=` for [`FlightCallOptions`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightCallOptions.html#pyarrow.flight.FlightCallOptions) to use a custom timeout. ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") query = "SELECT * from home WHERE time >= now() - INTERVAL '90 days'" client.query(query=query, timeout=5) ``` ### InfluxDBClient3.close Sends all remaining records from the batch to InfluxDB, and then closes the underlying write client and Flight client to release resources. #### Example: close a client ```python from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") client.close() ``` ## Class Point Provides an interface for constructing a time series data point for a measurement, and setting fields, tags, and timestamp. ```python from influxdb_client_3 import Point point = Point("home").tag("room", "Living Room").field("temp", 72) ``` See how to [write data using points](#example-write-data-using-points). ## Class WriteOptions Provides an interface for constructing options that customize batch writing behavior, such as batch size and retry. ```python from influxdb_client_3 import WriteOptions write_options = WriteOptions(batch_size=500, flush_interval=10_000, jitter_interval=2_000, retry_interval=5_000, max_retries=5, max_retry_delay=30_000, exponential_base=2) ``` See how to [use batch options for writing data](#example-use-batch-options-when-writing-file-data). ### Parameters * **`batch_size`**: Default is `1000`. * **`flush_interval`**: Default is `1000`. * **`jitter_interval`**: Default is `0`. * **`retry_interval`**: Default is `5000`. * **`max_retries`**: Default is `5`. * **`max_retry_delay`**: Default is `125000`. * **`max_retry_time`**: Default is `180000`. * **`exponential_base`**: Default is `2`. * **`max_close_wait`**: Default is `300000`. * **`write_scheduler`**: Default is `ThreadPoolScheduler(max_workers=1)`. ## Functions * [influxdb\_client\_3.write\_client\_options](#function-write_client_optionskwargs) * [influxdb\_client\_3.flight\_client\_options](#function-flight_client_optionskwargs) ### Function write\_client\_options(\*\*kwargs) Returns a `dict` with the specified write client options. #### Parameters The function takes the following keyword arguments: * **`write_options`** ([`WriteOptions`](#class-writeoptions)): Specifies whether the client writes data using synchronous mode or batching mode. If using batching mode, the client uses the specified batching options. * **`point_settings`** (dict): Default tags that the client will add to each point when writing the data to InfluxDB. * **`success_callback`** (callable): If using batching mode, a function to call after data is written successfully to InfluxDB (HTTP status `204`) * **`error_callback`** (callable): if using batching mode, a function to call if data is not written successfully (the response has a non-`204` HTTP status) * **`retry_callback`** (callable): if using batching mode, a function to call if the request is a retry (using batching mode) and data is not written successfully #### Example: instantiate options for batch writing ```python from influxdb_client_3 import write_client_options, WriteOptions from influxdb_client_3.write_client.client.write_api import WriteType def success(): print("Success") def error(): print("Error") def retry(): print("Retry error") write_options = WriteOptions() wco = write_client_options(success_callback=success, error_callback=error, retry_callback=retry, write_options=write_options) assert wco['success_callback'] assert wco['error_callback'] assert wco['retry_callback'] assert wco['write_options'].write_type == WriteType.batching ``` #### Example: instantiate options for synchronous writing ```python from influxdb_client_3 import write_client_options, SYNCHRONOUS from influxdb_client_3.write_client.client.write_api import WriteType wco = write_client_options(write_options=SYNCHRONOUS) assert wco['write_options'].write_type == WriteType.synchronous ``` ### Function flight\_client\_options(\*\*kwargs) Returns a `dict` with the specified [FlightClient](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html) parameters. #### Parameters * `kwargs`: keyword arguments for [`pyarrow.flight.FlightClient`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html) parameters #### Example: specify the root certificate path ```python from influxdb_client_3 import InfluxDBClient3, flight_client_options import certifi fh = open(certifi.where(), "r") cert = fh.read() fh.close() client = InfluxDBClient3(host=f"localhost:8181", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", flight_client_options=flight_client_options(tls_root_certs=cert)) ``` Replace the following: * `DATABASE_NAME`: the name of your InfluxDB 3 Core [database](/influxdb3/core/admin/databases/) * `DATABASE_TOKEN`: an InfluxDB 3 Core [database token](/influxdb3/core/admin/tokens/#database-tokens)with read permission on the specified database ## Constants * `influxdb_client_3.SYNCHRONOUS`: Represents synchronous write mode * `influxdb_client_3.WritePrecision`: Enum class that represents write precision ## Exceptions * `influxdb_client_3.InfluxDBError`: Exception class raised for InfluxDB-related errors #### Related [Flight API](/influxdb3/core/tags/flight-api/)[python](/influxdb3/core/tags/python/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-python release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/python/release-notes/ ## v0.20.0 ### Features 1. [#208](https://github.com/InfluxCommunity/influxdb3-python/pull/208): Add `influx3 query` CLI support for executing SQL/InfluxQL queries with JSON/JSONL/CSV/pretty output, including module execution via `python -m influxdb_client_3`. 2. [#213](https://github.com/InfluxCommunity/influxdb3-python/pull/213): Add partial write support and default writes to the V2 API endpoint. See [Partial writes](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/#partial-writes) for more.`no_sync` requires `use_v2_api=False`; `accept_partial` applies only to V3 API endpoint writes. ### Others 1. [#215](https://github.com/InfluxCommunity/influxdb3-python/pull/215): * Remove cookie/session-based signin/signout support from the writing client. * Remove basic authentication with a username and password. ## v0.19.0 ### Features 1. [#198](https://github.com/InfluxCommunity/influxdb3-python/pull/198): Support custom tag order via `tag_order` write option. See [Sort tags by priority](https://docs.influxdata.com/influxdb3/enterprise/write-data/best-practices/schema-design/#sort-tags-by-query-priority) for more. 2. [#202](https://github.com/InfluxCommunity/influxdb3-python/pull/202): Add escape for field keys when serializing to line protocol in `PolarsDataframeSerializer`. ## v0.18.0 ### Features 1. [#196](https://github.com/InfluxCommunity/influxdb3-python/pull/196): Support passing middleware functions to the Flight client. ### Bug Fixes 1. [#194](https://github.com/InfluxCommunity/influxdb3-python/pull/194): Fix `InfluxDBClient3.write_file()` and `InfluxDBClient3.write_dataframe()` fail with batching mode. 2. [#197](https://github.com/InfluxCommunity/influxdb3-python/pull/197): InfluxDB 3 Core/Enterprise write errors details handling. ## v0.17.0 ### Features 1. [#177](https://github.com/InfluxCommunity/influxdb3-python/pull/177): Add dedicated DataFrame methods for improved usability and type safety: * `write_dataframe()`: New method for writing pandas and polars DataFrames with explicit parameters (`measurement`, `timestamp_column`, `tags`, `timestamp_timezone`). * `query_dataframe()`: New method for querying data directly to a pandas or polars DataFrame via the `frame_type` parameter. * Updated README with clear examples for DataFrame operations. 2. [#179](https://github.com/InfluxCommunity/influxdb3-python/pull/179): Add option to disable gRPC response compression for Flight queries: * `disable_grpc_compression` parameter in `InfluxDBClient3` constructor * `INFLUX_DISABLE_GRPC_COMPRESSION` environment variable support in `from_env()` 3. [#180](https://github.com/InfluxCommunity/influxdb3-python/pull/180): Add `flush()` method to `InfluxDBClient3`: * Allows flushing the write buffer without closing the client when using batching mode. * Enables applications to ensure data is written before querying, while keeping the client open for further operations. 4. [#185](https://github.com/InfluxCommunity/influxdb3-python/pull/185): * Add API Reference page on document page * Remove old document link. * Add link to document page in README.md ### Bug Fixes 1. [#177](https://github.com/InfluxCommunity/influxdb3-python/pull/177): Fix `TypeError` when writing DataFrames. Serializer-specific kwargs (e.g., `data_frame_measurement_name`) are now filtered before being passed to the HTTP layer. * CI updates ## v0.16.0 ### Features 1. [#158](https://github.com/InfluxCommunity/influxdb3-python/pull/158) Improved parameters for setting timeouts * `InfluxDB3Client()` constructor now directly specifies * `write_timeout` - timeout in milliseconds to be used when writing data. * `query_timeout` - timeout in milliseconds to be used when querying data. * Timeouts can be specifically overridden in direct method calls. * `client.write()` now propagates the argument `_request_timeout` as an `int` in milliseconds on the call stack even in batching mode. * `client.query()` now propagates the argument `timeout` as a `float` in seconds on the call stack. * CI updates ## v0.15.0 ### Features 1. [#146](https://github.com/InfluxCommunity/influxdb3-python/pull/146): Add function to get InfluxDB version. 2. [#149](https://github.com/InfluxCommunity/influxdb3-python/pull/149): Run integration tests against a locally started InfluxDB 3 Core server. ## v0.14.0 ### Features 1. [#141](https://github.com/InfluxCommunity/influxdb3-python/pull/141) Move “setuptools” package to build dependency. 2. [#142](https://github.com/InfluxCommunity/influxdb3-python/pull/142): Support fast writes without waiting for WAL persistence: * New write option (`WriteOptions.no_sync`) added: `True` value means faster write but without the confirmation that the data was persisted. Default value: `False`. * **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!** * Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`). * Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`,`"second"` ( in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`). 3. [#145](https://github.com/InfluxCommunity/influxdb3-python/pull/145): Improve the document wording for README.md ## v0.13.0 ### Features 1. [#130](https://github.com/InfluxCommunity/influxdb3-python/pull/130): Remove org parameters from the example code because It is not mandatory in Influxdb3 2. [#139](https://github.com/InfluxCommunity/influxdb3-python/pull/139): Supports environment variables with the same name as other clients 3. [#140](https://github.com/InfluxCommunity/influxdb3-python/pull/140): Query api will throw `InfluxdbClientQueryError` when receiving `ArrowException` from gRPC servers ## v0.12.0 ### Features 1. [#123](https://github.com/InfluxCommunity/influxdb3-python/pull/123): Introduces `query_async()` method. From this release the client now has a `query_async()` method that takes advantage of asyncio’s event loop to run query calls in their own executor. For example: ``` table = await client.query_async(query) ``` ### Bug Fixes 1. [#121](https://github.com/InfluxCommunity/influxdb3-python/pull/121): Fix use of arguments `verify_ssl` and `ssl_ca_cert` in `QueryApi`. ## v0.11.0 ### Bug Fixes 1. [#119](https://github.com/InfluxCommunity/influxdb3-python/pull/119): Fix use of `proxy` argument in client and query\_api to use in channel solution for GRPC proxy. ## v0.10.0 ### Bug Fixes 1. [#113](https://github.com/InfluxCommunity/influxdb3-python/pull/113): Fix import error of `PolarsDataframeSerializer` in batching mode ## v0.9.0 ### Features 1. [#108](https://github.com/InfluxCommunity/influxdb3-python/pull/108): Better expose access to response headers in `InfluxDBError`. Example `handle_http_error` added. 2. [#112](https://github.com/InfluxCommunity/influxdb3-python/pull/112): Update batching examples, add integration tests of batching. ### Bug Fixes 1. [#107](https://github.com/InfluxCommunity/influxdb3-python/pull/107): Missing `py.typed` in distribution package 2. [#111](https://github.com/InfluxCommunity/influxdb3-python/pull/111): Reduce log level of disposal of batch processor to DEBUG ## v0.8.0 ### Features 1. [#101](https://github.com/InfluxCommunity/influxdb3-python/pull/101): Add support for InfluxDB Edge (OSS) authentication ### Bug Fixes 1. [#100](https://github.com/InfluxCommunity/influxdb3-python/pull/100): InfluxDB Edge (OSS) error handling 2. [#105](https://github.com/InfluxCommunity/influxdb3-python/pull/105): Importing Polars serialization module ## v0.7.0 ### Bug Fixes 1. [#95](https://github.com/InfluxCommunity/influxdb3-python/pull/95): `Polars` is optional dependency 2. [#99](https://github.com/InfluxCommunity/influxdb3-python/pull/99): Skip infinite values during serialization to line protocol ## v0.6.1 ### Bug Fixes 1. [#98](https://github.com/InfluxCommunity/influxdb3-python/pull/98): Missing declaration for `query` module ## v0.6.0 ### Features 1. [#89](https://github.com/InfluxCommunity/influxdb3-python/pull/89): Use `datetime.fromisoformat` over `dateutil.parse` in Python 3.11+ 2. [#92](https://github.com/InfluxCommunity/influxdb3-python/pull/92): Update `user-agent` header value to `influxdb3-python/{VERSION}` and add it to queries as well. ### Bug Fixes 1. [#86](https://github.com/InfluxCommunity/influxdb3-python/pull/86): Refactor to `timezone` specific `datetime` helpers to avoid use deprecated functions ## v0.5.0 ### Features 1. [#88](https://github.com/InfluxCommunity/influxdb3-python/pull/88): Add support for named query parameters: ``` from influxdb_client_3 import InfluxDBClient3 with InfluxDBClient3(host="https://us-east-1-1.aws.cloud2.influxdata.com", token="my-token", database="my-database") as client: table = client.query("select * from cpu where host=$host", query_parameters={"host": "server01"}) print(table.to_pandas()) ``` ### Bug Fixes 1. [#87](https://github.com/InfluxCommunity/influxdb3-python/pull/87): Fix examples to use `write_options` instead of the object name `WriteOptions` ### Others 1. [#84](https://github.com/InfluxCommunity/influxdb3-python/pull/84): Enable packaging type information - `py.typed` ## v0.4.0 ### Bugfix 1. [#77](https://github.com/InfluxCommunity/influxdb3-python/pull/77): Support using pandas nullable types ### Others 1. [#80](https://github.com/InfluxCommunity/influxdb3-python/pull/80): Integrate code style check into CI --- # Rust client library for InfluxDB 3 Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/rust/ The InfluxDB 3 [`influxdb3-rust` Rust client library](https://github.com/InfluxCommunity/influxdb3-rust) integrates with Rust applications to write and query data stored in InfluxDB 3 Core. **Latest version:**[v0.2.0](/influxdb3/core/reference/client-libraries/v3/rust/release-notes/)(2026-06-16) The documentation for this client library is available on [docs.rs](https://docs.rs/influxdb3-client/latest/influxdb3_client/). [InfluxDB 3 Rust client library](https://github.com/InfluxCommunity/influxdb3-rust) [Flight client](/influxdb3/core/tags/flight-client/)[Rust](/influxdb3/core/tags/rust/)[gRPC](/influxdb3/core/tags/grpc/)[SQL](/influxdb3/core/tags/sql/)[Flight SQL](/influxdb3/core/tags/flight-sql/)[client libraries](/influxdb3/core/tags/client-libraries/) --- # influxdb3-rust release notes Source: https://docs.influxdata.com/influxdb3/core/reference/client-libraries/v3/rust/release-notes/ ## v0.2.0 ### Features 1. [#12](https://github.com/InfluxCommunity/influxdb3-rust/pull/12): Expand client configuration support for environment variables and connection strings. Add auth scheme and write option support. Preserve explicit ports and strip userinfo from normalized hosts. Remove the legacy `bucket` and `INFLUX_BUCKET` aliases in favor of `database` and `INFLUX_DATABASE`. 2. [#19](https://github.com/InfluxCommunity/influxdb3-rust/pull/19): Default writes to the V2 API endpoint. Add builder methods for write defaults.`no_sync` requires `use_v2_api=false` to write to the V3 API endpoint.`accept_partial` applies only when writes are sent to the V3 API endpoint and is ignored otherwise. ### Bug Fixes 1. [#13](https://github.com/InfluxCommunity/influxdb3-rust/pull/13): Improve Arrow query result type support. Unsupported Arrow types now produce `Error::UnsupportedArrowType` instead of `Null`. ### Dependencies 1. [#18](https://github.com/InfluxCommunity/influxdb3-rust/pull/18): Upgrade Arrow dependencies to version 58 and require Rust 1.89 or later. ## v0.1.0 Initial release. ### Features * Async client for InfluxDB 3 Core and Enterprise over HTTP (writes) and Arrow Flight (queries). * Write API: a builder accepting line-protocol strings, `Vec`, and (with the `polars` feature) a DataFrame. Options for timestamp precision, batching, in-flight concurrency, default tags, gzip, and WAL no-sync. * Query API: SQL and InfluxQL, parameterised queries, row iteration, and streaming of results too large to hold in memory. * Automatic retries with exponential backoff and full jitter for transient failures (transport errors, `429`, `5xx`), honouring `Retry-After`. Configurable per client or per request. * Partial-write error reporting with per-line detail. * Optional `polars` feature: DataFrame writes and query-to-DataFrame conversion. ### Notes * Retries are enabled by default (`max_retries = 3`). Use `.no_retry()` or a custom `RetryConfig` to change this. --- # InfluxDB 3 Core configuration options Source: https://docs.influxdata.com/influxdb3/core/reference/config-options/ InfluxDB 3 Core lets you customize your configuration by using`influxdb3` command options or by setting environment variables. ## Configure your server Pass configuration options using either command options or environment variables. Command options take precedence over environment variables. ### TOML configuration files DEB and RPM installs include a TOML configuration file at`/etc/influxdb3/influxdb3-core.conf`. The systemd launcher reads this file and converts each entry to an`INFLUXDB3_*` environment variable (the pattern is `INFLUXDB3_`with hyphens replaced by underscores and uppercased) before invoking`influxdb3 serve`. `influxdb3 serve` does not yet natively read TOML; the file’s effect is applied through the environment variables the launcher sets. CLI flags passed to `influxdb3 serve` still override values defined in the TOML file because they override the environment variables that file becomes. For day-to-day systemd operation — including the edit-and-restart workflow for applying changes — see[Run as a system service (Linux)](/influxdb3/core/install/#run-as-a-system-service-linux). ### Global vs serve-specific options Some options are **global** (specified before the command) while others are **serve-specific** (specified after `serve`): * **Global options**: Apply to the `influxdb3` CLI itself (for example, `--num-io-threads`) * **Serve options**: Apply only to the `serve` command (for example, `--node-id`, `--object-store`, `--verbose`) #### Example command with global and serve-specific options ```sh influxdb3 --num-io-threads=4 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --verbose \ --log-filter info ``` ##### Example environment variables ``` export INFLUXDB3_NODE_ID=my-node export INFLUXDB3_OBJECT_STORE=file export INFLUXDB3_DATA_DIR=~/.influxdb3 export INFLUXDB3_LOG_FILTER=info influxdb3 serve ``` ### Deprecated names Many options and environment variables were renamed in InfluxDB 3 Core 3.11.0, with the old names kept as deprecated aliases. Option tables on this page list the pre-3.11 names where they exist. For the full old-to-new tables and compatibility rules, see[Configuration name changes in 3.11](#name-changes-in-3-11). ### Size option values Options that accept a size value require an explicit unit: * Append a unit suffix `b`, `kb`, `mb`, `gb`, or `tb`(case-insensitive)—for example, `10mb` or `8GB`. * Where noted, specify a percentage of total available memory—for example, `20%`. Bare numbers are rejected to avoid a silent change in meaning—historically, a bare number meant megabytes for some options and bytes for others. For compatibility with pre-3.11 configurations: * The deprecated `--parquet-mem-cache-size`, `--exec-mem-pool-bytes`, and`--force-snapshot-mem-threshold` options (and their environment variables) accept their pre-3.11 value format—a bare number means megabytes—with a startup deprecation warning. * `--max-http-request-size` (name unchanged) accepts a bare number as bytes, its pre-3.11 meaning, with a startup warning. ## Global configuration options The following options apply to the `influxdb3` CLI globally and must be specified **before** any subcommand (for example, `serve`): ### num-io-threads Sets the number of threads allocated to the IO runtime thread pool. IO threads handle HTTP request serving, line protocol parsing, and file operations. > [!Important] > `--num-io-threads` is a **global option** that must be specified before the `serve` command. ```bash # Set IO threads (global option before serve) influxdb3 --num-io-threads=8 serve --node-id=node0 --object-store=file ``` | influxdb3 option | Environment variable | |------------------|--------------------------| |`--num-io-threads`|`INFLUXDB3_NUM_IO_THREADS`| ## Server configuration options * [General](#general) * [Security](#security) * [AWS](#aws) * [Google Cloud Service](#google-cloud-service) * [Microsoft Azure](#microsoft-azure) * [Object Storage](#object-storage) * [Logs](#logs) * [Traces](#traces) * [DataFusion](#datafusion) * [HTTP](#http) * [Memory](#memory) * [Write-Ahead Log (WAL)](#write-ahead-log-wal) * [Compaction](#compaction) * [Caching](#caching) * [Processing Engine](#processing-engine) * [Resource Limits](#resource-limits) * [Data Lifecycle Management](#data-lifecycle-management) * [Telemetry](#telemetry) * [TCP Listeners](#tcp-listeners) ### General * [data-dir](#data-dir) * [node-id](#node-id) * [object-store](#object-store) * [query-file-limit](#query-file-limit) #### data-dir For the `file` object store, defines the location InfluxDB 3 Core uses to store files locally. Required when using the `file` [object store](#object-store). |influxdb3 serve option| Environment variables | |----------------------|--------------------------------------------------------------------------------------| | `--data-dir` |`INFLUXDB3_DATA_DIR`
`INFLUXDB3_DB_DIR` ([pre-3.11 name](#name-changes-in-3-11))| #### node-id Specifies the node identifier used as a prefix in all object store file paths. This should be unique for any hosts sharing the same object store configuration–for example, the same bucket. |influxdb3 serve option| Environment variables | |----------------------|-----------------------------------------------------------------------------------------------------| | `--node-id` |`INFLUXDB3_NODE_ID`
`INFLUXDB3_NODE_IDENTIFIER_PREFIX` ([pre-3.11 name](#name-changes-in-3-11))| #### object-store Specifies which object storage to use to store Parquet files. This option supports the following values: * `memory`: Effectively no object persistence * `memory-throttled`: Like `memory` but with latency and throughput that somewhat resembles a cloud object store * `file`: Stores objects in the local filesystem (must also set `--data-dir`) * `s3`: Amazon S3 (must also set `--bucket`, `--aws-access-key-id`, `--aws-secret-access-key`, and possibly `--aws-default-region`) * `google`: Google Cloud Storage (must also set `--bucket` and `--google-service-account`) * `azure`: Microsoft Azure blob storage (must also set `--bucket`, `--azure-storage-account`, and `--azure-storage-access-key`) |influxdb3 serve option| Environment variable | |----------------------|------------------------| | `--object-store` |`INFLUXDB3_OBJECT_STORE`| ### Security * [tls-key](#tls-key) * [tls-cert](#tls-cert) * [tls-minimum-versions](#tls-minimum-version) * [without-auth](#without-auth) * [disable-authz](#disable-authz) * [admin-token-recovery-http-bind](#admin-token-recovery-http-bind) * [admin-token-file](#admin-token-file) #### tls-key The path to a key file for TLS to be enabled. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--tls-key` |`INFLUXDB3_TLS_KEY` | #### tls-cert The path to a cert file for TLS to be enabled. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--tls-cert` |`INFLUXDB3_TLS_CERT`| #### tls-minimum-version The minimum version for TLS. Valid values are `tls-1.2` or `tls-1.3`. Default is `tls-1.2`. |influxdb3 serve option | Environment variable | |-----------------------|-------------------------------| |`--tls-minimum-version`|`INFLUXDB3_TLS_MINIMUM_VERSION`| #### without-auth Disables authentication for all server actions (CLI commands and API requests). The server processes all requests without requiring tokens or authentication. |influxdb3 serve option| Environment variables | |----------------------|------------------------------------------------------------------------------------------------------| | `--without-auth` |`INFLUXDB3_WITHOUT_AUTH`
`INFLUXDB3_START_WITHOUT_AUTH` ([pre-3.11 name](#name-changes-in-3-11))| #### disable-authz Optionally disable authz by passing in a comma separated list of resources. Valid values are `health`, `ping`, and `metrics`. |influxdb3 serve option| Environment variable | |----------------------|-------------------------| | `--disable-authz` |`INFLUXDB3_DISABLE_AUTHZ`| #### admin-token-recovery-http-bind Enables an admin token recovery HTTP server on a separate port. This server allows regenerating lost admin tokens without existing authentication. The server automatically shuts down after a successful token regeneration. > [!Warning] > This option creates an unauthenticated endpoint that can regenerate admin tokens. > Only use this when you have lost access to your admin token and ensure the > server is only accessible from trusted networks. **Default:** `127.0.0.1:8182` (when enabled) | influxdb3 serve option | Environment variable | |----------------------------------|------------------------------------------| |`--admin-token-recovery-http-bind`|`INFLUXDB3_ADMIN_TOKEN_RECOVERY_HTTP_BIND`| ##### Example usage ```bash # Start server with recovery endpoint influxdb3 serve --admin-token-recovery-http-bind # In another terminal, regenerate the admin token influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182 ``` #### admin-token-file Specifies an offline admin token file to use if no tokens exist when the server starts. Once started, you can interact with the server using the provided token. Offline admin tokens are designed to help with automated deployments. |influxdb3 serve option| Environment variable | |----------------------|----------------------------| | `--admin-token-file` |`INFLUXDB3_ADMIN_TOKEN_FILE`| Offline admin tokens are defined in a JSON-formatted file. Use the following command to generate an offline admin token file: ```bash influxdb3 create token --admin \ --name "example-admin-token" \ --expiry 1d \ --offline \ --output-file ./path/to/admin-token.json ``` [](#view-example-offline-admin-token-file) View example offline admin token file ```json { "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...", "name": "example-admin-token", "expiry_millis": 1756400061529 } ``` ##### Example usage ```bash # Generate an admin token offline influxdb3 create token \ --admin \ --name "example-admin-token" \ --expiry 1d \ --offline \ --output-file ./path/to/admin-token.json # Start InfluxDB 3 Core using the generated token influxdb3 serve --admin-token-file ./path/to/admin-token.json ``` ### AWS * [aws-access-key-id](#aws-access-key-id) * [aws-secret-access-key](#aws-secret-access-key) * [aws-default-region](#aws-default-region) * [aws-endpoint](#aws-endpoint) * [aws-session-token](#aws-session-token) * [aws-allow-http](#aws-allow-http) * [aws-skip-signature](#aws-skip-signature) * [aws-credentials-file](#aws-credentials-file) #### aws-access-key-id When using Amazon S3 as the object store, set this to an access key that has permission to read from and write to the specified S3 bucket. |influxdb3 serve option|Environment variable| |----------------------|--------------------| |`--aws-access-key-id` |`AWS_ACCESS_KEY_ID` | #### aws-secret-access-key When using Amazon S3 as the object store, set this to the secret access key that goes with the specified access key ID. | influxdb3 serve option | Environment variable | |-------------------------|-----------------------| |`--aws-secret-access-key`|`AWS_SECRET_ACCESS_KEY`| #### aws-default-region When using Amazon S3 as the object store, set this to the region that goes with the specified bucket if different from the fallback value. **Default:** `us-east-1` |influxdb3 serve option|Environment variable| |----------------------|--------------------| |`--aws-default-region`|`AWS_DEFAULT_REGION`| #### aws-endpoint When using an Amazon S3 compatibility storage service, set this to the endpoint. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--aws-endpoint` | `AWS_ENDPOINT` | #### aws-session-token When using Amazon S3 as an object store, set this to the session token. This is handy when using a federated login or SSO and fetching credentials via the UI. |influxdb3 serve option|Environment variable| |----------------------|--------------------| |`--aws-session-token` |`AWS_SESSION_TOKEN` | #### aws-allow-http Allows unencrypted HTTP connections to AWS. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--aws-allow-http` | `AWS_ALLOW_HTTP` | #### aws-skip-signature If enabled, S3 object stores do not fetch credentials and do not sign requests. |influxdb3 serve option|Environment variable| |----------------------|--------------------| |`--aws-skip-signature`|`AWS_SKIP_SIGNATURE`| #### aws-credentials-file Specifies the path to your S3 credentials file. When using a credentials file, settings in the file override the corresponding CLI flags. S3 credential files are JSON-formatted and should contain the following: ```json { "aws_access_key_id": "AWS_ACCESS_KEY_ID", "aws_secret_access_key": "AWS_SECRET_ACCESS_KEY", "aws_session_token": "AWS_SESSION_TOKEN", "expiry": "UNIX_SECONDS_TIMESTAMP" } ``` The `aws_session_token` and `expiry` fields are optional. The file is automatically checked for updates at the expiry time or at 1-hour intervals. If the object store returns an “Unauthenticated” error, InfluxDB will attempt to update its in-memory credentials from this file and then retry the object store request. | influxdb3 serve option | Environment variable | |------------------------|----------------------| |`--aws-credentials-file`|`AWS_CREDENTIALS_FILE`| ### Google Cloud Service * [google-service-account](#google-service-account) #### google-service-account When using Google Cloud Storage as the object store, set this to the path to the JSON file that contains the Google credentials. | influxdb3 serve option | Environment variable | |--------------------------|------------------------| |`--google-service-account`|`GOOGLE_SERVICE_ACCOUNT`| ### Microsoft Azure * [azure-storage-account](#azure-storage-account) * [azure-storage-access-key](#azure-storage-access-key) * [azure-endpoint](#azure-endpoint) * [azure-allow-http](#azure-allow-http) #### azure-storage-account When using Microsoft Azure as the object store, set this to the name you see when navigating to **All Services \> Storage accounts \> `[name]`**. | influxdb3 serve option | Environment variable | |-------------------------|-----------------------| |`--azure-storage-account`|`AZURE_STORAGE_ACCOUNT`| #### azure-storage-access-key When using Microsoft Azure as the object store, set this to one of the Key values in the Storage account’s **Settings \> Access keys**. | influxdb3 serve option | Environment variable | |----------------------------|--------------------------| |`--azure-storage-access-key`|`AZURE_STORAGE_ACCESS_KEY`| #### azure-endpoint When using Microsoft Azure as the object store, set this to the Azure Blob Storage endpoint. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--azure-endpoint` | `AZURE_ENDPOINT` | #### azure-allow-http When using Microsoft Azure as the object store, allow unencrypted HTTP requests to Azure Blob Storage. **Default:** `false` |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--azure-allow-http` | `AZURE_ALLOW_HTTP` | ### Object Storage * [bucket](#bucket) * [object-store-connection-limit](#object-store-connection-limit) * [object-store-http2-only](#object-store-http2-only) * [object-store-http2-max-frame-size](#object-store-http2-max-frame-size) * [object-store-request-timeout](#object-store-request-timeout) * [object-store-max-retries](#object-store-max-retries) * [object-store-retry-timeout](#object-store-retry-timeout) * [object-store-tls-allow-insecure](#object-store-tls-allow-insecure) * [object-store-tls-ca](#object-store-tls-ca) #### bucket Sets the name of the object storage bucket to use. Must also set`--object-store` to a cloud object storage for this option to take effect. |influxdb3 serve option|Environment variable| |----------------------|--------------------| | `--bucket` | `INFLUXDB3_BUCKET` | #### object-store-connection-limit When using a network-based object store, limits the number of connections to this value. **Default:** `16` | influxdb3 serve option | Environment variables | |---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-connection-limit`|`INFLUXDB3_OBJECT_STORE_CONNECTION_LIMIT` (preferred)
`OBJECT_STORE_CONNECTION_LIMIT` (deprecated; supported for backward compatibility)| #### object-store-http2-only Forces HTTP/2 connections to network-based object stores. | influxdb3 serve option | Environment variables | |---------------------------|----------------------------------------------------------------------------------------------------------------------------------| |`--object-store-http2-only`|`INFLUXDB3_OBJECT_STORE_HTTP2_ONLY` (preferred)
`OBJECT_STORE_HTTP2_ONLY` (deprecated; supported for backward compatibility)| #### object-store-http2-max-frame-size Sets the maximum frame size (in bytes/octets) for HTTP/2 connections. | influxdb3 serve option | Environment variables | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-http2-max-frame-size`|`INFLUXDB3_OBJECT_STORE_HTTP2_MAX_FRAME_SIZE` (preferred)
`OBJECT_STORE_HTTP2_MAX_FRAME_SIZE` (deprecated; supported for backward compatibility)| #### object-store-request-timeout Sets the HTTP request timeout for object store requests. **Default:** `30s` | influxdb3 serve option | Environment variables | |--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-request-timeout`|`INFLUXDB3_OBJECT_STORE_REQUEST_TIMEOUT` (preferred)
`OBJECT_STORE_REQUEST_TIMEOUT` (deprecated; supported for backward compatibility)| #### object-store-max-retries Defines the maximum number of times to retry a request. | influxdb3 serve option | Environment variables | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-max-retries`|`INFLUXDB3_OBJECT_STORE_MAX_RETRIES` (preferred)
`OBJECT_STORE_MAX_RETRIES` (deprecated; supported for backward compatibility)| #### object-store-retry-timeout Specifies the maximum length of time from the initial request after which no further retries are be attempted. | influxdb3 serve option | Environment variables | |------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-retry-timeout`|`INFLUXDB3_OBJECT_STORE_RETRY_TIMEOUT` (preferred)
`OBJECT_STORE_RETRY_TIMEOUT` (deprecated; supported for backward compatibility)| #### object-store-tls-allow-insecure Allows invalid TLS certificates when connecting to object storage. This disables TLS certificate verification and should only be used for testing. | influxdb3 serve option | Environment variables | |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| |`--object-store-tls-allow-insecure`|`INFLUXDB3_OBJECT_STORE_TLS_ALLOW_INSECURE` (preferred)
`OBJECT_STORE_TLS_ALLOW_INSECURE` (deprecated; supported for backward compatibility)| #### object-store-tls-ca Specifies the path to a custom CA certificate file (PEM format) for verifying object store connections. Use this when your object store uses a certificate signed by a private CA. |influxdb3 serve option | Environment variables | |-----------------------|--------------------------------------------------------------------------------------------------------------------------| |`--object-store-tls-ca`|`INFLUXDB3_OBJECT_STORE_TLS_CA` (preferred)
`OBJECT_STORE_TLS_CA` (deprecated; supported for backward compatibility)| ### Logs * [log-filter](#log-filter) * [log-destination](#log-destination) * [log-format](#log-format) * [query-log-max-entries](#query-log-max-entries) (`--query-log-size` before 3.11) #### log-filter Sets the filter directive for logs. Use this option to control the verbosity of server logs globally or for specific components. ##### Log levels The following log levels are available (from least to most verbose): | Level | Description | |-------|-----------------------------------------------------------------------------------| |`error`| Only errors | |`warn` | Warnings and errors | |`info` | Informational messages, warnings, and errors *(default)* | |`debug`| Debug information for troubleshooting, plus all above levels | |`trace`|Very detailed tracing information, plus all above levels (produces high log volume)| ##### Basic usage To set the log level globally, pass one of the log levels: ```sh influxdb3 serve --log-filter debug ``` ##### Targeted filtering Globally enabling `debug` or `trace` produces a high volume of log output. For more targeted debugging, you can set different log levels for specific components using the format `,=`. ###### Debug write buffer operations ```sh influxdb3 serve --log-filter info,influxdb3_write_buffer=debug ``` ###### Trace WAL operations ```sh influxdb3 serve --log-filter info,influxdb3_wal=trace ``` ###### Multiple targeted filters ```sh influxdb3 serve --log-filter info,influxdb3_write_buffer=debug,influxdb3_wal=debug ``` ##### Common component names The following are common component names you can use for targeted filtering: | Component | Description | |------------------------|-----------------------------| |`influxdb3_write_buffer`| Write buffer operations | | `influxdb3_wal` | Write-ahead log operations | | `influxdb3_catalog` |Catalog and schema operations| | `influxdb3_cache` | Caching operations | > [!Note] > Targeted filtering requires knowledge of the codebase component names. > The component names correspond to Rust package names in the InfluxDB 3 source > code. Use `debug` or `trace` sparingly on specific components to avoid > excessive log output. |influxdb3 serve option| Environment variables | |----------------------|--------------------------------------------------------------------------------------------------------| | `--log-filter` |`INFLUXDB3_LOG_FILTER` (preferred)
`LOG_FILTER` (deprecated; supported for backward compatibility)| #### log-destination Specifies the destination for logs. This option supports the following values: * `stdout` *(default)* * `stderr` **Default:** `stdout` |influxdb3 serve option| Environment variables | |----------------------|------------------------------------------------------------------------------------------------------------------| | `--log-destination` |`INFLUXDB3_LOG_DESTINATION` (preferred)
`LOG_DESTINATION` (deprecated; supported for backward compatibility)| #### log-format Defines the message format for logs. This option supports the following values: * `full` *(default)* **Default:** `full` |influxdb3 serve option| Environment variables | |----------------------|--------------------------------------------------------------------------------------------------------| | `--log-format` |`INFLUXDB3_LOG_FORMAT` (preferred)
`LOG_FORMAT` (deprecated; supported for backward compatibility)| #### query-log-max-entries Defines the maximum number of entries in the query log. Up to this many queries remain in the log before older queries are evicted to make room for new ones. **Default:** `1000` > [!Note] > `--query-log-max-entries` was [renamed in 3.11](#name-changes-in-3-11)from `--query-log-size`. > The legacy option and environment variable names are deprecated aliases. | influxdb3 serve option | Environment variables | |------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| |`--query-log-max-entries`
`--query-log-size` (pre-3.11 name)|`INFLUXDB3_QUERY_LOG_MAX_ENTRIES`
`INFLUXDB3_QUERY_LOG_SIZE` ([pre-3.11 name](#name-changes-in-3-11))| ### Traces * [traces-exporter](#traces-exporter) * [traces-exporter-jaeger-agent-host](#traces-exporter-jaeger-agent-host) * [traces-exporter-jaeger-agent-port](#traces-exporter-jaeger-agent-port) * [traces-exporter-jaeger-service-name](#traces-exporter-jaeger-service-name) * [traces-exporter-jaeger-trace-context-header-name](#traces-exporter-jaeger-trace-context-header-name) * [traces-jaeger-debug-name](#traces-jaeger-debug-name) * [traces-jaeger-tags](#traces-jaeger-tags) * [traces-jaeger-max-msgs-per-second](#traces-jaeger-max-msgs-per-second) #### traces-exporter Sets the type of tracing exporter. **Default:** `none` |influxdb3 serve option| Environment variables | |----------------------|------------------------------------------------------------------------------------------------------------------| | `--traces-exporter` |`INFLUXDB3_TRACES_EXPORTER` (preferred)
`TRACES_EXPORTER` (deprecated; supported for backward compatibility)| #### traces-exporter-jaeger-agent-host Specifies the Jaeger agent network hostname for tracing. **Default:** `0.0.0.0` | influxdb3 serve option | Environment variables | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-exporter-jaeger-agent-host`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_HOST` (preferred)
`TRACES_EXPORTER_JAEGER_AGENT_HOST` (deprecated; supported for backward compatibility)| #### traces-exporter-jaeger-agent-port Defines the Jaeger agent network port for tracing. **Default:** `6831` | influxdb3 serve option | Environment variables | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-exporter-jaeger-agent-port`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_PORT` (preferred)
`TRACES_EXPORTER_JAEGER_AGENT_PORT` (deprecated; supported for backward compatibility)| #### traces-exporter-jaeger-service-name Sets the Jaeger service name for tracing. **Default:** `iox-conductor` | influxdb3 serve option | Environment variables | |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-exporter-jaeger-service-name`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_SERVICE_NAME` (preferred)
`TRACES_EXPORTER_JAEGER_SERVICE_NAME` (deprecated; supported for backward compatibility)| #### traces-exporter-jaeger-trace-context-header-name Specifies the header name used for passing trace context. **Default:** `uber-trace-id` | influxdb3 serve option | Environment variables | |----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-exporter-jaeger-trace-context-header-name`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME` (preferred)
`TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME` (deprecated; supported for backward compatibility)| #### traces-jaeger-debug-name Specifies the header name used for force sampling in tracing. **Default:** `jaeger-debug-id` | influxdb3 serve option | Environment variables | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-jaeger-debug-name`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_DEBUG_NAME` (preferred)
`TRACES_EXPORTER_JAEGER_DEBUG_NAME` (deprecated; supported for backward compatibility)| #### traces-jaeger-tags Defines a set of `key=value` pairs to annotate tracing spans with. |influxdb3 serve option| Environment variables | |----------------------|------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-jaeger-tags`|`INFLUXDB3_TRACES_EXPORTER_JAEGER_TAGS` (preferred)
`TRACES_EXPORTER_JAEGER_TAGS` (deprecated; supported for backward compatibility)| #### traces-jaeger-max-msgs-per-second Specifies the maximum number of messages sent to a Jaeger service per second. **Default:** `1000` | influxdb3 serve option | Environment variables | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| |`--traces-jaeger-max-msgs-per-second`|`INFLUXDB3_TRACES_JAEGER_MAX_MSGS_PER_SECOND` (preferred)
`TRACES_JAEGER_MAX_MSGS_PER_SECOND` (deprecated; supported for backward compatibility)| ### DataFusion * [datafusion-num-threads](#datafusion-num-threads) * [datafusion-max-parquet-fanout](#datafusion-max-parquet-fanout) * [datafusion-use-cached-parquet-loader](#datafusion-use-cached-parquet-loader) * [datafusion-config](#datafusion-config) #### datafusion-num-threads Sets the maximum number of DataFusion runtime threads to use. | influxdb3 serve option | Environment variable | |--------------------------|----------------------------------| |`--datafusion-num-threads`|`INFLUXDB3_DATAFUSION_NUM_THREADS`| #### datafusion-max-parquet-fanout When multiple Parquet files are required in a sorted way (deduplication for example), specifies the maximum fanout. **Default:** `1000` | influxdb3 serve option | Environment variable | |---------------------------------|-----------------------------------------| |`--datafusion-max-parquet-fanout`|`INFLUXDB3_DATAFUSION_MAX_PARQUET_FANOUT`| #### datafusion-use-cached-parquet-loader Uses a cached Parquet loader when reading Parquet files from the object store. | influxdb3 serve option | Environment variable | |----------------------------------------|------------------------------------------------| |`--datafusion-use-cached-parquet-loader`|`INFLUXDB3_DATAFUSION_USE_CACHED_PARQUET_LOADER`| #### datafusion-config Provides custom configuration to DataFusion as a comma-separated list of`key:value` pairs. |influxdb3 serve option| Environment variable | |----------------------|-----------------------------| |`--datafusion-config` |`INFLUXDB3_DATAFUSION_CONFIG`| ### HTTP * [max-http-request-size](#max-http-request-size) * [http-bind](#http-bind) #### max-http-request-size Specifies the maximum size of HTTP requests. Prefer a [unit suffix](#size-option-values)—for example, `10mb`. A bare number is accepted as bytes (its pre-3.11 meaning) with a startup warning. **Default:** `10mb` | influxdb3 serve option | Environment variable | |-------------------------|---------------------------------| |`--max-http-request-size`|`INFLUXDB3_MAX_HTTP_REQUEST_SIZE`| #### http-bind Defines the address on which InfluxDB serves HTTP API requests. **Default:** `0.0.0.0:8181` |influxdb3 serve option| Environment variable | |----------------------|--------------------------| | `--http-bind` |`INFLUXDB3_HTTP_BIND_ADDR`| ### Memory * [exec-mem-pool-size](#exec-mem-pool-size) (`--exec-mem-pool-bytes` before 3.11) * [force-snapshot-mem-size](#force-snapshot-mem-size) (`--force-snapshot-mem-threshold` before 3.11) #### exec-mem-pool-size Specifies the size of the memory pool used for query processing and data operations. This memory pool is used when InfluxDB 3 Core processes queries and performs internal data management tasks. Provide a value with a [unit suffix](#size-option-values) or as a percentage of the total available memory—for example: `8gb` or `10%`. **Default:** `20%` > [!Note] > `--exec-mem-pool-size` was [renamed in 3.11](#name-changes-in-3-11)from `--exec-mem-pool-bytes`. > The legacy option and environment variable names are still > accepted–including the pre-3.11 bare-number format, meaning > megabytes–with a startup deprecation warning. | influxdb3 serve option | Environment variables | |--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| |`--exec-mem-pool-size`
`--exec-mem-pool-bytes` (pre-3.11 name)|`INFLUXDB3_EXEC_MEM_POOL_SIZE`
`INFLUXDB3_EXEC_MEM_POOL_BYTES` ([pre-3.11 name](#name-changes-in-3-11))| #### force-snapshot-mem-size Specifies the threshold for the internal memory buffer. Supports either a percentage (portion of available memory) or a value with a[unit suffix](#size-option-values)—for example: `70%` or `1000mb`. **Default:** `50%` > [!Note] > `--force-snapshot-mem-size` was [renamed in 3.11](#name-changes-in-3-11)from `--force-snapshot-mem-threshold`. > The legacy option and environment variable names are still > accepted–including the pre-3.11 bare-number format, meaning > megabytes–with a startup deprecation warning. | influxdb3 serve option | Environment variables | |----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| |`--force-snapshot-mem-size`
`--force-snapshot-mem-threshold` (pre-3.11 name)|`INFLUXDB3_FORCE_SNAPSHOT_MEM_SIZE`
`INFLUXDB3_FORCE_SNAPSHOT_MEM_THRESHOLD` ([pre-3.11 name](#name-changes-in-3-11))| ### Write-Ahead Log (WAL) * [checkpoint-interval](#checkpoint-interval) * [wal-flush-interval](#wal-flush-interval) * [wal-files-per-snapshot](#wal-files-per-snapshot) (`--wal-snapshot-size` before 3.11) * [wal-max-buffered-writes](#wal-max-buffered-writes) (`--wal-max-write-buffer-size` before 3.11) * [snapshotted-wal-files-to-keep](#snapshotted-wal-files-to-keep) * [wal-replay-fail-on-error](#wal-replay-fail-on-error) * [wal-replay-concurrency-limit](#wal-replay-concurrency-limit) #### checkpoint-interval Sets the interval for consolidating[snapshots](/influxdb3/core/admin/backup-restore/#file-structure) into monthly checkpoints for faster server startup. Snapshots accumulate in object storage over time and are not automatically deleted. Without checkpointing, the server loads individual snapshots on startup. The number of snapshots is determined by the lookback window ([`gen1-lookback-duration`](#gen1-lookback-duration), default 1 month) divided by [`gen1-duration`](#gen1-duration) (default 10 minutes), with a minimum of 100. With default settings, that can be up to \~4,320 snapshots. With checkpointing enabled, the server periodically consolidates snapshot metadata into checkpoints in object storage. On startup, the server loads one to two checkpoints per calendar month, then loads only snapshots created since the last checkpoint. Enabling checkpointing does not delete old snapshots. Up to 10 checkpoints load concurrently during startup. The server retains two checkpoints per calendar month and handles month rollovers automatically. Accepts a [duration](/influxdb3/core/reference/glossary/#duration) value–for example: `1h`, `30m`, `10m`. **Default:** *Not set (disabled)* |influxdb3 serve option | Environment variable | |-----------------------|-------------------------------| |`--checkpoint-interval`|`INFLUXDB3_CHECKPOINT_INTERVAL`| ##### Example ```bash influxdb3 serve --checkpoint-interval 1h ``` #### wal-flush-interval Specifies the interval to flush buffered data to a WAL file. Writes that wait for WAL confirmation take up to this interval to complete. Use `s` for seconds or `ms` for milliseconds. For local disks, `100 ms` is recommended. **Default:** `1s` |influxdb3 serve option| Environment variable | |----------------------|------------------------------| |`--wal-flush-interval`|`INFLUXDB3_WAL_FLUSH_INTERVAL`| #### wal-files-per-snapshot Defines the number of WAL files to attempt to remove in a snapshot. This, multiplied by the interval, determines how often snapshots are taken. **Default:** `600` > [!Note] > `--wal-files-per-snapshot` was [renamed in 3.11](#name-changes-in-3-11)from `--wal-snapshot-size`. > The legacy option and environment variable names are deprecated aliases. | influxdb3 serve option | Environment variables | |----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| |`--wal-files-per-snapshot`
`--wal-snapshot-size` (pre-3.11 name)|`INFLUXDB3_WAL_FILES_PER_SNAPSHOT`
`INFLUXDB3_WAL_SNAPSHOT_SIZE` ([pre-3.11 name](#name-changes-in-3-11))| #### wal-max-buffered-writes Specifies the maximum number of write requests that can be buffered before a flush must be executed and succeed. **Default:** `100000` > [!Note] > `--wal-max-buffered-writes` was [renamed in 3.11](#name-changes-in-3-11)from `--wal-max-write-buffer-size`. > The legacy option and environment variable names are deprecated aliases. | influxdb3 serve option | Environment variables | |-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| |`--wal-max-buffered-writes`
`--wal-max-write-buffer-size` (pre-3.11 name)|`INFLUXDB3_WAL_MAX_BUFFERED_WRITES`
`INFLUXDB3_WAL_MAX_WRITE_BUFFER_SIZE` ([pre-3.11 name](#name-changes-in-3-11))| #### snapshotted-wal-files-to-keep Specifies the number of snapshotted WAL files to retain in the object store. Flushing the WAL files does not clear the WAL files immediately; they are deleted when the number of snapshotted WAL files exceeds this number. **Default:** `300` | influxdb3 serve option | Environment variables | |---------------------------------|--------------------------------------------------------------------------------------------------------------------------| |`--snapshotted-wal-files-to-keep`|`INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP`
`INFLUXDB3_NUM_WAL_FILES_TO_KEEP` ([pre-3.11 name](#name-changes-in-3-11))| #### wal-replay-fail-on-error Determines whether WAL replay should fail when encountering errors. **Default:** `false` | influxdb3 serve option | Environment variable | |----------------------------|------------------------------------| |`--wal-replay-fail-on-error`|`INFLUXDB3_WAL_REPLAY_FAIL_ON_ERROR`| #### wal-replay-concurrency-limit Concurrency limit during WAL replay. Setting this number too high can lead to OOM. The default is dynamically determined. **Default:** `max(num_cpus, 10)` | influxdb3 serve option | Environment variable | |--------------------------------|----------------------------------------| |`--wal-replay-concurrency-limit`|`INFLUXDB3_WAL_REPLAY_CONCURRENCY_LIMIT`| ### Compaction * [gen1-duration](#gen1-duration) #### gen1-duration Specifies the duration that Parquet files are arranged into. Data timestamps land each row into a file of this duration. Supported durations are `1m`,`5m`, and `10m`. These files are known as “generation 1” files that the compactor in InfluxDB 3 Enterprise can merge into larger generations . **Default:** `10m` |influxdb3 serve option| Environment variable | |----------------------|-------------------------| | `--gen1-duration` |`INFLUXDB3_GEN1_DURATION`| ### Caching * [preemptive-cache-age](#preemptive-cache-age) * [file-cache-size](#file-cache-size) (`--parquet-mem-cache-size` before 3.11) * [parquet-mem-cache-prune-percentage](#parquet-mem-cache-prune-percentage) * [parquet-mem-cache-prune-interval](#parquet-mem-cache-prune-interval) * [file-cache-recency](#file-cache-recency) (`--parquet-mem-cache-query-path-duration` before 3.11) * [disable-file-cache](#disable-file-cache) (`--disable-parquet-mem-cache`, `--disable-data-file-cache` before 3.11) * [table-index-cache-max-entries](#table-index-cache-max-entries) * [table-index-cache-concurrency-limit](#table-index-cache-concurrency-limit) * [last-cache-eviction-interval](#last-cache-eviction-interval) * [distinct-cache-eviction-interval](#distinct-cache-eviction-interval) #### preemptive-cache-age Specifies the interval to prefetch into the Parquet cache during compaction. **Default:** `3d` | influxdb3 serve option | Environment variable | |------------------------|--------------------------------| |`--preemptive-cache-age`|`INFLUXDB3_PREEMPTIVE_CACHE_AGE`| #### file-cache-size Specifies the size of the in-memory data file cache. Provide a value with a [unit suffix](#size-option-values) or as a percentage of total available memory—for example, `4gb` or `20%`. This is a total budget. **Default:** `20%` > [!Note] > `--file-cache-size` was [renamed in 3.11](#name-changes-in-3-11)from `--parquet-mem-cache-size`. > The legacy option and environment variable names are still > accepted–including the pre-3.11 bare-number format, meaning > megabytes–with a startup deprecation warning. | influxdb3 serve option | Environment variables | |--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| |`--file-cache-size`
`--parquet-mem-cache-size` (pre-3.11 name)|`INFLUXDB3_FILE_CACHE_SIZE`
`INFLUXDB3_PARQUET_MEM_CACHE_SIZE` ([pre-3.11 name](#name-changes-in-3-11))| #### parquet-mem-cache-prune-percentage Specifies the percentage of entries to prune during a prune operation on the in-memory Parquet cache. **Default:** `0.1` | influxdb3 serve option | Environment variable | |--------------------------------------|----------------------------------------------| |`--parquet-mem-cache-prune-percentage`|`INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_PERCENTAGE`| #### parquet-mem-cache-prune-interval Sets the interval to check if the in-memory Parquet cache needs to be pruned. **Default:** `1s` | influxdb3 serve option | Environment variable | |------------------------------------|--------------------------------------------| |`--parquet-mem-cache-prune-interval`|`INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_INTERVAL`| #### file-cache-recency Specifies the time window for caching recent data files in memory. **Default:** `5h` Only files containing data with a timestamp between `now` and `now - duration`are cached when accessed during queries—for example, with a `5h` setting: * Current time: `2024-06-10 15:00:00` * Cache window: Last 5 hours (`2024-06-10 10:00:00` to now) If a query requests data from `2024-06-09` (old) and `2024-06-10 14:00` (recent): * **Cached**: data files with data from `2024-06-10 14:00` (within 5-hour window) * **Not cached**: data files with data from `2024-06-09` (outside 5-hour window) > [!Note] > `--file-cache-recency` was [renamed in 3.11](#name-changes-in-3-11)from `--parquet-mem-cache-query-path-duration`. > The legacy option and environment variable names are deprecated aliases. | influxdb3 serve option | Environment variables | |--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| |`--file-cache-recency`
`--parquet-mem-cache-query-path-duration` (pre-3.11 name)|`INFLUXDB3_FILE_CACHE_RECENCY`
`INFLUXDB3_PARQUET_MEM_CACHE_QUERY_PATH_DURATION` ([pre-3.11 name](#name-changes-in-3-11))| #### disable-file-cache Disables the in-memory data file cache. By default, the cache is enabled. > [!Note] > `--disable-file-cache` was [renamed in 3.11](#name-changes-in-3-11)from `--disable-parquet-mem-cache`. > The legacy option and environment variable names (including`disable-data-file-cache`) are deprecated aliases. | influxdb3 serve option | Environment variables | |----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| |`--disable-file-cache`
`--disable-parquet-mem-cache` (pre-3.11 name)
`--disable-data-file-cache` (pre-3.11 name)|`INFLUXDB3_DISABLE_FILE_CACHE`
`INFLUXDB3_DISABLE_PARQUET_MEM_CACHE`, `INFLUXDB3_DISABLE_DATA_FILE_CACHE` ([pre-3.11 names](#name-changes-in-3-11))| #### table-index-cache-max-entries Specifies the maximum number of entries in the table index cache. **Default:** `1000` | influxdb3 serve option | Environment variable | |---------------------------------|-----------------------------------------| |`--table-index-cache-max-entries`|`INFLUXDB3_TABLE_INDEX_CACHE_MAX_ENTRIES`| #### table-index-cache-concurrency-limit Limits the concurrency level for table index cache operations. **Default:** `8` | influxdb3 serve option | Environment variable | |---------------------------------------|-----------------------------------------------| |`--table-index-cache-concurrency-limit`|`INFLUXDB3_TABLE_INDEX_CACHE_CONCURRENCY_LIMIT`| #### last-cache-eviction-interval Specifies the interval to evict expired entries from the Last-N-Value cache, expressed as a human-readable duration–for example: `20s`, `1m`, `1h`. **Default:** `10s` | influxdb3 serve option | Environment variable | |--------------------------------|----------------------------------------| |`--last-cache-eviction-interval`|`INFLUXDB3_LAST_CACHE_EVICTION_INTERVAL`| ---------- #### distinct-cache-eviction-interval Specifies the interval to evict expired entries from the distinct value cache, expressed as a human-readable duration–for example: `20s`, `1m`, `1h`. **Default:** `10s` | influxdb3 serve option | Environment variable | |------------------------------------|--------------------------------------------| |`--distinct-cache-eviction-interval`|`INFLUXDB3_DISTINCT_CACHE_EVICTION_INTERVAL`| #### query-file-limit Limits the number of Parquet files a query can access. If a query attempts to read more than this limit, InfluxDB 3 Core returns an error. **Default:** `432` With the default `432` setting and the default [`gen1-duration`](#gen1-duration)setting of 10 minutes, queries can access up to a 72 hours of data, but potentially less depending on whether all data for a given 10 minute block of time was ingested during the same period. You can increase this limit to allow more files to be queried, but be aware of the following side-effects: * Degraded query performance for queries that read more Parquet files * Increased memory usage * Your system potentially killing the `influxdb3` process due to Out-of-Memory (OOM) errors * If using object storage to store data, many GET requests to access the data (as many as 2 per file) > [!Note] > We recommend keeping the default setting and querying smaller time ranges. > If you need to query longer time ranges or faster query performance on any query > that accesses an hour or more of data, [InfluxDB 3 Enterprise](/influxdb3/enterprise/)optimizes data storage by compacting and rearranging Parquet files to achieve > faster query performance. |influxdb3 serve option| Environment variable | |----------------------|----------------------------| | `--query-file-limit` |`INFLUXDB3_QUERY_FILE_LIMIT`| ### Processing Engine * [plugin-dir](#plugin-dir) * [plugin-repo](#plugin-repo) * [virtual-env-location](#virtual-env-location) * [package-manager](#package-manager) * [restrict-plugin-triggers-to](#restrict-plugin-triggers-to) #### plugin-dir Specifies the local directory that contains Python plugins and their test files. |influxdb3 serve option| Environment variable | |----------------------|----------------------| | `--plugin-dir` |`INFLUXDB3_PLUGIN_DIR`| ##### Default behavior by deployment type | Deployment |Default state| Configuration | |----------------|-------------|-----------------------------------------| | Docker images | **Enabled** | `INFLUXDB3_PLUGIN_DIR=/plugins` | |DEB/RPM packages| **Enabled** |`plugin-dir="/var/lib/influxdb3/plugins"`| | Binary/source | Disabled | No `plugin-dir` configured | ##### Disable the Processing Engine To disable the Processing Engine, ensure `plugin-dir` is not configured. > [!Warning] > Setting `plugin-dir=""` or `INFLUXDB3_PLUGIN_DIR=""` (empty string) does **not** disable the Processing Engine. > You must comment out, remove, or unset the configuration — not set it to empty. **Docker:** Use a custom entrypoint: ```bash docker run --entrypoint /bin/sh influxdb:3-core -c 'unset INFLUXDB3_PLUGIN_DIR && exec influxdb3 serve --object-store memory' ``` **systemd (DEB/RPM):** Comment out or remove `plugin-dir` in the configuration file: ```bash sudo nano /etc/influxdb3/influxdb3-core.conf ``` ```toml # plugin-dir="/var/lib/influxdb3/plugins" ``` Then restart the service: ```bash sudo systemctl restart influxdb3-core ``` When the Processing Engine is disabled: * The Python environment and PyO3 bindings are not initialized * Plugin-related operations return a “No plugin directory configured” error * The server runs with reduced resource usage #### plugin-repo Specifies the base URL of the remote repository used when referencing plugins with the `gh:` prefix. When you create a trigger with a plugin filename starting with `gh:`, InfluxDB fetches the plugin code from this repository URL. The URL construction automatically handles trailing slashes—both formats work identically: * `https://example.com/plugins/` (with trailing slash) * `https://example.com/plugins` (without trailing slash) **Default:** The official InfluxDB 3 plugins repository at `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/` |influxdb3 serve option| Environment variable | |----------------------|-----------------------| | `--plugin-repo` |`INFLUXDB3_PLUGIN_REPO`| ##### Example usage ```bash # Use a custom organization repository influxdb3 serve \ --plugin-dir ~/.plugins \ --plugin-repo "https://raw.githubusercontent.com/myorg/influxdb-plugins/main/" # Use an internal mirror influxdb3 serve \ --plugin-dir ~/.plugins \ --plugin-repo "https://internal.company.com/influxdb-plugins/" # Set via environment variable export INFLUXDB3_PLUGIN_REPO="https://custom-repo.example.com/plugins/" influxdb3 serve --plugin-dir ~/.plugins ``` #### virtual-env-location Specifies the location of the Python virtual environment that the processing engine uses. | influxdb3 serve option |Environment variable| |------------------------|--------------------| |`--virtual-env-location`| `VIRTUAL_ENV` | #### package-manager > [!Caution] > #### Deprecated in InfluxDB 3 Core 3.10 > > `--package-manager` is deprecated. > Python and `pip` are bundled with InfluxDB 3 Core, and `pip` is always > used for plugin dependency installation. > The server still starts if you set this option, but prints a deprecation > warning.`disabled` continues to block plugin package installation API calls for > compatibility. Specifies the Python package manager that the Processing Engine uses to install plugin dependencies. This option supports the following values: * `discover` *(default)*: Automatically detect and use available package manager (`uv` or `pip`) * `pip`: Use pip package manager exclusively * `uv`: Use uv package manager exclusively * `disabled`: Disable automatic package installation (all dependencies must be pre-installed) **Default:** `discover` ##### Security mode (disabled) When set to `disabled`, InfluxDB 3 Core blocks all package installation attempts for security and compliance requirements. The Processing Engine and plugins continue to function normally, but package installation requests (via CLI or API) return a `403 Forbidden` error. This mode is designed for: * **Enterprise security requirements**: Prevent arbitrary package installation * **Compliance environments**: Control exactly which packages are available * **Air-gapped deployments**: Pre-install all dependencies before deployment * **Multi-tenant scenarios**: Prevent tenants from installing potentially malicious packages > [!Important] > Before using `--package-manager disabled`, administrators must pre-install all required Python packages into the virtual environment that plugins will use. **Example:** ```bash # Start InfluxDB 3 with disabled package manager influxdb3 serve \ --node-id node0 \ --object-store file \ --data-dir ~/.influxdb3 \ --plugin-dir ~/.plugins \ --package-manager disabled ``` For more information about plugins and package management, see [Processing Engine plugins](/influxdb3/core/plugins/). |influxdb3 serve option| Environment variable | |----------------------|---------------------------| | `--package-manager` |`INFLUXDB3_PACKAGE_MANAGER`| #### restrict-plugin-triggers-to Restrict plugin triggers to one or more trigger types. Provide one or more of `wal`, `schedule`, or `request`. | influxdb3 serve option | Environment variable | |-------------------------------|---------------------------------------| |`--restrict-plugin-triggers-to`|`INFLUXDB3_RESTRICT_PLUGIN_TRIGGERS_TO`| ### Resource Limits * [max-concurrent-queries](#max-concurrent-queries) * [datafusion-num-threads](#datafusion-num-threads) * *[num-io-threads](#num-io-threads) - See [Global configuration options](#global-configuration-options)* #### max-concurrent-queries Limits the number of queries that can run concurrently. You can also update the limit at runtime with`POST /api/v3/configure/query_concurrency_limit`. | influxdb3 serve option | Environment variable | |--------------------------|----------------------------------| |`--max-concurrent-queries`|`INFLUXDB3_MAX_CONCURRENT_QUERIES`| #### datafusion-num-threads Sets the number of threads allocated to the DataFusion runtime thread pool. DataFusion threads handle: * Query execution and processing * Data aggregation and transformation * Snapshot creation (sort/dedupe operations) * Parquet file generation **Default:** All available cores minus IO threads > [!Note] > DataFusion threads are used for both query processing and snapshot operations. | influxdb3 serve option | Environment variable | |--------------------------|----------------------------------| |`--datafusion-num-threads`|`INFLUXDB3_DATAFUSION_NUM_THREADS`| > [!Note] > [`--num-io-threads`](#num-io-threads) is a [global configuration option](#global-configuration-options). ---------- ### Data Lifecycle Management * [gen1-lookback-duration](#gen1-lookback-duration) * [retention-check-interval](#retention-check-interval) * [delete-grace-period](#delete-grace-period) * [hard-delete-default-duration](#hard-delete-default-duration) #### gen1-lookback-duration Specifies how far back to look when creating generation 1 Parquet files. **Default:** `24h` | influxdb3 serve option | Environment variable | |--------------------------|----------------------------------| |`--gen1-lookback-duration`|`INFLUXDB3_GEN1_LOOKBACK_DURATION`| #### retention-check-interval The interval at which retention policies are checked and enforced. Enter as a human-readable time–for example: `30m` or `1h`. **Default:** `30m` | influxdb3 serve option | Environment variable | |----------------------------|------------------------------------| |`--retention-check-interval`|`INFLUXDB3_RETENTION_CHECK_INTERVAL`| #### delete-grace-period Specifies the grace period before permanently deleting data. **Default:** `24h` |influxdb3 serve option | Environment variable | |-----------------------|-------------------------------| |`--delete-grace-period`|`INFLUXDB3_DELETE_GRACE_PERIOD`| #### hard-delete-default-duration > [!Warning] > #### Deprecated: has no effect > > `--hard-delete-default-duration` has never had an effect in any release; > the server always uses the built-in default hard-delete duration. > The option is still accepted so existing configurations start, but the > server logs a startup warning–remove it from your configuration. | influxdb3 serve option | Environment variable | |--------------------------------|----------------------------------------| |`--hard-delete-default-duration`|`INFLUXDB3_HARD_DELETE_DEFAULT_DURATION`| ### Telemetry * [disable-telemetry-upload](#disable-telemetry-upload) * [telemetry-endpoint](#telemetry-endpoint) #### disable-telemetry-upload Disables the upload of telemetry data to InfluxData. **Default:** `false` | influxdb3 serve option | Environment variables | |----------------------------|------------------------------------------------------------------------------------------------------------------------| |`--disable-telemetry-upload`|`INFLUXDB3_DISABLE_TELEMETRY_UPLOAD`
`INFLUXDB3_TELEMETRY_DISABLE_UPLOAD` ([pre-3.11 name](#name-changes-in-3-11))| #### telemetry-endpoint Specifies the endpoint for telemetry data uploads. |influxdb3 serve option| Environment variable | |----------------------|------------------------------| |`--telemetry-endpoint`|`INFLUXDB3_TELEMETRY_ENDPOINT`| ### TCP Listeners * [tcp-listener-file-path](#tcp-listener-file-path) * [admin-token-recovery-tcp-listener-file-path](#admin-token-recovery-tcp-listener-file-path) #### tcp-listener-file-path Specifies the file path for the TCP listener configuration. | influxdb3 serve option | Environment variables | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------| |`--tcp-listener-file-path`|`INFLUXDB3_TCP_LISTENER_FILE_PATH`
`INFLUXDB3_TCP_LISTINER_FILE_PATH` ([misspelled pre-3.11 name](#name-changes-in-3-11))| #### admin-token-recovery-tcp-listener-file-path Specifies the TCP listener file path for admin token recovery operations. | influxdb3 serve option | Environment variable | |-----------------------------------------------|-------------------------------------------------------| |`--admin-token-recovery-tcp-listener-file-path`|`INFLUXDB3_ADMIN_TOKEN_RECOVERY_TCP_LISTENER_FILE_PATH`| ## Configuration name changes in 3.11 InfluxDB 3 Core 3.11.0 renamed many `influxdb3 serve` options and environment variables so that each variable matches its command option. On 3.11.0 and later, legacy names remain supported as deprecated aliases: the server logs a deprecation warning at startup when it detects one, and if both the new and the legacy name are set, the new name takes precedence. > [!Warning] > #### New names don’t work on releases earlier than 3.11.0 > > A pre-3.11 server doesn’t recognize names introduced by these 3.11 > renames: it exits with an error on an unknown command line option, but it**silently ignores** an unknown environment variable. > If you run a release earlier than 3.11.0, use the legacy names, and verify > in your startup logs that settings take effect. Use the following tables to migrate a deployment configuration—for example, Helm values or a systemd environment file—in one pass. ### Renamed options (legacy names aliased) The following `influxdb3 serve` options and their environment variables were renamed. Legacy names are still accepted; the server logs a deprecation warning at startup, and values in the old format are honored. | Legacy name | New name | |-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| |`--disable-parquet-mem-cache`
`INFLUXDB3_DISABLE_PARQUET_MEM_CACHE`
`--disable-data-file-cache`
`INFLUXDB3_DISABLE_DATA_FILE_CACHE`| `--disable-file-cache`
`INFLUXDB3_DISABLE_FILE_CACHE` | | `--exec-mem-pool-bytes`
`INFLUXDB3_EXEC_MEM_POOL_BYTES` | `--exec-mem-pool-size`
`INFLUXDB3_EXEC_MEM_POOL_SIZE` | | `--force-snapshot-mem-threshold`
`INFLUXDB3_FORCE_SNAPSHOT_MEM_THRESHOLD` |`--force-snapshot-mem-size`
`INFLUXDB3_FORCE_SNAPSHOT_MEM_SIZE`| | `--parquet-mem-cache-query-path-duration`
`INFLUXDB3_PARQUET_MEM_CACHE_QUERY_PATH_DURATION` | `--file-cache-recency`
`INFLUXDB3_FILE_CACHE_RECENCY` | | `--parquet-mem-cache-size`
`INFLUXDB3_PARQUET_MEM_CACHE_SIZE` | `--file-cache-size`
`INFLUXDB3_FILE_CACHE_SIZE` | | `--query-log-size`
`INFLUXDB3_QUERY_LOG_SIZE` | `--query-log-max-entries`
`INFLUXDB3_QUERY_LOG_MAX_ENTRIES` | | `--wal-max-write-buffer-size`
`INFLUXDB3_WAL_MAX_WRITE_BUFFER_SIZE` |`--wal-max-buffered-writes`
`INFLUXDB3_WAL_MAX_BUFFERED_WRITES`| | `--wal-snapshot-size`
`INFLUXDB3_WAL_SNAPSHOT_SIZE` | `--wal-files-per-snapshot`
`INFLUXDB3_WAL_FILES_PER_SNAPSHOT` | ### Renamed environment variables (legacy names aliased) The following environment variables were renamed to match their command options; the option names are unchanged. Legacy names remain supported as deprecated aliases. | Legacy name | New name | |------------------------------------|-----------------------------------------| | `INFLUXDB3_DB_DIR` | `INFLUXDB3_DATA_DIR` | |`INFLUXDB3_NODE_IDENTIFIER_FROM_ENV`| `INFLUXDB3_NODE_ID_FROM_ENV` | | `INFLUXDB3_NODE_IDENTIFIER_PREFIX` | `INFLUXDB3_NODE_ID` | | `INFLUXDB3_NUM_WAL_FILES_TO_KEEP` |`INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP`| | `INFLUXDB3_START_WITHOUT_AUTH` | `INFLUXDB3_WITHOUT_AUTH` | | `INFLUXDB3_TCP_LISTINER_FILE_PATH` | `INFLUXDB3_TCP_LISTENER_FILE_PATH` | |`INFLUXDB3_TELEMETRY_DISABLE_UPLOAD`| `INFLUXDB3_DISABLE_TELEMETRY_UPLOAD` | | influxdb3 option | Environment variable | | --- | --- | | influxdb3 option | Environment variable | | --num-io-threads | INFLUXDB3_NUM_IO_THREADS | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --data-dir | INFLUXDB3_DATA_DIR INFLUXDB3_DB_DIR ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --node-id | INFLUXDB3_NODE_ID INFLUXDB3_NODE_IDENTIFIER_PREFIX ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --object-store | INFLUXDB3_OBJECT_STORE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --tls-key | INFLUXDB3_TLS_KEY | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --tls-cert | INFLUXDB3_TLS_CERT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --tls-minimum-version | INFLUXDB3_TLS_MINIMUM_VERSION | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --without-auth | INFLUXDB3_WITHOUT_AUTH INFLUXDB3_START_WITHOUT_AUTH ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --disable-authz | INFLUXDB3_DISABLE_AUTHZ | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --admin-token-recovery-http-bind | INFLUXDB3_ADMIN_TOKEN_RECOVERY_HTTP_BIND | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --admin-token-file | INFLUXDB3_ADMIN_TOKEN_FILE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-access-key-id | AWS_ACCESS_KEY_ID | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-secret-access-key | AWS_SECRET_ACCESS_KEY | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-default-region | AWS_DEFAULT_REGION | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-endpoint | AWS_ENDPOINT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-session-token | AWS_SESSION_TOKEN | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-allow-http | AWS_ALLOW_HTTP | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-skip-signature | AWS_SKIP_SIGNATURE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --aws-credentials-file | AWS_CREDENTIALS_FILE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --google-service-account | GOOGLE_SERVICE_ACCOUNT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --azure-storage-account | AZURE_STORAGE_ACCOUNT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --azure-storage-access-key | AZURE_STORAGE_ACCESS_KEY | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --azure-endpoint | AZURE_ENDPOINT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --azure-allow-http | AZURE_ALLOW_HTTP | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --bucket | INFLUXDB3_BUCKET | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-connection-limit | INFLUXDB3_OBJECT_STORE_CONNECTION_LIMIT (preferred) OBJECT_STORE_CONNECTION_LIMIT (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-http2-only | INFLUXDB3_OBJECT_STORE_HTTP2_ONLY (preferred) OBJECT_STORE_HTTP2_ONLY (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-http2-max-frame-size | INFLUXDB3_OBJECT_STORE_HTTP2_MAX_FRAME_SIZE (preferred) OBJECT_STORE_HTTP2_MAX_FRAME_SIZE (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-request-timeout | INFLUXDB3_OBJECT_STORE_REQUEST_TIMEOUT (preferred) OBJECT_STORE_REQUEST_TIMEOUT (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-max-retries | INFLUXDB3_OBJECT_STORE_MAX_RETRIES (preferred) OBJECT_STORE_MAX_RETRIES (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-retry-timeout | INFLUXDB3_OBJECT_STORE_RETRY_TIMEOUT (preferred) OBJECT_STORE_RETRY_TIMEOUT (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-tls-allow-insecure | INFLUXDB3_OBJECT_STORE_TLS_ALLOW_INSECURE (preferred) OBJECT_STORE_TLS_ALLOW_INSECURE (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --object-store-tls-ca | INFLUXDB3_OBJECT_STORE_TLS_CA (preferred) OBJECT_STORE_TLS_CA (deprecated; supported for backward compatibility) | | Level | Description | | --- | --- | | Level | Description | | error | Only errors | | warn | Warnings and errors | | info | Informational messages, warnings, and errors (default) | | debug | Debug information for troubleshooting, plus all above levels | | trace | Very detailed tracing information, plus all above levels (produces high log volume) | | Component | Description | | --- | --- | | Component | Description | | influxdb3_write_buffer | Write buffer operations | | influxdb3_wal | Write-ahead log operations | | influxdb3_catalog | Catalog and schema operations | | influxdb3_cache | Caching operations | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --log-filter | INFLUXDB3_LOG_FILTER (preferred) LOG_FILTER (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --log-destination | INFLUXDB3_LOG_DESTINATION (preferred) LOG_DESTINATION (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --log-format | INFLUXDB3_LOG_FORMAT (preferred) LOG_FORMAT (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --query-log-max-entries --query-log-size (pre-3.11 name) | INFLUXDB3_QUERY_LOG_MAX_ENTRIES INFLUXDB3_QUERY_LOG_SIZE ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-exporter | INFLUXDB3_TRACES_EXPORTER (preferred) TRACES_EXPORTER (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-exporter-jaeger-agent-host | INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_HOST (preferred) TRACES_EXPORTER_JAEGER_AGENT_HOST (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-exporter-jaeger-agent-port | INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_PORT (preferred) TRACES_EXPORTER_JAEGER_AGENT_PORT (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-exporter-jaeger-service-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_SERVICE_NAME (preferred) TRACES_EXPORTER_JAEGER_SERVICE_NAME (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-exporter-jaeger-trace-context-header-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME (preferred) TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-jaeger-debug-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_DEBUG_NAME (preferred) TRACES_EXPORTER_JAEGER_DEBUG_NAME (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-jaeger-tags | INFLUXDB3_TRACES_EXPORTER_JAEGER_TAGS (preferred) TRACES_EXPORTER_JAEGER_TAGS (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --traces-jaeger-max-msgs-per-second | INFLUXDB3_TRACES_JAEGER_MAX_MSGS_PER_SECOND (preferred) TRACES_JAEGER_MAX_MSGS_PER_SECOND (deprecated; supported for backward compatibility) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --datafusion-num-threads | INFLUXDB3_DATAFUSION_NUM_THREADS | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --datafusion-max-parquet-fanout | INFLUXDB3_DATAFUSION_MAX_PARQUET_FANOUT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --datafusion-use-cached-parquet-loader | INFLUXDB3_DATAFUSION_USE_CACHED_PARQUET_LOADER | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --datafusion-config | INFLUXDB3_DATAFUSION_CONFIG | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --max-http-request-size | INFLUXDB3_MAX_HTTP_REQUEST_SIZE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --http-bind | INFLUXDB3_HTTP_BIND_ADDR | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --exec-mem-pool-size --exec-mem-pool-bytes (pre-3.11 name) | INFLUXDB3_EXEC_MEM_POOL_SIZE INFLUXDB3_EXEC_MEM_POOL_BYTES ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --force-snapshot-mem-size --force-snapshot-mem-threshold (pre-3.11 name) | INFLUXDB3_FORCE_SNAPSHOT_MEM_SIZE INFLUXDB3_FORCE_SNAPSHOT_MEM_THRESHOLD ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --checkpoint-interval | INFLUXDB3_CHECKPOINT_INTERVAL | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --wal-flush-interval | INFLUXDB3_WAL_FLUSH_INTERVAL | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --wal-files-per-snapshot --wal-snapshot-size (pre-3.11 name) | INFLUXDB3_WAL_FILES_PER_SNAPSHOT INFLUXDB3_WAL_SNAPSHOT_SIZE ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --wal-max-buffered-writes --wal-max-write-buffer-size (pre-3.11 name) | INFLUXDB3_WAL_MAX_BUFFERED_WRITES INFLUXDB3_WAL_MAX_WRITE_BUFFER_SIZE ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --snapshotted-wal-files-to-keep | INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP INFLUXDB3_NUM_WAL_FILES_TO_KEEP ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --wal-replay-fail-on-error | INFLUXDB3_WAL_REPLAY_FAIL_ON_ERROR | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --wal-replay-concurrency-limit | INFLUXDB3_WAL_REPLAY_CONCURRENCY_LIMIT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --gen1-duration | INFLUXDB3_GEN1_DURATION | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --preemptive-cache-age | INFLUXDB3_PREEMPTIVE_CACHE_AGE | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --file-cache-size --parquet-mem-cache-size (pre-3.11 name) | INFLUXDB3_FILE_CACHE_SIZE INFLUXDB3_PARQUET_MEM_CACHE_SIZE ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --parquet-mem-cache-prune-percentage | INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_PERCENTAGE | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --parquet-mem-cache-prune-interval | INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_INTERVAL | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --file-cache-recency --parquet-mem-cache-query-path-duration (pre-3.11 name) | INFLUXDB3_FILE_CACHE_RECENCY INFLUXDB3_PARQUET_MEM_CACHE_QUERY_PATH_DURATION ( pre-3.11 name ) | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --disable-file-cache --disable-parquet-mem-cache (pre-3.11 name) --disable-data-file-cache (pre-3.11 name) | INFLUXDB3_DISABLE_FILE_CACHE INFLUXDB3_DISABLE_PARQUET_MEM_CACHE , INFLUXDB3_DISABLE_DATA_FILE_CACHE ( pre-3.11 names ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --table-index-cache-max-entries | INFLUXDB3_TABLE_INDEX_CACHE_MAX_ENTRIES | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --table-index-cache-concurrency-limit | INFLUXDB3_TABLE_INDEX_CACHE_CONCURRENCY_LIMIT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --last-cache-eviction-interval | INFLUXDB3_LAST_CACHE_EVICTION_INTERVAL | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --distinct-cache-eviction-interval | INFLUXDB3_DISTINCT_CACHE_EVICTION_INTERVAL | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --query-file-limit | INFLUXDB3_QUERY_FILE_LIMIT | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --plugin-dir | INFLUXDB3_PLUGIN_DIR | | Deployment | Default state | Configuration | | --- | --- | --- | | Deployment | Default state | Configuration | | Docker images | Enabled | INFLUXDB3_PLUGIN_DIR=/plugins | | DEB/RPM packages | Enabled | plugin-dir="/var/lib/influxdb3/plugins" | | Binary/source | Disabled | No plugin-dir configured | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --plugin-repo | INFLUXDB3_PLUGIN_REPO | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --virtual-env-location | VIRTUAL_ENV | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --package-manager | INFLUXDB3_PACKAGE_MANAGER | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --restrict-plugin-triggers-to | INFLUXDB3_RESTRICT_PLUGIN_TRIGGERS_TO | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --max-concurrent-queries | INFLUXDB3_MAX_CONCURRENT_QUERIES | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --datafusion-num-threads | INFLUXDB3_DATAFUSION_NUM_THREADS | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --gen1-lookback-duration | INFLUXDB3_GEN1_LOOKBACK_DURATION | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --retention-check-interval | INFLUXDB3_RETENTION_CHECK_INTERVAL | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --delete-grace-period | INFLUXDB3_DELETE_GRACE_PERIOD | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --hard-delete-default-duration | INFLUXDB3_HARD_DELETE_DEFAULT_DURATION | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --disable-telemetry-upload | INFLUXDB3_DISABLE_TELEMETRY_UPLOAD INFLUXDB3_TELEMETRY_DISABLE_UPLOAD ( pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --telemetry-endpoint | INFLUXDB3_TELEMETRY_ENDPOINT | | influxdb3 serve option | Environment variables | | --- | --- | | influxdb3 serve option | Environment variables | | --tcp-listener-file-path | INFLUXDB3_TCP_LISTENER_FILE_PATH INFLUXDB3_TCP_LISTINER_FILE_PATH ( misspelled pre-3.11 name ) | | influxdb3 serve option | Environment variable | | --- | --- | | influxdb3 serve option | Environment variable | | --admin-token-recovery-tcp-listener-file-path | INFLUXDB3_ADMIN_TOKEN_RECOVERY_TCP_LISTENER_FILE_PATH | | Legacy name | New name | | --- | --- | | Legacy name | New name | | --disable-parquet-mem-cache INFLUXDB3_DISABLE_PARQUET_MEM_CACHE --disable-data-file-cache INFLUXDB3_DISABLE_DATA_FILE_CACHE | --disable-file-cache INFLUXDB3_DISABLE_FILE_CACHE | | --exec-mem-pool-bytes INFLUXDB3_EXEC_MEM_POOL_BYTES | --exec-mem-pool-size INFLUXDB3_EXEC_MEM_POOL_SIZE | | --force-snapshot-mem-threshold INFLUXDB3_FORCE_SNAPSHOT_MEM_THRESHOLD | --force-snapshot-mem-size INFLUXDB3_FORCE_SNAPSHOT_MEM_SIZE | | --parquet-mem-cache-query-path-duration INFLUXDB3_PARQUET_MEM_CACHE_QUERY_PATH_DURATION | --file-cache-recency INFLUXDB3_FILE_CACHE_RECENCY | | --parquet-mem-cache-size INFLUXDB3_PARQUET_MEM_CACHE_SIZE | --file-cache-size INFLUXDB3_FILE_CACHE_SIZE | | --query-log-size INFLUXDB3_QUERY_LOG_SIZE | --query-log-max-entries INFLUXDB3_QUERY_LOG_MAX_ENTRIES | | --wal-max-write-buffer-size INFLUXDB3_WAL_MAX_WRITE_BUFFER_SIZE | --wal-max-buffered-writes INFLUXDB3_WAL_MAX_BUFFERED_WRITES | | --wal-snapshot-size INFLUXDB3_WAL_SNAPSHOT_SIZE | --wal-files-per-snapshot INFLUXDB3_WAL_FILES_PER_SNAPSHOT | | Legacy name | New name | | --- | --- | | Legacy name | New name | | INFLUXDB3_DB_DIR | INFLUXDB3_DATA_DIR | | INFLUXDB3_NODE_IDENTIFIER_FROM_ENV | INFLUXDB3_NODE_ID_FROM_ENV | | INFLUXDB3_NODE_IDENTIFIER_PREFIX | INFLUXDB3_NODE_ID | | INFLUXDB3_NUM_WAL_FILES_TO_KEEP | INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP | | INFLUXDB3_START_WITHOUT_AUTH | INFLUXDB3_WITHOUT_AUTH | | INFLUXDB3_TCP_LISTINER_FILE_PATH | INFLUXDB3_TCP_LISTENER_FILE_PATH | | INFLUXDB3_TELEMETRY_DISABLE_UPLOAD | INFLUXDB3_DISABLE_TELEMETRY_UPLOAD | --- # Glossary Source: https://docs.influxdata.com/influxdb3/core/reference/glossary/ [A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) | [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | X | Y | Z A ---------- ### abstract syntax tree (AST) Tree representation of source code that shows the structure, content, and rules of programming statements and discards additional syntax elements. The tree is hierarchical, with elements of program statements broken down into their parts. For more information about AST design, see [Abstract Syntax Tree on Wikipedia](https://en.wikipedia.org/wiki/Abstract_syntax_tree). ### agent A background process started by (or on behalf of) a user that typically requires user input. [Telegraf](/telegraf/v1/) is an agent that requires user input (a configuration file) to gather metrics from declared input plugins and sends metrics to declared output plugins, based on the plugins enabled for a configuration. Related entries:[input plugin](#input-plugin),[output plugin](#output-plugin),[daemon](#daemon) ### aggregator plugin Receives metrics from input plugins, creates aggregate metrics, and then passes aggregate metrics to configured output plugins. Related entries:[input plugin](#input-plugin),[output plugin](#output-plugin),[processor plugin](#processor-plugin) ### aggregate A function that returns an aggregated value across a set of points. For a list of available aggregation functions, see [SQL aggregate functions](/influxdb3/core/reference/sql/functions/aggregate/). Related entries:[function](#function),[selector](#selector) ### API Application programming interface that facilitates and standardizes communication between two or more computer programs. ### argument A value passed to a function or command that determines how the process operates. Related entries:[parameter](#parameter) B ---------- ### batch A collection of points in line protocol format, separated by newlines (`0x0A`). Submitting a batch of points using a single HTTP request to the write endpoints drastically increases performance by reducing the HTTP overhead. InfluxData typically recommends batch sizes of 5,000-10,000 points. In some use cases, performance may improve with significantly smaller or larger batches. Related entries:[line protocol](#line-protocol-lp),[point](#point) ### batch size The number of lines or individual data points in a line protocol batch. The Telegraf agent sends metrics to output plugins in batches rather than individually. Batch size controls the size of each write batch that Telegraf sends to the output plugins. Related entries:[output plugin](#output-plugin) ### bin In a cumulative histogram, a bin includes all data points less than or equal to a specified upper bound. In a normal histogram, a bin includes all data points between the upper and lower bounds. Histogram bins are also sometimes referred to as “buckets.” ### boolean A data type with two possible values: true or false. By convention, you can express `true` as the integer `1` and false as the integer `0` (zero). ### bucket “Bucket” is the term used in InfluxDB 2.x and *InfluxDB Cloud Serverless* to refer to a named location where time series data is stored. Bucket is synonymous with “database” when using InfluxDB 3 Core. Related entries:[database](#database) C ---------- ### CSV Comma-separated values (CSV) delimits text between commas to separate values. A CSV file stores tabular data (numbers and text) in plain text. Each line of the file is a data row. Each row consists of one or more columns, separated by commas. CSV file format is not fully standardized. ### cardinality Cardinality is the number of unique values in a set. Series cardinality is the number of unique [series](#series) in a database as a whole. With the InfluxDB 3 storage engine, high series cardinality *does not* affect performance. ### cluster A collection of servers or processes that work together as a single unit. An InfluxDB cluster is a collection of InfluxDB servers dedicated to the workload of a single customer. ### collect Collect and write time series data to InfluxDB using line protocol and any of the following tools: * Telegraf * the InfluxDB v1, v2, or v3 HTTP APIs * `influxdb3` command line interface (CLI) for InfluxDB 3 Core and Enterprise * InfluxDB 3 Processing engine with the `LineBuilder` and `influxdb3_local` shared API. * v1 or v2 `influx` command line interface (CLI) * InfluxDB v1, v2, or v3 client libraries ### collection interval The default global interval for collecting data from each Telegraf input plugin. The collection interval can be overridden by each individual input plugin’s configuration. Related entries:[input plugin](#input-plugin) ### collection jitter Collection jitter prevents every input plugin from collecting metrics simultaneously, which can have a measurable effect on the system. For each collection interval, every Telegraf input plugin sleeps for a random time between zero and the collection jitter before collecting the metrics. Related entries:[collection interval](#collection-interval),[input plugin](#input-plugin) ### column InfluxDB data is stored in tables within rows and columns. Columns store tag sets and fields sets, and time values. The only required column is *time*, which stores timestamps and is included in all InfluxDB tables. ### common log format (CLF) A standardized text file format used by the InfluxDB server to create log entries when generating server log files. ### compaction Compressing time series data to optimize disk usage. ### continuous query (CQ) Continuous queries are a feature of InfluxDB 1.x used to regularly downsample or process time series data. D ---------- ### daemon A background process that runs without user input. ### dashboard A collection of data visualizations, charts, and panels organized in a single view to monitor and analyze time series data. Dashboards provide at-a-glance visualization of metrics and allow users to track trends, spot anomalies, and understand relationships between different data points over time. Some versions of InfluxDB include built-in dashboarding features. InfluxDB can integrate with third-party visualization and dashboard tools, such as[Grafana](https://grafana.com), [Apache Superset](https://superset.apache.org/),[Tableau](https://www.tableau.com/). ### data model A data model organizes elements of data and standardizes how they relate to one another and to properties of the real world entities. For more information, see the [InfluxDB 3 Core data model](/influxdb3/core/get-started/#data-model) ### data service Stores time series data and handles writes and queries. ### data source A source of data that InfluxDB collects or queries data from. Related entries:[database](#database) ### data type A data type is defined by the values it can take, the programming language used, or the operations that can be performed on it. InfluxDB supports the following data types: * string * boolean * float (64-bit) * integer (64-bit) * unsigned integer (64-bit) * time For more information about different data types, see: * [line protocol](/influxdb3/core/reference/syntax/line-protocol/#data-types-and-format) * [InfluxQL](/influxdb3/core/reference/influxql/#literals) * [SQL](/influxdb3/core/reference/sql/data-types/#sql-and-arrow-data-types) #### database A named location where time series data is stored. In InfluxDB 1.x, a database represented a logical container for users, retention policies, continuous queries, and time series data. In InfluxDB 2.x and InfluxDB Cloud Serverless, the equivalent of this concept is an InfluxDB [bucket](#bucket). Related entries:[bucket](#bucket),[retention policy](#retention-policy-rp) ### date-time InfluxDB stores the date-time format for each data point in a timestamp with nanosecond-precision Unix time. Specifying a timestamp is optional. If a timestamp isn’t specified for a data point, InfluxDB uses the server’s local nanosecond timestamp in UTC. ### downsample Aggregating high resolution data into lower resolution data to preserve disk space. ### duration A data type that represents a duration of time–for example, `1s`, `1m`, `1h`, `1d`. Retention periods are set using durations. Related entries:[retention period](#retention-period) E ---------- ### event Metrics gathered at irregular time intervals. ### expression A combination of one or more constants, variables, operators, and functions. In the following SQL example, `now() - INTERVAL '7 days'` is an expression that calculates the difference between the `now()` function expression and the duration represented by `INTERVAL '7 days`: ```sql SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ``` F ---------- ### field A key-value pair in InfluxDB’s data structure that records a data value. Generally, field values change over time. Fields are required in InfluxDB’s data structure. Related entries:[field key](#field-key),[field set](#field-set),[field value](#field-value),[tag](#tag) ### field key The key of the key-value pair. Field keys are strings. Related entries:[field](#field),[field set](#field-set),[field value](#field-value),[tag key](#tag-key) ### field set The collection of field key-value pairs. Related entries:[field](#field),[field key](#field-key),[field value](#field-value),[point](#point) ### field value The value of a key-value pair. Field values are the actual data; they can be strings, floats, integers, unsigned integers or booleans. A field value is always associated with a timestamp. Related entries:[field](#field),[field key](#field-key),[field set](#field-set),[tag set](#tag-set),[tag value](#tag-value),[timestamp](#timestamp) ### file block A file block is a fixed-length chunk of data read into memory when requested by an application. ### float A real number written with a decimal point dividing the integer and fractional parts (`1.0`, `3.14`, `-20.1`). InfluxDB supports 64-bit float values. ### flush interval The global interval for flushing data from each Telegraf output plugin to its destination. This value should not be set lower than the collection interval. Related entries:[collection interval](#collection-interval),[flush jitter](#flush-jitter),[output plugin](#output-plugin) ### flush jitter Flush jitter prevents every Telegraf output plugin from sending writes simultaneously, which can overwhelm some data sinks. Each flush interval, every Telegraf output plugin sleeps for a random time between zero and the flush jitter before emitting metrics. Flush jitter smooths out write spikes when running a large number of Telegraf instances. Related entries:[flush interval](#flush-interval),[output plugin](#output-plugin) ### function A function is an operation that performs a specific task. Functions take input, operate on that input, and then return output. For complete lists of available query language functions, see: * [InfluxQL functions](/influxdb3/core/reference/influxql/functions/) * [SQL functions](/influxdb3/core/reference/sql/functions/). Related entries:[aggregate](#aggregate),[selector](#selector) G ---------- ### gzip gzip is a type of data compression that compress chunks of data, which is restored by unzipping compressed gzip files. The gzip file extension is `.gz`. H ---------- ### histogram A visual representation of statistical information that uses rectangles to show the frequency of data items in successive, equal intervals or bins. I ---------- ### identifier Identifiers are tokens that refer to specific database objects such as database names, field keys, measurement names, tag keys, etc. Related entries:[database](#database),[field key](#field-key),[measurement](#measurement),[tag key](#tag-key) ### influx `influx` is a command line interface (CLI) that interacts with the InfluxDB v1.x and v2.x server. ### influxctl [`influxctl`](/influxdb3/cloud-dedicated/reference/cli/influxctl/) is a CLI that performs [administrative tasks](/influxdb3/cloud-dedicated/admin/) for an InfluxDB Cloud Dedicated cluster. ### influxd `influxd` is the InfluxDB OSS v1.x and v2.x daemon that runs the InfluxDB server and other required processes. ### InfluxDB An open source time series database (TSDB) developed by InfluxData, optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. ### influxdb3 `influxdb3` is: * the InfluxDB 3 Core and Enterprise daemon that runs the InfluxDB 3 server * the InfluxDB 3 CLI that interacts with the server for InfluxDB 3 Core and Enterprise ### InfluxQL The SQL-like query language used to query data in InfluxDB. ### input plugin Telegraf input plugins actively gather metrics and deliver them to the core agent, where aggregator, processor, and output plugins can operate on the metrics. To activate an input plugin, enable and configure it in the Telegraf configuration file. Related entries:[aggregator plugin](#aggregator-plugin),[collection interval](#collection-interval),[output plugin](#output-plugin),[processor plugin](#processor-plugin) ### influxdb3 CLI The command line interface for InfluxDB 3. Use the `influxdb3` CLI to administer your instance–for example, to create and manage databases, tables, and tokens–and to write and query data. ### instance An entity comprising data on a server (or virtual server in cloud computing). ### integer A whole number that is positive, negative, or zero (`0`, `-5`, `143`). InfluxDB supports 64-bit integers (minimum: `-9223372036854775808`, maximum: `9223372036854775807`). Related entries:[unsigned integer](#unsigned-integer) ### IOx The IOx storage engine (InfluxDB 3 storage engine) is a real-time, columnar database optimized for time series data built in Rust on top of[Apache Arrow](https://arrow.apache.org/) and[DataFusion](https://arrow.apache.org/datafusion/user-guide/introduction.html). IOx replaces the [TSM (Time Structured Merge tree)](#tsm-time-structured-merge-tree) storage engine. Related entries:[WAL tail](#wal-tail) For InfluxDB 3 Core-specific detail, see[Storage engine](/influxdb3/core/reference/internals/storage-engine/). J ---------- ### JWT Typically, JSON web tokens (JWT) are used to authenticate users between an identity provider and a service provider. A server can generate a JWT to assert any business processes. For example, an “admin” token sent to a client can prove the client is logged in as admin. Tokens are signed by one party’s private key (typically, the server). Private keys are used by both parties to verify that a token is legitimate. JWT uses an open standard specified in [RFC 7519](https://tools.ietf.org/html/rfc7519). ### Jaeger Open source tracing used in distributed systems to monitor and troubleshoot transactions. ### JSON JavaScript Object Notation (JSON) is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types. K ---------- ### keyword A keyword is reserved by a program because it has special meaning. Every programming language has a set of keywords (reserved names) that cannot be used as identifiers–for example, you can’t use `SELECT` (an SQL keyword) as a variable name in an SQL query. See keyword lists: * [SQL keywords](/influxdb3/core/reference/sql/#keywords) * [InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords) L ---------- ### literal A literal is a value in an expression, a number, character, string, function, record, or array. Literal values are interpreted as defined. ### load balancing Improves workload distribution across multiple computing resources in a network. Load balancing optimizes resource use, maximizes throughput, minimizes response time, and avoids overloading a single resource. Using multiple components with load balancing instead of a single component may increase reliability and availability. If requests to any server in a network increase, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. ### logs Logs record information. Event logs describe system events and activity that help to describe and diagnose problems. Transaction logs describe changes to stored data that help recover data if a database crashes or other errors occur. ### line protocol (LP) The text based format for writing points to InfluxDB. See [line protocol](/influxdb3/core/reference/syntax/line-protocol/). M ---------- ### measurement The part of InfluxDB’s data structure that describes the data stored in associated fields. Measurements are strings. Related entries:[field](#field), [series](#series) ### metric Data tracked over time. ### metric buffer The metric buffer caches individual metrics when writes are failing for an Telegraf output plugin. Telegraf will attempt to flush the buffer upon a successful write to the output. The oldest metrics are dropped first when this buffer fills. Related entries:[output plugin](#output-plugin) ### missing values Denoted by a null value. Identifies missing information, which may be useful to include in an error message. N ---------- ### node An independent process or server in a cluster. Related entries:[cluster](#cluster),[server](#server) ### now The local server’s nanosecond timestamp. ### null A data type that represents a missing or unknown value. Denoted by the `null` value. Values of [tags](#tag) and [fields](#field) may be `null`, but timestamp values are never `null`. O ---------- ### operator A symbol that usually represents an action or process. For example: `+`, `-`, `>`. Related entries:[operand](#operand) ### operand The object or value on either side of an [operator](#operator). Related entries:[operator](#operator) ### organization An InfluxDB v2 concept that describes workspace for a group of users. All InfluxDB v2 dashboards, tasks, buckets, members, and so on, belong to an organization. Organizations are not part of InfluxDB 3 Core. ### owner A type of role for a user. Owners have read/write permissions. Users can have owner roles for databases and other resources. Role permissions are separate from API token permissions. For additional information on API tokens, see [token](#token). ### output plugin Telegraf output plugins deliver metrics to their configured destination. To activate an output plugin, enable and configure the plugin in Telegraf’s configuration file. Related entries:[aggregator plugin](#aggregator-plugin),[flush interval](#flush-interval),[input plugin](#input-plugin),[processor plugin](#processor-plugin) P ---------- ### parameter A key-value pair used to pass information to a function that determines how the function operates. Related entries:[argument](#argument) ### pipe Method for passing information from one process to another. For example, an output parameter from one process is input to another process. Information passed through a pipe is retained until the receiving process reads the information. ### plugin A Python file with a specific function signature that corresponds to a[trigger](#trigger) type. Plugins run in the InfluxDB 3 [Processing engine](#processing-engine) to process data, respond to database events, and connect to external systems. Related entries:[Processing engine](#processing-engine),[trigger](#trigger) ### point Single data record identified by its *measurement*, *tag keys*, *tag values*,*field key*, and *timestamp*. In a [series](#series), each point has a unique timestamp. If you write a point to a series with a timestamp that matches an existing point, the field set becomes a union of the old and new field set, where any ties go to the new field set. Related entries:[measurement](#measurement),[tag set](#tag-set),[field set](#field-set),[timestamp](#timestamp) ### primary key With the InfluxDB 3 storage engine, the primary key is the list of columns used to uniquely identify each row in a table. Rows are uniquely identified by their timestamp and tag set. A row’s primary key tag set does not include tags with null values. ### precision The precision configuration setting determines the timestamp precision retained for input data points. All incoming timestamps are truncated to the specified precision. Valid precisions are `ns`, `us` or `µs`, `ms`, and `s`. In Telegraf, truncated timestamps are padded with zeros to create a nanosecond timestamp. Telegraf output plugins emit timestamps in nanoseconds. For example, if the precision is set to `ms`, the nanosecond epoch timestamp `1480000000123456789` is truncated to `1480000000123` in millisecond precision and padded with zeroes to make a new, less precise nanosecond timestamp of `1480000000123000000`. Telegraf output plugins do not alter the timestamp further. The precision setting is ignored for service input plugins. Related entries:[aggregator plugin](#aggregator-plugin),[input plugin](#input-plugin),[output plugin](#output-plugin),[processor plugin](#processor-plugin),[service input plugin](#service-input-plugin) ### predicate expression A predicate expression compares two values and returns `true` or `false` based on the relationship between the two values. A predicate expression is comprised of a left operand, a comparison operator, and a right operand. ### process A set of predetermined rules. A process can refer to instructions being executed by the computer processor or refer to the act of manipulating data. ### Processing engine The Processing engine is a Python virtual machine (VM) embedded within InfluxDB 3 Core and Enterprise for automatically processing data and responding to database events. It executes Python plugins in response to events defined by triggers. The Processing engine runs Python code directly in your database, allowing plugins to react to specific triggers without requiring external services. Related entries:[plugin](#plugin),[trigger](#trigger) ### processor plugin Telegraf processor plugins transform, decorate, and filter metrics collected by input plugins, passing the transformed metrics to the output plugins. Related entries:[aggregator plugin](#aggregator-plugin),[input plugin](#input-plugin),[output plugin](#output-plugin) ### Prometheus format A simple text-based format for exposing metrics and ingesting them into Prometheus. Q ---------- ### query A request for information. An InfluxDB query returns time series data. See [Query data in InfluxDB](/influxdb3/core/query-data/). ### query plan A sequence of steps (*nodes*) that the InfluxDB Querier devises and executes to calculate the result of the query in the least amount of time. A *logical plan* is a high level representation of a query and doesn’t consider cluster configuration or data organization. A *physical plan* represents the query execution plan and data flow through plan nodes that read (*scan*), deduplicate, merge, filter, and sort data. A physical plan is optimized for the cluster configuration and data organization. R ---------- ### REPL A Read-Eval-Print Loop (REPL) is an interactive programming environment where you type a command and immediately see the result. ### regular expressions Regular expressions (regex or regexp) are patterns used to match character combinations in strings. ### rejected points In a batch of data, points that InfluxDB couldn’t write to a database. Field type conflicts are a common cause of rejected points. ### retention period The [duration](#duration) of time that a database retains data. InfluxDB drops points with timestamps older than their database’s retention period relative to [now](#now). The minimum retention period is **one hour**. In InfluxDB Cloud Serverless, *bucket* is synonymous with database. Related entries:[bucket](#bucket)[database](#database) ### retention policy (RP) A retention policy is part of the InfluxDB 1.x data model that describes how long InfluxDB keeps data (duration), how many copies of the data to store when in a in the cluster (replication factor), and the time range covered by shard groups (shard group duration). RPs are unique per database and along with the measurement and tag set define a series. In InfluxDB 3 Core, the equivalent is [retention period](#retention-period), however retention periods are not part of the data model. The retention period describes the data persistence behavior of a database. In InfluxDB Cloud Serverless, *bucket* is synonymous with database. Related entries:[retention period](#retention-period), ### RFC3339 timestamp A timestamp that uses the human-readable DateTime format proposed in[RFC 3339](https://tools.ietf.org/html/rfc3339) (for example: `2020-01-01T00:00:00.00Z`). Related entries:[RFC3339Nano timestamp](#rfc3339nano-timestamp),[timestamp](#timestamp),[unix timestamp](#unix-timestamp) ### RFC3339Nano timestamp A [Golang representation of the RFC 3339 DateTime format](https://go.dev/src/time/format.go)that uses nanosecond resolution–for example:`2006-01-02T15:04:05.999999999Z07:00`. InfluxDB clients can return RFC3339Nano timestamps in log events and CSV-formatted query results. Related entries:[RFC3339 timestamp](#rfc3339-timestamp),[timestamp](#timestamp),[unix timestamp](#unix-timestamp) ### row A row in a [table](#table) represents a specific record or instance of data.[Column](#column) values in a row represent specific attributes or properties of the instance. Each row has a [primary key](/#primary-key) that makes the row unique from other rows in the table. Related entries:[column](#column),[primary key](#primary-key),[series](#series),[table](#table) S ---------- ### schema How data is organized in InfluxDB. The fundamentals of the InfluxDB schema are databases, measurements, tag keys, tag values, and field keys. Related entries:[bucket](#bucket),[database](#database),[field key](#field-key),[measurement](#measurement),[series](#series),[tag key](#tag-key),[tag value](#tag-value) ### secret Secrets are key-value pairs that contain information you want to control access to, such as API keys, passwords, or certificates. ### selector A function that returns a single point from the range of specified points. See [SQL selector functions](/influxdb3/core/reference/sql/functions/selector/)for a complete list of available SQL selector functions. Related entries:[aggregate](#aggregate),[function](#function),[transformation](#transformation) ### series In the InfluxDB 3 data structure, a collection of data that share a common*measurement* and *tag set*. Related entries:[field set](#field-set),[measurement](#measurement),[tag set](#tag-set) ### series cardinality The number of unique measurement, tag set, and field key combinations in an InfluxDB 3 Core database. For example, assume that an InfluxDB database has one measurement. The single measurement has two tag keys: `email` and `status`. If there are three different `email` tag values, and each email address is associated with two different `status` tag values, then the series cardinality for the measurement is 6 (3 × 2 = 6): | email |status| |--------------------|------| |lorr@influxdata.com |start | |lorr@influxdata.com |finish| |marv@influxdata.com |start | |marv@influxdata.com |finish| |cliff@influxdata.com|start | |cliff@influxdata.com|finish| In some cases, performing this multiplication may overestimate series cardinality because of the presence of dependent tags. Dependent tags are scoped by another tag and do not increase series cardinality. If we add the tag `firstname` to the preceding example, the series cardinality would not be 18 (3 × 2 × 3 = 18). The series cardinality would remain unchanged at 6, as `firstname` is already scoped by the `email` tag: | email |status|firstname| |--------------------|------|---------| |lorr@influxdata.com |start |lorraine | |lorr@influxdata.com |finish|lorraine | |marv@influxdata.com |start | marvin | |marv@influxdata.com |finish| marvin | |cliff@influxdata.com|start |clifford | |cliff@influxdata.com|finish|clifford | Related entries:[field key](#field-key),[measurement](#measurement),[tag key](#tag-key),[tag set](#tag-set) ### series key A series key identifies a particular series by measurement, tag set, and field key. For example: ```text # measurement, tag set, field key h2o_level, location=santa_monica, h2o_feet ``` Related entries:[series](#series) ### server A computer, virtual or physical, running InfluxDB. ### service input plugin Telegraf input plugins that run in a passive collection mode while the Telegraf agent is running. Service input plugins listen on a socket for known protocol inputs, or apply their own logic to ingested metrics before delivering metrics to the Telegraf agent. Related entries:[aggregator plugin](#aggregator-plugin),[input plugin](#input-plugin),[output plugin](#output-plugin),[processor plugin](#processor-plugin) ### string A data type used to represent text. T ---------- ### TCP Transmission Control Protocol. ### table A collection of related data organized in a structured way with a predefined set of columns and data types. Each row in the table represents a specific record or instance of the data, and each column represents a specific attribute or property of the data. In InfluxDB 3 Core, a table represents a measurement. Related entries:[column](#column),[measurement](#measurement),[primary key](#primary-key),[row](#row) ### tag The key-value pair in InfluxDB’s data structure that records metadata. Tags are an optional part of InfluxDB’s data structure but they are useful for storing commonly queried metadata. Related entries:[field](#field),[tag key](#tag-key),[tag set](#tag-set),[tag value](#tag-value) ### tag key The key of a tag key-value pair. Tag keys are strings and store metadata. Related entries:[field key](#field-key),[tag](#tag),[tag set](#tag-set),[tag value](#tag-value) ### tag set The collection of tag keys and tag values on a point. Related entries:[point](#point),[primary key](#primary-key),[series](#series),[tag](#tag),[tag key](#tag-key),[tag value](#tag-value) ### tag value The value of a tag key-value pair. Tag values are strings and they store metadata. Related entries:[tag](#tag),[tag key](#tag-key),[tag set](#tag-set) ### Telegraf A plugin-driven agent that collects, processes, aggregates, and writes metrics. Related entries:[Telegraf plugins](/telegraf/v1/plugins/),[Use Telegraf to collect data](/influxdb3/core/write-data/use-telegraf/), ### time (data type) A data type that represents a single point in time with nanosecond precision. ### time series data Sequence of data points typically consisting of successive measurements made from the same source over a time interval. Time series data shows how data evolves over time. On a time series data graph, one of the axes is always time. Time series data may be regular or irregular. Regular time series data changes in constant intervals. Irregular time series data changes at non-constant intervals. ### timestamp The date and time associated with a point. Time in InfluxDB is in UTC. To specify time when writing data, see[Elements of line protocol](/influxdb3/core/reference/syntax/line-protocol/#elements-of-line-protocol). Related entries:[point](#point),[unix timestamp](#unix-timestamp),[RFC3339 timestamp](#rfc3339-timestamp) ### token Tokens provide authorization to perform specific actions in InfluxDB. InfluxDB 3 Core supports different types of authorization tokens: * **Admin token:** A token that grants full access to InfluxDB 3 server actions. * **Resource token:** Tokens that grant read and write access to server resources, such as databases and system information. Database tokens allow for reading and writing data in your InfluxDB 3 Core instance. System tokens allow for reading system information and metrics for your server. For more information, see [Manage tokens](/influxdb3/core/admin/tokens/). ### transformation Data transformation refers to the process of converting or modifying input data from one format, value, or structure to another. InfluxQL [transformation functions](/influxdb3/core/reference/influxql/functions/transformations/)modify and return values in each row of queried data, but do not return an aggregated value across those rows. Related entries: [aggregate](#aggregate), [function](#function), [selector](#selector) ### trigger With InfluxDB 3 Core and Enterprise, a Processing engine trigger connects a Processing engine plugin to a specific type of event. A trigger has: * a *trigger specification* that defines the event (data ingestion, a time interval or schedule, or an HTTP request) that runs the plugin. * a plugin file that contains the code to run when the trigger fires. * optional configuration parameters that are passed to the plugin. Related entries:[plugin](#plugin),[Processing engine](#processing-engine) ### TSM (Time Structured Merge tree) The InfluxDB v1 and v2 data storage format that allows greater compaction and higher write and read throughput than B+ or LSM tree implementations. The TSM storage engine has been replaced by the [InfluxDB 3 storage engine (IOx)](#iox). Related entries:[IOx](#iox) U ---------- ### UDP User Datagram Protocol is a packet of information. When a request is made, a UDP packet is sent to the recipient. The sender doesn’t verify the packet is received. The sender continues to send the next packets. This means computers can communicate more quickly. This protocol is used when speed is desirable and error correction is not necessary. ### unix epoch The date and time from which Unix system times are measured. The Unix epoch is `1970-01-01T00:00:00Z`. ### unix timestamp Counts time since **Unix Epoch (1970-01-01T00:00:00Z UTC)** in specified units ([precision](#precision)). Specify timestamp precision when [writing data to InfluxDB](/influxdb3/core/write-data/). InfluxDB supports the following unix timestamp precisions: |Precision|Description | Example | |---------|------------|---------------------| | `ns` |Nanoseconds |`1577836800000000000`| | `us` |Microseconds| `1577836800000000` | | `ms` |Milliseconds| `1577836800000` | | `s` | Seconds | `1577836800` | *The examples above represent **2020-01-01T00:00:00Z UTC**.* Related entries:[timestamp](#timestamp),[RFC3339 timestamp](#rfc3339-timestamp) ### unsigned integer A whole number that is positive or zero (`0`, `143`). Also known as a “uinteger.” InfluxDB supports 64-bit unsigned integers (minimum: `0`, maximum: `18446744073709551615`). Related entries:[integer](#integer) ### user InfluxDB users are granted permission to access InfluxDB. V ---------- ### values per second The preferred measurement of the rate at which data is persisted to InfluxDB. Write speeds are generally quoted in values per second. To calculate the values per second rate, multiply the number of points written per second by the number of values stored per point. For example, if the points have four fields each, and a batch of 5000 points is written 10 times per second, the values per second rate is: **4 field values per point** × **5000 points per batch** × **10 batches per second** = **200,000 values per second** Related entries:[batch](#batch),[field](#field),[point](#point) ### variable A storage location (identified by a memory address) paired with an associated symbolic name (an identifier). A variable contains some known or unknown quantity of information referred to as a value. ### variable assignment A statement that sets or updates the value stored in a variable. W ---------- ### WAL (Write-Ahead Log) The temporary cache for recently written points. To reduce the frequency that permanent storage files are accessed, InfluxDB caches new points in the WAL until their total size or age triggers a flush to more permanent storage. This allows for efficient batching of the writes into the storage engine. Points in the WAL are queryable and persist through a system reboot. On process start, all points in the WAL must be flushed before the system accepts new writes. ### WAL tail The most recent points in the [WAL](#wal-write-ahead-log) that have not yet been durably persisted beyond the WAL. For details, see[Data durability](/influxdb3/core/reference/internals/durability/#wal-tail). ### windowing Grouping data based on specified time intervals. This is also referred to as “time binning” or “date binning.” [glossary](/influxdb3/core/tags/glossary/) | email | status | | --- | --- | | email | status | | lorr@influxdata.com | start | | lorr@influxdata.com | finish | | marv@influxdata.com | start | | marv@influxdata.com | finish | | cliff@influxdata.com | start | | cliff@influxdata.com | finish | | email | status | firstname | | --- | --- | --- | | email | status | firstname | | lorr@influxdata.com | start | lorraine | | lorr@influxdata.com | finish | lorraine | | marv@influxdata.com | start | marvin | | marv@influxdata.com | finish | marvin | | cliff@influxdata.com | start | clifford | | cliff@influxdata.com | finish | clifford | | Precision | Description | Example | | --- | --- | --- | | Precision | Description | Example | | ns | Nanoseconds | 1577836800000000000 | | us | Microseconds | 1577836800000000 | | ms | Milliseconds | 1577836800000 | | s | Seconds | 1577836800 | --- # InfluxQL reference documentation Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/ InfluxQL (Influx Query Language) is an SQL-like query language used to interact with InfluxDB and work with times series data. > [!Important] > #### InfluxQL feature support > > InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. > This process is ongoing and some InfluxQL features are still being implemented. > For information about the current implementation status of InfluxQL features, > see [InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/). * [Notation](#notation) * [Query representation](#query-representation) * [Characters](#characters) * [Letters and digits](#letters-and-digits) * [Identifiers](#identifiers) * [Keywords](#keywords) * [Literals](#literals) * [Queries](#queries) * [Statements](#statements) * [Clauses](#clauses) * [Expressions](#expressions) * [Comments](#comments) * [Other](#other) * [Result set](#result-set) ## Notation The syntax is specified using Extended Backus-Naur Form (“EBNF”). EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). ```go Production = production_name "=" [ Expression ] "." . Expression = Alternative { "|" Alternative } . Alternative = Term { Term } . Term = production_name | token [ "…" token ] | Group | Option | Repetition . Group = "(" Expression ")" . Option = "[" Expression "]" . Repetition = "{" Expression "}" . ``` Notation operators in order of increasing precedence: ``` | alternation () grouping [] option (0 or 1 times) {} repetition (0 to n times) ``` ## Query representation ### Characters InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). ``` newline = /* the Unicode code point U+000A */ . unicode_char = /* an arbitrary Unicode code point except newline */ . ``` ### Letters and digits Letters are the set of ASCII letters and the underscore (`_`, U+005F). Only decimal digits are supported. ``` letter = ascii_letter | "_" . ascii_letter = "A" … "Z" | "a" … "z" . digit = "0" … "9" . ``` ### Identifiers Identifiers are tokens that refer to[database](/influxdb3/core/reference/glossary/#database) names,[retention policy](/influxdb3/core/reference/glossary/#retention-policy-rp) names,[measurement](/influxdb3/core/reference/glossary/#measurement) names,[tag keys](/influxdb3/core/reference/glossary/#tag-key), and[field keys](/influxdb3/core/reference/glossary/#field-key). The rules are as follows: * Double-quoted identifiers can contain any Unicode character except for a new line. * Double-quoted identifiers can also contain escaped `"` characters (that is, `\"`) * Double-quoted identifiers can include InfluxQL [keywords](#keywords). * Unquoted identifiers must start with an upper or lowercase ASCII character or “\_”. * Unquoted identifiers may contain only ASCII letters, decimal digits, and “\_”. ``` identifier = unquoted_identifier | quoted_identifier . unquoted_identifier = ( letter ) { letter | digit } . quoted_identifier = `"` unicode_char { unicode_char } `"` . ``` #### Examples ``` cpu _cpu_stats "1h" "anything really" "1_Crazy-1337.identifier>NAME👍" ``` ### Keywords ``` ALL ALTER ANY AS ASC BEGIN BY CREATE CONTINUOUS DATABASE DATABASES DEFAULT DELETE DESC DESTINATIONS DIAGNOSTICS DISTINCT DROP DURATION END EVERY EXPLAIN FIELD FOR FROM GRANT GRANTS GROUP GROUPS IN INF INSERT INTO KEY KEYS KILL LIMIT SHOW MEASUREMENT MEASUREMENTS NAME OFFSET ON ORDER PASSWORD POLICY POLICIES PRIVILEGES QUERIES QUERY READ REPLICATION RESAMPLE RETENTION REVOKE SELECT SERIES SET SHARD SHARDS SLIMIT SOFFSET STATS SUBSCRIPTION SUBSCRIPTIONS TAG TO USER USERS VALUES WHERE WITH WRITE ``` If you use an InfluxQL keyword as an[identifier](/influxdb3/core/reference/glossary/#identifier), double-quote the identifier in every query. The `time` keyword is a special case.`time` can be a database name,[measurement](/influxdb3/core/reference/glossary/#measurement) name,[retention policy](/influxdb3/core/reference/glossary/#retention-policy-rp) name, and[user](/influxdb3/core/reference/glossary/#user) name. In those cases, you don’t need to double-quote `time` in queries. `time` can’t be a [field key](/influxdb3/core/reference/glossary/#field-key) or[tag key](/influxdb3/core/reference/glossary/#tag-key); InfluxDB rejects writes with `time` as a field key or tag key and returns an error. ### Literals #### Integers InfluxQL supports decimal integer literals. Hexadecimal and octal literals aren’t currently supported. ``` int_lit = ( "1" … "9" ) { digit } . ``` #### Floats InfluxQL supports floating-point literals. Exponents aren’t currently supported. ``` float_lit = int_lit "." int_lit . ``` #### Strings String literals must be surrounded by single quotes. Strings may contain `'` characters as long as they are escaped (that is, , `\'`) ``` string_lit = `'` { unicode_char } `'` . ``` #### Durations Duration literals specify a length of time. An integer literal followed immediately (with no spaces) by one of the duration units listed below is interpreted as a duration literal. Durations can be specified with mixed units. ##### Duration units |Units | Meaning | |------|---------------------------------------| | ns | nanoseconds (1 billionth of a second) | |u or µ|microseconds (1 millionth of a second) | | ms |milliseconds (1 thousandth of a second)| | s | second | | m | minute | | h | hour | | d | day | | w | week | ``` duration_lit = int_lit duration_unit . duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . ``` #### Dates & Times Unlike other notations used in InfluxQL, the date and time literal format isn’t specified by EBNF. InfluxQL date and time is specified using Go’s time parsing format and[reference date](https://pkg.go.dev/time#pkg-constants) written in the format required by InfluxQL. The reference date time is: InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM ``` time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" . ``` #### Booleans ``` bool_lit = TRUE | FALSE . ``` #### Regular Expressions ``` regex_lit = "/" { unicode_char } "/" . ``` **Comparators:**`=~` matches against`!~` doesn’t match against > [!Note] > InfluxQL supports using regular expressions when specifying: > > * [field keys](/influxdb3/core/reference/glossary/#field-key) and [tag keys](/influxdb3/core/reference/glossary/\> #tag-key) in the [`SELECT` clause](/influxdb3/core/reference/influxql/select/) > * [measurements](/influxdb3/core/reference/glossary/#measurement) in the [`FROM` clause](/influxdb3/core/reference/\> influxql/select/#from-clause) > * [tag values](/influxdb3/core/reference/glossary/#tag-value) and > string [field values](/influxdb3/core/reference/glossary/#field-value)in the [`WHERE` clause](/influxdb3/core/reference/influxql/where/) > * [tag keys](/influxdb3/core/reference/glossary/#tag-key) in the[`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/) > > Currently, InfluxQL doesn’t support using regular expressions to match non-string > field values in the `WHERE` clause, [databases](/influxdb3/core/reference/glossary/#database), > and [retention polices](/influxdb3/core/reference/glossary/#retention-policy-rp). ## Queries A query is composed of one or more statements separated by a semicolon (`;`). ``` query = statement { ";" statement } . statement = explain_stmt | explain_analyze_stmt | select_stmt | show_field_keys_stmt | show_measurements_stmt | show_retention_policies_stmt | show_tag_keys_stmt | show_tag_values_with_key = stmt . ``` ## Statements ### EXPLAIN Parses and plans the query, and then prints a summary of estimated costs. Many SQL engines use the `EXPLAIN` statement to show join order, join algorithms, and predicate and expression pushdown. Since InfluxQL doesn’t support joins, the cost of an InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned. A query plan generated by `EXPLAIN` contains the following elements: * expression * auxiliary fields * number of shards * number of series * cached values * number of files * number of blocks * size of blocks ``` explain_stmt = "EXPLAIN" select_stmt . ``` #### Example ```sql > explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname; > QUERY PLAN ------ EXPRESSION: sum(pointReq::integer) NUMBER OF SHARDS: 2 NUMBER OF SERIES: 2 CACHED VALUES: 110 NUMBER OF FILES: 1 NUMBER OF BLOCKS: 1 SIZE OF BLOCKS: 931 ``` ### EXPLAIN ANALYZE Executes the specified `SELECT` statement and returns data about the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). For example, if you execute the following statement: ```sql explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z' ``` The output is similar to the following: ``` ## EXPLAIN ANALYZE . └── select ├── execution_time: 2.25823ms ├── planning_time: 18.381616ms ├── total_time: 20.639846ms └── field_iterators ├── labels │ └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu └── expression ├── labels │ └── expr: mean(usage_steal::float) └── create_iterator ├── labels │ ├── measurement: cpu │ └── shard_id: 608 ├── cursors_ref: 779 ├── cursors_aux: 0 ├── cursors_cond: 0 ├── float_blocks_decoded: 431 ├── float_blocks_size_bytes: 1003552 ├── integer_blocks_decoded: 0 ├── integer_blocks_size_bytes: 0 ├── unsigned_blocks_decoded: 0 ├── unsigned_blocks_size_bytes: 0 ├── string_blocks_decoded: 0 ├── string_blocks_size_bytes: 0 ├── boolean_blocks_decoded: 0 ├── boolean_blocks_size_bytes: 0 └── planning_time: 14.805277ms``` ``` > [!Note] > `EXPLAIN ANALYZE` ignores query output, so the cost of serialization to JSON or > CSV isn’t accounted for. ##### execution\_time Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn’t include the time taken to serialize the output into JSON or other formats. ##### planning\_time Shows the amount of time the query took to plan. Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and how much memory the planning requires. First, InfluxDB determines the effective time range of the query and selects the shards to access. Next, for each shard and each measurement, InfluxDB performs the following steps: 1. Select matching series keys from the index, filtered by tag predicates in the `WHERE` clause. 2. Group filtered series keys into tag sets based on the `GROUP BY` dimensions. 3. Enumerate each tag set and create a cursor and iterator for each series key. 4. Merge iterators and return the merged result to the query executor. ##### iterator type `EXPLAIN ANALYZE` supports the following iterator types: * `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. * (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. For more information about iterators, see [Understanding iterators](#understanding-iterators). ##### cursor type `EXPLAIN ANALYZE` distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement: * cursor\_ref: Reference cursor created for `SELECT` projections that include a function, such as `last()` or `mean()`. * cursor\_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. * cursor\_cond: Condition cursor created for fields referenced in a `WHERE` clause. For more information about cursors, see [Understanding cursors](#understanding-cursors). ##### block types `EXPLAIN ANALYZE` separates storage block types, and reports the total number of blocks decoded and their size (in bytes) on disk. The following block types are supported: | Type | Description | |----------|-------------------------------------| | `float` |64-bit IEEE-754 floating-point number| |`integer` | 64-bit signed integer | |`unsigned`| 64-bit unsigned integer | |`boolean` | 1-bit, LSB encoded | | `string` | UTF-8 string | ### SELECT ``` select_stmt = "SELECT" fields from_clause [ where_clause ] [ group_by_clause ] [ order_by_clause ] [ limit_clause ] [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] . ``` #### Example Select from measurements grouped by the day with a timezone ```sql SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago') ``` ### SHOW FIELD KEYS ``` show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] . ``` #### Examples ```sql -- show field keys and field value data types from all measurements SHOW FIELD KEYS -- show field keys and field value data types from specified measurement SHOW FIELD KEYS FROM "cpu" ``` ### SHOW MEASUREMENTS ``` show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Examples ```sql -- show all measurements SHOW MEASUREMENTS -- show measurements where region tag = 'uswest' AND host tag = 'serverA' SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' -- show measurements that start with 'h2o' SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ ``` ### SHOW TAG KEYS ``` show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Examples ```sql -- show all tag keys SHOW TAG KEYS -- show all tag keys from the cpu measurement SHOW TAG KEYS FROM "cpu" -- show all tag keys from the cpu measurement where the region key = 'uswest' SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' -- show all tag keys where the host key = 'serverA' SHOW TAG KEYS WHERE "host" = 'serverA' ``` ### SHOW TAG VALUES ``` show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Examples ```sql -- show all tag values across all measurements for the region tag SHOW TAG VALUES WITH KEY = "region" -- show tag values from the cpu measurement for the region tag SHOW TAG VALUES FROM "cpu" WITH KEY = "region" -- show tag values across all measurements for all tag keys that do not include the letter c SHOW TAG VALUES WITH KEY !~ /.*c.*/ -- show tag values from the cpu measurement for region & host tag keys where service = 'redis' SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' ``` ## Clauses ``` from_clause = "FROM" measurements . group_by_clause = "GROUP BY" dimensions fill(fill_option). limit_clause = "LIMIT" int_lit . offset_clause = "OFFSET" int_lit . slimit_clause = "SLIMIT" int_lit . soffset_clause = "SOFFSET" int_lit . timezone_clause = tz(string_lit) . on_clause = "ON" db_name . order_by_clause = "ORDER BY" sort_fields . where_clause = "WHERE" expr . with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) . with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) . ``` ## Expressions ``` binary_op = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" | "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" . expr = unary_expr { binary_op unary_expr } . unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | float_lit | bool_lit | duration_lit | regex_lit . ``` ## Default time range The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to *now*. ## Comments Use comments with InfluxQL statements to describe your queries. * A single line comment begins with two hyphens (`--`) and ends where InfluxDB detects a line break. This comment type cannot span several lines. * A multi-line comment begins with `/*` and ends with `*/`. This comment type can span several lines. Multi-line comments do not support nested multi-line comments. ## Other ``` alias = "AS" identifier . back_ref = ( policy_name ".:MEASUREMENT" ) | ( db_name "." [ policy_name ] ".:MEASUREMENT" ) . db_name = identifier . dimension = expr . dimensions = dimension { "," dimension } . field_key = identifier . field = expr [ alias ] . fields = field { "," field } . fill_option = "null" | "none" | "previous" | int_lit | float_lit | "linear" . host = string_lit . measurement = measurement_name | ( policy_name "." measurement_name ) | ( db_name "." [ policy_name ] "." measurement_name ) . measurements = measurement { "," measurement } . measurement_name = identifier | regex_lit . policy_name = identifier . retention_policy = identifier . retention_policy_name = "NAME" identifier . series_id = int_lit . sort_field = field_key [ ASC | DESC ] . sort_fields = sort_field { "," sort_field } . tag_key = identifier . tag_keys = tag_key { "," tag_key } . var_ref = measurement . ``` | Units | Meaning | | --- | --- | | Units | Meaning | | ns | nanoseconds (1 billionth of a second) | | u or µ | microseconds (1 millionth of a second) | | ms | milliseconds (1 thousandth of a second) | | s | second | | m | minute | | h | hour | | d | day | | w | week | | Type | Description | | --- | --- | | Type | Description | | float | 64-bit IEEE-754 floating-point number | | integer | 64-bit signed integer | | unsigned | 64-bit unsigned integer | | boolean | 1-bit, LSB encoded | | string | UTF-8 string | --- # InfluxQL feature support Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/feature-support/ InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. This process is ongoing and some InfluxQL features are still being implemented. This page provides information about the current implementation status of InfluxQL features. * [In-progress features](#in-progress-features) * [SLIMIT clause](#slimit-clause) * [SOFFSET clause](#soffset-clause) * [Metaqueries](#metaqueries) * [Function support](#function-support) * [Aggregate functions](#aggregate-functions) * [Selector functions](#selector-functions) * [Transformations](#transformations) * [Technical and predictive analysis](#technical-and-predictive-analysis) ## In-progress features ### SLIMIT clause InfluxQL in InfluxDB 3 Core does not currently support the `SLIMIT` clause, which limits the number of [series](/influxdb3/core/reference/glossary/#series)returned in query results. ### SOFFSET clause InfluxQL in InfluxDB 3 Core does not currently support the `SOFFSET` clause, which specifies the number of [series](/influxdb3/core/reference/glossary/#series)to skip before returning results. ### Metaqueries InfluxQL metaqueries return information about the schema of time series data stored in InfluxDB. The following table provides information about what metaqueries are available in InfluxDB 3 Core: | Metaquery |Supported| |---------------------------|---------| | SHOW DATABASES | | |**SHOW RETENTION POLICIES**| **✓** | | **SHOW MEASUREMENTS** | **✓** | | SHOW SERIES | | | SHOW SERIES CARDINALITY | | | **SHOW TAG KEYS** | **✓** | | SHOW TAG KEY CARDINALITY | | | **SHOW TAG VALUES** | **✓** | |SHOW TAG VALUES CARDINALITY| | | **SHOW FIELD KEYS** | **✓** | |SHOW FIELD KEYS CARDINALITY| | > [!Note] > #### Cardinality metaqueries > > With the InfluxDB 3 storage engine, series cardinality is no longer a limiting > factor for database performance. > Cardinality-related metaqueries will likely not be supported with the InfluxDB 3 > storage engine. ## Function support ### Aggregate functions | Function |Supported| |-------------------------------------------------------------------------------|---------| | [COUNT()](/influxdb3/core/reference/influxql/functions/aggregates/#count) | **✓** | |[DISTINCT()](/influxdb3/core/reference/influxql/functions/aggregates/#distinct)| **✓** | |[INTEGRAL()](/influxdb3/core/reference/influxql/functions/aggregates/#integral)| **✓** | | [MEAN()](/influxdb3/core/reference/influxql/functions/aggregates/#mean) | **✓** | | [MEDIAN()](/influxdb3/core/reference/influxql/functions/aggregates/#median) | **✓** | | [MODE()](/influxdb3/core/reference/influxql/functions/aggregates/#mode) | **✓** | | [SPREAD()](/influxdb3/core/reference/influxql/functions/aggregates/#spread) | **✓** | | [STDDEV()](/influxdb3/core/reference/influxql/functions/aggregates/#stddev) | **✓** | | [SUM()](/influxdb3/core/reference/influxql/functions/aggregates/#sum) | **✓** | ### Selector functions | Function |Supported| |----------------------------------------------------------------------------------|---------| | [BOTTOM()](/influxdb3/core/reference/influxql/functions/selectors/#bottom) | **✓** | | [FIRST()](/influxdb3/core/reference/influxql/functions/selectors/#first) | **✓** | | [LAST()](/influxdb3/core/reference/influxql/functions/selectors/#last) | **✓** | | [MAX()](/influxdb3/core/reference/influxql/functions/selectors/#max) | **✓** | | [MIN()](/influxdb3/core/reference/influxql/functions/selectors/#min) | **✓** | |[PERCENTILE()](/influxdb3/core/reference/influxql/functions/selectors/#percentile)| **✓** | | SAMPLE() | | | [TOP()](/influxdb3/core/reference/influxql/functions/selectors/#top) | **✓** | ### Transformations | Function |Supported| |--------------------------------------------------------------------------------------------------------------------|---------| | [ABS()](/influxdb3/core/reference/influxql/functions/transformations/#abs) | **✓** | | [ACOS()](/influxdb3/core/reference/influxql/functions/transformations/#acos) | **✓** | | [ASIN()](/influxdb3/core/reference/influxql/functions/transformations/#asin) | **✓** | | [ATAN()](/influxdb3/core/reference/influxql/functions/transformations/#atan) | **✓** | | [ATAN2()](/influxdb3/core/reference/influxql/functions/transformations/#atan2) | **✓** | | [CEIL()](/influxdb3/core/reference/influxql/functions/transformations/#ceil) | **✓** | | [COS()](/influxdb3/core/reference/influxql/functions/transformations/#cos) | **✓** | | [CUMULATIVE\_SUM()](/influxdb3/core/reference/influxql/functions/transformations/#cumulative_sum) | **✓** | | [DERIVATIVE()](/influxdb3/core/reference/influxql/functions/transformations/#derivative) | **✓** | | [DIFFERENCE()](/influxdb3/core/reference/influxql/functions/transformations/#difference) | **✓** | | [ELAPSED()](/influxdb3/core/reference/influxql/functions/transformations/#elapsed) | **✓** | | [EXP()](/influxdb3/core/reference/influxql/functions/transformations/#exp) | **✓** | | [FLOOR()](/influxdb3/core/reference/influxql/functions/transformations/#floor) | **✓** | | [LN()](/influxdb3/core/reference/influxql/functions/transformations/#ln) | **✓** | | [LOG()](/influxdb3/core/reference/influxql/functions/transformations/#log) | **✓** | | [LOG2()](/influxdb3/core/reference/influxql/functions/transformations/#log2) | **✓** | | [LOG10()](/influxdb3/core/reference/influxql/functions/transformations/#log10) | **✓** | | [MOVING\_AVERAGE()](/influxdb3/core/reference/influxql/functions/transformations/#moving_average) | **✓** | |[NON\_NEGATIVE\_DERIVATIVE()](/influxdb3/core/reference/influxql/functions/transformations/#non_negative_derivative)| **✓** | |[NON\_NEGATIVE\_DIFFERENCE()](/influxdb3/core/reference/influxql/functions/transformations/#non_negative_difference)| **✓** | | [POW()](/influxdb3/core/reference/influxql/functions/transformations/#pow) | **✓** | | [ROUND()](/influxdb3/core/reference/influxql/functions/transformations/#round) | **✓** | | [SIN()](/influxdb3/core/reference/influxql/functions/transformations/#sin) | **✓** | | [SQRT()](/influxdb3/core/reference/influxql/functions/transformations/#sqrt) | **✓** | | [TAN()](/influxdb3/core/reference/influxql/functions/transformations/#tan) | **✓** | ### Technical and predictive analysis | Function |Supported| |--------------------------------------|---------| | CHANDE\_MOMENTUM\_OSCILLATOR() | | |DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE()| | | EXPONENTIAL\_MOVING\_AVERAGE() | | | HOLT\_WINTERS() | | | HOLT\_WINTERS\_WITH\_FIT() | | | KAUFMANS\_EFFICIENCY\_RATIO() | | |KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE() | | | RELATIVE\_STRENGTH\_INDEX() | | |TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE()| | | TRIPLE\_EXPONENTIAL\_DERIVATIVE() | | ### Date and time functions | Function |Supported| |----------------------------------------------------------------------|---------| | [now()](/influxdb3/core/reference/influxql/functions/date-time/#now) | **✓** | |[time()](/influxdb3/core/reference/influxql/functions/date-time/#time)| **✓** | | [tz()](/influxdb3/core/reference/influxql/functions/date-time/#tz) | **✓** | ### Miscellaneous functions | Function |Supported| |-----------------------------------------------------------------|---------| |[fill()](/influxdb3/core/reference/influxql/functions/misc/#fill)| **✓** | | Metaquery | Supported | | --- | --- | | Metaquery | Supported | | SHOW DATABASES | | | SHOW RETENTION POLICIES | ✓ | | SHOW MEASUREMENTS | ✓ | | SHOW SERIES | | | SHOW SERIES CARDINALITY | | | SHOW TAG KEYS | ✓ | | SHOW TAG KEY CARDINALITY | | | SHOW TAG VALUES | ✓ | | SHOW TAG VALUES CARDINALITY | | | SHOW FIELD KEYS | ✓ | | SHOW FIELD KEYS CARDINALITY | | | Function | Supported | | --- | --- | | Function | Supported | | COUNT() | ✓ | | DISTINCT() | ✓ | | INTEGRAL() | ✓ | | MEAN() | ✓ | | MEDIAN() | ✓ | | MODE() | ✓ | | SPREAD() | ✓ | | STDDEV() | ✓ | | SUM() | ✓ | | Function | Supported | | --- | --- | | Function | Supported | | BOTTOM() | ✓ | | FIRST() | ✓ | | LAST() | ✓ | | MAX() | ✓ | | MIN() | ✓ | | PERCENTILE() | ✓ | | SAMPLE() | | | TOP() | ✓ | | Function | Supported | | --- | --- | | Function | Supported | | ABS() | ✓ | | ACOS() | ✓ | | ASIN() | ✓ | | ATAN() | ✓ | | ATAN2() | ✓ | | CEIL() | ✓ | | COS() | ✓ | | CUMULATIVE_SUM() | ✓ | | DERIVATIVE() | ✓ | | DIFFERENCE() | ✓ | | ELAPSED() | ✓ | | EXP() | ✓ | | FLOOR() | ✓ | | LN() | ✓ | | LOG() | ✓ | | LOG2() | ✓ | | LOG10() | ✓ | | MOVING_AVERAGE() | ✓ | | NON_NEGATIVE_DERIVATIVE() | ✓ | | NON_NEGATIVE_DIFFERENCE() | ✓ | | POW() | ✓ | | ROUND() | ✓ | | SIN() | ✓ | | SQRT() | ✓ | | TAN() | ✓ | | Function | Supported | | --- | --- | | Function | Supported | | CHANDE_MOMENTUM_OSCILLATOR() | | | DOUBLE_EXPONENTIAL_MOVING_AVERAGE() | | | EXPONENTIAL_MOVING_AVERAGE() | | | HOLT_WINTERS() | | | HOLT_WINTERS_WITH_FIT() | | | KAUFMANS_EFFICIENCY_RATIO() | | | KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | | | RELATIVE_STRENGTH_INDEX() | | | TRIPLE_EXPONENTIAL_MOVING_AVERAGE() | | | TRIPLE_EXPONENTIAL_DERIVATIVE() | | | Function | Supported | | --- | --- | | Function | Supported | | now() | ✓ | | time() | ✓ | | tz() | ✓ | | Function | Supported | | --- | --- | | Function | Supported | | fill() | ✓ | --- # View InfluxQL functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/ Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. > [!Note] > #### Missing InfluxQL functions > > Some InfluxQL functions are in the process of being rearchitected to work with > the InfluxDB 3 storage engine. If a function you need is not here, check the[InfluxQL feature support page](/influxdb3/core/reference/influxql/feature-support/#function-support)for more information. ## InfluxQL functions (by type) * [Aggregates](/influxdb3/core/reference/influxql/functions/aggregates/) * [COUNT()](/influxdb3/core/reference/influxql/functions/aggregates/#count) * [DISTINCT()](/influxdb3/core/reference/influxql/functions/aggregates/#distinct) * [MEAN()](/influxdb3/core/reference/influxql/functions/aggregates/#mean) * [MEDIAN()](/influxdb3/core/reference/influxql/functions/aggregates/#median) * [MODE()](/influxdb3/core/reference/influxql/functions/aggregates/#mode) * [SPREAD()](/influxdb3/core/reference/influxql/functions/aggregates/#spread) * [STDDEV()](/influxdb3/core/reference/influxql/functions/aggregates/#stddev) * [SUM()](/influxdb3/core/reference/influxql/functions/aggregates/#sum) * [Selectors](/influxdb3/core/reference/influxql/functions/selectors/) * [BOTTOM()](/influxdb3/core/reference/influxql/functions/selectors/#bottom) * [FIRST()](/influxdb3/core/reference/influxql/functions/selectors/#first) * [LAST()](/influxdb3/core/reference/influxql/functions/selectors/#last) * [MAX()](/influxdb3/core/reference/influxql/functions/selectors/#max) * [MIN()](/influxdb3/core/reference/influxql/functions/selectors/#min) * [PERCENTILE()](/influxdb3/core/reference/influxql/functions/selectors/#percentile) * [TOP()](/influxdb3/core/reference/influxql/functions/selectors/#top) * [Transformations](/influxdb3/core/reference/influxql/functions/transformations/) * [ABS()](/influxdb3/core/reference/influxql/functions/transformations/#abs) * [ACOS()](/influxdb3/core/reference/influxql/functions/transformations/#acos) * [ASIN()](/influxdb3/core/reference/influxql/functions/transformations/#asin) * [ATAN()](/influxdb3/core/reference/influxql/functions/transformations/#atan) * [ATAN2()](/influxdb3/core/reference/influxql/functions/transformations/#atan2) * [CEIL()](/influxdb3/core/reference/influxql/functions/transformations/#ceil) * [COS()](/influxdb3/core/reference/influxql/functions/transformations/#cos) * [CUMULATIVE\_SUM()](/influxdb3/core/reference/influxql/functions/transformations/#cumulative_sum) * [DERIVATIVE()](/influxdb3/core/reference/influxql/functions/transformations/#derivative) * [DIFFERENCE()](/influxdb3/core/reference/influxql/functions/transformations/#difference) * [EXP()](/influxdb3/core/reference/influxql/functions/transformations/#exp) * [FLOOR()](/influxdb3/core/reference/influxql/functions/transformations/#floor) * [HISTOGRAM()](/influxdb3/core/reference/influxql/functions/transformations/#histogram) * [LN()](/influxdb3/core/reference/influxql/functions/transformations/#ln) * [LOG()](/influxdb3/core/reference/influxql/functions/transformations/#log) * [LOG2()](/influxdb3/core/reference/influxql/functions/transformations/#log2) * [LOG10()](/influxdb3/core/reference/influxql/functions/transformations/#log10) * [MOVING\_AVERAGE()](/influxdb3/core/reference/influxql/functions/transformations/#moving_average) * [NON\_NEGATIVE\_DERIVATIVE()](/influxdb3/core/reference/influxql/functions/transformations/#non_negative_derivative) * [NON\_NEGATIVE\_DIFFERENCE()](/influxdb3/core/reference/influxql/functions/transformations/#non_negative_difference) * [POW()](/influxdb3/core/reference/influxql/functions/transformations/#pow) * [ROUND()](/influxdb3/core/reference/influxql/functions/transformations/#round) * [SIN()](/influxdb3/core/reference/influxql/functions/transformations/#sin) * [SQRT()](/influxdb3/core/reference/influxql/functions/transformations/#sqrt) * [TAN()](/influxdb3/core/reference/influxql/functions/transformations/#tan) * [Date and time](/influxdb3/core/reference/influxql/functions/date-time/) * [now()](/influxdb3/core/reference/influxql/functions/date-time/#now) * [time()](/influxdb3/core/reference/influxql/functions/date-time/#time) * [Miscellaneous](/influxdb3/core/reference/influxql/functions/misc/) * [fill()](/influxdb3/core/reference/influxql/functions/misc/#fill) --- # InfluxQL aggregate functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/aggregates/ Use aggregate functions to assess, aggregate, and return values in your data. Aggregate functions return one row containing the aggregate values from each InfluxQL group. *Examples use the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* * [COUNT()](#count) * [DISTINCT()](#distinct) * [INTEGRAL()](#integral) * [MEAN()](#mean) * [MEDIAN()](#median) * [MODE()](#mode) * [SPREAD()](#spread) * [STDDEV()](#stddev) * [SUM()](#sum) ## COUNT() Returns the number of non-null [field values](/influxdb3/core/reference/glossary/#field-value). ```sql COUNT(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field types. #### Examples [](#count-the-number-of-non-null-values-in-a-field) Count the number of non-null values in a field ```sql SELECT COUNT(temp) FROM home ``` name: home | time |count| |--------------------|-----| |1970-01-01T00:00:00Z| 26 | [](#count-the-number-of-non-null-values-in-each-field) Count the number of non-null values in each field ```sql SELECT COUNT(*) FROM home ``` name: home | time |count\_co|count\_hum|count\_temp| |--------------------|---------|----------|-----------| |1970-01-01T00:00:00Z| 26 | 26 | 26 | [](#count-the-number-of-non-null-values-in-fields-where-the-field-key-matches-a-regular-expression) Count the number of non-null values in fields where the field key matches a regular expression ```sql SELECT COUNT(/^[th]/) FROM home ``` name: home | time |count\_hum|count\_temp| |--------------------|----------|-----------| |1970-01-01T00:00:00Z| 26 | 26 | [](#count-distinct-values-for-a-field) Count distinct values for a field InfluxQL supports nesting [`DISTINCT()`](#distinct) in `COUNT()`. ```sql SELECT COUNT(DISTINCT(co)) FROM home ``` name: home | time |count| |--------------------|-----| |1970-01-01T00:00:00Z| 12 | [](#count-the-number-of-non-null-field-values-within-time-windows-grouped-by-time) Count the number of non-null field values within time windows (grouped by time) ```sql SELECT COUNT(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |count| |--------------------|-----| |2022-01-01T06:00:00Z| 4 | |2022-01-01T12:00:00Z| 6 | |2022-01-01T18:00:00Z| 3 | ## DISTINCT() Returns the list of unique [field values](/influxdb3/core/reference/glossary/#field-value). ```sql DISTINCT(field_key) ``` #### Arguments * **field\_key**: Field key to return distinct values from. Supports all field types. #### Notable behaviors * InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count-distinct-values-for-a-field). #### Examples [](#list-the-distinct-field-values) List the distinct field values ```sql SELECT DISTINCT(co) FROM home ``` name: home | time |distinct| |--------------------|--------| |1970-01-01T00:00:00Z| 0 | |1970-01-01T00:00:00Z| 1 | |1970-01-01T00:00:00Z| 3 | |1970-01-01T00:00:00Z| 4 | |1970-01-01T00:00:00Z| 7 | |1970-01-01T00:00:00Z| 5 | |1970-01-01T00:00:00Z| 9 | |1970-01-01T00:00:00Z| 18 | |1970-01-01T00:00:00Z| 14 | |1970-01-01T00:00:00Z| 22 | |1970-01-01T00:00:00Z| 17 | |1970-01-01T00:00:00Z| 26 | ## INTEGRAL() Returns the area under the curve for queried [field values](/influxdb3/core/reference/glossary/#field-value)and converts those results into the summed area per **unit** of time. > [!Important] > * `INTEGRAL()` does not support [`fill()`](/influxdb3/core/reference/influxql/group-by/#group-by-time-and-fill-gaps). > * `INTEGRAL()` supports int64 and float64 field value [data types](/influxdb3/core/reference/glossary/#data-type). ```sql INTEGRAL(field_expression[, unit]) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). * **unit**: Unit of time to use when calculating the integral. Default is `1s` (one second). #### Examples [](#calculate-the-integral-for-a-field) Calculate the integral for a field ```sql SELECT INTEGRAL(co) FROM home WHERE room = 'Kitchen' ``` name: home | time |integral| |--------------------|--------| |1970-01-01T00:00:00Z| 266400 | [](#calculate-the-integral-for-a-field-and-specify-the-unit-option) Calculate the integral for a field and specify the unit option ```sql SELECT INTEGRAL(co, 1h) FROM home WHERE room = 'Kitchen' ``` name: home | time |integral| |--------------------|--------| |1970-01-01T00:00:00Z| 74 | [](#calculate-the-integral-for-_each_-field-and-specify-the-unit-option) Calculate the integral for *each* field and specify the unit option Return the area under the curve (in minutes) for the field values associated with each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has on numeric field: `water_level`. ```sql SELECT INTEGRAL(*, 1h) FROM home WHERE room = 'Kitchen' ``` name: home | time |integral\_co|integral\_hum|integral\_temp| |--------------------|------------|-------------|--------------| |1970-01-01T00:00:00Z| 74 | 435 | 272.25 | [](#calculate-the-integral-for-the-field-keys-that-matches-a-regular-expression) Calculate the integral for the field keys that matches a regular expression ```sql SELECT INTEGRAL(/^[th]/, 1h) FROM home WHERE room = 'Kitchen' ``` name: home | time |integral\_hum|integral\_temp| |--------------------|-------------|--------------| |1970-01-01T00:00:00Z| 435 | 272.25 | [](#calculate-the-integral-for-a-field-grouping-by-time) Calculate the integral for a field grouping by time ```sql SELECT INTEGRAL(co, 1h) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |integral| |--------------------|--------| |2022-01-01T06:00:00Z| 0 | |2022-01-01T12:00:00Z| 30 | |2022-01-01T18:00:00Z| 44 | ## MEAN() Returns the arithmetic mean (average) of [field values](/influxdb3/core/reference/glossary/#field-value). ```sql MEAN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Examples [](#calculate-the-mean-value-of-a-field) Calculate the mean value of a field ```sql SELECT MEAN(temp) FROM home ``` name: home | time | mean | |--------------------|------------------| |1970-01-01T00:00:00Z|22.396153846153844| [](#calculate-the-mean-value-of-each-field) Calculate the mean value of each field ```sql SELECT MEAN(*) FROM home ``` name: home | time | mean\_co |mean\_hum| mean\_temp | |--------------------|-----------------|---------|------------------| |1970-01-01T00:00:00Z|5.269230769230769| 36.15 |22.396153846153844| [](#calculate-the-mean-value-of-fields-where-the-field-key-matches-a-regular-expression) Calculate the mean value of fields where the field key matches a regular expression ```sql SELECT MEAN(/^[th]/) FROM home ``` name: home | time |mean\_hum| mean\_temp | |--------------------|---------|------------------| |1970-01-01T00:00:00Z| 36.15 |22.396153846153844| [](#calculate-the-mean-value-of-a-field-within-time-windows-grouped-by-time) Calculate the mean value of a field within time windows (grouped by time) ```sql SELECT MEAN(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time | mean | |--------------------|------------------| |2022-01-01T06:00:00Z| 22.275 | |2022-01-01T12:00:00Z|22.649999999999995| |2022-01-01T18:00:00Z|23.033333333333335| ## MEDIAN() Returns the middle value from a sorted list of [field values](/influxdb3/core/reference/glossary/#field-value). ```sql MEDIAN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Notable behaviors * `MEDIAN()` is nearly equivalent to[`PERCENTILE(field_key, 50)`](/influxdb3/core/reference/influxql/functions/selectors/#percentile), except `MEDIAN()` returns the average of the two middle field values if the field contains an even number of values. #### Examples [](#calculate-the-median-value-of-a-field) Calculate the median value of a field ```sql SELECT MEDIAN(temp) FROM home ``` name: home | time |median| |--------------------|------| |1970-01-01T00:00:00Z|22.45 | [](#calculate-the-median-value-of-each-field) Calculate the median value of each field ```sql SELECT MEDIAN(*) FROM home ``` name: home | time |median\_co|median\_hum|median\_temp| |--------------------|----------|-----------|------------| |1970-01-01T00:00:00Z| 1 | 36.05 | 22.45 | [](#calculate-the-median-value-of-fields-where-the-field-key-matches-a-regular-expression) Calculate the median value of fields where the field key matches a regular expression ```sql SELECT MEDIAN(/^[th]/) FROM home ``` name: home | time |median\_hum|median\_temp| |--------------------|-----------|------------| |1970-01-01T00:00:00Z| 36.05 | 22.45 | [](#calculate-the-median-value-of-a-field-within-time-windows-grouped-by-time) Calculate the median value of a field within time windows (grouped by time) ```sql SELECT MEDIAN(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time | median | |--------------------|------------------| |2022-01-01T06:00:00Z|22.549999999999997| |2022-01-01T12:00:00Z| 22.7 | |2022-01-01T18:00:00Z| 23.1 | ## MODE() Returns the most frequent value in a list of[field values](/influxdb3/core/reference/glossary/#field-value). ```sql MODE(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field types. #### Notable behaviors * `MODE()` returns the field value with the earliest[timestamp](/influxdb3/core/reference/glossary/#timestamp)if there’s a tie between two or more values for the maximum number of occurrences. #### Examples [](#calculate-the-mode-value-of-a-field) Calculate the mode value of a field ```sql SELECT MODE(co) FROM home ``` name: home | time |mode| |--------------------|----| |1970-01-01T00:00:00Z| 0 | [](#calculate-the-mode-value-of-each-field) Calculate the mode value of each field ```sql SELECT MODE(*) FROM home ``` name: home | time |mode\_co|mode\_hum|mode\_temp| |--------------------|--------|---------|----------| |1970-01-01T00:00:00Z| 0 | 36 | 22.7 | [](#calculate-the-mode-of-field-keys-that-match-a-regular-expression) Calculate the mode of field keys that match a regular expression ```sql SELECT MODE(/^[th]/) FROM home ``` name: home | time |mode\_hum|mode\_temp| |--------------------|---------|----------| |1970-01-01T00:00:00Z| 36 | 22.7 | [](#calculate-the-mode-a-field-within-time-windows-grouped-by-time) Calculate the mode a field within time windows (grouped by time) ```sql SELECT MODE(co) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |mode| |--------------------|----| |2022-01-01T06:00:00Z| 0 | |2022-01-01T12:00:00Z| 1 | |2022-01-01T18:00:00Z| 18 | ## SPREAD() Returns the difference between the minimum and maximum[field values](/influxdb3/core/reference/glossary/#field-value). ```sql SPREAD(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Examples [](#calculate-the-spread-of-a-field) Calculate the spread of a field ```sql SELECT SPREAD(temp) FROM home ``` name: home | time | spread | |--------------------|------------------| |1970-01-01T00:00:00Z|2.3000000000000007| [](#calculate-the-spread-of-each-field) Calculate the spread of each field ```sql SELECT SPREAD(*) FROM home ``` name: home | time |spread\_co|spread\_hum| spread\_temp | |--------------------|----------|-----------|------------------| |1970-01-01T00:00:00Z| 26 | 1 |2.3000000000000007| [](#calculate-the-spread-of-field-keys-that-match-a-regular-expression) Calculate the spread of field keys that match a regular expression ```sql SELECT SPREAD(/^[th]/) FROM home ``` name: home | time |spread\_hum| spread\_temp | |--------------------|-----------|------------------| |1970-01-01T00:00:00Z| 1 |2.3000000000000007| [](#calculate-the-spread-of-a-field-within-time-windows-grouped-by-time) Calculate the spread of a field within time windows (grouped by time) ```sql SELECT SPREAD(co) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |spread| |--------------------|------| |2022-01-01T06:00:00Z| 0 | |2022-01-01T12:00:00Z| 9 | |2022-01-01T18:00:00Z| 8 | ## STDDEV() Returns the standard deviation of [field values](/influxdb3/core/reference/glossary/#field-value). ```sql STDDEV(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Examples [](#calculate-the-standard-deviation-of-a-field) Calculate the standard deviation of a field ```sql SELECT STDDEV(temp) FROM home ``` name: home | time | stddev | |--------------------|------------------| |1970-01-01T00:00:00Z|0.5553238833191091| [](#calculate-the-standard-deviation-of-each-field) Calculate the standard deviation of each field ```sql SELECT STDDEV(*) FROM home ``` name: home | time | stddev\_co | stddev\_hum | stddev\_temp | |--------------------|-----------------|-------------------|------------------| |1970-01-01T00:00:00Z|7.774613519951676|0.25495097567963926|0.5553238833191091| [](#calculate-the-standard-deviation-of-fields-where-the-field-key-matches-a-regular-expression) Calculate the standard deviation of fields where the field key matches a regular expression ```sql SELECT STDDEV(/^[th]/) FROM home ``` name: home | time | stddev\_hum | stddev\_temp | |--------------------|-------------------|------------------| |1970-01-01T00:00:00Z|0.25495097567963926|0.5553238833191091| [](#calculate-the-standard-deviation-of-a-field-within-time-windows-grouped-by-time) Calculate the standard deviation of a field within time windows (grouped by time) ```sql SELECT STDDEV(co) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time | stddev | |--------------------|------------------| |2022-01-01T06:00:00Z| 0 | |2022-01-01T12:00:00Z|3.6742346141747673| |2022-01-01T18:00:00Z| 4 | ## SUM() Returns the sum of [field values](/influxdb3/core/reference/glossary/#field-value). ```sql SUM(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Examples [](#calculate-the-sum-of-values-in-a-field) Calculate the sum of values in a field ```sql SELECT SUM(co) FROM home ``` name: home | time |sum| |--------------------|---| |1970-01-01T00:00:00Z|137| [](#calculate-the-sum-of-values-in-each-field) Calculate the sum of values in each field ```sql SELECT SUM(*) FROM home ``` name: home | time |sum\_co|sum\_hum|sum\_temp| |--------------------|-------|--------|---------| |1970-01-01T00:00:00Z| 137 | 939.9 | 582.3 | [](#calculate-the-sum-of-values-for-fields-where-the-field-key-matches-a-regular-expression) Calculate the sum of values for fields where the field key matches a regular expression ```sql SELECT SUM(/^[th]/) FROM home ``` name: home | time |sum\_hum|sum\_temp| |--------------------|--------|---------| |1970-01-01T00:00:00Z| 939.9 | 582.3 | [](#calculate-the-sum-of-values-in-a-field-within-time-windows-grouped-by-time) Calculate the sum of values in a field within time windows (grouped by time) ```sql SELECT SUM(co) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |sum| |--------------------|---| |2022-01-01T06:00:00Z| 0 | |2022-01-01T12:00:00Z|21 | |2022-01-01T18:00:00Z|66 | #### Related * [Aggregate data with InfluxQL](/influxdb3/core/query-data/influxql/aggregate-select/) | time | count | | --- | --- | | time | count | | 1970-01-01T00:00:00Z | 26 | | time | count_co | count_hum | count_temp | | --- | --- | --- | --- | | time | count_co | count_hum | count_temp | | 1970-01-01T00:00:00Z | 26 | 26 | 26 | | time | count_hum | count_temp | | --- | --- | --- | | time | count_hum | count_temp | | 1970-01-01T00:00:00Z | 26 | 26 | | time | count | | --- | --- | | time | count | | 1970-01-01T00:00:00Z | 12 | | time | count | | --- | --- | | time | count | | 2022-01-01T06:00:00Z | 4 | | 2022-01-01T12:00:00Z | 6 | | 2022-01-01T18:00:00Z | 3 | | time | distinct | | --- | --- | | time | distinct | | 1970-01-01T00:00:00Z | 0 | | 1970-01-01T00:00:00Z | 1 | | 1970-01-01T00:00:00Z | 3 | | 1970-01-01T00:00:00Z | 4 | | 1970-01-01T00:00:00Z | 7 | | 1970-01-01T00:00:00Z | 5 | | 1970-01-01T00:00:00Z | 9 | | 1970-01-01T00:00:00Z | 18 | | 1970-01-01T00:00:00Z | 14 | | 1970-01-01T00:00:00Z | 22 | | 1970-01-01T00:00:00Z | 17 | | 1970-01-01T00:00:00Z | 26 | | time | integral | | --- | --- | | time | integral | | 1970-01-01T00:00:00Z | 266400 | | time | integral | | --- | --- | | time | integral | | 1970-01-01T00:00:00Z | 74 | | time | integral_co | integral_hum | integral_temp | | --- | --- | --- | --- | | time | integral_co | integral_hum | integral_temp | | 1970-01-01T00:00:00Z | 74 | 435 | 272.25 | | time | integral_hum | integral_temp | | --- | --- | --- | | time | integral_hum | integral_temp | | 1970-01-01T00:00:00Z | 435 | 272.25 | | time | integral | | --- | --- | | time | integral | | 2022-01-01T06:00:00Z | 0 | | 2022-01-01T12:00:00Z | 30 | | 2022-01-01T18:00:00Z | 44 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 22.396153846153844 | | time | mean_co | mean_hum | mean_temp | | --- | --- | --- | --- | | time | mean_co | mean_hum | mean_temp | | 1970-01-01T00:00:00Z | 5.269230769230769 | 36.15 | 22.396153846153844 | | time | mean_hum | mean_temp | | --- | --- | --- | | time | mean_hum | mean_temp | | 1970-01-01T00:00:00Z | 36.15 | 22.396153846153844 | | time | mean | | --- | --- | | time | mean | | 2022-01-01T06:00:00Z | 22.275 | | 2022-01-01T12:00:00Z | 22.649999999999995 | | 2022-01-01T18:00:00Z | 23.033333333333335 | | time | median | | --- | --- | | time | median | | 1970-01-01T00:00:00Z | 22.45 | | time | median_co | median_hum | median_temp | | --- | --- | --- | --- | | time | median_co | median_hum | median_temp | | 1970-01-01T00:00:00Z | 1 | 36.05 | 22.45 | | time | median_hum | median_temp | | --- | --- | --- | | time | median_hum | median_temp | | 1970-01-01T00:00:00Z | 36.05 | 22.45 | | time | median | | --- | --- | | time | median | | 2022-01-01T06:00:00Z | 22.549999999999997 | | 2022-01-01T12:00:00Z | 22.7 | | 2022-01-01T18:00:00Z | 23.1 | | time | mode | | --- | --- | | time | mode | | 1970-01-01T00:00:00Z | 0 | | time | mode_co | mode_hum | mode_temp | | --- | --- | --- | --- | | time | mode_co | mode_hum | mode_temp | | 1970-01-01T00:00:00Z | 0 | 36 | 22.7 | | time | mode_hum | mode_temp | | --- | --- | --- | | time | mode_hum | mode_temp | | 1970-01-01T00:00:00Z | 36 | 22.7 | | time | mode | | --- | --- | | time | mode | | 2022-01-01T06:00:00Z | 0 | | 2022-01-01T12:00:00Z | 1 | | 2022-01-01T18:00:00Z | 18 | | time | spread | | --- | --- | | time | spread | | 1970-01-01T00:00:00Z | 2.3000000000000007 | | time | spread_co | spread_hum | spread_temp | | --- | --- | --- | --- | | time | spread_co | spread_hum | spread_temp | | 1970-01-01T00:00:00Z | 26 | 1 | 2.3000000000000007 | | time | spread_hum | spread_temp | | --- | --- | --- | | time | spread_hum | spread_temp | | 1970-01-01T00:00:00Z | 1 | 2.3000000000000007 | | time | spread | | --- | --- | | time | spread | | 2022-01-01T06:00:00Z | 0 | | 2022-01-01T12:00:00Z | 9 | | 2022-01-01T18:00:00Z | 8 | | time | stddev | | --- | --- | | time | stddev | | 1970-01-01T00:00:00Z | 0.5553238833191091 | | time | stddev_co | stddev_hum | stddev_temp | | --- | --- | --- | --- | | time | stddev_co | stddev_hum | stddev_temp | | 1970-01-01T00:00:00Z | 7.774613519951676 | 0.25495097567963926 | 0.5553238833191091 | | time | stddev_hum | stddev_temp | | --- | --- | --- | | time | stddev_hum | stddev_temp | | 1970-01-01T00:00:00Z | 0.25495097567963926 | 0.5553238833191091 | | time | stddev | | --- | --- | | time | stddev | | 2022-01-01T06:00:00Z | 0 | | 2022-01-01T12:00:00Z | 3.6742346141747673 | | 2022-01-01T18:00:00Z | 4 | | time | sum | | --- | --- | | time | sum | | 1970-01-01T00:00:00Z | 137 | | time | sum_co | sum_hum | sum_temp | | --- | --- | --- | --- | | time | sum_co | sum_hum | sum_temp | | 1970-01-01T00:00:00Z | 137 | 939.9 | 582.3 | | time | sum_hum | sum_temp | | --- | --- | --- | | time | sum_hum | sum_temp | | 1970-01-01T00:00:00Z | 939.9 | 582.3 | | time | sum | | --- | --- | | time | sum | | 2022-01-01T06:00:00Z | 0 | | 2022-01-01T12:00:00Z | 21 | | 2022-01-01T18:00:00Z | 66 | --- # InfluxQL date and time functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/date-time/ Use InfluxQL date and time functions to perform time-related operations. * [now()](#now) * [time()](#time) * [tz()](#tz) ## now() Returns the current system time (UTC).*Supported only in the [`WHERE` clause](/influxdb3/core/reference/influxql/where/).* ```sql now() ``` ## time() Used in the [`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/)to group data into time-based intervals, also known as “windows”, using the specified interval. Timestamps in the `time` column are updated to the start boundary of the window they’re in and grouped by `time`. Windows use preset round-number boundaries based on the specified interval that are independent of time conditions in the[`WHERE` clause](/influxdb3/core/reference/influxql/where/). This operation can be used to do the following: * Downsample data by aggregating multiple points in each window into a single point per window. * Normalize irregular time series data to occur at regular intervals. *Supported only in the [`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/).* ```sql time(interval[, offset]) ``` #### Arguments * **interval**: Duration literal that specifies the window interval. * **offset**: Duration literal that shifts preset time boundaries forward or backward. Can be positive or negative. *Default is `0s`.* ##### Examples [](#downsample-data-into-time-based-intervals) Downsample data into time-based intervals The following example uses the[Bitcoin price sample dataset](/influxdb3/core/reference/sample-data/#bitcoin-price-data). ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'GBP' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-15T00:00:00Z' GROUP BY time(2d) ``` name: bitcoin | time | mean | |--------------------|------------------| |2023-05-01T00:00:00Z|23680.120447159094| |2023-05-03T00:00:00Z|24048.71484033149 | |2023-05-05T00:00:00Z| 24461.9194901099 | |2023-05-07T00:00:00Z|23796.43801933702 | |2023-05-09T00:00:00Z|23118.709889285707| |2023-05-11T00:00:00Z|22465.008364444446| |2023-05-13T00:00:00Z|22499.464763186803| ## tz() Applies a timezone offset to timestamps in query results. Offsets include any seasonal offset such as Daylight Savings Time (DST) or British Summer Time (BST).*Supported only in the [time zone clause](/influxdb3/core/reference/influxql/time-and-timezone/#time-zone-clause).* ```sql tz(time_zone) ``` #### Arguments * **time\_zone**: Timezone string literal to adjust times to. Uses timezone names defined in the[Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). #### Examples [](#return-the-utc-offset-for-chicagos-time-zone) Return the UTC offset for Chicago’s time zone The following example uses the[Home sensor sample dataset](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' tz('America/Chicago') ``` name: home | time |co |hum | room |temp| |-------------------------|---|----|-------|----| |2022-01-01T02:00:00-06:00| 0 |35.9|Kitchen| 21 | |2022-01-01T03:00:00-06:00| 0 |36.2|Kitchen| 23 | |2022-01-01T04:00:00-06:00| 0 |36.1|Kitchen|22.7| |2022-01-01T05:00:00-06:00| 0 | 36 |Kitchen|22.4| |2022-01-01T06:00:00-06:00| 0 | 36 |Kitchen|22.5| | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 23680.120447159094 | | 2023-05-03T00:00:00Z | 24048.71484033149 | | 2023-05-05T00:00:00Z | 24461.9194901099 | | 2023-05-07T00:00:00Z | 23796.43801933702 | | 2023-05-09T00:00:00Z | 23118.709889285707 | | 2023-05-11T00:00:00Z | 22465.008364444446 | | 2023-05-13T00:00:00Z | 22499.464763186803 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T02:00:00-06:00 | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T03:00:00-06:00 | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T04:00:00-06:00 | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T05:00:00-06:00 | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T06:00:00-06:00 | 0 | 36 | Kitchen | 22.5 | --- # InfluxQL miscellaneous functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/misc/ Use InfluxQL miscellaneous functions to perform different operations in InfluxQL queries. * [fill()](#fill) ## fill() Fills *null* field values returned from empty time windows in `GROUP BY time()`queries with a specified fill value. *Supported only in the [`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/).* ```sql fill(behavior) ``` #### Arguments * **behavior**: Defines the behavior of the fill operation. If no `FILL` clause is included, the default behavior is `fill(null)`. The following options are available: * **numeric literal**: Replaces null values with the specified numeric literal. * **linear**: Uses linear interpolation between existing values to replace null values. * **none**: Removes rows with null field values. * **null**: Keeps null values and associated timestamps. * **previous**: Replaces null values with the most recent non-null value. #### Examples The following example uses the[Bitcoin price sample dataset](/influxdb3/core/reference/sample-data/#bitcoin-price-data). #### fill(numeric\_literal) #### ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(0) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z| 0 | |2023-05-01T01:30:00Z|29263.2886| ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(linear) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z|29285.3651| |2023-05-01T01:30:00Z|29263.2886| ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(none) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:30:00Z|29263.2886| ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(null) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z| | |2023-05-01T01:30:00Z|29263.2886| ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(previous) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z|29307.4416| |2023-05-01T01:30:00Z|29263.2886| | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 0 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 29285.3651 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 29307.4416 | | 2023-05-01T01:30:00Z | 29263.2886 | --- # InfluxQL selector functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/selectors/ Use selector functions to assess, select, and return values in your data. Selector functions return one or more rows with the selected values from each InfluxQL group. *Examples use the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* * [BOTTOM()](#bottom) * [FIRST()](#first) * [LAST()](#last) * [MAX()](#max) * [MIN()](#min) * [PERCENTILE()](#percentile) * [TOP()](#top) * [Notable behaviors of selector functions](#notable-behaviors-of-selector-functions) > [!Important] > #### Missing InfluxQL functions > > Some InfluxQL functions are in the process of being rearchitected to work with > the InfluxDB 3 storage engine. If a function you need is not here, check the[InfluxQL feature support page](/influxdb3/core/reference/influxql/feature-support/#function-support)for more information. ## BOTTOM() Returns the smallest `N` [field values](/influxdb3/core/reference/glossary/#field-value).`BOTTOM()` supports int64 and float64 field value [data types](/influxdb3/core/reference/glossary/#field-value). ```sql BOTTOM(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) ``` > [!Note] > **Note:** `BOTTOM()` returns the field value with the earliest timestamp if > there’s a tie between two or more values for the smallest value. #### Arguments * **field\_expression**: Expression to identify the field to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key)or constant. * **tag\_expression**: Expression to identify a tag key to segment by. Can be a [tag key](/influxdb3/core/reference/glossary/#tag-key)or constant. Comma-delimit multiple tags. * **N**: Number of results to return from each InfluxQL group or specified tag segment. #### Notable behaviors * `BOTTOM()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). * `BOTTOM()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). #### Examples [](#select-the-bottom-three-values-of-a-field) Select the bottom three values of a field ```sql SELECT BOTTOM(temp, 3) FROM home ``` name: home | time |bottom| |--------------------|------| |2022-01-01T08:00:00Z| 21 | |2022-01-01T08:00:00Z| 21.1 | |2022-01-01T09:00:00Z| 21.4 | [](#select-the-bottom-field-value-for-two-unique-tag-values) Select the bottom field value for two unique tag values ```sql SELECT BOTTOM(temp, room, 2) FROM home ``` name: home | time |bottom| room | |--------------------|------|-----------| |2022-01-01T08:00:00Z| 21 | Kitchen | |2022-01-01T08:00:00Z| 21.1 |Living Room| [](#select-the-bottom-three-field-values-and-the-tag-value-associated-with-each) Select the bottom three field values and the tag value associated with each ```sql SELECT BOTTOM(temp, 3), room FROM home ``` name: home | time |bottom| room | |--------------------|------|-----------| |2022-01-01T08:00:00Z| 21 | Kitchen | |2022-01-01T08:00:00Z| 21.1 |Living Room| |2022-01-01T09:00:00Z| 21.4 |Living Room| [](#select-the-bottom-field-values-for-unique-tag-values-and-within-time-windows-grouped-by-time) Select the bottom field values for unique tag values and within time windows (grouped by time) ```sql SELECT BOTTOM(temp, room, 2) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' GROUP BY time(2h) ``` name: home | time |bottom| room | |--------------------|------|-----------| |2022-01-01T08:00:00Z| 21 | Kitchen | |2022-01-01T08:00:00Z| 21.1 |Living Room| |2022-01-01T10:00:00Z| 21.8 |Living Room| |2022-01-01T11:00:00Z| 22.4 | Kitchen | |2022-01-01T12:00:00Z| 22.2 |Living Room| |2022-01-01T12:00:00Z| 22.5 | Kitchen | Notice that when grouping by time, `BOTTOM()`[maintains the point’s original timestamp](#timestamps-when-grouping-by-time). ## FIRST() Returns the [field value](/influxdb3/core/reference/glossary/#field-value) with the oldest timestamp. ```sql FIRST(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Notable behaviors * `FIRST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) #### Examples [](#select-the-first-value-for-a-field) Select the first value for a field ```sql SELECT FIRST(temp) FROM home ``` name: home | time |first| |--------------------|-----| |2022-01-01T08:00:00Z|21.1 | [](#select-the-first-value-from-each-field) Select the first value from each field ```sql SELECT FIRST(*) FROM home ``` name: home | time |first\_co|first\_hum|first\_temp| |--------------------|---------|----------|-----------| |1970-01-01T00:00:00Z| 0 | 35.9 | 21.1 | [](#select-the-first-value-from-field-keys-that-match-a-regular-expression) Select the first value from field keys that match a regular expression ```sql SELECT FIRST(/^[th]/) FROM home ``` name: home | time |first\_hum|first\_temp| |--------------------|----------|-----------| |1970-01-01T00:00:00Z| 35.9 | 21.1 | [](#select-the-first-value-from-a-field-within-time-windows-grouped-by-time) Select the first value from a field within time windows (grouped by time) ``` SELECT FIRST(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |first| |--------------------|-----| |2022-01-01T06:00:00Z| 21 | |2022-01-01T12:00:00Z|22.5 | |2022-01-01T18:00:00Z|23.3 | Notice that when grouping by time, `FIRST()`[overrides the point’s original timestamp](#timestamps-when-grouping-by-time). ## LAST() Returns the [field value](/influxdb3/core/reference/glossary/#field-value) with the most recent timestamp. ```sql LAST(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Notable behaviors * `LAST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) #### Examples [](#select-the-last-value-for-a-field) Select the last value for a field ```sql SELECT LAST(temp) FROM home ``` name: home | time |last| |--------------------|----| |2022-01-01T20:00:00Z|22.7| [](#select-the-last-value-from-each-field) Select the last value from each field ```sql SELECT LAST(*) FROM home ``` name: home | time |last\_co|last\_hum|last\_temp| |--------------------|--------|---------|----------| |1970-01-01T00:00:00Z| 26 | 36.5 | 22.7 | [](#select-the-last-value-from-field-keys-that-match-a-regular-expression) Select the last value from field keys that match a regular expression ```sql SELECT LAST(/^[th]/) FROM home ``` name: home | time |last\_hum|last\_temp| |--------------------|---------|----------| |1970-01-01T00:00:00Z| 36.5 | 22.7 | [](#select-the-last-value-from-a-field-within-time-windows-grouped-by-time) Select the last value from a field within time windows (grouped by time) ``` SELECT LAST(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |last| |--------------------|----| |2022-01-01T06:00:00Z|22.4| |2022-01-01T12:00:00Z|22.7| |2022-01-01T18:00:00Z|22.7| Notice that when grouping by time, `LAST()`[overrides the point’s original timestamp](#timestamps-when-grouping-by-time). ## MAX() Returns the greatest [field value](/influxdb3/core/reference/glossary/#field-value). ```sql MAX(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Notable behaviors * `MAX()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). #### Examples [](#select-the-maximum-value-from-a-field) Select the maximum value from a field ```sql SELECT MAX(co) FROM home ``` name: home | time |max| |--------------------|---| |2022-01-01T20:00:00Z|26 | [](#select-the-maximum-value-from-each-field) Select the maximum value from each field ```sql SELECT MAX(*) FROM home ``` name: home | time |max\_co|max\_hum|max\_temp| |--------------------|-------|--------|---------| |1970-01-01T00:00:00Z| 26 | 36.9 | 23.3 | [](#select-the-maximum-value-from-field-keys-that-match-a-regular-expression) Select the maximum value from field keys that match a regular expression ```sql SELECT MAX(/^[th]/) FROM home ``` name: home | time |max\_hum|max\_temp| |--------------------|--------|---------| |1970-01-01T00:00:00Z| 36.9 | 23.3 | [](#select-the-maximum-value-from-a-field-within-time-windows-grouped-by-time) Select the maximum value from a field within time windows (grouped by time) ```sql SELECT MAX(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |max | |--------------------|----| |2022-01-01T06:00:00Z| 23 | |2022-01-01T12:00:00Z|22.8| |2022-01-01T18:00:00Z|23.3| Notice that when grouping by time, `MAX()`[overrides the point’s original timestamp](#timestamps-when-grouping-by-time). ## MIN() Returns the lowest [field value](/influxdb3/core/reference/glossary/#field-value). ```sql MIN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. #### Notable behaviors * `MIN()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). #### Examples [](#select-the-minimum-value-from-a-field) Select the minimum value from a field ```sql SELECT MIN(temp) FROM home ``` name: home | time |min| |--------------------|---| |2022-01-01T08:00:00Z|21 | [](#select-the-minimum-value-from-each-field) Select the minimum value from each field ```sql SELECT MIN(*) FROM home ``` name: home | time |min\_co|min\_hum|min\_temp| |--------------------|-------|--------|---------| |1970-01-01T00:00:00Z| 0 | 35.9 | 21 | [](#select-the-minimum-value-from-field-keys-that-match-a-regular-expression) Select the minimum value from field keys that match a regular expression ```sql SELECT MIN(/^[th]/) FROM home ``` name: home | time |min\_hum|min\_temp| |--------------------|--------|---------| |1970-01-01T00:00:00Z| 35.9 | 21 | [](#select-the-minimum-value-from-a-field-within-time-windows-grouped-by-time) Select the minimum value from a field within time windows (grouped by time) ```sql SELECT MIN(temp) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |min | |--------------------|----| |2022-01-01T06:00:00Z| 21 | |2022-01-01T12:00:00Z|22.4| |2022-01-01T18:00:00Z|22.7| Notice that when grouping by time, `MIN()`[overrides the point’s original timestamp](#timestamps-when-grouping-by-time). ## PERCENTILE() Returns the `N`th percentile [field value](/influxdb3/core/reference/glossary/#field-value). ```sql PERCENTILE(field_expression, N) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports **numeric fields**. * **N**: Percentile to return. Must be an integer or float value **greater than 0 and less than or equal to 100**. #### Notable behaviors * `PERCENTILE()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). * `PERCENTILE(example_field, 100)` is equivalent to [`MAX(example_field)`](#max). * `PERCENTILE(example_field, 50)` is nearly equivalent to[`MEDIAN(example_field)`](/influxdb3/core/reference/influxql/functions/aggregates/#median), except `MEDIAN()` returns the average of the two middle values if the field contains an even number of values. * `PERCENTILE(example_field, 0)` returns *null*. #### Examples [](#select-the-50th-percentile-value-from-a-field) Select the 50th percentile value from a field ```sql SELECT PERCENTILE(temp, 50) FROM home ``` name: home | time |percentile| |--------------------|----------| |2022-01-01T11:00:00Z| 22.4 | [](#select-the-50th-percentile-value-from-each-field) Select the 50th percentile value from each field ```sql SELECT PERCENTILE(*, 50) FROM home ``` name: home | time |percentile\_co|percentile\_hum|percentile\_temp| |--------------------|--------------|---------------|----------------| |1970-01-01T00:00:00Z| 1 | 36 | 22.4 | [](#select-the-50th-percentile-value-from-field-keys-that-match-a-regular-expression) Select the 50th percentile value from field keys that match a regular expression ```sql SELECT PERCENTILE(/^[th]/, 50) FROM home ``` name: home | time |percentile\_hum|percentile\_temp| |--------------------|---------------|----------------| |1970-01-01T00:00:00Z| 36 | 22.4 | [](#select-the-50th-percentile-value-from-a-field-within-time-windows-grouped-by-time) Select the 50th percentile value from a field within time windows (grouped by time) ```sql SELECT PERCENTILE(temp, 50) FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY time(6h) ``` name: home | time |percentile| |--------------------|----------| |2022-01-01T06:00:00Z| 22.4 | |2022-01-01T12:00:00Z| 22.7 | |2022-01-01T18:00:00Z| 23.1 | Notice that when grouping by time, `PERCENTILE()`[overrides the point’s original timestamp](#timestamps-when-grouping-by-time). ## TOP() Returns the greatest `N` [field values](/influxdb3/core/reference/glossary/#field-value).`TOP()` supports int64 and float64 field value [data types](/influxdb3/core/reference/glossary/#field-value). ```sql TOP(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) ``` > [!Note] > **Note:** `TOP()` returns the field value with the earliest timestamp if there’s > a tie between two or more values for the greatest value. #### Arguments * **field\_expression**: Expression to identify the field to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key)or constant. * **tag\_expression**: Expression to identify a tag key to segment by. Can be a [tag key](/influxdb3/core/reference/glossary/#tag-key)or constant. Comma-delimit multiple tags. * **N**: Number of results to return from each InfluxQL group or specified tag segment. #### Notable behaviors * `TOP()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). * `TOP()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). #### Examples [](#select-the-top-three-values-of-a-field) Select the top three values of a field ```sql SELECT TOP(temp, 3) FROM home ``` name: home | time |top | |--------------------|----| |2022-01-01T09:00:00Z| 23 | |2022-01-01T18:00:00Z|23.3| |2022-01-01T19:00:00Z|23.1| [](#select-the-top-field-value-for-two-unique-tag-values) Select the top field value for two unique tag values ```sql SELECT TOP(temp, room, 2) FROM home ``` name: home | time |top | room | |--------------------|----|-----------| |2022-01-01T18:00:00Z|23.3| Kitchen | |2022-01-01T18:00:00Z|22.8|Living Room| [](#select-the-top-three-field-values-and-the-tag-value-associated-with-each) Select the top three field values and the tag value associated with each ```sql SELECT TOP(temp, 3), room FROM home ``` name: home | time |top | room | |--------------------|----|-------| |2022-01-01T09:00:00Z| 23 |Kitchen| |2022-01-01T18:00:00Z|23.3|Kitchen| |2022-01-01T19:00:00Z|23.1|Kitchen| [](#select-the-top-field-values-for-unique-tag-values-and-within-time-windows-grouped-by-time) Select the top field values for unique tag values and within time windows (grouped by time) ```sql SELECT TOP(temp, room, 2) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' GROUP BY time(2h) ``` name: home | time |top | room | |--------------------|----|-----------| |2022-01-01T09:00:00Z| 23 | Kitchen | |2022-01-01T09:00:00Z|21.4|Living Room| |2022-01-01T10:00:00Z|22.7| Kitchen | |2022-01-01T11:00:00Z|22.2|Living Room| |2022-01-01T12:00:00Z|22.5| Kitchen | |2022-01-01T12:00:00Z|22.2|Living Room| Notice that when grouping by time, `TOP()`[maintains the point’s original timestamp](#timestamps-when-grouping-by-time). ## Notable behaviors of selector functions * [Timestamps when grouping by time](#timestamps-when-grouping-by-time) * [Selector functions may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected) ### Timestamps when grouping by time When using selector functions with a `GROUP BY time()` clause, most selector functions return the timestamp of the starting boundary for each time interval. However functions with an `N` argument that specifies the number of results to return per group maintain the original timestamp of each returned point. ###### Return the start time of each time interval * [FIRST()](#first) * [LAST()](#last) * [MAX()](#max) * [MIN()](#min) * [PERCENTILE()](#percentile) ###### Maintain the original timestamp * [BOTTOM()](#bottom) * [TOP()](#top) ### Selector functions may return fewer points than expected Queries that use the following selector functions with an `N` argument may return fewer points than expected. * [BOTTOM()](#bottom) * [TOP()](#top) If the InfluxQL group or specified tag key contains `X` points or unique tag values and `X` is less than `N`, the function returns `X` results instead of `N`for each group or tag value. [](#view-example-for-fnfield_key-n) View example for `FN(field_key, N)` The example below selects the bottom 5 temperatures from the Kitchen between2022-01-01T08:00:00Zand 2022-01-01T10:00:00Z. There are only 3 points recorded for the Kitchen during the queried time range, so the query returns 3 points instead of 5. ```sql SELECT BOTTOM(temp, 5) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' AND room = 'Kitchen' ``` | time |bottom| |--------------------|------| |2022-01-01T08:00:00Z| 21 | |2022-01-01T09:00:00Z| 23 | |2022-01-01T10:00:00Z| 22.7 | [](#view-example-for-fnfield_key-tag_key-n) View example for `FN(field_key, tag_key, N)` The example below selects the top temperature from 3 unique values of the `room` tag. However, the `room` tag only has 2 unique values, so results only contain 2 values. ```sql SELECT TOP(temp, room, 3) FROM home ``` | time |top | room | |--------------------|----|-----------| |2022-01-01T18:00:00Z|23.3| Kitchen | |2022-01-01T18:00:00Z|22.8|Living Room| #### Related * [Aggregate data with InfluxQL](/influxdb3/core/query-data/influxql/aggregate-select/) | time | bottom | | --- | --- | | time | bottom | | 2022-01-01T08:00:00Z | 21 | | 2022-01-01T08:00:00Z | 21.1 | | 2022-01-01T09:00:00Z | 21.4 | | time | bottom | room | | --- | --- | --- | | time | bottom | room | | 2022-01-01T08:00:00Z | 21 | Kitchen | | 2022-01-01T08:00:00Z | 21.1 | Living Room | | time | bottom | room | | --- | --- | --- | | time | bottom | room | | 2022-01-01T08:00:00Z | 21 | Kitchen | | 2022-01-01T08:00:00Z | 21.1 | Living Room | | 2022-01-01T09:00:00Z | 21.4 | Living Room | | time | bottom | room | | --- | --- | --- | | time | bottom | room | | 2022-01-01T08:00:00Z | 21 | Kitchen | | 2022-01-01T08:00:00Z | 21.1 | Living Room | | 2022-01-01T10:00:00Z | 21.8 | Living Room | | 2022-01-01T11:00:00Z | 22.4 | Kitchen | | 2022-01-01T12:00:00Z | 22.2 | Living Room | | 2022-01-01T12:00:00Z | 22.5 | Kitchen | | time | first | | --- | --- | | time | first | | 2022-01-01T08:00:00Z | 21.1 | | time | first_co | first_hum | first_temp | | --- | --- | --- | --- | | time | first_co | first_hum | first_temp | | 1970-01-01T00:00:00Z | 0 | 35.9 | 21.1 | | time | first_hum | first_temp | | --- | --- | --- | | time | first_hum | first_temp | | 1970-01-01T00:00:00Z | 35.9 | 21.1 | | time | first | | --- | --- | | time | first | | 2022-01-01T06:00:00Z | 21 | | 2022-01-01T12:00:00Z | 22.5 | | 2022-01-01T18:00:00Z | 23.3 | | time | last | | --- | --- | | time | last | | 2022-01-01T20:00:00Z | 22.7 | | time | last_co | last_hum | last_temp | | --- | --- | --- | --- | | time | last_co | last_hum | last_temp | | 1970-01-01T00:00:00Z | 26 | 36.5 | 22.7 | | time | last_hum | last_temp | | --- | --- | --- | | time | last_hum | last_temp | | 1970-01-01T00:00:00Z | 36.5 | 22.7 | | time | last | | --- | --- | | time | last | | 2022-01-01T06:00:00Z | 22.4 | | 2022-01-01T12:00:00Z | 22.7 | | 2022-01-01T18:00:00Z | 22.7 | | time | max | | --- | --- | | time | max | | 2022-01-01T20:00:00Z | 26 | | time | max_co | max_hum | max_temp | | --- | --- | --- | --- | | time | max_co | max_hum | max_temp | | 1970-01-01T00:00:00Z | 26 | 36.9 | 23.3 | | time | max_hum | max_temp | | --- | --- | --- | | time | max_hum | max_temp | | 1970-01-01T00:00:00Z | 36.9 | 23.3 | | time | max | | --- | --- | | time | max | | 2022-01-01T06:00:00Z | 23 | | 2022-01-01T12:00:00Z | 22.8 | | 2022-01-01T18:00:00Z | 23.3 | | time | min | | --- | --- | | time | min | | 2022-01-01T08:00:00Z | 21 | | time | min_co | min_hum | min_temp | | --- | --- | --- | --- | | time | min_co | min_hum | min_temp | | 1970-01-01T00:00:00Z | 0 | 35.9 | 21 | | time | min_hum | min_temp | | --- | --- | --- | | time | min_hum | min_temp | | 1970-01-01T00:00:00Z | 35.9 | 21 | | time | min | | --- | --- | | time | min | | 2022-01-01T06:00:00Z | 21 | | 2022-01-01T12:00:00Z | 22.4 | | 2022-01-01T18:00:00Z | 22.7 | | time | percentile | | --- | --- | | time | percentile | | 2022-01-01T11:00:00Z | 22.4 | | time | percentile_co | percentile_hum | percentile_temp | | --- | --- | --- | --- | | time | percentile_co | percentile_hum | percentile_temp | | 1970-01-01T00:00:00Z | 1 | 36 | 22.4 | | time | percentile_hum | percentile_temp | | --- | --- | --- | | time | percentile_hum | percentile_temp | | 1970-01-01T00:00:00Z | 36 | 22.4 | | time | percentile | | --- | --- | | time | percentile | | 2022-01-01T06:00:00Z | 22.4 | | 2022-01-01T12:00:00Z | 22.7 | | 2022-01-01T18:00:00Z | 23.1 | | time | top | | --- | --- | | time | top | | 2022-01-01T09:00:00Z | 23 | | 2022-01-01T18:00:00Z | 23.3 | | 2022-01-01T19:00:00Z | 23.1 | | time | top | room | | --- | --- | --- | | time | top | room | | 2022-01-01T18:00:00Z | 23.3 | Kitchen | | 2022-01-01T18:00:00Z | 22.8 | Living Room | | time | top | room | | --- | --- | --- | | time | top | room | | 2022-01-01T09:00:00Z | 23 | Kitchen | | 2022-01-01T18:00:00Z | 23.3 | Kitchen | | 2022-01-01T19:00:00Z | 23.1 | Kitchen | | time | top | room | | --- | --- | --- | | time | top | room | | 2022-01-01T09:00:00Z | 23 | Kitchen | | 2022-01-01T09:00:00Z | 21.4 | Living Room | | 2022-01-01T10:00:00Z | 22.7 | Kitchen | | 2022-01-01T11:00:00Z | 22.2 | Living Room | | 2022-01-01T12:00:00Z | 22.5 | Kitchen | | 2022-01-01T12:00:00Z | 22.2 | Living Room | | time | bottom | | --- | --- | | time | bottom | | 2022-01-01T08:00:00Z | 21 | | 2022-01-01T09:00:00Z | 23 | | 2022-01-01T10:00:00Z | 22.7 | | time | top | room | | --- | --- | --- | | time | top | room | | 2022-01-01T18:00:00Z | 23.3 | Kitchen | | 2022-01-01T18:00:00Z | 22.8 | Living Room | --- # InfluxQL transformation functions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/functions/transformations/ InfluxQL transformation functions modify and return values in each row of queried data. * [ABS()](#abs) * [ACOS()](#acos) * [ASIN()](#asin) * [ATAN()](#atan) * [ATAN2()](#atan2) * [CEIL()](#ceil) * [COS()](#cos) * [CUMULATIVE\_SUM()](#cumulative_sum) * [DERIVATIVE()](#derivative) * [DIFFERENCE()](#difference) * [ELAPSED()](#elapsed) * [EXP()](#exp) * [FLOOR()](#floor) * [LN()](#ln) * [LOG()](#log) * [LOG2()](#log2) * [LOG10()](#log10) * [MOVING\_AVERAGE()](#moving_average) * [NON\_NEGATIVE\_DERIVATIVE()](#non_negative_derivative) * [NON\_NEGATIVE\_DIFFERENCE()](#non_negative_difference) * [POW()](#pow) * [ROUND()](#round) * [SIN()](#sin) * [SQRT()](#sqrt) * [TAN()](#tan) > [!Important] > #### Missing InfluxQL functions > > Some InfluxQL functions are in the process of being rearchitected to work with > the InfluxDB 3 storage engine. If a function you need is not here, check the[InfluxQL feature support page](/influxdb3/core/reference/influxql/feature-support/#function-support)for more information. ## Notable behaviors of transformation functions #### Must use aggregate or selector functions when grouping by time Most transformation functions support `GROUP BY` clauses that group by tags, but do not directly support `GROUP BY` clauses that group by time. To use transformation functions with with a `GROUP BY time()` clause, apply an [aggregate](/influxdb3/core/reference/influxql/functions/aggregates/)or [selector](/influxdb3/core/reference/influxql/functions/selectors/)function to the **field\_expression** argument. The transformation operates on the result of the aggregate or selector operation. ## ABS() Returns the absolute value of the field value. ```sql ABS(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-abs-to-a-field) Apply `ABS()` to a field ```sql SELECT a, ABS(a) FROM numbers LIMIT 6 ``` name: numbers | time | a | abs | |--------------------|-------------------|-----------------| |2023-01-01T00:00:00Z| 0.33909108671076 |0.33909108671076 | |2023-01-01T00:01:00Z|\-0.774984088561186|0.774984088561186| |2023-01-01T00:02:00Z|\-0.921037167720451|0.921037167720451| |2023-01-01T00:03:00Z|\-0.73880754843378 |0.73880754843378 | |2023-01-01T00:04:00Z|\-0.905980032168252|0.905980032168252| |2023-01-01T00:05:00Z|\-0.891164752631417|0.891164752631417| [](#apply-abs-to-each-field) Apply `ABS()` to each field ```sql SELECT ABS(*) FROM numbers LIMIT 6 ``` name: numbers | time | abs\_a | abs\_b | |--------------------|-----------------|------------------| |2023-01-01T00:00:00Z|0.33909108671076 |0.163643058925645 | |2023-01-01T00:01:00Z|0.774984088561186|0.137034364053949 | |2023-01-01T00:02:00Z|0.921037167720451|0.482943221384294 | |2023-01-01T00:03:00Z|0.73880754843378 |0.0729732928756677| |2023-01-01T00:04:00Z|0.905980032168252| 1.77857552719844 | |2023-01-01T00:05:00Z|0.891164752631417|0.741147445214238 | [](#apply-abs-to-time-windows-grouped-by-time) Apply `ABS()` to time windows (grouped by time) ```sql SELECT ABS(MEAN(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | abs | |--------------------|--------------------| |2023-01-01T00:00:00Z| 0.4345725888930678 | |2023-01-01T00:10:00Z|0.12861008519618367 | |2023-01-01T00:20:00Z|0.030168160597251192| |2023-01-01T00:30:00Z|0.02928699660831855 | |2023-01-01T00:40:00Z|0.02211434600834538 | |2023-01-01T00:50:00Z|0.15530468657783394 | ## ACOS() Returns the arccosine (in radians) of the field value. Field values must be between -1 and 1. ```sql ACOS(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-acos-to-a-field) Apply `ACOS()` to a field ```sql SELECT a, ACOS(a) FROM numbers LIMIT 6 ``` name: numbers | time | a | acos | |--------------------|-------------------|------------------| |2023-01-01T00:00:00Z| 0.33909108671076 |1.2248457522250173| |2023-01-01T00:01:00Z|\-0.774984088561186| 2.4574862443115 | |2023-01-01T00:02:00Z|\-0.921037167720451|2.741531473732281 | |2023-01-01T00:03:00Z|\-0.73880754843378 |2.4020955294179256| |2023-01-01T00:04:00Z|\-0.905980032168252|2.7044854502651114| |2023-01-01T00:05:00Z|\-0.891164752631417| 2.6707024029338 | [](#apply-acos-to-each-field) Apply `ACOS()` to each field ```sql SELECT ACOS(*) FROM numbers LIMIT 6 ``` name: numbers | time | acos\_a | acos\_b | |--------------------|------------------|------------------| |2023-01-01T00:00:00Z|1.2248457522250173|1.7351786975993897| |2023-01-01T00:01:00Z| 2.4574862443115 |1.433329416131427 | |2023-01-01T00:02:00Z|2.741531473732281 |2.074809114132046 | |2023-01-01T00:03:00Z|2.4020955294179256|1.6438345403920092| |2023-01-01T00:04:00Z|2.7044854502651114| | |2023-01-01T00:05:00Z| 2.6707024029338 |0.7360183965088304| [](#apply-acos-to-time-windows-grouped-by-time) Apply `ACOS()` to time windows (grouped by time) ```sql SELECT ACOS(MEAN(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | acos | |--------------------|------------------| |2023-01-01T00:00:00Z|2.0203599837582877| |2023-01-01T00:10:00Z|1.441829029328407 | |2023-01-01T00:20:00Z|1.5406235882252437| |2023-01-01T00:30:00Z|1.5415051418561052| |2023-01-01T00:40:00Z|1.5486801779072885| |2023-01-01T00:50:00Z| 1.41486045205998 | ## ASIN() Returns the arcsine (in radians) of the field value. Field values must be between -1 and 1. ```sql ASIN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-asin-to-a-field) Apply `ASIN()` to a field ```sql SELECT a, ASIN(a) FROM numbers LIMIT 6 ``` name: numbers | time | a | asin | |--------------------|-------------------|--------------------| |2023-01-01T00:00:00Z| 0.33909108671076 |0.34595057456987915 | |2023-01-01T00:01:00Z|\-0.774984088561186|\-0.8866899175166036| |2023-01-01T00:02:00Z|\-0.921037167720451|\-1.1707351469373848| |2023-01-01T00:03:00Z|\-0.73880754843378 |\-0.8312992026230288| |2023-01-01T00:04:00Z|\-0.905980032168252|\-1.133689123470215 | |2023-01-01T00:05:00Z|\-0.891164752631417|\-1.0999060761389035| [](#apply-asin-to-each-field) Apply `ASIN()` to each field ```sql SELECT ASIN(*) FROM numbers LIMIT 6 ``` name: numbers | time | asin\_a | asin\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z|0.34595057456987915 |\-0.1643823708044932 | |2023-01-01T00:01:00Z|\-0.8866899175166036| 0.1374669106634696 | |2023-01-01T00:02:00Z|\-1.1707351469373848|\-0.5040127873371497 | |2023-01-01T00:03:00Z|\-0.8312992026230288|\-0.07303821359711259| |2023-01-01T00:04:00Z|\-1.133689123470215 | | |2023-01-01T00:05:00Z|\-1.0999060761389035| 0.8347779302860662 | [](#apply-asin-to-time-windows-grouped-by-time) Apply `ASIN()` to time windows (grouped by time) ```sql SELECT ASIN(MEAN(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | asin | |--------------------|---------------------| |2023-01-01T00:00:00Z|\-0.44956365696339134| |2023-01-01T00:10:00Z| 0.1289672974664895 | |2023-01-01T00:20:00Z|0.030172738569652847 | |2023-01-01T00:30:00Z|0.029291184938791334 | |2023-01-01T00:40:00Z|0.022116148887608062 | |2023-01-01T00:50:00Z| 0.15593587473491674 | ## ATAN() Returns the arctangent (in radians) of the field value. ```sql ATAN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-atan-to-a-field) Apply `ATAN()` to a field ```sql SELECT a, ATAN(a) FROM numbers LIMIT 6 ``` name: numbers | time | a | atan | |--------------------|-------------------|--------------------| |2023-01-01T00:00:00Z| 0.33909108671076 |0.32692355076199897 | |2023-01-01T00:01:00Z|\-0.774984088561186|\-0.659300127490126 | |2023-01-01T00:02:00Z|\-0.921037167720451|\-0.7443170183837121| |2023-01-01T00:03:00Z|\-0.73880754843378 |\-0.6362993731936669| |2023-01-01T00:04:00Z|\-0.905980032168252|\-0.7361091800814261| |2023-01-01T00:05:00Z|\-0.891164752631417|\-0.727912249468035 | [](#apply-atan-to-each-field) Apply `ATAN()` to each field ```sql SELECT ATAN(*) FROM numbers LIMIT 6 ``` name: numbers | time | atan\_a | atan\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z|0.32692355076199897 |\-0.1622053541422186 | |2023-01-01T00:01:00Z|\-0.659300127490126 | 0.13618613793696105 | |2023-01-01T00:02:00Z|\-0.7443170183837121|\-0.4499093121666581 | |2023-01-01T00:03:00Z|\-0.6362993731936669|\-0.07284417510130452| |2023-01-01T00:04:00Z|\-0.7361091800814261| 1.0585985450688151 | |2023-01-01T00:05:00Z|\-0.727912249468035 | 0.6378113578294793 | [](#apply-atan-to-time-windows-grouped-by-time) Apply `ATAN()` to time windows (grouped by time) ```sql SELECT ATAN(MEAN(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | atan | |--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.4099506966510045| |2023-01-01T00:10:00Z| 0.1279079463727065 | |2023-01-01T00:20:00Z|0.030159013397288013| |2023-01-01T00:30:00Z|0.02927862748761639 | |2023-01-01T00:40:00Z|0.022110742100818606| |2023-01-01T00:50:00Z|0.15407382461141705 | ## ATAN2() Returns the the arctangent of `y/x` in radians. ```sql ATAN2(expression_y, expression_x) ``` #### Arguments * **expression\_y**: Expression to identify the `y` numeric value or one or more fields to operate on. Can be a number literal, [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. * **expression\_x**: Expression to identify the `x` numeric value or one or more fields to operate on. Can be a number literal, [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-atan2-to-a-field-divided-by-another-field) Apply `ATAN2()` to a field divided by another field ```sql SELECT ATAN2(a, b) FROM numbers LIMIT 6 ``` name: numbers | time | atan2 | |--------------------|---------------------| |2023-01-01T00:00:00Z| 2.0204217911794937 | |2023-01-01T00:01:00Z| \-1.395783190047229 | |2023-01-01T00:02:00Z| \-2.053731408859953 | |2023-01-01T00:03:00Z| \-1.669248713922653 | |2023-01-01T00:04:00Z|\-0.47112754043763505| |2023-01-01T00:05:00Z|\-0.8770454978291377 | [](#apply-atan2-to-each-field-divided-by-a-numeric-value) Apply `ATAN2()` to each field divided by a numeric value ```sql SELECT ATAN2(*, 2) FROM numbers LIMIT 6 ``` name: numbers | time | atan2\_a | atan2\_b | |--------------------|---------------------|----------------------| |2023-01-01T00:00:00Z| 0.16794843225523703 | \-0.0816396675119722 | |2023-01-01T00:01:00Z|\-0.36967737169970566| 0.06841026268126137 | |2023-01-01T00:02:00Z|\-0.4315666721698651 | \-0.2369359777533473 | |2023-01-01T00:03:00Z|\-0.35385538623378937|\-0.036470468100670846| |2023-01-01T00:04:00Z|\-0.4253376417906667 | 0.7268651162204586 | |2023-01-01T00:05:00Z|\-0.41917415992493756| 0.35488446257957357 | [](#apply-atan2-to-time-windows-grouped-by-time) Apply `ATAN2()` to time windows (grouped by time) ```sql SELECT ATAN2(MEAN(a), MEAN(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | atan2 | |--------------------|-------------------| |2023-01-01T00:00:00Z|\-1.278967897411707| |2023-01-01T00:10:00Z|2.3520553840586773 | |2023-01-01T00:20:00Z| 2.226497789888965 | |2023-01-01T00:30:00Z|3.0977773783018656 | |2023-01-01T00:40:00Z|2.9285769547942677 | |2023-01-01T00:50:00Z|0.9505419744107901 | ## CEIL() Returns the subsequent value rounded up to the nearest integer. ```sql CEIL(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-ceil-to-a-field) Apply `CEIL()` to a field ```sql SELECT b, CEIL(b) FROM numbers LIMIT 6 ``` name: numbers | time | b |ceil| |--------------------|--------------------|----| |2023-01-01T00:00:00Z|\-0.163643058925645 |\-0 | |2023-01-01T00:01:00Z| 0.137034364053949 | 1 | |2023-01-01T00:02:00Z|\-0.482943221384294 |\-0 | |2023-01-01T00:03:00Z|\-0.0729732928756677|\-0 | |2023-01-01T00:04:00Z| 1.77857552719844 | 2 | |2023-01-01T00:05:00Z| 0.741147445214238 | 1 | [](#apply-ceil-to-each-field) Apply `CEIL()` to each field ```sql SELECT CEIL(*) FROM numbers LIMIT 6 ``` name: numbers | time |ceil\_a|ceil\_b| |--------------------|-------|-------| |2023-01-01T00:00:00Z| 1 | \-0 | |2023-01-01T00:01:00Z| \-0 | 1 | |2023-01-01T00:02:00Z| \-0 | \-0 | |2023-01-01T00:03:00Z| \-0 | \-0 | |2023-01-01T00:04:00Z| \-0 | 2 | |2023-01-01T00:05:00Z| \-0 | 1 | [](#apply-ceil-to-time-windows-grouped-by-time) Apply `CEIL()` to time windows (grouped by time) ```sql SELECT CEIL(MEAN(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time |ceil| |--------------------|----| |2023-01-01T00:00:00Z| 1 | |2023-01-01T00:10:00Z|\-0 | |2023-01-01T00:20:00Z|\-0 | |2023-01-01T00:30:00Z|\-0 | |2023-01-01T00:40:00Z|\-0 | |2023-01-01T00:50:00Z| 1 | ## COS() Returns the cosine of the field value. ```sql COS(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-cos-to-a-field) Apply `COS()` to a field ```sql SELECT b, COS(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | cos | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | 0.9866403278718959 | |2023-01-01T00:01:00Z| 0.137034364053949 | 0.9906254752128878 | |2023-01-01T00:02:00Z|\-0.482943221384294 | 0.8856319645801471 | |2023-01-01T00:03:00Z|\-0.0729732928756677| 0.9973386305831397 | |2023-01-01T00:04:00Z| 1.77857552719844 |\-0.20628737691395405| |2023-01-01T00:05:00Z| 0.741147445214238 | 0.7376943643170851 | [](#apply-cos-to-each-field) Apply `COS()` to each field ```sql SELECT COS(*) FROM numbers LIMIT 6 ``` name: numbers | time | cos\_a | cos\_b | |--------------------|------------------|---------------------| |2023-01-01T00:00:00Z|0.9430573869206459| 0.9866403278718959 | |2023-01-01T00:01:00Z|0.7144321674550146| 0.9906254752128878 | |2023-01-01T00:02:00Z|0.6049946586273094| 0.8856319645801471 | |2023-01-01T00:03:00Z|0.7392720891861374| 0.9973386305831397 | |2023-01-01T00:04:00Z|0.616914561474936 |\-0.20628737691395405| |2023-01-01T00:05:00Z|0.6285065034701617| 0.7376943643170851 | [](#apply-cos-to-time-windows-grouped-by-time) Apply `COS()` to time windows (grouped by time) ```sql SELECT COS(MEAN(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | cos | |--------------------|------------------| |2023-01-01T00:00:00Z|0.9914907269510592| |2023-01-01T00:10:00Z|0.9918765457796455| |2023-01-01T00:20:00Z|0.9997307399250498| |2023-01-01T00:30:00Z|0.7850670342365872| |2023-01-01T00:40:00Z|0.9947779847618986| |2023-01-01T00:50:00Z|0.9938532355205111| ## CUMULATIVE\_SUM() Returns the running total of subsequent [field values](/influxdb3/core/reference/glossary/#field-value). ```sql CUMULATIVE_SUM(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-cumulative_sum-to-a-field) Apply `CUMULATIVE_SUM()` to a field ```sql SELECT CUMULATIVE_SUM(b) FROM numbers LIMIT 6 ``` name: numbers | time | cumulative\_sum | |--------------------|---------------------| |2023-01-01T00:00:00Z| \-0.163643058925645 | |2023-01-01T00:01:00Z|\-0.02660869487169601| |2023-01-01T00:02:00Z|\-0.5095519162559901 | |2023-01-01T00:03:00Z|\-0.5825252091316577 | |2023-01-01T00:04:00Z| 1.1960503180667823 | |2023-01-01T00:05:00Z| 1.9371977632810204 | [](#apply-cumulative_sum-to-each-field) Apply `CUMULATIVE_SUM()` to each field ```sql SELECT CUMULATIVE_SUM(*) FROM numbers LIMIT 6 ``` name: numbers | time | cumulative\_sum\_a | cumulative\_sum\_b | |--------------------|---------------------|---------------------| |2023-01-01T00:00:00Z| 0.33909108671076 | \-0.163643058925645 | |2023-01-01T00:01:00Z|\-0.43589300185042595|\-0.02660869487169601| |2023-01-01T00:02:00Z|\-1.3569301695708769 |\-0.5095519162559901 | |2023-01-01T00:03:00Z| \-2.095737718004657 |\-0.5825252091316577 | |2023-01-01T00:04:00Z| \-3.001717750172909 | 1.1960503180667823 | |2023-01-01T00:05:00Z| \-3.892882502804326 | 1.9371977632810204 | [](#apply-cumulative_sum-to-field-keys-that-match-a-regular-expression) Apply `CUMULATIVE_SUM()` to field keys that match a regular expression ```sql SELECT CUMULATIVE_SUM(/[ab]/) FROM numbers LIMIT 6 ``` name: numbers | time | cumulative\_sum\_a | cumulative\_sum\_b | |--------------------|---------------------|---------------------| |2023-01-01T00:00:00Z| 0.33909108671076 | \-0.163643058925645 | |2023-01-01T00:01:00Z|\-0.43589300185042595|\-0.02660869487169601| |2023-01-01T00:02:00Z|\-1.3569301695708769 |\-0.5095519162559901 | |2023-01-01T00:03:00Z| \-2.095737718004657 |\-0.5825252091316577 | |2023-01-01T00:04:00Z| \-3.001717750172909 | 1.1960503180667823 | |2023-01-01T00:05:00Z| \-3.892882502804326 | 1.9371977632810204 | [](#apply-cumulative_sum-to-time-windows-grouped-by-time) Apply `CUMULATIVE_SUM()` to time windows (grouped by time) ```sql SELECT CUMULATIVE_SUM(SUM(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | cumulative\_sum | |--------------------|---------------------| |2023-01-01T00:00:00Z| 1.3054783385851743 | |2023-01-01T00:10:00Z|0.029980276948385454 | |2023-01-01T00:20:00Z|\-0.20208529969578404| |2023-01-01T00:30:00Z| \-6.882005145666267 | |2023-01-01T00:40:00Z| \-7.904410787756402 | |2023-01-01T00:50:00Z| \-6.795080184131271 | ## DERIVATIVE() Returns the rate of change between subsequent [field values](/influxdb3/core/reference/glossary/#field-value)per `unit`. ```sql SELECT DERIVATIVE(field_expression[, unit]) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports numeric field types. * **unit**: Unit of time to use to calculate the rate of change. Supports [duration literals](/influxdb3/core/reference/influxql/#durations).*Default is `1s` (per second)*. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Related functions * [NON\_NEGATIVE\_DERIVATIVE()](#non_negative_derivative) #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-derivative-to-a-field-to-calculate-the-per-second-change) Apply `DERIVATIVE()` to a field to calculate the per second change ```sql SELECT DERIVATIVE(b) FROM numbers LIMIT 6 ``` name: numbers | time | derivative | |--------------------|----------------------| |2023-01-01T00:01:00Z| 0.005011290382993233 | |2023-01-01T00:02:00Z|\-0.01033295975730405 | |2023-01-01T00:03:00Z| 0.006832832141810439 | |2023-01-01T00:04:00Z| 0.03085914700123513 | |2023-01-01T00:05:00Z|\-0.017290468033070033| |2023-01-01T00:06:00Z|\-0.007557890705063634| [](#apply-derivative-to-a-field-to-calculate-the-per-5-minute-change) Apply `DERIVATIVE()` to a field to calculate the per 5 minute change ```sql SELECT DERIVATIVE(b, 5m) FROM numbers LIMIT 6 ``` name: numbers | time | derivative | |--------------------|--------------------| |2023-01-01T00:01:00Z| 1.5033871148979698 | |2023-01-01T00:02:00Z|\-3.0998879271912148| |2023-01-01T00:03:00Z| 2.0498496425431316 | |2023-01-01T00:04:00Z| 9.257744100370537 | |2023-01-01T00:05:00Z|\-5.187140409921009 | |2023-01-01T00:06:00Z| \-2.26736721151909 | [](#apply-derivative-to-each-field) Apply `DERIVATIVE()` to each field ```sql SELECT DERIVATIVE(*) FROM numbers LIMIT 6 ``` name: numbers | time | derivative\_a | derivative\_b | |--------------------|-----------------------|----------------------| |2023-01-01T00:01:00Z|\-0.018567919587865765 | 0.005011290382993233 | |2023-01-01T00:02:00Z|\-0.0024342179859877505|\-0.01033295975730405 | |2023-01-01T00:03:00Z| 0.0030371603214445152 | 0.006832832141810439 | |2023-01-01T00:04:00Z|\-0.0027862080622411984| 0.03085914700123513 | |2023-01-01T00:05:00Z|0.00024692132561391543 |\-0.017290468033070033| |2023-01-01T00:06:00Z| 0.016704951104985283 |\-0.007557890705063634| [](#apply-derivative-to-field-keys-that-match-a-regular-expression) Apply `DERIVATIVE()` to field keys that match a regular expression ```sql SELECT DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 ``` name: numbers | time | derivative\_a | derivative\_b | |--------------------|-----------------------|----------------------| |2023-01-01T00:01:00Z|\-0.018567919587865765 | 0.005011290382993233 | |2023-01-01T00:02:00Z|\-0.0024342179859877505|\-0.01033295975730405 | |2023-01-01T00:03:00Z| 0.0030371603214445152 | 0.006832832141810439 | |2023-01-01T00:04:00Z|\-0.0027862080622411984| 0.03085914700123513 | |2023-01-01T00:05:00Z|0.00024692132561391543 |\-0.017290468033070033| |2023-01-01T00:06:00Z| 0.016704951104985283 |\-0.007557890705063634| [](#apply-derivative-to-time-windows-grouped-by-time) Apply `DERIVATIVE()` to time windows (grouped by time) ```sql SELECT DERIVATIVE(MEAN(b), 1m) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | derivative | |--------------------|----------------------| |2023-01-01T00:10:00Z|\-0.025809764002219633| |2023-01-01T00:20:00Z| 0.010434324849926194 | |2023-01-01T00:30:00Z|\-0.06447854269326314 | |2023-01-01T00:40:00Z| 0.05657514203880348 | |2023-01-01T00:50:00Z| 0.021317362457152655 | ## DIFFERENCE() Returns the result of subtraction between subsequent [field values](/influxdb3/core/reference/glossary/#field-value). ```sql DIFFERENCE(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Related functions * [NON\_NEGATIVE\_DIFFERENCE()](#non_negative_difference) #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-difference-to-a-field) Apply `DIFFERENCE()` to a field ```sql SELECT DIFFERENCE(b) FROM numbers LIMIT 6 ``` name: numbers | time | difference | |--------------------|---------------------| |2023-01-01T00:01:00Z| 0.300677422979594 | |2023-01-01T00:02:00Z| \-0.619977585438243 | |2023-01-01T00:03:00Z| 0.40996992850862635 | |2023-01-01T00:04:00Z| 1.8515488200741077 | |2023-01-01T00:05:00Z|\-1.0374280819842019 | |2023-01-01T00:06:00Z|\-0.45347344230381803| [](#apply-difference-to-each-field) Apply `DIFFERENCE()` to each field ```sql SELECT DIFFERENCE(*) FROM numbers LIMIT 6 ``` name: numbers | time | difference\_a | difference\_b | |--------------------|---------------------|---------------------| |2023-01-01T00:01:00Z| \-1.114075175271946 | 0.300677422979594 | |2023-01-01T00:02:00Z|\-0.14605307915926502| \-0.619977585438243 | |2023-01-01T00:03:00Z| 0.18222961928667092 | 0.40996992850862635 | |2023-01-01T00:04:00Z|\-0.1671724837344719 | 1.8515488200741077 | |2023-01-01T00:05:00Z|0.014815279536834924 |\-1.0374280819842019 | |2023-01-01T00:06:00Z| 1.002297066299117 |\-0.45347344230381803| [](#apply-difference-to-field-keys-that-match-a-regular-expression) Apply `DIFFERENCE()` to field keys that match a regular expression ```sql SELECT DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 ``` name: numbers | time | difference\_a | difference\_b | |--------------------|---------------------|---------------------| |2023-01-01T00:01:00Z| \-1.114075175271946 | 0.300677422979594 | |2023-01-01T00:02:00Z|\-0.14605307915926502| \-0.619977585438243 | |2023-01-01T00:03:00Z| 0.18222961928667092 | 0.40996992850862635 | |2023-01-01T00:04:00Z|\-0.1671724837344719 | 1.8515488200741077 | |2023-01-01T00:05:00Z|0.014815279536834924 |\-1.0374280819842019 | |2023-01-01T00:06:00Z| 1.002297066299117 |\-0.45347344230381803| [](#apply-difference-to-time-windows-grouped-by-time) Apply `DIFFERENCE()` to time windows (grouped by time) ```sql SELECT DIFFERENCE(MEAN(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | difference | |--------------------|--------------------| |2023-01-01T00:10:00Z|\-0.2580976400221963| |2023-01-01T00:20:00Z|0.10434324849926194 | |2023-01-01T00:30:00Z|\-0.6447854269326314| |2023-01-01T00:40:00Z| 0.5657514203880348 | |2023-01-01T00:50:00Z|0.21317362457152655 | ## ELAPSED() Returns the difference between subsequent [field value’s](/influxdb3/core/reference/glossary/#field-value)timestamps in a specified `unit` of time. ```sql ELAPSED(field_expression[, unit ]) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field types. * **unit**: Unit of time to return the elapsed time in. Supports [duration literals](/influxdb3/core/reference/influxql/#durations).*Default is `1ns` (nanoseconds)*. #### Notable behaviors * If the `unit` is greater than the elapsed time between points, `ELAPSED()`returns `0`. * `ELAPSED()` supports the `GROUP BY time()` clause but the query results aren’t very useful. An `ELAPSED()` query with a nested function and a `GROUP BY time()` clause returns the interval specified in the `GROUP BY time()` clause. #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-elapsed-to-a-field-and-return-elapsed-time-in-nanoseconds) Apply `ELAPSED()` to a field and return elapsed time in nanoseconds ```sql SELECT ELAPSED(b) FROM numbers LIMIT 6 ``` name: numbers | time | elapsed | |--------------------|-----------| |2023-01-01T00:01:00Z|60000000000| |2023-01-01T00:02:00Z|60000000000| |2023-01-01T00:03:00Z|60000000000| |2023-01-01T00:04:00Z|60000000000| |2023-01-01T00:05:00Z|60000000000| |2023-01-01T00:06:00Z|60000000000| [](#apply-elapsed-to-a-field-and-return-elapsed-time-in-seconds) Apply `ELAPSED()` to a field and return elapsed time in seconds ```sql SELECT ELAPSED(b, 1s) FROM numbers LIMIT 6 ``` name: numbers | time |elapsed| |--------------------|-------| |2023-01-01T00:01:00Z| 60 | |2023-01-01T00:02:00Z| 60 | |2023-01-01T00:03:00Z| 60 | |2023-01-01T00:04:00Z| 60 | |2023-01-01T00:05:00Z| 60 | |2023-01-01T00:06:00Z| 60 | [](#apply-elapsed-to-each-field) Apply `ELAPSED()` to each field ```sql SELECT ELAPSED(*) FROM numbers LIMIT 6 ``` name: numbers | time |elapsed\_a |elapsed\_b | |--------------------|-----------|-----------| |2023-01-01T00:01:00Z|60000000000|60000000000| |2023-01-01T00:02:00Z|60000000000|60000000000| |2023-01-01T00:03:00Z|60000000000|60000000000| |2023-01-01T00:04:00Z|60000000000|60000000000| |2023-01-01T00:05:00Z|60000000000|60000000000| |2023-01-01T00:06:00Z|60000000000|60000000000| [](#apply-elapsed-to-field-keys-that-match-a-regular-expression) Apply `ELAPSED()` to field keys that match a regular expression ```sql SELECT ELAPSED(/[ab]/, 1s) FROM numbers LIMIT 6 ``` name: numbers | time |elapsed\_a|elapsed\_b| |--------------------|----------|----------| |2023-01-01T00:01:00Z| 60 | 60 | |2023-01-01T00:02:00Z| 60 | 60 | |2023-01-01T00:03:00Z| 60 | 60 | |2023-01-01T00:04:00Z| 60 | 60 | |2023-01-01T00:05:00Z| 60 | 60 | |2023-01-01T00:06:00Z| 60 | 60 | ## EXP() Returns the exponential of the field value. ```sql EXP(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-exp-to-a-field) Apply `EXP()` to a field ```sql SELECT a, EXP(a) FROM numbers LIMIT 6 ``` name: numbers | time | a | exp | |--------------------|-------------------|-------------------| |2023-01-01T00:00:00Z| 0.33909108671076 |1.4036711951820788 | |2023-01-01T00:01:00Z|\-0.774984088561186| 0.460711111517308 | |2023-01-01T00:02:00Z|\-0.921037167720451|0.39810592427186076| |2023-01-01T00:03:00Z|\-0.73880754843378 |0.4776831901055915 | |2023-01-01T00:04:00Z|\-0.905980032168252|0.40414561525252984| |2023-01-01T00:05:00Z|\-0.891164752631417|0.4101777188333968 | [](#apply-exp-to-each-field) Apply `EXP()` to each field ```sql SELECT EXP(*) FROM numbers LIMIT 6 ``` name: numbers | time | exp\_a | exp\_b | |--------------------|-------------------|------------------| |2023-01-01T00:00:00Z|1.4036711951820788 |0.8490450268435884| |2023-01-01T00:01:00Z| 0.460711111517308 | 1.14686755886191 | |2023-01-01T00:02:00Z|0.39810592427186076|0.6169648527893578| |2023-01-01T00:03:00Z|0.4776831901055915 |0.929625657322271 | |2023-01-01T00:04:00Z|0.40414561525252984|5.921415512753404 | |2023-01-01T00:05:00Z|0.4101777188333968 | 2.09834186598405 | [](#apply-exp-to-time-windows-grouped-by-time) Apply `EXP()` to time windows (grouped by time) ```sql SELECT EXP(MEAN(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | exp | |--------------------|------------------| |2023-01-01T00:00:00Z|0.6475413743155294| |2023-01-01T00:10:00Z|1.137246608416461 | |2023-01-01T00:20:00Z|1.030627830373793 | |2023-01-01T00:30:00Z|1.029720078241656 | |2023-01-01T00:40:00Z|1.0223606806499268| |2023-01-01T00:50:00Z|1.1680137850180072| ## FLOOR() Returns the subsequent value rounded down to the nearest integer. ```sql FLOOR(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-floor-to-a-field) Apply `FLOOR()` to a field ```sql SELECT b, FLOOR(b) FROM numbers LIMIT 6 ``` name: numbers | time | b |floor| |--------------------|--------------------|-----| |2023-01-01T00:00:00Z|\-0.163643058925645 | \-1 | |2023-01-01T00:01:00Z| 0.137034364053949 | 0 | |2023-01-01T00:02:00Z|\-0.482943221384294 | \-1 | |2023-01-01T00:03:00Z|\-0.0729732928756677| \-1 | |2023-01-01T00:04:00Z| 1.77857552719844 | 1 | |2023-01-01T00:05:00Z| 0.741147445214238 | 0 | [](#apply-floor-to-each-field) Apply `FLOOR()` to each field ```sql SELECT FLOOR(*) FROM numbers LIMIT 6 ``` name: numbers | time |floor\_a|floor\_b| |--------------------|--------|--------| |2023-01-01T00:00:00Z| 0 | \-1 | |2023-01-01T00:01:00Z| \-1 | 0 | |2023-01-01T00:02:00Z| \-1 | \-1 | |2023-01-01T00:03:00Z| \-1 | \-1 | |2023-01-01T00:04:00Z| \-1 | 1 | |2023-01-01T00:05:00Z| \-1 | 0 | [](#apply-floor-to-time-windows-grouped-by-time) Apply `FLOOR()` to time windows (grouped by time) ```sql SELECT FLOOR(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time |floor| |--------------------|-----| |2023-01-01T00:00:00Z| \-5 | |2023-01-01T00:10:00Z| 1 | |2023-01-01T00:20:00Z| 0 | |2023-01-01T00:30:00Z| 0 | |2023-01-01T00:40:00Z| 0 | |2023-01-01T00:50:00Z| 1 | ## LN() Returns the natural logarithm of the field value. Field values must be greater than or equal to 0. ```sql LN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-ln-to-a-field) Apply `LN()` to a field ```sql SELECT b, LN(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | ln | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | | |2023-01-01T00:01:00Z| 0.137034364053949 | \-1.98752355209665 | |2023-01-01T00:02:00Z|\-0.482943221384294 | | |2023-01-01T00:03:00Z|\-0.0729732928756677| | |2023-01-01T00:04:00Z| 1.77857552719844 | 0.5758127783016702 | |2023-01-01T00:05:00Z| 0.741147445214238 |\-0.2995556920844895| [](#apply-ln-to-each-field) Apply `LN()` to each field ```sql SELECT LN(*) FROM numbers LIMIT 6 ``` name: numbers | time | ln\_a | ln\_b | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-1.0814865153308908| | |2023-01-01T00:01:00Z| | \-1.98752355209665 | |2023-01-01T00:02:00Z| | | |2023-01-01T00:03:00Z| | | |2023-01-01T00:04:00Z| | 0.5758127783016702 | |2023-01-01T00:05:00Z| |\-0.2995556920844895| [](#apply-ln-to-time-windows-grouped-by-time) Apply `LN()` to time windows (grouped by time) ```sql SELECT LN(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | ln | |--------------------|--------------------| |2023-01-01T00:00:00Z| | |2023-01-01T00:10:00Z|0.25161504572793725 | |2023-01-01T00:20:00Z|\-1.1983831026157092| |2023-01-01T00:30:00Z|\-1.2280265702380913| |2023-01-01T00:40:00Z|\-1.5089436474159283| |2023-01-01T00:50:00Z| 0.4402187212890264 | ## LOG() Returns the logarithm of the field value with base `b`. Field values must be greater than or equal to 0. ```sql LOG(field_expression, b) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. * **b**: Logarithm base to use in the operation. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-log-to-a-field-with-a-base-of-3) Apply `LOG()` to a field with a base of 3 ```sql SELECT b, LOG(b, 3) FROM numbers LIMIT 6 ``` name: numbers | time | b | log | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | | |2023-01-01T00:01:00Z| 0.137034364053949 |\-1.8091219009630797| |2023-01-01T00:02:00Z|\-0.482943221384294 | | |2023-01-01T00:03:00Z|\-0.0729732928756677| | |2023-01-01T00:04:00Z| 1.77857552719844 | 0.5241273780031629 | |2023-01-01T00:05:00Z| 0.741147445214238 |\-0.2726673414946528| [](#apply-log-to-each-field-with-a-base-of-5) Apply `LOG()` to each field with a base of 5 ```sql SELECT LOG(*, 5) FROM numbers LIMIT 6 ``` name: numbers | time | log\_a | log\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z|\-0.6719653532302217| | |2023-01-01T00:01:00Z| |\-1.2349178161776593 | |2023-01-01T00:02:00Z| | | |2023-01-01T00:03:00Z| | | |2023-01-01T00:04:00Z| | 0.3577725949246566 | |2023-01-01T00:05:00Z| |\-0.18612441633827553| [](#apply-log-to-time-windows-grouped-by-time) Apply `LOG()` to time windows (grouped by time) ```sql SELECT LOG(SUM(a), 10) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | log | |--------------------|--------------------| |2023-01-01T00:00:00Z| | |2023-01-01T00:10:00Z|0.10927502592347751 | |2023-01-01T00:20:00Z|\-0.5204511686721008| |2023-01-01T00:30:00Z|\-0.5333251630849791| |2023-01-01T00:40:00Z|\-0.6553258995757036| |2023-01-01T00:50:00Z| 0.1911845614863297 | ## LOG2() Returns the logarithm of the field value to the base 2. Field values must be greater than or equal to 0. ```sql LOG2(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-log2-to-a-field) Apply `LOG2()` to a field ```sql SELECT b, LOG2(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | log2 | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | | |2023-01-01T00:01:00Z| 0.137034364053949 |\-2.8673903722598544| |2023-01-01T00:02:00Z|\-0.482943221384294 | | |2023-01-01T00:03:00Z|\-0.0729732928756677| | |2023-01-01T00:04:00Z| 1.77857552719844 | 0.8307222397363156 | |2023-01-01T00:05:00Z| 0.741147445214238 |\-0.4321675114403543| [](#apply-log2-to-each-field) Apply `LOG2()` to each field ```sql SELECT LOG2(*) FROM numbers LIMIT 6 ``` name: numbers | time | log2\_a | log2\_b | |--------------------|-------------------|--------------------| |2023-01-01T00:00:00Z|\-1.560255232456162| | |2023-01-01T00:01:00Z| |\-2.8673903722598544| |2023-01-01T00:02:00Z| | | |2023-01-01T00:03:00Z| | | |2023-01-01T00:04:00Z| | 0.8307222397363156 | |2023-01-01T00:05:00Z| |\-0.4321675114403543| [](#apply-log2-to-time-windows-grouped-by-time) Apply `LOG2()` to time windows (grouped by time) ```sql SELECT LOG2(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | log2 | |--------------------|--------------------| |2023-01-01T00:00:00Z| | |2023-01-01T00:10:00Z|0.36300377868474476 | |2023-01-01T00:20:00Z|\-1.7289013592288134| |2023-01-01T00:30:00Z|\-1.7716678429623767| |2023-01-01T00:40:00Z|\-2.1769455171078644| |2023-01-01T00:50:00Z| 0.6351013661101591 | ## LOG10() Returns the logarithm of the field value to the base 10. Field values must be greater than or equal to 0. ```sql LOG10(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-log10-to-a-field) Apply `LOG10()` to a field ```sql SELECT b, LOG10(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | log10 | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | | |2023-01-01T00:01:00Z| 0.137034364053949 |\-0.8631705113283253| |2023-01-01T00:02:00Z|\-0.482943221384294 | | |2023-01-01T00:03:00Z|\-0.0729732928756677| | |2023-01-01T00:04:00Z| 1.77857552719844 |0.25007231222579585 | |2023-01-01T00:05:00Z| 0.741147445214238 |\-0.1300953840950034| [](#apply-log10-to-each-field) Apply `LOG10()` to each field ```sql SELECT LOG10(*) FROM numbers LIMIT 6 ``` name: numbers | time | log10\_a | log10\_b | |--------------------|---------------------|--------------------| |2023-01-01T00:00:00Z|\-0.46968362586098245| | |2023-01-01T00:01:00Z| |\-0.8631705113283253| |2023-01-01T00:02:00Z| | | |2023-01-01T00:03:00Z| | | |2023-01-01T00:04:00Z| |0.25007231222579585 | |2023-01-01T00:05:00Z| |\-0.1300953840950034| [](#apply-log10-to-time-windows-grouped-by-time) Apply `LOG10()` to time windows (grouped by time) ```sql SELECT LOG10(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | log10 | |--------------------|--------------------| |2023-01-01T00:00:00Z| | |2023-01-01T00:10:00Z|0.10927502592347751 | |2023-01-01T00:20:00Z|\-0.520451168672101 | |2023-01-01T00:30:00Z|\-0.5333251630849791| |2023-01-01T00:40:00Z|\-0.6553258995757036| |2023-01-01T00:50:00Z|0.19118456148632973 | ## MOVING\_AVERAGE() Returns the rolling average across a window of subsequent [field values](/influxdb3/core/reference/glossary/#field-value). ```sql MOVING_AVERAGE(field_expression, N) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports all field types. * **N**: Number of field values to use when calculating the moving average. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-moving_average-to-a-field) Apply `MOVING_AVERAGE()` to a field ```sql SELECT MOVING_AVERAGE(a, 3) FROM numbers LIMIT 6 ``` name: numbers | time | moving\_average | |--------------------|--------------------| |2023-01-01T00:02:00Z|\-0.4523100565236256| |2023-01-01T00:03:00Z|\-0.8116096015718056| |2023-01-01T00:04:00Z|\-0.8552749161074944| |2023-01-01T00:05:00Z|\-0.8453174444111498| |2023-01-01T00:06:00Z|\-0.5620041570439896| |2023-01-01T00:07:00Z|\-0.3569778402485757| [](#apply-moving_average-to-each-field) Apply `MOVING_AVERAGE()` to each field ```sql SELECT MOVING_AVERAGE(*, 3) FROM numbers LIMIT 6 ``` name: numbers | time | moving\_average\_a | moving\_average\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:02:00Z|\-0.4523100565236256|\-0.16985063875199669| |2023-01-01T00:03:00Z|\-0.8116096015718056|\-0.13962738340200423| |2023-01-01T00:04:00Z|\-0.8552749161074944| 0.40755300431282615 | |2023-01-01T00:05:00Z|\-0.8453174444111498| 0.815583226512337 | |2023-01-01T00:06:00Z|\-0.5620041570439896| 0.9357989917743662 | |2023-01-01T00:07:00Z|\-0.3569778402485757| 0.15985821845558748 | [](#apply-moving_average-to-field-keys-that-match-a-regular-expression) Apply `MOVING_AVERAGE()` to field keys that match a regular expression ```sql SELECT MOVING_AVERAGE(/[ab]/, 3) FROM numbers LIMIT 6 ``` name: numbers | time | moving\_average\_a | moving\_average\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:02:00Z|\-0.4523100565236256|\-0.16985063875199669| |2023-01-01T00:03:00Z|\-0.8116096015718056|\-0.13962738340200423| |2023-01-01T00:04:00Z|\-0.8552749161074944| 0.40755300431282615 | |2023-01-01T00:05:00Z|\-0.8453174444111498| 0.815583226512337 | |2023-01-01T00:06:00Z|\-0.5620041570439896| 0.9357989917743662 | |2023-01-01T00:07:00Z|\-0.3569778402485757| 0.15985821845558748 | [](#apply-moving_average-to-time-windows-grouped-by-time) Apply `MOVING_AVERAGE()` to time windows (grouped by time) ```sql SELECT MOVING_AVERAGE(SUM(a), 3) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | moving\_average | |--------------------|--------------------| |2023-01-01T00:20:00Z|\-0.9193144769987766| |2023-01-01T00:30:00Z| 0.626884141339178 | |2023-01-01T00:40:00Z|0.27189834404638374 | |2023-01-01T00:50:00Z| 0.6890200973149928 | ## NON\_NEGATIVE\_DERIVATIVE() Returns only non-negative rate of change between subsequent[field values](/influxdb3/core/reference/glossary/#field-value). Negative rates of change return *null*. ```sql NON_NEGATIVE_DERIVATIVE(field_expression[, unit]) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports numeric field types. * **unit**: Unit of time to use to calculate the rate of change. Supports [duration literals](/influxdb3/core/reference/influxql/#durations).*Default is `1s` (per second)*. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Related functions * [DERIVATIVE()](#derivative) #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-non_negative_derivative-to-a-field-to-calculate-the-per-second-change) Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per second change ```sql SELECT NON_NEGATIVE_DERIVATIVE(b) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_derivative| |--------------------|-------------------------| |2023-01-01T00:01:00Z| 0.005011290382993233 | |2023-01-01T00:03:00Z| 0.006832832141810439 | |2023-01-01T00:04:00Z| 0.03085914700123513 | |2023-01-01T00:08:00Z| 0.0227877053636946 | |2023-01-01T00:10:00Z| 0.001676063810538834 | |2023-01-01T00:11:00Z| 0.014999637478226817 | [](#apply-non_negative_derivative-to-a-field-to-calculate-the-per-5-minute-change) Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per 5 minute change ```sql SELECT NON_NEGATIVE_DERIVATIVE(b, 5m) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_derivative| |--------------------|-------------------------| |2023-01-01T00:01:00Z| 1.5033871148979698 | |2023-01-01T00:03:00Z| 2.0498496425431316 | |2023-01-01T00:04:00Z| 9.257744100370537 | |2023-01-01T00:08:00Z| 6.836311609108379 | |2023-01-01T00:10:00Z| 0.5028191431616502 | |2023-01-01T00:11:00Z| 4.499891243468045 | [](#apply-non_negative_derivative-to-each-field) Apply `NON_NEGATIVE_DERIVATIVE()` to each field ```sql SELECT NON_NEGATIVE_DERIVATIVE(*) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_derivative\_a|non\_negative\_derivative\_b| |--------------------|----------------------------|----------------------------| |2023-01-01T00:01:00Z| | 0.005011290382993233 | |2023-01-01T00:03:00Z| 0.0030371603214445152 | 0.006832832141810439 | |2023-01-01T00:04:00Z| | 0.03085914700123513 | |2023-01-01T00:05:00Z| 0.00024692132561391543 | | |2023-01-01T00:06:00Z| 0.016704951104985283 | | |2023-01-01T00:08:00Z| | 0.0227877053636946 | |2023-01-01T00:09:00Z| 0.018437240876186967 | | |2023-01-01T00:10:00Z| | 0.001676063810538834 | |2023-01-01T00:11:00Z| | 0.014999637478226817 | |2023-01-01T00:13:00Z| 0.006694752202850366 | | |2023-01-01T00:14:00Z| 0.011836797386191167 | | [](#apply-non_negative_derivative-to-field-keys-that-match-a-regular-expression) Apply `NON_NEGATIVE_DERIVATIVE()` to field keys that match a regular expression ```sql SELECT NON_NEGATIVE_DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_derivative\_a|non\_negative\_derivative\_b| |--------------------|----------------------------|----------------------------| |2023-01-01T00:01:00Z| | 0.005011290382993233 | |2023-01-01T00:03:00Z| 0.0030371603214445152 | 0.006832832141810439 | |2023-01-01T00:04:00Z| | 0.03085914700123513 | |2023-01-01T00:05:00Z| 0.00024692132561391543 | | |2023-01-01T00:06:00Z| 0.016704951104985283 | | |2023-01-01T00:08:00Z| | 0.0227877053636946 | |2023-01-01T00:09:00Z| 0.018437240876186967 | | |2023-01-01T00:10:00Z| | 0.001676063810538834 | |2023-01-01T00:11:00Z| | 0.014999637478226817 | |2023-01-01T00:13:00Z| 0.006694752202850366 | | |2023-01-01T00:14:00Z| 0.011836797386191167 | | [](#apply-non_negative_derivative-to-time-windows-grouped-by-time) Apply `NON_NEGATIVE_DERIVATIVE()` to time windows (grouped by time) ```sql SELECT NON_NEGATIVE_DERIVATIVE(MEAN(b), 1m) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time |non\_negative\_derivative| |--------------------|-------------------------| |2023-01-01T00:20:00Z| 0.010434324849926194 | |2023-01-01T00:40:00Z| 0.05657514203880348 | |2023-01-01T00:50:00Z| 0.021317362457152655 | ## NON\_NEGATIVE\_DIFFERENCE() Returns only non-negative result of subtraction between subsequent[field values](/influxdb3/core/reference/glossary/#field-value). Negative differences return *null*. ```sql NON_NEGATIVE_DIFFERENCE(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, regular expression, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Related functions * [DIFFERENCE()](#difference) #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-non_negative_difference-to-a-field) Apply `NON_NEGATIVE_DIFFERENCE()` to a field ```sql SELECT NON_NEGATIVE_DIFFERENCE(b) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_difference| |--------------------|-------------------------| |2023-01-01T00:01:00Z| 0.300677422979594 | |2023-01-01T00:03:00Z| 0.40996992850862635 | |2023-01-01T00:04:00Z| 1.8515488200741077 | |2023-01-01T00:08:00Z| 1.367262321821676 | |2023-01-01T00:10:00Z| 0.10056382863233004 | |2023-01-01T00:11:00Z| 0.899978248693609 | [](#apply-non_negative_difference-to-each-field) Apply `NON_NEGATIVE_DIFFERENCE()` to each field ```sql SELECT NON_NEGATIVE_DIFFERENCE(*) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_difference\_a|non\_negative\_difference\_b| |--------------------|----------------------------|----------------------------| |2023-01-01T00:01:00Z| | 0.300677422979594 | |2023-01-01T00:03:00Z| 0.18222961928667092 | 0.40996992850862635 | |2023-01-01T00:04:00Z| | 1.8515488200741077 | |2023-01-01T00:05:00Z| 0.014815279536834924 | | |2023-01-01T00:06:00Z| 1.002297066299117 | | |2023-01-01T00:08:00Z| | 1.367262321821676 | |2023-01-01T00:09:00Z| 1.106234452571218 | | |2023-01-01T00:10:00Z| | 0.10056382863233004 | |2023-01-01T00:11:00Z| | 0.899978248693609 | |2023-01-01T00:13:00Z| 0.401685132171022 | | |2023-01-01T00:14:00Z| 0.71020784317147 | | [](#apply-non_negative_difference-to-field-keys-that-match-a-regular-expression) Apply `NON_NEGATIVE_DIFFERENCE()` to field keys that match a regular expression ```sql SELECT NON_NEGATIVE_DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 ``` name: numbers | time |non\_negative\_difference\_a|non\_negative\_difference\_b| |--------------------|----------------------------|----------------------------| |2023-01-01T00:01:00Z| | 0.300677422979594 | |2023-01-01T00:03:00Z| 0.18222961928667092 | 0.40996992850862635 | |2023-01-01T00:04:00Z| | 1.8515488200741077 | |2023-01-01T00:05:00Z| 0.014815279536834924 | | |2023-01-01T00:06:00Z| 1.002297066299117 | | |2023-01-01T00:08:00Z| | 1.367262321821676 | |2023-01-01T00:09:00Z| 1.106234452571218 | | |2023-01-01T00:10:00Z| | 0.10056382863233004 | |2023-01-01T00:11:00Z| | 0.899978248693609 | |2023-01-01T00:13:00Z| 0.401685132171022 | | |2023-01-01T00:14:00Z| 0.71020784317147 | | [](#apply-non_negative_difference-to-time-windows-grouped-by-time) Apply `NON_NEGATIVE_DIFFERENCE()` to time windows (grouped by time) ```sql SELECT NON_NEGATIVE_DIFFERENCE(MEAN(b)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time |non\_negative\_difference| |--------------------|-------------------------| |2023-01-01T00:20:00Z| 0.10434324849926194 | |2023-01-01T00:40:00Z| 0.5657514203880348 | |2023-01-01T00:50:00Z| 0.21317362457152655 | ## POW() Returns the field value to the power of `x`. ```sql POW(field_expression, x) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. * **x**: Power to raise to. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-pow-to-a-field-with-a-power-of-3) Apply `POW()` to a field with a power of 3 ```sql SELECT b, POW(b, 3) FROM numbers LIMIT 6 ``` name: numbers | time | b | pow | |--------------------|--------------------|-----------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 |\-0.004382205777325515 | |2023-01-01T00:01:00Z| 0.137034364053949 | 0.002573288422171338 | |2023-01-01T00:02:00Z|\-0.482943221384294 | \-0.1126388541916811 | |2023-01-01T00:03:00Z|\-0.0729732928756677|\-0.0003885901893904874| |2023-01-01T00:04:00Z| 1.77857552719844 | 5.626222933751733 | |2023-01-01T00:05:00Z| 0.741147445214238 | 0.4071119474284653 | [](#apply-pow-to-each-field-with-a-power-of-5) Apply `POW()` to each field with a power of 5 ```sql SELECT POW(*, 5) FROM numbers LIMIT 6 ``` name: numbers | time | pow\_a | pow\_b | |--------------------|---------------------|-------------------------| |2023-01-01T00:00:00Z|0.004483135555212479 |\-0.00011735131084020357 | |2023-01-01T00:01:00Z|\-0.2795528536239978 | 0.000048322282876973225 | |2023-01-01T00:02:00Z|\-0.6628050073932118 | \-0.026271227986693114 | |2023-01-01T00:03:00Z|\-0.22011853819169455|\-0.000002069282189962477| |2023-01-01T00:04:00Z|\-0.6103699296012646 | 17.797604890097084 | |2023-01-01T00:05:00Z|\-0.5620694808926487 | 0.22362640363833164 | [](#apply-pow-to-time-windows-grouped-by-time) Apply `POW()` to time windows (grouped by time) ```sql SELECT POW(SUM(a), 10) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | pow | |--------------------|------------------------| |2023-01-01T00:00:00Z| 2402278.159218532 | |2023-01-01T00:10:00Z| 12.380844221267186 | |2023-01-01T00:20:00Z|0.000006244365466732681 | |2023-01-01T00:30:00Z|0.0000046424621235691315| |2023-01-01T00:40:00Z| 2.7973126174031977e-7 | |2023-01-01T00:50:00Z| 81.6292140233699 | ## ROUND() Returns a field value rounded to the nearest integer. ```sql ROUND(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-round-to-a-field) Apply `ROUND()` to a field ```sql SELECT b, ROUND(b) FROM numbers LIMIT 6 ``` name: numbers | time | b |round| |--------------------|--------------------|-----| |2023-01-01T00:00:00Z|\-0.163643058925645 | \-0 | |2023-01-01T00:01:00Z| 0.137034364053949 | 0 | |2023-01-01T00:02:00Z|\-0.482943221384294 | \-0 | |2023-01-01T00:03:00Z|\-0.0729732928756677| \-0 | |2023-01-01T00:04:00Z| 1.77857552719844 | 2 | |2023-01-01T00:05:00Z| 0.741147445214238 | 1 | [](#apply-round-to-each-field) Apply `ROUND()` to each field ```sql SELECT ROUND(*) FROM numbers LIMIT 6 ``` name: numbers | time |round\_a|round\_b| |--------------------|--------|--------| |2023-01-01T00:00:00Z| 0 | \-0 | |2023-01-01T00:01:00Z| \-1 | 0 | |2023-01-01T00:02:00Z| \-1 | \-0 | |2023-01-01T00:03:00Z| \-1 | \-0 | |2023-01-01T00:04:00Z| \-1 | 2 | |2023-01-01T00:05:00Z| \-1 | 1 | [](#apply-round-to-time-windows-grouped-by-time) Apply `ROUND()` to time windows (grouped by time) ```sql SELECT ROUND(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time |round| |--------------------|-----| |2023-01-01T00:00:00Z| \-4 | |2023-01-01T00:10:00Z| 1 | |2023-01-01T00:20:00Z| 0 | |2023-01-01T00:30:00Z| 0 | |2023-01-01T00:40:00Z| 0 | |2023-01-01T00:50:00Z| 2 | ## SIN() Returns the sine of a field value. ```sql SIN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-sin-to-a-field) Apply `SIN()` to a field ```sql SELECT b, SIN(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | sin | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 |\-0.1629136686003898| |2023-01-01T00:01:00Z| 0.137034364053949 |0.13660588515594851 | |2023-01-01T00:02:00Z|\-0.482943221384294 |\-0.4643877941052164| |2023-01-01T00:03:00Z|\-0.0729732928756677|\-0.0729085450859347| |2023-01-01T00:04:00Z| 1.77857552719844 | 0.9784914502058565 | |2023-01-01T00:05:00Z| 0.741147445214238 | 0.6751348197618099 | [](#apply-sin-to-each-field) Apply `SIN()` to each field ```sql SELECT SIN(*) FROM numbers LIMIT 6 ``` name: numbers | time | sin\_a | sin\_b | |--------------------|--------------------|--------------------| |2023-01-01T00:00:00Z| 0.3326300722640741 |\-0.1629136686003898| |2023-01-01T00:01:00Z|\-0.6997047077914582|0.13660588515594851 | |2023-01-01T00:02:00Z|\-0.7962295291135749|\-0.4643877941052164| |2023-01-01T00:03:00Z|\-0.673406844448706 |\-0.0729085450859347| |2023-01-01T00:04:00Z|\-0.7870301289278495| 0.9784914502058565 | |2023-01-01T00:05:00Z|\-0.7778043295686337| 0.6751348197618099 | [](#apply-sin-to-time-windows-grouped-by-time) Apply `SIN()` to time windows (grouped by time) ```sql SELECT SIN(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | sin | |--------------------|-------------------| |2023-01-01T00:00:00Z| 0.933528830283535 | |2023-01-01T00:10:00Z|0.9597472276784815 | |2023-01-01T00:20:00Z|0.29712628761434723| |2023-01-01T00:30:00Z|0.2887011711003489 | |2023-01-01T00:40:00Z|0.21934537994884437| |2023-01-01T00:50:00Z|0.9998424824522808 | ## SQRT() Returns the square root of a field value. Field values must be greater than or equal to 0. Negative field values return null. ```sql SQRT(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-sqrt-to-a-field) Apply `SQRT()` to a field ```sql SELECT b, SQRT(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | sqrt | |--------------------|--------------------|------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 | | |2023-01-01T00:01:00Z| 0.137034364053949 |0.370181528515334 | |2023-01-01T00:02:00Z|\-0.482943221384294 | | |2023-01-01T00:03:00Z|\-0.0729732928756677| | |2023-01-01T00:04:00Z| 1.77857552719844 |1.3336324558132349| |2023-01-01T00:05:00Z| 0.741147445214238 |0.860899207349059 | [](#apply-sqrt-to-each-field) Apply `SQRT()` to each field ```sql SELECT SQRT(*) FROM numbers LIMIT 6 ``` name: numbers | time | sqrt\_a | sqrt\_b | |--------------------|------------------|------------------| |2023-01-01T00:00:00Z|0.5823152811928947| | |2023-01-01T00:01:00Z| |0.370181528515334 | |2023-01-01T00:02:00Z| | | |2023-01-01T00:03:00Z| | | |2023-01-01T00:04:00Z| |1.3336324558132349| |2023-01-01T00:05:00Z| |0.860899207349059 | [](#apply-sqrt-to-time-windows-grouped-by-time) Apply `SQRT()` to time windows (grouped by time) ```sql SELECT SQRT(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | sqrt | |--------------------|------------------| |2023-01-01T00:00:00Z| | |2023-01-01T00:10:00Z|1.134063865909604 | |2023-01-01T00:20:00Z|0.5492555015405052| |2023-01-01T00:30:00Z|0.5411746169982342| |2023-01-01T00:40:00Z|0.4702589287652642| |2023-01-01T00:50:00Z|1.2462130097934059| ## TAN() Returns the tangent of the field value. ```sql TAN(field_expression) ``` #### Arguments * **field\_expression**: Expression to identify one or more fields to operate on. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, or wildcard (`*`). Supports numeric field types. #### Notable behaviors * [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). #### Examples The following examples use the[Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data). [](#apply-tan-to-a-field) Apply `TAN()` to a field ```sql SELECT b, TAN(b) FROM numbers LIMIT 6 ``` name: numbers | time | b | tan | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z|\-0.163643058925645 |\-0.16511961248511045| |2023-01-01T00:01:00Z| 0.137034364053949 | 0.13789861917955581 | |2023-01-01T00:02:00Z|\-0.482943221384294 |\-0.5243575352718546 | |2023-01-01T00:03:00Z|\-0.0729732928756677|\-0.07310309943905952| |2023-01-01T00:04:00Z| 1.77857552719844 | \-4.743341375725582 | |2023-01-01T00:05:00Z| 0.741147445214238 | 0.9151958486043346 | [](#apply-tan-to-each-field) Apply `TAN()` to each field ```sql SELECT TAN(*) FROM numbers LIMIT 6 ``` name: numbers | time | tan\_a | tan\_b | |--------------------|--------------------|---------------------| |2023-01-01T00:00:00Z| 0.3527145610408791 |\-0.16511961248511045| |2023-01-01T00:01:00Z|\-0.9793857830953787| 0.13789861917955581 | |2023-01-01T00:02:00Z|\-1.3160934857179802|\-0.5243575352718546 | |2023-01-01T00:03:00Z|\-0.9109052733075013|\-0.07310309943905952| |2023-01-01T00:04:00Z|\-1.2757522322802637| \-4.743341375725582 | |2023-01-01T00:05:00Z|\-1.2375438046768912| 0.9151958486043346 | [](#apply-tan-to-time-windows-grouped-by-time) Apply `TAN()` to time windows (grouped by time) ```sql SELECT TAN(SUM(a)) FROM numbers WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-01-01T01:00:00Z' GROUP BY time(10m) ``` name: numbers | time | tan | |--------------------|-------------------| |2023-01-01T00:00:00Z|\-2.603968631156288| |2023-01-01T00:10:00Z|3.4171098358131733 | |2023-01-01T00:20:00Z|0.31117972731464494| |2023-01-01T00:30:00Z|0.30154101138968664| |2023-01-01T00:40:00Z|0.22482036866737865| |2023-01-01T00:50:00Z| 56.3338223288096 | | time | a | abs | | --- | --- | --- | | time | a | abs | | 2023-01-01T00:00:00Z | 0.33909108671076 | 0.33909108671076 | | 2023-01-01T00:01:00Z | -0.774984088561186 | 0.774984088561186 | | 2023-01-01T00:02:00Z | -0.921037167720451 | 0.921037167720451 | | 2023-01-01T00:03:00Z | -0.73880754843378 | 0.73880754843378 | | 2023-01-01T00:04:00Z | -0.905980032168252 | 0.905980032168252 | | 2023-01-01T00:05:00Z | -0.891164752631417 | 0.891164752631417 | | time | abs_a | abs_b | | --- | --- | --- | | time | abs_a | abs_b | | 2023-01-01T00:00:00Z | 0.33909108671076 | 0.163643058925645 | | 2023-01-01T00:01:00Z | 0.774984088561186 | 0.137034364053949 | | 2023-01-01T00:02:00Z | 0.921037167720451 | 0.482943221384294 | | 2023-01-01T00:03:00Z | 0.73880754843378 | 0.0729732928756677 | | 2023-01-01T00:04:00Z | 0.905980032168252 | 1.77857552719844 | | 2023-01-01T00:05:00Z | 0.891164752631417 | 0.741147445214238 | | time | abs | | --- | --- | | time | abs | | 2023-01-01T00:00:00Z | 0.4345725888930678 | | 2023-01-01T00:10:00Z | 0.12861008519618367 | | 2023-01-01T00:20:00Z | 0.030168160597251192 | | 2023-01-01T00:30:00Z | 0.02928699660831855 | | 2023-01-01T00:40:00Z | 0.02211434600834538 | | 2023-01-01T00:50:00Z | 0.15530468657783394 | | time | a | acos | | --- | --- | --- | | time | a | acos | | 2023-01-01T00:00:00Z | 0.33909108671076 | 1.2248457522250173 | | 2023-01-01T00:01:00Z | -0.774984088561186 | 2.4574862443115 | | 2023-01-01T00:02:00Z | -0.921037167720451 | 2.741531473732281 | | 2023-01-01T00:03:00Z | -0.73880754843378 | 2.4020955294179256 | | 2023-01-01T00:04:00Z | -0.905980032168252 | 2.7044854502651114 | | 2023-01-01T00:05:00Z | -0.891164752631417 | 2.6707024029338 | | time | acos_a | acos_b | | --- | --- | --- | | time | acos_a | acos_b | | 2023-01-01T00:00:00Z | 1.2248457522250173 | 1.7351786975993897 | | 2023-01-01T00:01:00Z | 2.4574862443115 | 1.433329416131427 | | 2023-01-01T00:02:00Z | 2.741531473732281 | 2.074809114132046 | | 2023-01-01T00:03:00Z | 2.4020955294179256 | 1.6438345403920092 | | 2023-01-01T00:04:00Z | 2.7044854502651114 | | | 2023-01-01T00:05:00Z | 2.6707024029338 | 0.7360183965088304 | | time | acos | | --- | --- | | time | acos | | 2023-01-01T00:00:00Z | 2.0203599837582877 | | 2023-01-01T00:10:00Z | 1.441829029328407 | | 2023-01-01T00:20:00Z | 1.5406235882252437 | | 2023-01-01T00:30:00Z | 1.5415051418561052 | | 2023-01-01T00:40:00Z | 1.5486801779072885 | | 2023-01-01T00:50:00Z | 1.41486045205998 | | time | a | asin | | --- | --- | --- | | time | a | asin | | 2023-01-01T00:00:00Z | 0.33909108671076 | 0.34595057456987915 | | 2023-01-01T00:01:00Z | -0.774984088561186 | -0.8866899175166036 | | 2023-01-01T00:02:00Z | -0.921037167720451 | -1.1707351469373848 | | 2023-01-01T00:03:00Z | -0.73880754843378 | -0.8312992026230288 | | 2023-01-01T00:04:00Z | -0.905980032168252 | -1.133689123470215 | | 2023-01-01T00:05:00Z | -0.891164752631417 | -1.0999060761389035 | | time | asin_a | asin_b | | --- | --- | --- | | time | asin_a | asin_b | | 2023-01-01T00:00:00Z | 0.34595057456987915 | -0.1643823708044932 | | 2023-01-01T00:01:00Z | -0.8866899175166036 | 0.1374669106634696 | | 2023-01-01T00:02:00Z | -1.1707351469373848 | -0.5040127873371497 | | 2023-01-01T00:03:00Z | -0.8312992026230288 | -0.07303821359711259 | | 2023-01-01T00:04:00Z | -1.133689123470215 | | | 2023-01-01T00:05:00Z | -1.0999060761389035 | 0.8347779302860662 | | time | asin | | --- | --- | | time | asin | | 2023-01-01T00:00:00Z | -0.44956365696339134 | | 2023-01-01T00:10:00Z | 0.1289672974664895 | | 2023-01-01T00:20:00Z | 0.030172738569652847 | | 2023-01-01T00:30:00Z | 0.029291184938791334 | | 2023-01-01T00:40:00Z | 0.022116148887608062 | | 2023-01-01T00:50:00Z | 0.15593587473491674 | | time | a | atan | | --- | --- | --- | | time | a | atan | | 2023-01-01T00:00:00Z | 0.33909108671076 | 0.32692355076199897 | | 2023-01-01T00:01:00Z | -0.774984088561186 | -0.659300127490126 | | 2023-01-01T00:02:00Z | -0.921037167720451 | -0.7443170183837121 | | 2023-01-01T00:03:00Z | -0.73880754843378 | -0.6362993731936669 | | 2023-01-01T00:04:00Z | -0.905980032168252 | -0.7361091800814261 | | 2023-01-01T00:05:00Z | -0.891164752631417 | -0.727912249468035 | | time | atan_a | atan_b | | --- | --- | --- | | time | atan_a | atan_b | | 2023-01-01T00:00:00Z | 0.32692355076199897 | -0.1622053541422186 | | 2023-01-01T00:01:00Z | -0.659300127490126 | 0.13618613793696105 | | 2023-01-01T00:02:00Z | -0.7443170183837121 | -0.4499093121666581 | | 2023-01-01T00:03:00Z | -0.6362993731936669 | -0.07284417510130452 | | 2023-01-01T00:04:00Z | -0.7361091800814261 | 1.0585985450688151 | | 2023-01-01T00:05:00Z | -0.727912249468035 | 0.6378113578294793 | | time | atan | | --- | --- | | time | atan | | 2023-01-01T00:00:00Z | -0.4099506966510045 | | 2023-01-01T00:10:00Z | 0.1279079463727065 | | 2023-01-01T00:20:00Z | 0.030159013397288013 | | 2023-01-01T00:30:00Z | 0.02927862748761639 | | 2023-01-01T00:40:00Z | 0.022110742100818606 | | 2023-01-01T00:50:00Z | 0.15407382461141705 | | time | atan2 | | --- | --- | | time | atan2 | | 2023-01-01T00:00:00Z | 2.0204217911794937 | | 2023-01-01T00:01:00Z | -1.395783190047229 | | 2023-01-01T00:02:00Z | -2.053731408859953 | | 2023-01-01T00:03:00Z | -1.669248713922653 | | 2023-01-01T00:04:00Z | -0.47112754043763505 | | 2023-01-01T00:05:00Z | -0.8770454978291377 | | time | atan2_a | atan2_b | | --- | --- | --- | | time | atan2_a | atan2_b | | 2023-01-01T00:00:00Z | 0.16794843225523703 | -0.0816396675119722 | | 2023-01-01T00:01:00Z | -0.36967737169970566 | 0.06841026268126137 | | 2023-01-01T00:02:00Z | -0.4315666721698651 | -0.2369359777533473 | | 2023-01-01T00:03:00Z | -0.35385538623378937 | -0.036470468100670846 | | 2023-01-01T00:04:00Z | -0.4253376417906667 | 0.7268651162204586 | | 2023-01-01T00:05:00Z | -0.41917415992493756 | 0.35488446257957357 | | time | atan2 | | --- | --- | | time | atan2 | | 2023-01-01T00:00:00Z | -1.278967897411707 | | 2023-01-01T00:10:00Z | 2.3520553840586773 | | 2023-01-01T00:20:00Z | 2.226497789888965 | | 2023-01-01T00:30:00Z | 3.0977773783018656 | | 2023-01-01T00:40:00Z | 2.9285769547942677 | | 2023-01-01T00:50:00Z | 0.9505419744107901 | | time | b | ceil | | --- | --- | --- | | time | b | ceil | | 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 1 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | | 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | | time | ceil_a | ceil_b | | --- | --- | --- | | time | ceil_a | ceil_b | | 2023-01-01T00:00:00Z | 1 | -0 | | 2023-01-01T00:01:00Z | -0 | 1 | | 2023-01-01T00:02:00Z | -0 | -0 | | 2023-01-01T00:03:00Z | -0 | -0 | | 2023-01-01T00:04:00Z | -0 | 2 | | 2023-01-01T00:05:00Z | -0 | 1 | | time | ceil | | --- | --- | | time | ceil | | 2023-01-01T00:00:00Z | 1 | | 2023-01-01T00:10:00Z | -0 | | 2023-01-01T00:20:00Z | -0 | | 2023-01-01T00:30:00Z | -0 | | 2023-01-01T00:40:00Z | -0 | | 2023-01-01T00:50:00Z | 1 | | time | b | cos | | --- | --- | --- | | time | b | cos | | 2023-01-01T00:00:00Z | -0.163643058925645 | 0.9866403278718959 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0.9906254752128878 | | 2023-01-01T00:02:00Z | -0.482943221384294 | 0.8856319645801471 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | 0.9973386305831397 | | 2023-01-01T00:04:00Z | 1.77857552719844 | -0.20628737691395405 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0.7376943643170851 | | time | cos_a | cos_b | | --- | --- | --- | | time | cos_a | cos_b | | 2023-01-01T00:00:00Z | 0.9430573869206459 | 0.9866403278718959 | | 2023-01-01T00:01:00Z | 0.7144321674550146 | 0.9906254752128878 | | 2023-01-01T00:02:00Z | 0.6049946586273094 | 0.8856319645801471 | | 2023-01-01T00:03:00Z | 0.7392720891861374 | 0.9973386305831397 | | 2023-01-01T00:04:00Z | 0.616914561474936 | -0.20628737691395405 | | 2023-01-01T00:05:00Z | 0.6285065034701617 | 0.7376943643170851 | | time | cos | | --- | --- | | time | cos | | 2023-01-01T00:00:00Z | 0.9914907269510592 | | 2023-01-01T00:10:00Z | 0.9918765457796455 | | 2023-01-01T00:20:00Z | 0.9997307399250498 | | 2023-01-01T00:30:00Z | 0.7850670342365872 | | 2023-01-01T00:40:00Z | 0.9947779847618986 | | 2023-01-01T00:50:00Z | 0.9938532355205111 | | time | cumulative_sum | | --- | --- | | time | cumulative_sum | | 2023-01-01T00:00:00Z | -0.163643058925645 | | 2023-01-01T00:01:00Z | -0.02660869487169601 | | 2023-01-01T00:02:00Z | -0.5095519162559901 | | 2023-01-01T00:03:00Z | -0.5825252091316577 | | 2023-01-01T00:04:00Z | 1.1960503180667823 | | 2023-01-01T00:05:00Z | 1.9371977632810204 | | time | cumulative_sum_a | cumulative_sum_b | | --- | --- | --- | | time | cumulative_sum_a | cumulative_sum_b | | 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | | 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | | 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | | 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | | 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | | 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | | time | cumulative_sum_a | cumulative_sum_b | | --- | --- | --- | | time | cumulative_sum_a | cumulative_sum_b | | 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | | 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | | 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | | 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | | 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | | 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | | time | cumulative_sum | | --- | --- | | time | cumulative_sum | | 2023-01-01T00:00:00Z | 1.3054783385851743 | | 2023-01-01T00:10:00Z | 0.029980276948385454 | | 2023-01-01T00:20:00Z | -0.20208529969578404 | | 2023-01-01T00:30:00Z | -6.882005145666267 | | 2023-01-01T00:40:00Z | -7.904410787756402 | | 2023-01-01T00:50:00Z | -6.795080184131271 | | time | derivative | | --- | --- | | time | derivative | | 2023-01-01T00:01:00Z | 0.005011290382993233 | | 2023-01-01T00:02:00Z | -0.01033295975730405 | | 2023-01-01T00:03:00Z | 0.006832832141810439 | | 2023-01-01T00:04:00Z | 0.03085914700123513 | | 2023-01-01T00:05:00Z | -0.017290468033070033 | | 2023-01-01T00:06:00Z | -0.007557890705063634 | | time | derivative | | --- | --- | | time | derivative | | 2023-01-01T00:01:00Z | 1.5033871148979698 | | 2023-01-01T00:02:00Z | -3.0998879271912148 | | 2023-01-01T00:03:00Z | 2.0498496425431316 | | 2023-01-01T00:04:00Z | 9.257744100370537 | | 2023-01-01T00:05:00Z | -5.187140409921009 | | 2023-01-01T00:06:00Z | -2.26736721151909 | | time | derivative_a | derivative_b | | --- | --- | --- | | time | derivative_a | derivative_b | | 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | | 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | | 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | | 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | | 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | | 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | | time | derivative_a | derivative_b | | --- | --- | --- | | time | derivative_a | derivative_b | | 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | | 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | | 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | | 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | | 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | | 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | | time | derivative | | --- | --- | | time | derivative | | 2023-01-01T00:10:00Z | -0.025809764002219633 | | 2023-01-01T00:20:00Z | 0.010434324849926194 | | 2023-01-01T00:30:00Z | -0.06447854269326314 | | 2023-01-01T00:40:00Z | 0.05657514203880348 | | 2023-01-01T00:50:00Z | 0.021317362457152655 | | time | difference | | --- | --- | | time | difference | | 2023-01-01T00:01:00Z | 0.300677422979594 | | 2023-01-01T00:02:00Z | -0.619977585438243 | | 2023-01-01T00:03:00Z | 0.40996992850862635 | | 2023-01-01T00:04:00Z | 1.8515488200741077 | | 2023-01-01T00:05:00Z | -1.0374280819842019 | | 2023-01-01T00:06:00Z | -0.45347344230381803 | | time | difference_a | difference_b | | --- | --- | --- | | time | difference_a | difference_b | | 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | | 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | | 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | | 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | | 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | | 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | | time | difference_a | difference_b | | --- | --- | --- | | time | difference_a | difference_b | | 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | | 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | | 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | | 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | | 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | | 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | | time | difference | | --- | --- | | time | difference | | 2023-01-01T00:10:00Z | -0.2580976400221963 | | 2023-01-01T00:20:00Z | 0.10434324849926194 | | 2023-01-01T00:30:00Z | -0.6447854269326314 | | 2023-01-01T00:40:00Z | 0.5657514203880348 | | 2023-01-01T00:50:00Z | 0.21317362457152655 | | time | elapsed | | --- | --- | | time | elapsed | | 2023-01-01T00:01:00Z | 60000000000 | | 2023-01-01T00:02:00Z | 60000000000 | | 2023-01-01T00:03:00Z | 60000000000 | | 2023-01-01T00:04:00Z | 60000000000 | | 2023-01-01T00:05:00Z | 60000000000 | | 2023-01-01T00:06:00Z | 60000000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2023-01-01T00:01:00Z | 60 | | 2023-01-01T00:02:00Z | 60 | | 2023-01-01T00:03:00Z | 60 | | 2023-01-01T00:04:00Z | 60 | | 2023-01-01T00:05:00Z | 60 | | 2023-01-01T00:06:00Z | 60 | | time | elapsed_a | elapsed_b | | --- | --- | --- | | time | elapsed_a | elapsed_b | | 2023-01-01T00:01:00Z | 60000000000 | 60000000000 | | 2023-01-01T00:02:00Z | 60000000000 | 60000000000 | | 2023-01-01T00:03:00Z | 60000000000 | 60000000000 | | 2023-01-01T00:04:00Z | 60000000000 | 60000000000 | | 2023-01-01T00:05:00Z | 60000000000 | 60000000000 | | 2023-01-01T00:06:00Z | 60000000000 | 60000000000 | | time | elapsed_a | elapsed_b | | --- | --- | --- | | time | elapsed_a | elapsed_b | | 2023-01-01T00:01:00Z | 60 | 60 | | 2023-01-01T00:02:00Z | 60 | 60 | | 2023-01-01T00:03:00Z | 60 | 60 | | 2023-01-01T00:04:00Z | 60 | 60 | | 2023-01-01T00:05:00Z | 60 | 60 | | 2023-01-01T00:06:00Z | 60 | 60 | | time | a | exp | | --- | --- | --- | | time | a | exp | | 2023-01-01T00:00:00Z | 0.33909108671076 | 1.4036711951820788 | | 2023-01-01T00:01:00Z | -0.774984088561186 | 0.460711111517308 | | 2023-01-01T00:02:00Z | -0.921037167720451 | 0.39810592427186076 | | 2023-01-01T00:03:00Z | -0.73880754843378 | 0.4776831901055915 | | 2023-01-01T00:04:00Z | -0.905980032168252 | 0.40414561525252984 | | 2023-01-01T00:05:00Z | -0.891164752631417 | 0.4101777188333968 | | time | exp_a | exp_b | | --- | --- | --- | | time | exp_a | exp_b | | 2023-01-01T00:00:00Z | 1.4036711951820788 | 0.8490450268435884 | | 2023-01-01T00:01:00Z | 0.460711111517308 | 1.14686755886191 | | 2023-01-01T00:02:00Z | 0.39810592427186076 | 0.6169648527893578 | | 2023-01-01T00:03:00Z | 0.4776831901055915 | 0.929625657322271 | | 2023-01-01T00:04:00Z | 0.40414561525252984 | 5.921415512753404 | | 2023-01-01T00:05:00Z | 0.4101777188333968 | 2.09834186598405 | | time | exp | | --- | --- | | time | exp | | 2023-01-01T00:00:00Z | 0.6475413743155294 | | 2023-01-01T00:10:00Z | 1.137246608416461 | | 2023-01-01T00:20:00Z | 1.030627830373793 | | 2023-01-01T00:30:00Z | 1.029720078241656 | | 2023-01-01T00:40:00Z | 1.0223606806499268 | | 2023-01-01T00:50:00Z | 1.1680137850180072 | | time | b | floor | | --- | --- | --- | | time | b | floor | | 2023-01-01T00:00:00Z | -0.163643058925645 | -1 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -1 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -1 | | 2023-01-01T00:04:00Z | 1.77857552719844 | 1 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0 | | time | floor_a | floor_b | | --- | --- | --- | | time | floor_a | floor_b | | 2023-01-01T00:00:00Z | 0 | -1 | | 2023-01-01T00:01:00Z | -1 | 0 | | 2023-01-01T00:02:00Z | -1 | -1 | | 2023-01-01T00:03:00Z | -1 | -1 | | 2023-01-01T00:04:00Z | -1 | 1 | | 2023-01-01T00:05:00Z | -1 | 0 | | time | floor | | --- | --- | | time | floor | | 2023-01-01T00:00:00Z | -5 | | 2023-01-01T00:10:00Z | 1 | | 2023-01-01T00:20:00Z | 0 | | 2023-01-01T00:30:00Z | 0 | | 2023-01-01T00:40:00Z | 0 | | 2023-01-01T00:50:00Z | 1 | | time | b | ln | | --- | --- | --- | | time | b | ln | | 2023-01-01T00:00:00Z | -0.163643058925645 | | | 2023-01-01T00:01:00Z | 0.137034364053949 | -1.98752355209665 | | 2023-01-01T00:02:00Z | -0.482943221384294 | | | 2023-01-01T00:03:00Z | -0.0729732928756677 | | | 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5758127783016702 | | 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2995556920844895 | | time | ln_a | ln_b | | --- | --- | --- | | time | ln_a | ln_b | | 2023-01-01T00:00:00Z | -1.0814865153308908 | | | 2023-01-01T00:01:00Z | | -1.98752355209665 | | 2023-01-01T00:02:00Z | | | | 2023-01-01T00:03:00Z | | | | 2023-01-01T00:04:00Z | | 0.5758127783016702 | | 2023-01-01T00:05:00Z | | -0.2995556920844895 | | time | ln | | --- | --- | | time | ln | | 2023-01-01T00:00:00Z | | | 2023-01-01T00:10:00Z | 0.25161504572793725 | | 2023-01-01T00:20:00Z | -1.1983831026157092 | | 2023-01-01T00:30:00Z | -1.2280265702380913 | | 2023-01-01T00:40:00Z | -1.5089436474159283 | | 2023-01-01T00:50:00Z | 0.4402187212890264 | | time | b | log | | --- | --- | --- | | time | b | log | | 2023-01-01T00:00:00Z | -0.163643058925645 | | | 2023-01-01T00:01:00Z | 0.137034364053949 | -1.8091219009630797 | | 2023-01-01T00:02:00Z | -0.482943221384294 | | | 2023-01-01T00:03:00Z | -0.0729732928756677 | | | 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5241273780031629 | | 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2726673414946528 | | time | log_a | log_b | | --- | --- | --- | | time | log_a | log_b | | 2023-01-01T00:00:00Z | -0.6719653532302217 | | | 2023-01-01T00:01:00Z | | -1.2349178161776593 | | 2023-01-01T00:02:00Z | | | | 2023-01-01T00:03:00Z | | | | 2023-01-01T00:04:00Z | | 0.3577725949246566 | | 2023-01-01T00:05:00Z | | -0.18612441633827553 | | time | log | | --- | --- | | time | log | | 2023-01-01T00:00:00Z | | | 2023-01-01T00:10:00Z | 0.10927502592347751 | | 2023-01-01T00:20:00Z | -0.5204511686721008 | | 2023-01-01T00:30:00Z | -0.5333251630849791 | | 2023-01-01T00:40:00Z | -0.6553258995757036 | | 2023-01-01T00:50:00Z | 0.1911845614863297 | | time | b | log2 | | --- | --- | --- | | time | b | log2 | | 2023-01-01T00:00:00Z | -0.163643058925645 | | | 2023-01-01T00:01:00Z | 0.137034364053949 | -2.8673903722598544 | | 2023-01-01T00:02:00Z | -0.482943221384294 | | | 2023-01-01T00:03:00Z | -0.0729732928756677 | | | 2023-01-01T00:04:00Z | 1.77857552719844 | 0.8307222397363156 | | 2023-01-01T00:05:00Z | 0.741147445214238 | -0.4321675114403543 | | time | log2_a | log2_b | | --- | --- | --- | | time | log2_a | log2_b | | 2023-01-01T00:00:00Z | -1.560255232456162 | | | 2023-01-01T00:01:00Z | | -2.8673903722598544 | | 2023-01-01T00:02:00Z | | | | 2023-01-01T00:03:00Z | | | | 2023-01-01T00:04:00Z | | 0.8307222397363156 | | 2023-01-01T00:05:00Z | | -0.4321675114403543 | | time | log2 | | --- | --- | | time | log2 | | 2023-01-01T00:00:00Z | | | 2023-01-01T00:10:00Z | 0.36300377868474476 | | 2023-01-01T00:20:00Z | -1.7289013592288134 | | 2023-01-01T00:30:00Z | -1.7716678429623767 | | 2023-01-01T00:40:00Z | -2.1769455171078644 | | 2023-01-01T00:50:00Z | 0.6351013661101591 | | time | b | log10 | | --- | --- | --- | | time | b | log10 | | 2023-01-01T00:00:00Z | -0.163643058925645 | | | 2023-01-01T00:01:00Z | 0.137034364053949 | -0.8631705113283253 | | 2023-01-01T00:02:00Z | -0.482943221384294 | | | 2023-01-01T00:03:00Z | -0.0729732928756677 | | | 2023-01-01T00:04:00Z | 1.77857552719844 | 0.25007231222579585 | | 2023-01-01T00:05:00Z | 0.741147445214238 | -0.1300953840950034 | | time | log10_a | log10_b | | --- | --- | --- | | time | log10_a | log10_b | | 2023-01-01T00:00:00Z | -0.46968362586098245 | | | 2023-01-01T00:01:00Z | | -0.8631705113283253 | | 2023-01-01T00:02:00Z | | | | 2023-01-01T00:03:00Z | | | | 2023-01-01T00:04:00Z | | 0.25007231222579585 | | 2023-01-01T00:05:00Z | | -0.1300953840950034 | | time | log10 | | --- | --- | | time | log10 | | 2023-01-01T00:00:00Z | | | 2023-01-01T00:10:00Z | 0.10927502592347751 | | 2023-01-01T00:20:00Z | -0.520451168672101 | | 2023-01-01T00:30:00Z | -0.5333251630849791 | | 2023-01-01T00:40:00Z | -0.6553258995757036 | | 2023-01-01T00:50:00Z | 0.19118456148632973 | | time | moving_average | | --- | --- | | time | moving_average | | 2023-01-01T00:02:00Z | -0.4523100565236256 | | 2023-01-01T00:03:00Z | -0.8116096015718056 | | 2023-01-01T00:04:00Z | -0.8552749161074944 | | 2023-01-01T00:05:00Z | -0.8453174444111498 | | 2023-01-01T00:06:00Z | -0.5620041570439896 | | 2023-01-01T00:07:00Z | -0.3569778402485757 | | time | moving_average_a | moving_average_b | | --- | --- | --- | | time | moving_average_a | moving_average_b | | 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | | 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | | 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | | 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | | 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | | 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | | time | moving_average_a | moving_average_b | | --- | --- | --- | | time | moving_average_a | moving_average_b | | 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | | 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | | 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | | 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | | 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | | 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | | time | moving_average | | --- | --- | | time | moving_average | | 2023-01-01T00:20:00Z | -0.9193144769987766 | | 2023-01-01T00:30:00Z | 0.626884141339178 | | 2023-01-01T00:40:00Z | 0.27189834404638374 | | 2023-01-01T00:50:00Z | 0.6890200973149928 | | time | non_negative_derivative | | --- | --- | | time | non_negative_derivative | | 2023-01-01T00:01:00Z | 0.005011290382993233 | | 2023-01-01T00:03:00Z | 0.006832832141810439 | | 2023-01-01T00:04:00Z | 0.03085914700123513 | | 2023-01-01T00:08:00Z | 0.0227877053636946 | | 2023-01-01T00:10:00Z | 0.001676063810538834 | | 2023-01-01T00:11:00Z | 0.014999637478226817 | | time | non_negative_derivative | | --- | --- | | time | non_negative_derivative | | 2023-01-01T00:01:00Z | 1.5033871148979698 | | 2023-01-01T00:03:00Z | 2.0498496425431316 | | 2023-01-01T00:04:00Z | 9.257744100370537 | | 2023-01-01T00:08:00Z | 6.836311609108379 | | 2023-01-01T00:10:00Z | 0.5028191431616502 | | 2023-01-01T00:11:00Z | 4.499891243468045 | | time | non_negative_derivative_a | non_negative_derivative_b | | --- | --- | --- | | time | non_negative_derivative_a | non_negative_derivative_b | | 2023-01-01T00:01:00Z | | 0.005011290382993233 | | 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | | 2023-01-01T00:04:00Z | | 0.03085914700123513 | | 2023-01-01T00:05:00Z | 0.00024692132561391543 | | | 2023-01-01T00:06:00Z | 0.016704951104985283 | | | 2023-01-01T00:08:00Z | | 0.0227877053636946 | | 2023-01-01T00:09:00Z | 0.018437240876186967 | | | 2023-01-01T00:10:00Z | | 0.001676063810538834 | | 2023-01-01T00:11:00Z | | 0.014999637478226817 | | 2023-01-01T00:13:00Z | 0.006694752202850366 | | | 2023-01-01T00:14:00Z | 0.011836797386191167 | | | time | non_negative_derivative_a | non_negative_derivative_b | | --- | --- | --- | | time | non_negative_derivative_a | non_negative_derivative_b | | 2023-01-01T00:01:00Z | | 0.005011290382993233 | | 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | | 2023-01-01T00:04:00Z | | 0.03085914700123513 | | 2023-01-01T00:05:00Z | 0.00024692132561391543 | | | 2023-01-01T00:06:00Z | 0.016704951104985283 | | | 2023-01-01T00:08:00Z | | 0.0227877053636946 | | 2023-01-01T00:09:00Z | 0.018437240876186967 | | | 2023-01-01T00:10:00Z | | 0.001676063810538834 | | 2023-01-01T00:11:00Z | | 0.014999637478226817 | | 2023-01-01T00:13:00Z | 0.006694752202850366 | | | 2023-01-01T00:14:00Z | 0.011836797386191167 | | | time | non_negative_derivative | | --- | --- | | time | non_negative_derivative | | 2023-01-01T00:20:00Z | 0.010434324849926194 | | 2023-01-01T00:40:00Z | 0.05657514203880348 | | 2023-01-01T00:50:00Z | 0.021317362457152655 | | time | non_negative_difference | | --- | --- | | time | non_negative_difference | | 2023-01-01T00:01:00Z | 0.300677422979594 | | 2023-01-01T00:03:00Z | 0.40996992850862635 | | 2023-01-01T00:04:00Z | 1.8515488200741077 | | 2023-01-01T00:08:00Z | 1.367262321821676 | | 2023-01-01T00:10:00Z | 0.10056382863233004 | | 2023-01-01T00:11:00Z | 0.899978248693609 | | time | non_negative_difference_a | non_negative_difference_b | | --- | --- | --- | | time | non_negative_difference_a | non_negative_difference_b | | 2023-01-01T00:01:00Z | | 0.300677422979594 | | 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | | 2023-01-01T00:04:00Z | | 1.8515488200741077 | | 2023-01-01T00:05:00Z | 0.014815279536834924 | | | 2023-01-01T00:06:00Z | 1.002297066299117 | | | 2023-01-01T00:08:00Z | | 1.367262321821676 | | 2023-01-01T00:09:00Z | 1.106234452571218 | | | 2023-01-01T00:10:00Z | | 0.10056382863233004 | | 2023-01-01T00:11:00Z | | 0.899978248693609 | | 2023-01-01T00:13:00Z | 0.401685132171022 | | | 2023-01-01T00:14:00Z | 0.71020784317147 | | | time | non_negative_difference_a | non_negative_difference_b | | --- | --- | --- | | time | non_negative_difference_a | non_negative_difference_b | | 2023-01-01T00:01:00Z | | 0.300677422979594 | | 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | | 2023-01-01T00:04:00Z | | 1.8515488200741077 | | 2023-01-01T00:05:00Z | 0.014815279536834924 | | | 2023-01-01T00:06:00Z | 1.002297066299117 | | | 2023-01-01T00:08:00Z | | 1.367262321821676 | | 2023-01-01T00:09:00Z | 1.106234452571218 | | | 2023-01-01T00:10:00Z | | 0.10056382863233004 | | 2023-01-01T00:11:00Z | | 0.899978248693609 | | 2023-01-01T00:13:00Z | 0.401685132171022 | | | 2023-01-01T00:14:00Z | 0.71020784317147 | | | time | non_negative_difference | | --- | --- | | time | non_negative_difference | | 2023-01-01T00:20:00Z | 0.10434324849926194 | | 2023-01-01T00:40:00Z | 0.5657514203880348 | | 2023-01-01T00:50:00Z | 0.21317362457152655 | | time | b | pow | | --- | --- | --- | | time | b | pow | | 2023-01-01T00:00:00Z | -0.163643058925645 | -0.004382205777325515 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0.002573288422171338 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -0.1126388541916811 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0003885901893904874 | | 2023-01-01T00:04:00Z | 1.77857552719844 | 5.626222933751733 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0.4071119474284653 | | time | pow_a | pow_b | | --- | --- | --- | | time | pow_a | pow_b | | 2023-01-01T00:00:00Z | 0.004483135555212479 | -0.00011735131084020357 | | 2023-01-01T00:01:00Z | -0.2795528536239978 | 0.000048322282876973225 | | 2023-01-01T00:02:00Z | -0.6628050073932118 | -0.026271227986693114 | | 2023-01-01T00:03:00Z | -0.22011853819169455 | -0.000002069282189962477 | | 2023-01-01T00:04:00Z | -0.6103699296012646 | 17.797604890097084 | | 2023-01-01T00:05:00Z | -0.5620694808926487 | 0.22362640363833164 | | time | pow | | --- | --- | | time | pow | | 2023-01-01T00:00:00Z | 2402278.159218532 | | 2023-01-01T00:10:00Z | 12.380844221267186 | | 2023-01-01T00:20:00Z | 0.000006244365466732681 | | 2023-01-01T00:30:00Z | 0.0000046424621235691315 | | 2023-01-01T00:40:00Z | 2.7973126174031977e-7 | | 2023-01-01T00:50:00Z | 81.6292140233699 | | time | b | round | | --- | --- | --- | | time | b | round | | 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | | 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | | time | round_a | round_b | | --- | --- | --- | | time | round_a | round_b | | 2023-01-01T00:00:00Z | 0 | -0 | | 2023-01-01T00:01:00Z | -1 | 0 | | 2023-01-01T00:02:00Z | -1 | -0 | | 2023-01-01T00:03:00Z | -1 | -0 | | 2023-01-01T00:04:00Z | -1 | 2 | | 2023-01-01T00:05:00Z | -1 | 1 | | time | round | | --- | --- | | time | round | | 2023-01-01T00:00:00Z | -4 | | 2023-01-01T00:10:00Z | 1 | | 2023-01-01T00:20:00Z | 0 | | 2023-01-01T00:30:00Z | 0 | | 2023-01-01T00:40:00Z | 0 | | 2023-01-01T00:50:00Z | 2 | | time | b | sin | | --- | --- | --- | | time | b | sin | | 2023-01-01T00:00:00Z | -0.163643058925645 | -0.1629136686003898 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13660588515594851 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -0.4643877941052164 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0729085450859347 | | 2023-01-01T00:04:00Z | 1.77857552719844 | 0.9784914502058565 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0.6751348197618099 | | time | sin_a | sin_b | | --- | --- | --- | | time | sin_a | sin_b | | 2023-01-01T00:00:00Z | 0.3326300722640741 | -0.1629136686003898 | | 2023-01-01T00:01:00Z | -0.6997047077914582 | 0.13660588515594851 | | 2023-01-01T00:02:00Z | -0.7962295291135749 | -0.4643877941052164 | | 2023-01-01T00:03:00Z | -0.673406844448706 | -0.0729085450859347 | | 2023-01-01T00:04:00Z | -0.7870301289278495 | 0.9784914502058565 | | 2023-01-01T00:05:00Z | -0.7778043295686337 | 0.6751348197618099 | | time | sin | | --- | --- | | time | sin | | 2023-01-01T00:00:00Z | 0.933528830283535 | | 2023-01-01T00:10:00Z | 0.9597472276784815 | | 2023-01-01T00:20:00Z | 0.29712628761434723 | | 2023-01-01T00:30:00Z | 0.2887011711003489 | | 2023-01-01T00:40:00Z | 0.21934537994884437 | | 2023-01-01T00:50:00Z | 0.9998424824522808 | | time | b | sqrt | | --- | --- | --- | | time | b | sqrt | | 2023-01-01T00:00:00Z | -0.163643058925645 | | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0.370181528515334 | | 2023-01-01T00:02:00Z | -0.482943221384294 | | | 2023-01-01T00:03:00Z | -0.0729732928756677 | | | 2023-01-01T00:04:00Z | 1.77857552719844 | 1.3336324558132349 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0.860899207349059 | | time | sqrt_a | sqrt_b | | --- | --- | --- | | time | sqrt_a | sqrt_b | | 2023-01-01T00:00:00Z | 0.5823152811928947 | | | 2023-01-01T00:01:00Z | | 0.370181528515334 | | 2023-01-01T00:02:00Z | | | | 2023-01-01T00:03:00Z | | | | 2023-01-01T00:04:00Z | | 1.3336324558132349 | | 2023-01-01T00:05:00Z | | 0.860899207349059 | | time | sqrt | | --- | --- | | time | sqrt | | 2023-01-01T00:00:00Z | | | 2023-01-01T00:10:00Z | 1.134063865909604 | | 2023-01-01T00:20:00Z | 0.5492555015405052 | | 2023-01-01T00:30:00Z | 0.5411746169982342 | | 2023-01-01T00:40:00Z | 0.4702589287652642 | | 2023-01-01T00:50:00Z | 1.2462130097934059 | | time | b | tan | | --- | --- | --- | | time | b | tan | | 2023-01-01T00:00:00Z | -0.163643058925645 | -0.16511961248511045 | | 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13789861917955581 | | 2023-01-01T00:02:00Z | -0.482943221384294 | -0.5243575352718546 | | 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.07310309943905952 | | 2023-01-01T00:04:00Z | 1.77857552719844 | -4.743341375725582 | | 2023-01-01T00:05:00Z | 0.741147445214238 | 0.9151958486043346 | | time | tan_a | tan_b | | --- | --- | --- | | time | tan_a | tan_b | | 2023-01-01T00:00:00Z | 0.3527145610408791 | -0.16511961248511045 | | 2023-01-01T00:01:00Z | -0.9793857830953787 | 0.13789861917955581 | | 2023-01-01T00:02:00Z | -1.3160934857179802 | -0.5243575352718546 | | 2023-01-01T00:03:00Z | -0.9109052733075013 | -0.07310309943905952 | | 2023-01-01T00:04:00Z | -1.2757522322802637 | -4.743341375725582 | | 2023-01-01T00:05:00Z | -1.2375438046768912 | 0.9151958486043346 | | time | tan | | --- | --- | | time | tan | | 2023-01-01T00:00:00Z | -2.603968631156288 | | 2023-01-01T00:10:00Z | 3.4171098358131733 | | 2023-01-01T00:20:00Z | 0.31117972731464494 | | 2023-01-01T00:30:00Z | 0.30154101138968664 | | 2023-01-01T00:40:00Z | 0.22482036866737865 | | 2023-01-01T00:50:00Z | 56.3338223288096 | --- # GROUP BY clause Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/group-by/ Use the `GROUP BY` clause to group data by one or more specified[tags](/influxdb3/core/reference/glossary/#tag) or into specified time intervals.`GROUP BY` requires an [aggregate](/influxdb3/core/reference/influxql/functions/aggregates/)or [selector](/influxdb3/core/reference/influxql/functions/selectors/)function in the `SELECT` statement. * [Syntax](#syntax) * [GROUP BY clause behaviors](#group-by-clause-behaviors) * [GROUP BY tags](#group-by-tags) * [GROUP BY tags examples](#group-by-tags-examples) * [GROUP BY time](#group-by-time) * [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) * [GROUP BY time examples](#group-by-time-examples)- [GROUP BY time with offset](#group-by-time-with-offset)- [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) * [Result set](#result-set) * [Default time range](#default-time-range) * [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) * [Cannot group by fields](#cannot-group-by-fields) * [Tag order does not matter](#tag-order-does-not-matter) * [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) * [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) * [Example data](#example-data) * [Query results](#query-results) * [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) * [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) * [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) ## Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] ``` * **group\_expression**: Expression to identify tags or time intervals to group by. Can be a [tag key](/influxdb3/core/reference/glossary/#tag-key), constant, [regular expression](/influxdb3/core/reference/influxql/regular-expressions/), wildcard (`*`), or [function expression](/influxdb3/core/reference/influxql/functions/). ## GROUP BY clause behaviors * `GROUP BY tag_key` - Groups data by a specific tag * `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag * `GROUP BY *` - Groups data by all [tags](/influxdb3/core/reference/glossary/#tag) * `GROUP BY /regex/` - Groups data by tag keys that match the regular expression * `GROUP BY time()` - Groups data into time intervals (windows) > [!Note] > If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear after > the `WHERE` clause. ## GROUP BY tags Groups data by one or more tag columns. ### GROUP BY tags examples The following examples use the[Bitcoin price sample data](/influxdb3/core/reference/sample-data/#bitcoin-price-data). [](#group-data-by-a-single-tag) Group data by a single tag ```sql SELECT MEAN(*) FROM bitcoin GROUP BY code ``` name: bitcoin tags: code=EUR | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|27328.848667840004| name: bitcoin tags: code=GBP | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|23441.832453919982| name: bitcoin tags: code=USD | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|28054.160950480004| [](#group-data-by-more-than-one-tag) Group data by more than one tag ```sql SELECT MEAN(*) FROM bitcoin GROUP BY code, description ``` name: bitcoin tags: code=EUR, description=Euro | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|27328.848667840004| name: bitcoin tags: code=GBP, description=British Pound Sterling | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|23441.832453919982| name: bitcoin tags: code=USD, description=United States Dollar | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|28054.160950480004| [](#group-data-by-all-tags) Group data by all tags ```sql SELECT MEAN(*) FROM bitcoin GROUP BY * ``` name: bitcoin tags: code=EUR, crypto=bitcoin, description=Euro, symbol=€ | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|27328.848667840004| name: bitcoin tags: code=GBP, crypto=bitcoin, description=British Pound Sterling, symbol=£ | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|23441.832453919982| name: bitcoin tags: code=USD, crypto=bitcoin, description=United States Dollar, symbol=$ | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|28054.160950480004| [](#group-data-by-tag-keys-that-match-a-regular-expression) Group data by tag keys that match a regular expression ```sql SELECT MEAN(*) FROM bitcoin GROUP BY /^[cd]/ ``` name: bitcoin tags: code=EUR, crypto=bitcoin, description=Euro | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|27328.848667840004| name: bitcoin tags: code=GBP, crypto=bitcoin, description=British Pound Sterling | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|23441.832453919982| name: bitcoin tags: code=USD, crypto=bitcoin, description=United States Dollar | time | mean\_price | |--------------------|------------------| |1970-01-01T00:00:00Z|28054.160950480004| ## GROUP BY time `GROUP BY time()` groups data by into specified time intervals, also known as “windows”, and applies the [aggregate](/influxdb3/core/reference/influxql/functions/aggregates/)and [selector](/influxdb3/core/reference/influxql/functions/selectors/)functions in the `SELECT` clause to each interval. Use the [`time()` function](/influxdb3/core/reference/influxql/functions/date-time/#time)to specify the time interval to group by. ```sql SELECT_clause FROM_clause WHERE GROUP BY time(time_interval[, offset])[, group_expression (...)] [fill(behavior)] ``` `GROUP BY time()` intervals use preset round-number time boundaries that are independent of time conditions in the [`WHERE` clause](/influxdb3/core/reference/influxql/where/).**Output data uses window start boundaries as the aggregate timestamps.**Use the `offset` argument of the `time()` function to shift time boundaries forward or backward in time. ### GROUP by time and fill gaps When grouping by time, if a window in the queried time range does not contain data, results return a row for the empty window containing the timestamp of the empty window and *null* values for each queried field. Use the [`fill()` function](/influxdb3/core/reference/influxql/functions/misc/#fill)*at the end of the `GROUP BY` clause* to replace *null* field values. If no `FILL` clause is included, the default behavior is `fill(null)`. `fill()` provides the following behaviors for filling values: * **numeric literal**: Replaces null values with the specified numeric literal. * **linear**: Uses linear interpolation between existing values to replace null values. * **none**: Removes rows with null field values. * **null**: Keeps null values and associated timestamps. * **previous**: Replaces null values with the most recent non-null value. *See the [`fill()` documentation](/influxdb3/core/reference/influxql/functions/misc/#fill)for detailed examples.* ### GROUP BY time examples The following examples use the[Bitcoin price sample data](/influxdb3/core/reference/sample-data/#bitcoin-price-data). [](#group-and-aggregate-query-results-into-1-hour-windows) Group and aggregate query results into 1 hour windows ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-15T00:00:00Z' GROUP BY time(1h) ``` name: bitcoin | time | mean | |--------------------|------------------| |2023-05-01T00:00:00Z| 24494.27265 | |2023-05-01T01:00:00Z| 24452.1698 | |2023-05-01T02:00:00Z|23902.666124999996| |2023-05-01T03:00:00Z|23875.211349999998| |2023-05-01T04:00:00Z| 23855.6441 | | … | … | [](#group-and-aggregate-query-results-into-1-week-intervals-by-tag) Group and aggregate query results into 1 week intervals by tag ```sql SELECT MEAN(price) FROM bitcoin WHERE time >= '2023-05-01T00:00:00Z' AND time < '2023-05-15T00:00:00Z' GROUP BY time(1w), code ``` name: bitcoin tags: code=EUR | time | mean | |--------------------|------------------| |2023-04-27T00:00:00Z|27681.21808576779 | |2023-05-04T00:00:00Z|27829.413580354256| |2023-05-11T00:00:00Z|26210.24799033149 | name: bitcoin tags: code=GBP | time | mean | |--------------------|------------------| |2023-04-27T00:00:00Z|23744.083925842704| |2023-05-04T00:00:00Z|23871.201395652173| |2023-05-11T00:00:00Z|22482.33174723755 | name: bitcoin tags: code=USD | time | mean | |--------------------|------------------| |2023-04-27T00:00:00Z|28415.88231123595 | |2023-05-04T00:00:00Z|28568.010941384844| |2023-05-11T00:00:00Z|26905.87242099449 | ###### GROUP BY time with offset [](#group-and-aggregate-query-results-into-1-hour-intervals-and-offset-time-boundaries-by-15-minutes) Group and aggregate query results into 1 hour intervals and offset time boundaries by +15 minutes ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-02T00:00:00Z' GROUP BY time(1h, 15m) ``` name: bitcoin | time | mean | |--------------------|------------------| |2023-04-30T23:15:00Z| | |2023-05-01T00:15:00Z| 29313.6754 | |2023-05-01T01:15:00Z| 28932.0882 | |2023-05-01T02:15:00Z|28596.375225000003| |2023-05-01T03:15:00Z| 28578.915075 | | … | … | *Note that `offset` forces the first time boundary to be outside the queried time range so the query returns no results for that first interval.* [](#group-and-aggregate-query-results-into-1-hour-intervals-and-offset-time-boundaries-by--15-minutes) Group and aggregate query results into 1 hour intervals and offset time boundaries by -15 minutes ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-02T00:00:00Z' GROUP BY time(1h, -15m) ``` name: bitcoin | time | mean | |--------------------|------------------| |2023-04-30T23:45:00Z| 29319.9092 | |2023-05-01T00:45:00Z| 29285.3651 | |2023-05-01T01:45:00Z|28607.202666666668| |2023-05-01T02:45:00Z| 28576.056175 | |2023-05-01T03:45:00Z| 28566.96315 | | … | … | ###### GROUP BY time and fill gaps [](#group-and-aggregate-query-results-into-30-minute-intervals-and-fill-gaps-with-0) Group and aggregate query results into 30 minute intervals and fill gaps with `0` ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(0) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z| 0 | |2023-05-01T01:30:00Z|29263.2886| [](#group-and-aggregate-query-results-into-30-minute-intervals-and-fill-gaps-using-linear-interpolation) Group and aggregate query results into 30 minute intervals and fill gaps using linear interpolation ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(linear) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z|29285.3651| |2023-05-01T01:30:00Z|29263.2886| [](#group-and-aggregate-query-results-into-30-minute-intervals-and-fill-gaps-with-previous-values) Group and aggregate query results into 30 minute intervals and fill gaps with previous values ```sql SELECT MEAN(price) FROM bitcoin WHERE code = 'USD' AND time >= '2023-05-01T00:00:00Z' AND time < '2023-05-01T02:00:00Z' GROUP BY time(30m) fill(previous) ``` name: bitcoin | time | mean | |--------------------|----------| |2023-05-01T00:00:00Z|29319.9092| |2023-05-01T00:30:00Z|29307.4416| |2023-05-01T01:00:00Z|29307.4416| |2023-05-01T01:30:00Z|29263.2886| ## Result set If at least one row satisfies the query, InfluxDB 3 Core returns row data in the query result set. If a query uses a `GROUP BY` clause, the result set includes the following: * Columns listed in the query’s `SELECT` clause * A `time` column that contains the timestamp for the record or the group * An `iox::measurement` column that contains the record’s measurement (table) name * Columns listed in the query’s `GROUP BY` clause; each row in the result set contains the values used for grouping ### Default time range If a query doesn’t specify a time range in the[`WHERE` clause](/influxdb3/core/reference/influxql/where/), InfluxDB uses the[default time range](/influxdb3/core/reference/influxql/#default-time-range) for filtering and grouping by time. If a query includes the `GROUP BY` clause and doesn’t specify a time range in the`WHERE` clause, the default time group is the[default time range](/influxdb3/core/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range–for example: ```sql SELECT mean(temp) FROM home GROUP BY room ``` name: home tags: room=Kitchen | time | mean | |--------------------|------------------| |1970-01-01T00:00:00Z|22.623076923076926| name: home tags: room=Living Room | time | mean | |--------------------|-----------------| |1970-01-01T00:00:00Z|22.16923076923077| ## Notable behaviors of the GROUP BY clause ### Cannot group by fields InfluxQL does not support grouping data by **fields**. ### Tag order does not matter The order that tags are listed in the `GROUP BY` clause does not affect how data is grouped. ### Grouping by tag and no time range returns unexpected timestamps The `time` column contains the start of the [default time range](#default-time-range). ### Data grouped by time may return unexpected timestamps Because `GROUP BY time()` intervals use preset round-number time boundaries that are independent of time conditions in the [`WHERE` clause](/influxdb3/core/reference/influxql/where/), results may include timestamps outside of the queried time range. Results represent only data with timestamps in the specified time range, but output timestamps are determined by by the preset time boundaries. The following example groups data by 1-hour intervals, but the time range defined in the `WHERE` clause covers only part of a window: ``` SELECT MEAN(field) FROM example WHERE time >= '2022-01-01T00:30:00Z' AND time <= '2022-01-01T01:30:00Z' GROUP BY time(1h) ``` > [!Note] > **Note**: The timestamp in the first row of query results data occurs before the start of > the queried time range.[See why](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range). #### Example data | time |field| |--------------------|-----| |2022-01-01T00:00:00Z| 8 | |2022-01-01T00:15:00Z| 4 | |2022-01-01T00:30:00Z| 0 | |2022-01-01T00:45:00Z| 8 | |2022-01-01T01:00:00Z| 5 | |2022-01-01T01:15:00Z| 0 | |2022-01-01T01:30:00Z| 8 | |2022-01-01T01:45:00Z| 8 | |2022-01-01T02:00:00Z| 9 | |2022-01-01T02:15:00Z| 6 | |2022-01-01T02:30:00Z| 3 | |2022-01-01T02:45:00Z| 0 | #### Query results | time |field| |--------------------|-----| |2022-01-01T00:00:00Z| 4 | |2022-01-01T01:00:00Z|5.25 | |2022-01-01T02:00:00Z| 6 | [](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range) Why do these results include timestamps outside of the queried time range? `GROUP BY time()` creates windows with predefined time boundaries based on the specified interval. These boundaries are not determined by the queried time range, however, aggregate values in query results are calculated using only values that are in the queried time range. | time |field| |:-------------------|----:| |2022-01-01T00:00:00Z| 8 | |2022-01-01T00:15:00Z| 4 | |2022-01-01T00:30:00Z| 0 | |2022-01-01T00:45:00Z| 8 | |2022-01-01T01:00:00Z| 5 | |2022-01-01T01:15:00Z| 0 | |2022-01-01T01:30:00Z| 8 | |2022-01-01T01:45:00Z| 8 | |2022-01-01T02:00:00Z| 9 | |2022-01-01T02:15:00Z| 6 | |2022-01-01T02:30:00Z| 3 | |2022-01-01T02:45:00Z| 0 | 2022-01-01T00:00:00Z 2022-01-01T01:00:00Z 2022-01-01T02:00:00Z ### Fill with no data in the queried time range Queries ignore `fill()` if no data exists in the queried time range. This is the expected behavior. ### Fill with previous if no previous value exists `fill(previous)` doesn’t fill null values if there is no previous value in the queried time range. ### Fill with linear interpolation if there are not two values to interpolate between `fill(linear)` doesn’t fill null values if there are no values before or after the null value in the queried time range. | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 27328.848667840004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 23441.832453919982 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 28054.160950480004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 27328.848667840004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 23441.832453919982 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 28054.160950480004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 27328.848667840004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 23441.832453919982 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 28054.160950480004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 27328.848667840004 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 23441.832453919982 | | time | mean_price | | --- | --- | | time | mean_price | | 1970-01-01T00:00:00Z | 28054.160950480004 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 24494.27265 | | 2023-05-01T01:00:00Z | 24452.1698 | | 2023-05-01T02:00:00Z | 23902.666124999996 | | 2023-05-01T03:00:00Z | 23875.211349999998 | | 2023-05-01T04:00:00Z | 23855.6441 | | … | … | | time | mean | | --- | --- | | time | mean | | 2023-04-27T00:00:00Z | 27681.21808576779 | | 2023-05-04T00:00:00Z | 27829.413580354256 | | 2023-05-11T00:00:00Z | 26210.24799033149 | | time | mean | | --- | --- | | time | mean | | 2023-04-27T00:00:00Z | 23744.083925842704 | | 2023-05-04T00:00:00Z | 23871.201395652173 | | 2023-05-11T00:00:00Z | 22482.33174723755 | | time | mean | | --- | --- | | time | mean | | 2023-04-27T00:00:00Z | 28415.88231123595 | | 2023-05-04T00:00:00Z | 28568.010941384844 | | 2023-05-11T00:00:00Z | 26905.87242099449 | | time | mean | | --- | --- | | time | mean | | 2023-04-30T23:15:00Z | | | 2023-05-01T00:15:00Z | 29313.6754 | | 2023-05-01T01:15:00Z | 28932.0882 | | 2023-05-01T02:15:00Z | 28596.375225000003 | | 2023-05-01T03:15:00Z | 28578.915075 | | … | … | | time | mean | | --- | --- | | time | mean | | 2023-04-30T23:45:00Z | 29319.9092 | | 2023-05-01T00:45:00Z | 29285.3651 | | 2023-05-01T01:45:00Z | 28607.202666666668 | | 2023-05-01T02:45:00Z | 28576.056175 | | 2023-05-01T03:45:00Z | 28566.96315 | | … | … | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 0 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 29285.3651 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 2023-05-01T00:00:00Z | 29319.9092 | | 2023-05-01T00:30:00Z | 29307.4416 | | 2023-05-01T01:00:00Z | 29307.4416 | | 2023-05-01T01:30:00Z | 29263.2886 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 22.623076923076926 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 22.16923076923077 | | time | field | | --- | --- | | time | field | | 2022-01-01T00:00:00Z | 8 | | 2022-01-01T00:15:00Z | 4 | | 2022-01-01T00:30:00Z | 0 | | 2022-01-01T00:45:00Z | 8 | | 2022-01-01T01:00:00Z | 5 | | 2022-01-01T01:15:00Z | 0 | | 2022-01-01T01:30:00Z | 8 | | 2022-01-01T01:45:00Z | 8 | | 2022-01-01T02:00:00Z | 9 | | 2022-01-01T02:15:00Z | 6 | | 2022-01-01T02:30:00Z | 3 | | 2022-01-01T02:45:00Z | 0 | | time | field | | --- | --- | | time | field | | 2022-01-01T00:00:00Z | 4 | | 2022-01-01T01:00:00Z | 5.25 | | 2022-01-01T02:00:00Z | 6 | | time | field | | --- | --- | | time | field | | 2022-01-01T00:00:00Z | 8 | | 2022-01-01T00:15:00Z | 4 | | 2022-01-01T00:30:00Z | 0 | | 2022-01-01T00:45:00Z | 8 | | 2022-01-01T01:00:00Z | 5 | | 2022-01-01T01:15:00Z | 0 | | 2022-01-01T01:30:00Z | 8 | | 2022-01-01T01:45:00Z | 8 | | 2022-01-01T02:00:00Z | 9 | | 2022-01-01T02:15:00Z | 6 | | 2022-01-01T02:30:00Z | 3 | | 2022-01-01T02:45:00Z | 0 | --- # InfluxQL internals Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/internals/ Learn about the implementation of InfluxQL to understand how results are processed and how to create efficient queries: * [Query life cycle](#query-life-cycle) * [Understanding iterators](#understanding-iterators) * [Cursors](#cursors) * [Auxiliary fields](#auxiliary-fields) * [Built-in iterators](#built-in-iterators) * [Call iterators](#call-iterators) ## Query life cycle 1. InfluxQL query string is tokenized and then parsed into an abstract syntax tree (AST). This is the code representation of the query itself. 2. The AST is passed to the `QueryExecutor` which directs queries to the appropriate handlers. For example, queries related to meta data are executed by the **meta service** and `SELECT` statements are executed by the shards themselves. 3. The query engine then determines the shards that match the `SELECT`statement’s time range. From these shards, iterators are created for each field in the statement. 4. Iterators are passed to the emitter which drains them and joins the resulting points. The emitter’s job is to convert simple time/value points into the more complex result objects that are returned to the client. ### Understanding iterators Iterators provide a simple interface for looping over a set of points. For example, this is an iterator over Float points: ``` type FloatIterator interface { Next() *FloatPoint } ``` These iterators are created through the `IteratorCreator` interface: ``` type IteratorCreator interface { CreateIterator(opt *IteratorOptions) (Iterator, error) } ``` The `IteratorOptions` provide arguments about field selection, time ranges, and dimensions that the iterator creator can use when planning an iterator. The `IteratorCreator` interface is used at many levels such as the `Shards`,`Shard`, and `Engine`. This allows optimizations to be performed when applicable such as returning a precomputed `COUNT()`. Iterators aren’t just for reading raw data from storage, though. Iterators can be composed so that they provide additional functionality around an input iterator. For example, a `DistinctIterator` can compute the distinct values for each time window for an input iterator. Or a `FillIterator` can generate additional points that are missing from an input iterator. This composition also lends itself well to aggregation. For example, in the following SQL, `MEAN(value)` is a `MeanIterator` that wraps an iterator from the underlying shards: ```sql SELECT MEAN(value) FROM cpu GROUP BY time(10m) ``` The following example wraps `MEAN(value)` with an additional iterator (`DERIVATIVE()`) to determine the derivative of the mean: ```sql SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m) ``` ### Cursors A **cursor** identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor traverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the `(time, value)` tuples by time in ascending or descending order. For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard). ### Auxiliary fields Because InfluxQL allows users to use selector functions such as `FIRST()`,`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related data at the same time with the selected point. Let’s look at the following query: ```sql SELECT FIRST(value), host FROM cpu GROUP BY time(1h) ``` We are selecting the first `value` that occurs every hour but we also want to retrieve the `host` associated with that point. Since the `Point` types only specify a single typed `Value` for efficiency, we push the `host` into the auxiliary fields of the point. These auxiliary fields are attached to the point until it is passed to the emitter where the fields get split off to their own iterator. ### Built-in iterators There are many helper iterators that let us build queries: * Merge Iterator - This iterator combines one or more iterators into a single new iterator of the same type. This iterator guarantees that all points within a window will be output before starting the next window, but does not provide ordering guarantees within the window. This allows for fast access for aggregate queries that don’t need stronger sorting guarantees. * Sorted Merge Iterator - Like `MergeIterator`, this iterator combines one or more iterators into a new iterator of the same type. However, this iterator guarantees time ordering of every point. This makes it slower than the `MergeIterator`but this ordering guarantee is required for non-aggregate queries which return the raw data points. * Limit Iterator - This iterator limits the number of points per name or tag group. This is the implementation of the `LIMIT` & `OFFSET` syntax. * Fill Iterator - This iterator injects extra points if they are missing from the input iterator. It can provide `null` points, points with the previous value, or points with a specific value. * Buffered Iterator - This iterator provides the ability to “unread” a point back onto a buffer so it can be read again next time. This is used extensively to provide lookahead for windowing. * Reduce Iterator - This iterator calls a reduction function for each point in a window. When the window is complete, then all points for that window are output. This is used for simple aggregate functions such as `COUNT()`. * Reduce Slice Iterator - This iterator collects all points for a window first, and then passes them all to a reduction function at once. The results are returned from the iterator. This is used for aggregate functions such as`DERIVATIVE()`. * Transform Iterator - This iterator calls a transform function for each point from an input iterator. This is used for executing binary expressions. * Dedupe Iterator - This iterator only outputs unique points. Because it is resource-intensive, this iterator is only used for small queries such as meta query statements. ### Call iterators Function calls in InfluxQL are implemented at two levels: * Some calls can be wrapped at multiple layers to improve efficiency. For example, a `COUNT()` can be performed at the shard level and then multiple `CountIterator`s can be wrapped with another `CountIterator` to compute the count of all shards. These iterators can be created using `NewCallIterator()`. * Some iterators are more complex or need to be implemented at a higher level. For example, the `DERIVATIVE()` function needs to retrieve all points for a window before performing the calculation. This iterator is created by the engine itself and is never requested to be created by the lower levels. --- # LIMIT and SLIMIT clauses Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/limit-and-slimit/ Use `LIMIT` to limit the number of **rows** returned per InfluxQL group. Use `SLIMIT` to limit the number of [series](/influxdb3/core/reference/glossary/#series)returned in query results. * [LIMIT clause](#limit-clause) * [Syntax](#limit-syntax) * [Examples](#limit-examples) * [SLIMIT clause](#slimit-clause) ## LIMIT clause The `LIMIT` clause limits the number of rows to return from each InfluxQL group. If the query doesn’t include a [`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/), the entire result set is considered a single group. If a query [groups data by time](/influxdb3/core/reference/influxql/group-by/#group-by-time), limits are applied after aggregate and selector operations are applied to each time window. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT N ``` #### Arguments * **N**: Maximum number of points to return from each InfluxQL group. If `N` is greater than the number of points in a group, all points from the group are returned. ### Examples The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). [](#limit-the-number-of-rows-returned) Limit the number of rows returned ```sql SELECT * FROM home LIMIT 3 ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T08:00:00Z| 0 |35.9| Kitchen | 21 | |2022-01-01T08:00:00Z| 0 |35.9|Living Room|21.1| |2022-01-01T09:00:00Z| 0 |36.2| Kitchen | 23 | [](#limit-the-number-of-rows-returned-from-each-influxql-group) Limit the number of rows returned from each InfluxQL group ```sql SELECT MEAN(*) FROM home GROUP BY time(2h), room LIMIT 3 ``` name: home tags: room=Kitchen | time |mean\_co|mean\_hum| mean\_temp | |--------------------|--------|---------|------------------| |2022-01-01T08:00:00Z| 0 | 36.05 | 22 | |2022-01-01T10:00:00Z| 0 | 36.05 |22.549999999999997| |2022-01-01T12:00:00Z| 0.5 | 36.25 | 22.65 | name: home tags: room=Living Room | time |mean\_co|mean\_hum| mean\_temp | |--------------------|--------|---------|------------------| |2022-01-01T08:00:00Z| 0 | 35.9 | 21.25 | |2022-01-01T10:00:00Z| 0 | 36 | 22 | |2022-01-01T12:00:00Z| 0 | 35.95 |22.299999999999997| ## SLIMIT clause > [!Important] > InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. > This process is ongoing and some InfluxQL features, such as `SLIMIT` are still > being implemented. For more information, see[InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/). | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | time | mean_co | mean_hum | mean_temp | | --- | --- | --- | --- | | time | mean_co | mean_hum | mean_temp | | 2022-01-01T08:00:00Z | 0 | 36.05 | 22 | | 2022-01-01T10:00:00Z | 0 | 36.05 | 22.549999999999997 | | 2022-01-01T12:00:00Z | 0.5 | 36.25 | 22.65 | | time | mean_co | mean_hum | mean_temp | | --- | --- | --- | --- | | time | mean_co | mean_hum | mean_temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | 21.25 | | 2022-01-01T10:00:00Z | 0 | 36 | 22 | | 2022-01-01T12:00:00Z | 0 | 35.95 | 22.299999999999997 | --- # InfluxQL math operators Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/math-operators/ Use InfluxQL mathematical operators to perform mathematical operations in InfluxQL queries. Mathematical operators follow the [standard order of operations](https://golang.org/ref/spec#Operator_precedence). Parentheses take precedence to division and multiplication, which takes precedence to addition and subtraction. For example `5 / 2 + 3 * 2 = (5 / 2) + (3 * 2)` and `5 + 2 * 3 - 2 = 5 + (2 * 3) - 2`. * [Addition](#addition) * [Subtraction](#subtraction) * [Multiplication](#multiplication) * [Division](#division) * [Modulo](#modulo) * [Bitwise AND](#bitwise-and) * [Bitwise OR](#bitwise-or) * [Bitwise Exclusive-OR](#bitwise-exclusive-or) * [Unsupported Operators](#unsupported-operators) * [Notable behaviors of mathematical operators](#notable-behaviors-of-mathematical-operators) ## Addition Add two numeric operands. Operands may be an identifier, constant, or literal numeric value. ```sql SELECT A + 5 FROM example SELECT A + B FROM example SELECT * FROM example WHERE A + 5 > 10 SELECT * FROM example WHERE A + B > 10 ``` ## Subtraction Subtract one numeric operand from another. Operands may be an identifier, constant, or literal numeric value. ```sql SELECT 1 - A FROM example SELECT B - A FROM example SELECT * FROM example WHERE 1 - A <= 3 SELECT * FROM example WHERE B - A <= 3 ``` ## Multiplication Multiply two numeric operands. Operands may be an identifier, constant, or literal numeric value. ```sql SELECT A * 10 FROM example SELECT A * B FROM example SELECT * FROM example WHERE A * 10 >= 20 SELECT * FROM example WHERE A * B >= 20 ``` Multiplication distributes across other operators. ```sql SELECT 10 * (A + B + C) FROM example SELECT 10 * (A - B - C) FROM example SELECT 10 * (A + B - C) FROM example ``` ## Division Divide one numeric operand by another. Operands may be an identifier, constant, or literal numeric value. ```sql SELECT A / 10 FROM example SELECT A / B FROM example SELECT * FROM example WHERE A / 10 <= 2 SELECT * FROM example WHERE A / B <= 2 ``` Division distributes across other operators. ```sql SELECT 10 / (A + B + C) FROM example SELECT 10 / (A - B - C) FROM example SELECT 10 / (A + B - C) FROM example ``` ## Modulo Perform a modulo operation with two numeric operands. Operands may be an identifier, constant, or literal numeric value. ```sql SELECT A % 2 FROM example SELECT A % B FROM example SELECT A FROM example WHERE A % 2 = 0 SELECT A, B FROM example WHERE A % B = 0 ``` ## Bitwise AND Perform a bitwise `AND` operation on two operands *of the same type*. Supported types are **integers** and **booleans**. Operands may be an identifier, constant, literal integer value, or literal boolean value. ```sql SELECT A & 255 FROM example SELECT A & B FROM example SELECT (A ^ true) & B FROM example SELECT * FROM example WHERE A & 15 > 0 ``` ## Bitwise OR Perform a bitwise `OR` operation on two operands *of the same type*. Supported types are **integers** and **booleans**. Operands may be an identifier, constant, literal integer value, or literal boolean value. ```sql SELECT A | 5 FROM example SELECT A | B FROM example SELECT * FROM example WHERE "bitfield" | 12 = 12 ``` ## Bitwise Exclusive-OR Perform a bitwise `Exclusive-OR` operation on two operands *of the same type*. Supported types are **integers** and **booleans**. Operands may be an identifier, constant, literal integer value, or literal boolean value. ```sql SELECT A ^ 255 FROM example SELECT A ^ B FROM example SELECT * FROM example WHERE "bitfield" ^ 6 > 0 ``` ## Unsupported Operators ### Inequalities Using any of `=`,`!=`,`<`,`>`,`<=`,`>=`,`<>` in the `SELECT` statement yields empty results for all types. Comparison operators can only be used in the `WHERE` clause. ### Logical Operators Using any of `!|`,`NAND`,`XOR`,`NOR` yield a parser error. Additionally using `AND`, `OR` in the `SELECT` clause of a query will not behave as mathematical operators and simply yield empty results, as they are InfluxQL tokens. However, you can apply the bitwise operators `&`, `|` and `^` to boolean values. ### Bitwise Not There is no bitwise-not operator, because the results you expect depend on the width of your bitfield. InfluxQL does not know how wide your bitfield is, so cannot implement a suitable bitwise-not operator. For example, if your bitfield is 8 bits wide, then the integer 1 represents the bits `0000 0001`. The bitwise-not of this should return the bits `1111 1110` (that is, the integer 254) However, if your bitfield is 16 bits wide, then the integer 1 represents the bits `0000 0000 0000 0001`. The bitwise-not of this should return the bits `1111 1111 1111 1110` (that is, the integer 65534) #### Solution You can implement a bitwise-not operation by using the `^` (bitwise xor) operator together with the number representing all-ones for your word-width: For 8-bit data: ```sql SELECT A ^ 255 FROM example ``` For 16-bit data: ```sql SELECT A ^ 65535 FROM example ``` For 32-bit data: ```sql SELECT A ^ 4294967295 FROM example ``` In each case, the constant you need can be calculated as `(2 ** width) - 1`. ## Notable behaviors of mathematical operators * [Mathematical operators with wildcards and regular expressions](#mathematical-operators-with-wildcards-and-regular-expressions) * [Mathematical operators with functions](#mathematical-operators-with-functions) ### Mathematical operators with wildcards and regular expressions InfluxQL does not support combining mathematical operations with a wildcard (`*`) or [regular expression](/influxdb3/core/reference/influxql/regular-expressions/)in the `SELECT` clause. The following queries are invalid and the output is an error: Perform a mathematical operation on a wildcard. ```sql SELECT * + 2 FROM "nope" -- ERR: unsupported expression with wildcard: * + 2 ``` Perform a mathematical operation on a wildcard within a function. ```sql SELECT COUNT(*) / 2 FROM "nope" -- ERR: unsupported expression with wildcard: count(*) / 2 ``` Perform a mathematical operation on a regular expression. ```sql SELECT /A/ + 2 FROM "nope" -- ERR: error parsing query: found +, expected FROM at line 1, char 12 ``` Perform a mathematical operation on a regular expression within a function. ```sql SELECT COUNT(/A/) + 2 FROM "nope" -- ERR: unsupported expression with regex field: count(/A/) + 2 ``` ### Mathematical operators with functions InfluxQL does not support mathematical operators inside of function calls. Note that InfluxQL only allows functions in the `SELECT` clause. For example, the following will work: ```sql SELECT 10 * mean("value") FROM "cpu" ``` However, the following query will return a parse error: ```sql SELECT mean(10 * "value") FROM "cpu" -- Error: expected field argument in mean() ``` > [!Tip] > InfluxQL supports [subqueries](/influxdb/v2/query-data/influxql/explore-data/subqueries/)which offer similar functionality to using mathematical operators inside a function call. --- # OFFSET and SOFFSET clauses Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/offset-and-soffset/ Use `OFFSET` to specify the number of [rows](/influxdb3/core/reference/glossary/#series)to skip in each InfluxQL group before returning results. Use `SOFFSET` to specify the number of [series](/influxdb3/core/reference/glossary/#series)to skip before returning results. * [OFFSET clause](#offset-clause) * [Syntax](#offset-syntax) * [Notable OFFSET clause behaviors](#notable-offset-clause-behaviors) * [Examples](#offset-examples) * [SOFFSET clause](#soffset-clause) ## `OFFSET` clause The `OFFSET` clause skips `N` rows in each InfluxQL group before returning results. Offsets honor row limits specified in the[`LIMIT` clause](/influxdb3/core/reference/influxql/limit-and-slimit/#limit-clause)and display the limited number of rows after the specified offset. Use `LIMIT` and `OFFSET` together to paginate query results. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET N [SLIMIT_clause] [SOFFSET_clause] ``` #### Arguments * **N**: Number of rows to skip in each InfluxQL group before returning results. ### Notable OFFSET clause behaviors * If there is no `LIMIT` clause in a query with an `OFFSET` clause, the query returns a single row per InfluxQL group at the specified offset. * If the query doesn’t include a [`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/), the entire result set is considered a single group and is returned in full. * If a query [groups data by time](/influxdb3/core/reference/influxql/group-by/#group-by-time), the offset is applied after aggregate and selector operations are applied to each time window. * If the [`WHERE` clause](/influxdb3/core/reference/influxql/where/)includes a time range and the `OFFSET` clause causes InfluxQL to return points with timestamps outside of that time range, InfluxQL returns no results. ### Examples The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). [](#return-the-nth-row) Return the nth row ```sql SELECT * FROM home OFFSET 3 ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T09:00:00Z| 0 |35.9|Living Room|21.4| [](#paginate-results-by-3-and-return-the-2nd-page-of-results) Paginate results by 3 and return the 2nd page of results ```sql SELECT * FROM home WHERE room = 'Kitchen' LIMIT 3 OFFSET 3 ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| |2022-01-01T13:00:00Z| 1 |36.5|Kitchen|22.8| [](#paginate-results-from-each-series-by-3-and-return-the-2nd-page-of-each-series) Paginate results from each series by 3 and return the 2nd page of each series ```sql SELECT * FROM home GROUP BY * LIMIT 3 OFFSET 3 ``` name: home tags: room=Kitchen | time |co |hum |temp| |--------------------|---|----|----| |2022-01-01T11:00:00Z| 0 | 36 |22.4| |2022-01-01T12:00:00Z| 0 | 36 |22.5| |2022-01-01T13:00:00Z| 1 |36.5|22.8| name: home tags: room=Living Room | time |co |hum |temp| |--------------------|---|----|----| |2022-01-01T11:00:00Z| 0 | 36 |22.2| |2022-01-01T12:00:00Z| 0 |35.9|22.2| |2022-01-01T13:00:00Z| 0 | 36 |22.4| ## `SOFFSET` clause > [!Important] > InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. > This process is ongoing and some InfluxQL features, such as `SOFFSET` are still > being implemented. For more information, see[InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/). | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | | time | co | hum | temp | | --- | --- | --- | --- | | time | co | hum | temp | | 2022-01-01T11:00:00Z | 0 | 36 | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | 22.5 | | 2022-01-01T13:00:00Z | 1 | 36.5 | 22.8 | | time | co | hum | temp | | --- | --- | --- | --- | | time | co | hum | temp | | 2022-01-01T11:00:00Z | 0 | 36 | 22.2 | | 2022-01-01T12:00:00Z | 0 | 35.9 | 22.2 | | 2022-01-01T13:00:00Z | 0 | 36 | 22.4 | --- # ORDER BY clause Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/order-by/ Use the `ORDER BY` clause to sort data by time in ascending or descending order. InfluxQL only supports sorting data by `time`. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DESC] ``` * If the the `ORDER BY` clause is not included, the default behavior is to sort data by time in **ascending** order: `ORDER BY time ASC`. * If the query includes [`WHERE`](/influxdb3/core/reference/influxql/where/)and [`GROUP BY`](/influxdb3/core/reference/influxql/group-by/) clauses, the `ORDER BY` clause must come **after** these clauses. #### Sort orders * **ASC (ascending)**: The first row in the results has the oldest timestamp. The last row in the results has the most recent timestamp. * **DESC (descending)**: The first row in the results has the most recent timestamp. The last row in the results has the oldest timestamp. ## Examples The following examples use the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). [](#sort-data-with-the-oldest-points-first) Sort data with the oldest points first > [!Tip] > Ordering data by time in ascending order is the default behavior. > Including `ORDER BY time ASC` in the query isn’t necessary, but it is supported. ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' ORDER BY time ASC ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| [](#sort-data-with-the-newest-points-first) Sort data with the newest points first ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' ORDER BY time DESC ``` | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | --- # Quotation Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/quoting/ InfluxQL supports both single and double quotation marks, but they each function differently and serve different purposes. * [Single quotes](#single-quotes) * [Double quotes](#double-quotes) ## Single quotes Use single quotation marks (`'`) in the[string literal](/influxdb3/core/reference/influxql/#strings) and[timestamp literal](/influxdb3/core/reference/influxql/#dates--times) syntax. In the following example, the `WHERE` clause evaluates the value of the `room` tag. Tags only contain string values, so the right operand of the predicate expression should be a string literal. ```sql ... WHERE room = 'Kitchen' ``` ## Double quotes Use double quotation marks (`"`) to quote [identifiers](/influxdb3/core/reference/influxql/#identifiers). Identifiers **must** be double-quoted in the following cases: * The identifier contains non-word characters. Word characters are defined as `[a-z,A-Z,0-9,_]`. * The identifier is case-sensitive. * The identifier contains [InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords). * The identifier begins with a digit. Double-quoted identifiers can also: * Contain any Unicode character except for a new line. * Contain escaped `"` characters (for example: `\"`). * Include [InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords). **While not always necessary, we recommend that you double quote identifiers.** > [!Important] > InfluxQL quoting guidelines differ from[line protocol quoting guidelines](/influxdb3/core/reference/syntax/line-protocol/#quotes). --- # Regular expressions Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/regular-expressions/ Regular expressions are a sequence of characters used to identify patterns in identifiers and string values. InfluxQL supports regular expressions in the following operations: * Identifying **fields** and **tags** to query in the[`SELECT` clause](/influxdb3/core/reference/influxql/select/). * Identifying **measurements** to query in the[`FROM` clause](/influxdb3/core/reference/influxql/select/#from-clause). * Testing **tag values** and **string field values** in the[`WHERE` clause](/influxdb3/core/reference/influxql/where/). * Identifying **tag keys** to group by in the[`GROUP BY` clause](/influxdb3/core/reference/influxql/group-by/) > [!Important] > #### Query performance > > Regular expression comparisons are more computationally intensive than exact > string comparisons. Queries with regular expressions are not as performant > as those without. ## Regular expression syntax InfluxQL Regular expressions are surrounded by `/` characters and use the[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). ```sql /regular_expression/ ``` ### Regular expression flags Regular expression flags modify the pattern-matching behavior of the expression. InfluxQL supports the following regular expression flags: |Flag| Description | |----|-------------------------------------------------------------------------------| | i | case-insensitive | | m |multi-line mode: `^` and `$` match begin/end line in addition to begin/end text| | s | let `.` match `\n` | | U | ungreedy: swap meaning of `x*` and `x*?`, `x+` and `x+?`, etc. | Include regular expression flags at the beginning of your regular expression pattern enclosed in parentheses (`()`) and preceded by a question mark (`?`). ```sql /(?iU)foo*/ ``` ## Regular expression operators InfluxQL provides the following regular expression operators that test if a string operand matches a regular expression: * `=~`: Returns true if the string matches the regular expression * `!~`: Returns true if the string does not match the regular expression InfluxQL regular expression operators are used to test string column values in the [`WHERE` clause](/influxdb3/core/reference/influxql/where/). ## Regular expression examples The examples below use the following sample data sets: * [NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data) * [Get started home sensor data](/influxdb3/core/reference/sample-data/#home-sensor-data) [](#use-a-regular-expression-to-specify-field-keys-and-tag-keys-in-the-select-clause) Use a regular expression to specify field keys and tag keys in the SELECT clause ```sql SELECT /^t/ FROM weather ``` name: weather | time |temp\_avg|temp\_max|temp\_min| |--------------------|---------|---------|---------| |2020-01-01T00:00:00Z| 52 | 66 | 44 | |2020-01-01T00:00:00Z| 53 | 59 | 47 | |2020-01-01T00:00:00Z| 50 | 57 | 44 | |2020-01-02T00:00:00Z| 54 | 61 | 49 | |2020-01-02T00:00:00Z| 51 | 60 | 44 | |2020-01-02T00:00:00Z| 53 | 66 | 42 | | … | … | … | … | [](#use-a-regular-expression-to-specify-measurements-in-the-from-clause) Use a regular expression to specify measurements in the FROM clause ```sql SELECT /^t/ FROM /^[hw]/ ``` name: weather | time |temp|temp\_avg|temp\_max|temp\_min| |--------------------|----|---------|---------|---------| |2020-01-01T00:00:00Z| | 52 | 66 | 44 | |2020-01-01T00:00:00Z| | 53 | 59 | 47 | |2020-01-01T00:00:00Z| | 50 | 57 | 44 | |2020-01-02T00:00:00Z| | 54 | 61 | 49 | |2020-01-02T00:00:00Z| | 51 | 60 | 44 | |2020-01-02T00:00:00Z| | 53 | 66 | 42 | | … | … | … | … | … | [](#use-a-regular-expression-to-specify-tag-values-in-the-where-clause) Use a regular expression to specify tag values in the WHERE clause ```sql SELECT * FROM weather WHERE location !~ /^[S]/ ``` name: weather | time |location|precip|temp\_avg|temp\_max|temp\_min|wind\_avg| |--------------------|--------|------|---------|---------|---------|---------| |2020-01-01T00:00:00Z|Concord | 0 | 52 | 66 | 44 | 3.13 | |2020-01-01T00:00:00Z|Hayward | 0 | 50 | 57 | 44 | 2.24 | |2020-01-02T00:00:00Z|Concord | 0 | 53 | 66 | 42 | 3.13 | |2020-01-02T00:00:00Z|Hayward | 0 | 51 | 60 | 44 | 3.8 | |2020-01-03T00:00:00Z|Concord | 0 | 49 | 60 | 38 | 2.68 | |2020-01-03T00:00:00Z|Hayward | 0 | 50 | 62 | 41 | 3.13 | | … | … | … | … | … | … | … | [](#use-a-regular-expression-to-specify-a-tag-with-no-value-in-the-where-clause) Use a regular expression to specify a tag with no value in the WHERE clause ```sql SELECT * FROM home, weather WHERE location !~ /./ ``` name: weather | time |co |hum |location|precip| room |temp|temp\_avg|temp\_max|temp\_min|wind\_avg| |--------------------|---|----|--------|------|-----------|----|---------|---------|---------|---------| |2022-01-01T08:00:00Z| 0 |35.9| | | Kitchen | 21 | | | | | |2022-01-01T08:00:00Z| 0 |35.9| | |Living Room|21.1| | | | | |2022-01-01T09:00:00Z| 0 |36.2| | | Kitchen | 23 | | | | | |2022-01-01T09:00:00Z| 0 |35.9| | |Living Room|21.4| | | | | |2022-01-01T10:00:00Z| 0 |36.1| | | Kitchen |22.7| | | | | |2022-01-01T10:00:00Z| 0 | 36 | | |Living Room|21.8| | | | | | … | … | … | … | … | … | … | … | … | … | … | [](#use-a-regular-expression-to-specify-tag-keys-in-the-group-by-clause) Use a regular expression to specify tag keys in the GROUP BY clause ```sql SELECT MAX(precip) FROM weather GROUP BY /^l/ ``` name: weather tags: location=Concord | time |max | |--------------------|----| |2021-10-24T00:00:00Z|4.53| name: weather tags: location=Hayward | time |max | |--------------------|----| |2022-12-31T00:00:00Z|4.34| name: weather tags: location=San Francisco | time |max | |--------------------|----| |2021-10-24T00:00:00Z|4.02| | Flag | Description | | --- | --- | | Flag | Description | | i | case-insensitive | | m | multi-line mode: ^ and $ match begin/end line in addition to begin/end text | | s | let . match \n | | U | ungreedy: swap meaning of x* and x*? , x+ and x+? , etc. | | time | temp_avg | temp_max | temp_min | | --- | --- | --- | --- | | time | temp_avg | temp_max | temp_min | | 2020-01-01T00:00:00Z | 52 | 66 | 44 | | 2020-01-01T00:00:00Z | 53 | 59 | 47 | | 2020-01-01T00:00:00Z | 50 | 57 | 44 | | 2020-01-02T00:00:00Z | 54 | 61 | 49 | | 2020-01-02T00:00:00Z | 51 | 60 | 44 | | 2020-01-02T00:00:00Z | 53 | 66 | 42 | | … | … | … | … | | time | temp | temp_avg | temp_max | temp_min | | --- | --- | --- | --- | --- | | time | temp | temp_avg | temp_max | temp_min | | 2020-01-01T00:00:00Z | | 52 | 66 | 44 | | 2020-01-01T00:00:00Z | | 53 | 59 | 47 | | 2020-01-01T00:00:00Z | | 50 | 57 | 44 | | 2020-01-02T00:00:00Z | | 54 | 61 | 49 | | 2020-01-02T00:00:00Z | | 51 | 60 | 44 | | 2020-01-02T00:00:00Z | | 53 | 66 | 42 | | … | … | … | … | … | | time | location | precip | temp_avg | temp_max | temp_min | wind_avg | | --- | --- | --- | --- | --- | --- | --- | | time | location | precip | temp_avg | temp_max | temp_min | wind_avg | | 2020-01-01T00:00:00Z | Concord | 0 | 52 | 66 | 44 | 3.13 | | 2020-01-01T00:00:00Z | Hayward | 0 | 50 | 57 | 44 | 2.24 | | 2020-01-02T00:00:00Z | Concord | 0 | 53 | 66 | 42 | 3.13 | | 2020-01-02T00:00:00Z | Hayward | 0 | 51 | 60 | 44 | 3.8 | | 2020-01-03T00:00:00Z | Concord | 0 | 49 | 60 | 38 | 2.68 | | 2020-01-03T00:00:00Z | Hayward | 0 | 50 | 62 | 41 | 3.13 | | … | … | … | … | … | … | … | | time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | | 2022-01-01T08:00:00Z | 0 | 35.9 | | | Kitchen | 21 | | | | | | 2022-01-01T08:00:00Z | 0 | 35.9 | | | Living Room | 21.1 | | | | | | 2022-01-01T09:00:00Z | 0 | 36.2 | | | Kitchen | 23 | | | | | | 2022-01-01T09:00:00Z | 0 | 35.9 | | | Living Room | 21.4 | | | | | | 2022-01-01T10:00:00Z | 0 | 36.1 | | | Kitchen | 22.7 | | | | | | 2022-01-01T10:00:00Z | 0 | 36 | | | Living Room | 21.8 | | | | | | … | … | … | … | … | … | … | … | … | … | … | | time | max | | --- | --- | | time | max | | 2021-10-24T00:00:00Z | 4.53 | | time | max | | --- | --- | | time | max | | 2022-12-31T00:00:00Z | 4.34 | | time | max | | --- | --- | | time | max | | 2021-10-24T00:00:00Z | 4.02 | --- # SELECT statement Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/select/ Use the `SELECT` statement to query data from one or more[measurements](/influxdb3/core/reference/glossary/#measurement). The `SELECT` statement **requires** a [`SELECT` clause](#select-clause) and a[`FROM` clause](#from-clause). * [Syntax](#syntax) * [SELECT clause](#select-clause) * [FROM clause](#from-clause) * [Notable SELECT statement behaviors](#notable-select-statement-behaviors) * [Data types and casting operations](#data-types-and-casting-operations) * [SELECT statement examples](#select-statement-examples) ## Syntax ```sql SELECT field_expression[, ..., field_expression_n[, tag_expression[, ..., tag_expression_n]]] FROM measurement_expression[, ..., measurement_expression_n] ``` ### SELECT clause The `SELECT` clause supports several formats for identifying data to query. It requires one or more **field expressions** and optional **tag expressions**. * **field\_expression**: Expression to identify one or more fields to return in query results. Can be a [field key](/influxdb3/core/reference/glossary/#field-key), constant, [regular expression](/influxdb3/core/reference/influxql/regular-expressions/),[wildcard (`*`)](#wildcard-expressions-in-select-clauses), or[function expression](/influxdb3/core/reference/influxql/functions/) and any combination of arithmetic operators. * **tag\_expression**: Expression to identify one or more tags to return in query results. Can be a [tag key](/influxdb3/core/reference/glossary/#tag-key) or constant. #### Select clause behaviors * `SELECT field_key` - Returns a specific field. * `SELECT field_key1, field_key2` - Returns two specific fields. * `SELECT field_key, tag_key` - Returns a specific field and tag. * `SELECT *` - Returns all [fields](/influxdb3/core/reference/glossary/#field)and [tags](/influxdb3/core/reference/glossary/#tag).*See [Wildcard expressions](#wildcard-expressions).* * `SELECT /^[t]/` - Returns all [fields](/influxdb3/core/reference/glossary/#field)and [tags](/influxdb3/core/reference/glossary/#tag) with keys that match the regular expression. At least one field key must match the regular expression. If no field keys match the regular expression, no results are returned. ### FROM clause The `FROM` clause specifies the[measurement](/influxdb3/core/reference/glossary/#measurement) or[subquery](/influxdb3/core/reference/influxql/subqueries/) to query. It requires one or more comma-delimited[measurement expressions](#measurement_expression) or [subqueries](#subquery). #### measurement\_expression A measurement expression identifies a measurement to query. It can be a measurement name, fully-qualified measurement, constant, or a [regular expression](/influxdb3/core/reference/influxql/regular-expressions/). * **Measurement name**: When using just the measurement name, InfluxQL assumes the default retention policy of the database specified in the query request. ``` FROM measurement ``` * **Fully-qualified measurement**: A fully qualified measurement includes a database name, retention policy name, and measurement name, each separated by a period (`.`). If the retention policy is not specified, InfluxQL uses the default retention policy for the specified database. ```sql FROM database.retention_policy.measurement -- Fully-qualified measurement with default retention policy FROM database..measurement ``` > [!Important] > #### InfluxQL retention policies > > In InfluxDB 3 Core, **retention policies** are not part of the data model > like they are in InfluxDB 1.x. > Each InfluxDB 3 Core database has a **retention period** which defines the > maximum age of data to retain in the database. To use fully-qualified > measurements in InfluxQL queries, use the following naming convention when[creating a database](/influxdb3/core/admin/databases/create/): > > ``` > database_name/retention_policy > ``` #### Subquery An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. The outer query queries results returned by the inner query (subquery). For more information, see [InfluxQL subqueries](/influxdb3/core/reference/influxql/subqueries/). ## Notable SELECT statement behaviors * [Must query at least one field](#must-query-at-least-one-field) * [Wildcard expressions](#wildcard-expressions) * [Cannot include both aggregate and non-aggregate field expressions](#cannot-include-both-aggregate-and-non-aggregate-field-expressions) ### Must query at least one field A query requires at least one [field key](/influxdb3/core/reference/glossary/#field-key)in the `SELECT` clause to return data. If the `SELECT` clause includes only [tag keys](/influxdb3/core/reference/glossary/#tag-key), the query returns an empty result. When using regular expressions in the `SELECT` clause, if regular expression matches only tag keys and no field keys, the query returns an empty result. To return data associated with tag keys, include at least one field key in the`SELECT` clause. ### Wildcard expressions When using a wildcard expression (`*`) in the `SELECT` clause, the query returns all tags and fields. If a [function](/influxdb3/core/reference/influxql/functions/) is applied to a wildcard expression, the query returns all *fields* with the function applied, but does not return *tags* unless they are included in the `SELECT` clause. ### Cannot include both aggregate and non-aggregate field expressions The `SELECT` statement cannot include an aggregate field expression (one that uses an [aggregate](/influxdb3/core/reference/influxql/functions/aggregates/)or [selector](/influxdb3/core/reference/influxql/functions/aggregates/)function) **and** a non-aggregate field expression. For example, in the following query, an aggregate function is applied to one field, but not the other: ```sql SELECT mean(temp), hum FROM home ``` This query returns an error. For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). ## Data types and casting operations The [`SELECT` clause](#select-clause) supports specifying a[field’s](/influxdb3/core/reference/glossary/#field) type and basic casting operations with the `::` syntax. ```sql SELECT field_expression::type FROM measurement_expression ``` The `::` syntax allows users to perform basic cast operations in queries. Currently, InfluxQL supports casting *numeric* [field values](/influxdb3/core/reference/glossary/#field-value)to other numeric types. Casting to an **identifier type** acts as a filter on results and returns only columns of that specific identifier type along with the `time` column. ##### Numeric types * `float` * `integer` * `unsigned` ##### Non-numeric types * `string` * `boolean` ##### Identifier types * `field` * `tag` > [!Important] > InfluxQL returns no data if the query attempts to cast a numeric value to a > non-numeric type and vice versa. When casting a float value to an integer or unsigned integer, the float value is truncated at the decimal point. No rounding is performed. ## SELECT statement examples The examples below use the following sample data sets: * [Get started home sensor data](/influxdb3/core/reference/sample-data/#home-sensor-data) * [NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data) [](#select-all-fields-and-tags-from-a-measurement) Select all fields and tags from a measurement ```sql SELECT * FROM home ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T08:00:00Z| 0 |35.9| Kitchen | 21 | |2022-01-01T08:00:00Z| 0 |35.9|Living Room|21.1| |2022-01-01T09:00:00Z| 0 |36.2| Kitchen | 23 | |2022-01-01T09:00:00Z| 0 |35.9|Living Room|21.4| |2022-01-01T10:00:00Z| 0 |36.1| Kitchen |22.7| |2022-01-01T10:00:00Z| 0 | 36 |Living Room|21.8| | … | … | … | … | … | [](#select-specific-tags-and-fields-from-a-measurement) Select specific tags and fields from a measurement ```sql SELECT temp, hum, room FROM home ``` Name: home | time |temp|hum | room | |--------------------|----|----|-----------| |2022-01-01T08:00:00Z| 21 |35.9| Kitchen | |2022-01-01T08:00:00Z|21.1|35.9|Living Room| |2022-01-01T09:00:00Z| 23 |36.2| Kitchen | |2022-01-01T09:00:00Z|21.4|35.9|Living Room| |2022-01-01T10:00:00Z|22.7|36.1| Kitchen | |2022-01-01T10:00:00Z|21.8| 36 |Living Room| | … | … | … | … | [](#select-all-fields-from-a-measurement) Select all fields from a measurement ```sql SELECT *::field FROM home ``` Name: home | time |co |hum |temp| |--------------------|---|----|----| |2022-01-01T08:00:00Z| 0 |35.9| 21 | |2022-01-01T08:00:00Z| 0 |35.9|21.1| |2022-01-01T09:00:00Z| 0 |36.2| 23 | |2022-01-01T09:00:00Z| 0 |35.9|21.4| |2022-01-01T10:00:00Z| 0 |36.1|22.7| |2022-01-01T10:00:00Z| 0 | 36 |21.8| | … | … | … | … | [](#select-a-field-from-a-measurement-and-perform-basic-arithmetic) Select a field from a measurement and perform basic arithmetic ```sql SELECT (temp * (9 / 5)) + 32 FROM home ``` Name: home | time | temp | |--------------------|-----------------| |2022-01-01T08:00:00Z|69.80000000000001| |2022-01-01T08:00:00Z| 69.98 | |2022-01-01T09:00:00Z| 73.4 | |2022-01-01T09:00:00Z| 70.52 | |2022-01-01T10:00:00Z| 72.86 | |2022-01-01T10:00:00Z|71.24000000000001| | … | … | > [!Note] > **Note:** InfluxDB follows the standard order of operations. > See [InfluxQL mathematical operators](/influxdb3/core/reference/influxql/math-operators/)for more on supported operators. [](#select-all-data-from-more-than-one-measurement) Select all data from more than one measurement ```sql SELECT * FROM home, weather ``` Name: weather | time |co |hum| location |precip|room|temp|temp\_avg|temp\_max|temp\_min|wind\_avg| |--------------------|---|---|-------------|------|----|----|---------|---------|---------|---------| |2020-01-01T00:00:00Z| | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | |2020-01-01T00:00:00Z| | |San Francisco| 0 | | | 53 | 59 | 47 | 14.32 | |2020-01-01T00:00:00Z| | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | |2020-01-02T00:00:00Z| | |San Francisco| 0 | | | 54 | 61 | 49 | 5.82 | |2020-01-02T00:00:00Z| | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | |2020-01-02T00:00:00Z| | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | | … | … | … | … | … | … | … | … | … | … | … | [](#select-all-data-from-a-fully-qualified-measurement-with-default-retention-policy) Select all data from a fully-qualified measurement (with default retention policy) ```sql SELECT * FROM "get-started"..home ``` Name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T08:00:00Z| 0 |35.9| Kitchen | 21 | |2022-01-01T08:00:00Z| 0 |35.9|Living Room|21.1| |2022-01-01T09:00:00Z| 0 |36.2| Kitchen | 23 | |2022-01-01T09:00:00Z| 0 |35.9|Living Room|21.4| |2022-01-01T10:00:00Z| 0 |36.1| Kitchen |22.7| |2022-01-01T10:00:00Z| 0 | 36 |Living Room|21.8| | … | … | … | … | … | ### Type-casting examples [](#cast-an-integer-field-to-a-float) Cast an integer field to a float ```sql SELECT co::float FROM home ``` [](#cast-a-float-field-to-an-integer) Cast a float field to an integer ```sql SELECT temp::integer FROM home ``` [](#cast-a-float-field-to-an-unsigned-integer) Cast a float field to an unsigned integer ```sql SELECT temp::unsigned FROM home ``` | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | | … | … | … | … | … | | time | temp | hum | room | | --- | --- | --- | --- | | time | temp | hum | room | | 2022-01-01T08:00:00Z | 21 | 35.9 | Kitchen | | 2022-01-01T08:00:00Z | 21.1 | 35.9 | Living Room | | 2022-01-01T09:00:00Z | 23 | 36.2 | Kitchen | | 2022-01-01T09:00:00Z | 21.4 | 35.9 | Living Room | | 2022-01-01T10:00:00Z | 22.7 | 36.1 | Kitchen | | 2022-01-01T10:00:00Z | 21.8 | 36 | Living Room | | … | … | … | … | | time | co | hum | temp | | --- | --- | --- | --- | | time | co | hum | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | 21 | | 2022-01-01T08:00:00Z | 0 | 35.9 | 21.1 | | 2022-01-01T09:00:00Z | 0 | 36.2 | 23 | | 2022-01-01T09:00:00Z | 0 | 35.9 | 21.4 | | 2022-01-01T10:00:00Z | 0 | 36.1 | 22.7 | | 2022-01-01T10:00:00Z | 0 | 36 | 21.8 | | … | … | … | … | | time | temp | | --- | --- | | time | temp | | 2022-01-01T08:00:00Z | 69.80000000000001 | | 2022-01-01T08:00:00Z | 69.98 | | 2022-01-01T09:00:00Z | 73.4 | | 2022-01-01T09:00:00Z | 70.52 | | 2022-01-01T10:00:00Z | 72.86 | | 2022-01-01T10:00:00Z | 71.24000000000001 | | … | … | | time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | | 2020-01-01T00:00:00Z | | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | | 2020-01-01T00:00:00Z | | | San Francisco | 0 | | | 53 | 59 | 47 | 14.32 | | 2020-01-01T00:00:00Z | | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | | 2020-01-02T00:00:00Z | | | San Francisco | 0 | | | 54 | 61 | 49 | 5.82 | | 2020-01-02T00:00:00Z | | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | | 2020-01-02T00:00:00Z | | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | | … | … | … | … | … | … | … | … | … | … | … | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | | … | … | … | … | … | --- # InfluxQL SHOW statements Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/show/ Use InfluxQL `SHOW` statements to query schema information from a database. * [SHOW RETENTION POLICIES](#show-retention-policies) * [SHOW MEASUREMENTS](#show-measurements) * [SHOW FIELD KEYS](#show-field-keys) * [SHOW TAG KEYS](#show-tag-keys) * [SHOW TAG VALUES](#show-tag-values) ## SHOW RETENTION POLICIES Use the `SHOW RETENTION POLICIES` statement to list retention policies associated with a database. Each database has a single retention policy–`autogen`. > [!Note] > In InfluxDB 3 Core, retention policies are not part of the > data structure but are expected by InfluxQL and used in fully-qualified measurements > in the [`FROM` clause](/influxdb3/core/reference/influxql/select/#from-clause). > The data returned for each retention policy does not represent the actual > retention-related attributes of the database. The values are placeholder values > meant only for InfluxQL feature parity. > > For information about database data retention, see[List databases](/influxdb3/core/admin/databases/list/). ```sql SHOW RETENTION POLICIES [ON ] ``` #### Examples ```sql -- Show retention policies in the database specified in the query request SHOW RETENTION POLICIES -- Show retention policies in a specific database SHOW RETENTION POLICIES ON "example-database" ``` ## SHOW MEASUREMENTS Use the `SHOW MEASUREMENTS` statement to list measurements in a database. ```sql SHOW MEASUREMENTS [with_measurement_clause] [where_clause] [limit_clause] [offset_clause] ``` #### Examples ```sql -- Show all measurements SHOW MEASUREMENTS -- Show measurements where region tag = 'uswest' AND host tag = 'serverA' SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' -- Show measurements that start with 'h2o' SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ ``` ## SHOW FIELD KEYS Use the `SHOW FIELD KEYS` statement to list all field keys in a measurement. ```sql SHOW FIELD KEYS [from_clause] ``` #### Examples ```sql -- Show field keys and field value data types from all measurements SHOW FIELD KEYS -- Show field keys and field value data types from specified measurement SHOW FIELD KEYS FROM "cpu" ``` ## SHOW TAG KEYS Use the `SHOW TAG KEYS` statement to list tag keys in a measurement. ```sql SHOW TAG KEYS [from_clause] [where_clause] [limit_clause] [offset_clause] ``` #### Examples ```sql -- Show all tag keys SHOW TAG KEYS -- Show all tag keys from the cpu measurement SHOW TAG KEYS FROM "cpu" -- Show all tag keys from the cpu measurement where the region key = 'uswest' SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' -- Show all tag keys where the host key = 'serverA' SHOW TAG KEYS WHERE "host" = 'serverA' ``` ## SHOW TAG VALUES Use the `SHOW TAG VALUES` statement to list values of specified tags in a database. ```sql SHOW TAG VALUES [from_clause] WITH KEY = [where_clause] [limit_clause] [offset_clause] ``` By default, the `SHOW TAG VALUES` statement only returns unique tag values from**the last day**. To modify the time range, include a[`WHERE` clause with a time-based predicate](/influxdb3/core/reference/influxql/where/#time-ranges). > [!Important] > #### Include a FROM clause > > We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES`statement that specifies 1-50 tables to query. > Without a `FROM` clause, the InfluxDB query engine must read data from all > tables and return unique tag values from each. > > Depending on the number of tables in your database and the number of unique tag > values in each table, excluding a `FROM` clause can result in poor query performance, > query timeouts, or unnecessary resource allocation that may affect other queries. #### Examples ```sql -- Show tag values from the cpu measurement for the region tag SHOW TAG VALUES FROM "cpu" WITH KEY = "region" -- Show tag values from the cpu measurement for the region tag for a custom time range SHOW TAG VALUES FROM "cpu" WITH KEY = "region" WHERE time > -7d -- Show tag values from multiple measurements for the region tag SHOW TAG VALUES FROM "cpu", "memory", "disk" WITH KEY = "region" -- Show tag values from the cpu measurement for all tag keys that do not include the letter c SHOW TAG VALUES FROM "cpu" WITH KEY !~ /.*c.*/ -- Show tag values from the cpu measurement for region & host tag keys where service = 'redis' SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' ``` #### Related * [Explore your schema with InfluxQL](/influxdb3/core/query-data/influxql/explore-schema/) --- # InfluxQL subqueries Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/subqueries/ An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. The outer query queries results returned by the inner query (subquery). * [Syntax](#syntax) * [Examples](#examples) * [Notable subquery behaviors](#notable-subquery-behaviors) > [!Important] > InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer > functionality similar to the [SQL `HAVING` clause](/influxdb3/core/reference/sql/having/). ## Syntax ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` When using subqueries, InfluxQL **performs the inner query first**, then performs the outer query. The outer query requires a [`SELECT` clause](/influxdb3/core/reference/influxql/select/#select-clause)and a [`FROM` clause](/influxdb3/core/reference/influxql/select/#from-clause). The inner query is enclosed in parentheses in the outer query’s `FROM` clause. InfluxQL supports multiple nested subqueries: ```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` ## Examples > [!Note] > #### Sample data > > The examples below use the following sample data sets: > > * [Get started home sensor data](/influxdb3/core/reference/sample-data/#home-sensor-data) > * [Random numbers sample data](/influxdb3/core/reference/sample-data/#random-numbers-sample-data) [](#apply-an-aggregate-function-to-an-aggregated-result-set) Apply an aggregate function to an aggregated result set ```sql SELECT SUM(max) FROM ( SELECT MAX(temp) FROM home GROUP BY room ) ``` Table: home | time |sum | |--------------------|----| |1970-01-01T00:00:00Z|46.1| [](#calculate-the-average-difference-between-two-fields) Calculate the average difference between two fields ```sql SELECT MEAN(difference) FROM ( SELECT a - b AS difference FROM numbers ) ``` Table: numbers | time | mean | |--------------------|---------------------| |1970-01-01T00:00:00Z|\-0.03629771779732732| [](#filter-aggregate-values-based-on-a-threshold) Filter aggregate values based on a threshold ```sql SELECT co_change FROM ( SELECT SPREAD(co) AS co_change FROM home GROUP BY room, time(2h) ) WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' AND co_change >= 4 ``` Table: home | time |co\_chnage| |--------------------|----------| |2022-01-01T18:00:00Z| 4 | |2022-01-01T18:00:00Z| 5 | [](#perform-additional-aggregate-operations-on-aggregate-values) Perform additional aggregate operations on aggregate values ```sql SELECT SUM(co_derivative) AS sum_derivative FROM ( SELECT DERIVATIVE(MEAN(co)) AS co_derivative FROM home GROUP BY time(12m), room ) WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY room ``` Table: home | time | room |sum\_derivative| |--------------------|-----------|---------------| |1970-01-01T00:00:00Z| Kitchen | 5.2 | |1970-01-01T00:00:00Z|Living Room| 3.4 | ## Notable subquery behaviors * [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) * [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) ### Apply time bounds to the outer query to improve performance To improve the performance of InfluxQL queries that use subqueries and a specified time range, apply the `WHERE` clause with time-based predicates to the outer query rather than the inner query. For example–the following queries return the same results, but **the query with time-based predicate on the outer query is more performant than the query with time-based predicate on the inner query**: #### Time bounds on the outer query ```sql SELECT inner_value AS value FROM ( SELECT raw_value as inner_value ) WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` #### Time bounds on the inner query ```sql SELECT inner_value AS value FROM ( SELECT raw_value as inner_value WHERE time >= '2022-07-19T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ) ``` ### Cannot use multiple SELECT statements in a subquery InfluxQL does not support multiple[`SELECT` statements](/influxdb3/core/reference/influxql/select/)per subquery: ```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` However, InfluxQL does support multiple nested subqueries per outer query: ```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` | time | sum | | --- | --- | | time | sum | | 1970-01-01T00:00:00Z | 46.1 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | -0.03629771779732732 | | time | co_chnage | | --- | --- | | time | co_chnage | | 2022-01-01T18:00:00Z | 4 | | 2022-01-01T18:00:00Z | 5 | | time | room | sum_derivative | | --- | --- | --- | | time | room | sum_derivative | | 1970-01-01T00:00:00Z | Kitchen | 5.2 | | 1970-01-01T00:00:00Z | Living Room | 3.4 | --- # Time and time zones Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/time-and-timezone/ InfluxQL is designed for working with time series data and includes features specifically for working with time. You can review the following ways to work with time and timestamps in your InfluxQL queries: * [Time syntax](#time-syntax) * [Add and subtract time values](#add-and-subtract-time-values) * [Query time range](#query-time-range) * [Supported operators](#supported-operators) * [Query examples](#query-examples) * [Time zone clause](#time-zone-clause) * [Notable behaviors](#notable-behaviors) * [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) * [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) * [Cannot use parameters for durations](#cannot-use-parameters-for-durations) ## Time syntax InfluxQL supports the following timestamp literal syntaxes: ```sql '2006-01-02T15:04:05.00Z' -- RFC3339 date-time string '2006-01-02 15:04:05.00' -- RFC3339-like date-time string 1136189045000000000 -- Unix nanosecond epoch time 1136189045s -- Unix epoch time ``` * **RFC3339 date-time string**:[String literal](/influxdb3/core/reference/influxql/#strings) using the RFC3339 timestamp format, `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`. * **RFC3339-like date-time string**:[String literal](/influxdb3/core/reference/influxql/#strings) using the RFC3339-like timestamp format, `YYYY-MM-DD HH:MM:SS.nnnnnnnnn`. * **Unix nanosecond epoch time**:[Integer](/influxdb3/core/reference/influxql/#integers) that represents the number of nanoseconds elapsed since the[Unix epoch](/influxdb3/core/reference/glossary/#unix-epoch). * **Unix epoch time**:[Duration literal](/influxdb3/core/reference/influxql/#durations)that represents the number of specified time units elapsed since the[Unix epoch](/influxdb3/core/reference/glossary/#unix-epoch).*[View supported duration units](/influxdb3/core/reference/influxql/#durations)*. ##### Supported timestamp values | | RFC3339 |Unix nanosecond time | |-----------|------------------------------|---------------------| |**Maximum**|2262-04-11T23:47:16.854775807Z| 9223372036854775807 | |**Minimum**|1677-09-21T00:12:43.145224193Z|\-9223372036854775807| ### Add and subtract time values Timestamp values support addition and subtraction operations with[duration literals](/influxdb3/core/reference/influxql/#durations). Add (`+`) or subtract (`-`) a duration to or from a timestamp to return an updated timestamp. ```sql '2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z '2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z 1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z ``` > [!Important] > InfluxQL requires a whitespace between the `+` operators `-` and the duration literal. ## Query time range To specify the time range of a query, use conditional expressions in the[`WHERE` clause](/influxdb3/core/reference/influxql/where/) that compare the value of the `time` column to an absolute timestamp or a relative timestamp. * **Absolute time range**: Define query time bounds with timestamp literals ``` WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 WHERE time >= 1672531200s and time <= 1688169600000ms ``` * **Relative time range**: Define query time bounds with a duration literal added to or subtracted from timestamp literals. > [!Tip] > Use `now()` to return the current system time (UTC). ``` -- Query data from the last day WHERE time >= now() - 1d -- Query data from the previous week WHERE time >= now() - 1w AND time <= now() - 2w -- Query data relative to a specific time WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w ``` ### Supported operators Conditional expressions with time operands support the following comparison operators: |Operator| Meaning | |--------|------------------------| | `=` | equal to | | `<>` | not equal to | | `!=` | not equal to | | `>` | greater than | | `>=` |greater than or equal to| | `<` | less than | | `<=` | less than or equal to | > [!Important] > InfluxQL supports the `AND` logical operator to define query time bounds, but > does not support using the `OR` logical operator to query multiple time ranges. ## Query examples The following examples use the[Home sensor sample dataset](/influxdb3/core/reference/sample-data/#home-sensor-data). [](#specify-a-time-range-with-rfc3339-date-time-strings) Specify a time range with RFC3339 date-time strings ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| [](#specify-a-time-range-with-rfc3339-like-date-time-strings) Specify a time range with RFC3339-like date-time strings ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01 08:00:00' AND time <= '2022-01-01 12:00:00' ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| [](#specify-a-time-range-with-nanosecond-epoch-timestamps) Specify a time range with nanosecond epoch timestamps ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= 1641024000000000000 AND time <= 1641038400000000000 ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| [](#specify-a-time-range-with-second-precision-epoch-timestamps) Specify a time range with second-precision epoch timestamps ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= 1641024000s AND time <= 1641038400s ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T08:00:00Z| 0 |35.9|Kitchen| 21 | |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T10:00:00Z| 0 |36.1|Kitchen|22.7| |2022-01-01T11:00:00Z| 0 | 36 |Kitchen|22.4| |2022-01-01T12:00:00Z| 0 | 36 |Kitchen|22.5| [](#specify-a-time-range-relative-to-a-timestamp) Specify a time range relative to a timestamp ```sql SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T18:00:00Z|18 |36.9| Kitchen |23.3| |2022-01-01T18:00:00Z| 9 |36.2|Living Room|22.8| |2022-01-01T19:00:00Z|22 |36.6| Kitchen |23.1| |2022-01-01T19:00:00Z|14 |36.3|Living Room|22.5| |2022-01-01T20:00:00Z|26 |36.5| Kitchen |22.7| |2022-01-01T20:00:00Z|17 |36.4|Living Room|22.2| [](#specify-a-time-range-relative-to-now) Specify a time range relative to now ```sql SELECT * FROM home WHERE time >= now() - 2h ``` ## Time zone clause By default, InfluxDB stores and returns timestamps in UTC. Use the time zone clause and the `tz()` function to apply a time zone offset to UTC times and return timestamps in the specified time zone including any applicable seasonal offset such as Daylight Savings Time (DST) or British Summer Time (BST). ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('time_zone') ``` * **time\_zone**: Time zone string literal to adjust times to. Uses time zone names defined in the[Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). ### Time zone example [](#return-the-utc-offset-for-chicagos-time-zone) Return the UTC offset for Chicago’s time zone The following example uses the[Home sensor sample dataset](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT * FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' tz('America/Chicago') ``` name: home | time |co |hum | room |temp| |-------------------------|---|----|-------|----| |2022-01-01T02:00:00-06:00| 0 |35.9|Kitchen| 21 | |2022-01-01T03:00:00-06:00| 0 |36.2|Kitchen| 23 | |2022-01-01T04:00:00-06:00| 0 |36.1|Kitchen|22.7| |2022-01-01T05:00:00-06:00| 0 | 36 |Kitchen|22.4| |2022-01-01T06:00:00-06:00| 0 | 36 |Kitchen|22.5| ## Notable behaviors * [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) * [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) * [Cannot use parameters for durations](#cannot-use-parameters-for-durations) ### Cannot query multiple time ranges InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. For example, the following query returns no results: ```sql SELECT * FROM home WHERE (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') ``` ### Querying future data with a `GROUP BY time()` clause Queries that do not specify time bounds in the `WHERE` clause and do not include a `GROUP BY time()` clause use the [minimum and maximum timestamps](#supported-timestamp-values)as the default time range. If the query includes a `GROUP BY time()` clause, the default time range is between `1677-09-21T00:12:43.145224193Z` and[`now()`](/influxdb3/core/reference/influxql/functions/date-time/#now). To query data with timestamps that occur in the future (after `now()`), provide an explicit upper bound in the `WHERE` clause. ### Cannot use parameters for durations Currently, InfluxDB doesn’t support using parameters for durations in[parameterized queries](/influxdb3/core/query-data/influxql/parameterized-queries/). | | RFC3339 | Unix nanosecond time | | --- | --- | --- | | | RFC3339 | Unix nanosecond time | | Maximum | 2262-04-11T23:47:16.854775807Z | 9223372036854775807 | | Minimum | 1677-09-21T00:12:43.145224193Z | -9223372036854775807 | | Operator | Meaning | | --- | --- | | Operator | Meaning | | = | equal to | | <> | not equal to | | != | not equal to | | > | greater than | | >= | greater than or equal to | | < | less than | | <= | less than or equal to | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | | 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | | 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | | 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | | 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | | 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T02:00:00-06:00 | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T03:00:00-06:00 | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T04:00:00-06:00 | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T05:00:00-06:00 | 0 | 36 | Kitchen | 22.4 | | 2022-01-01T06:00:00-06:00 | 0 | 36 | Kitchen | 22.5 | --- # WHERE clause Source: https://docs.influxdata.com/influxdb3/core/reference/influxql/where/ Use the `WHERE` clause to filter data based on[field values](/influxdb3/core/reference/glossary/#field),[tag values](/influxdb3/core/reference/glossary/#tag), and[timestamps](/influxdb3/core/reference/glossary/#timestamp). * [Syntax](#syntax) * [Operators](#comparison-operators) * [Comparison operators](#comparison-operators) * [Logical operators](#logical-operators) * [Time ranges](#time-ranges) * [Regular expressions](#regular-expressions) * [WHERE clause examples](#where-clause-examples) * [Notable behaviors](#notable-behaviors) * [Single and double quotes](#single-and-double-quotes) * [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) ## Syntax ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` * **conditional\_expression**: Comparison between two operands that evaluates to`true` or `false`. Comparison logic is determined by[operators](#operators) used in the expression. These expressions can operate on InfluxDB fields, tags, and timestamps. Use logical operators (`AND`, `OR`) to chain multiple conditional expressions together. ## Operators Operators evaluate the relationship between two operands and return`true` or `false`. ### Comparison operators |Operator| Meaning |Supported data types| |--------|----------------------------------|--------------------| | `=` | Equal to | all | | `<>` | Not equal to | all | | `!=` | Not equal to | all | | `>` | Greater than | numeric, timestamp | | `>=` | Greater than or equal to | numeric, timestamp | | `<` | Less than | numeric, timestamp | | `<=` | Less than or equal to | numeric, timestamp | | `=~` | Matches a regular expression | strings | | `!~` |Doesn’t match a regular expression| strings | ### Logical operators |Operator| Meaning | |--------|-----------------------------------------------------------------------| | `AND` |Returns `true` if both operands are `true`. Otherwise, returns `false`.| | `OR` | Returns `true` if any operand is `true`. Otherwise, returns `false`. | ## Time ranges Use the `WHERE` clause to specify a time range to query. If a time range isn’t specified in the `WHERE` clause, the [default time range](/influxdb3/core/reference/influxql/#default-time-range) is used. Timestamps are stored in the `time` column. Use comparison operators to compare the value of the `time` column to a timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb3/core/reference/glossary/#expression). #### Timestamp #### ```sql WHERE time >= '2023-01-01T00:00:00Z' AND time < '2023-07-01T00:00:00Z' ``` ```sql WHERE time >= 1672531200000000000 AND time < 1688169600000000000 ``` ```sql WHERE time >= now() - 1d AND time < now() ``` See [Time syntax](/influxdb3/core/reference/influxql/time-and-timezone/#time-syntax)for information on how to specify alternative time ranges in the `WHERE` clause. > [!Important] > InfluxQL [does not support querying multiple time ranges](#cannot-query-multiple-time-ranges). ## Regular expressions Regular expressions can be used to evaluate *string* values in the `WHERE` clause using regular expression comparison operators: * `=~`: Matches a regular expression * `!~`: Doesn’t match a regular expression ```sql SELECT * FROM home WHERE room =~ /^K/ ``` For more information about InfluxQL regular expression syntax, see[InfluxQL regular expressions](/influxdb3/core/reference/influxql/regular-expressions/). ## WHERE clause examples The following examples use the[Home sensor sample dataset](/influxdb3/core/reference/sample-data/#home-sensor-data). [](#select-data-with-a-specific-tag-value) Select data with a specific tag value ```sql SELECT * FROM home WHERE room = 'Living Room' ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T08:00:00Z| 0 |35.9|Living Room|21.1| |2022-01-01T09:00:00Z| 0 |35.9|Living Room|21.4| |2022-01-01T10:00:00Z| 0 | 36 |Living Room|21.8| |2022-01-01T11:00:00Z| 0 | 36 |Living Room|22.2| |2022-01-01T12:00:00Z| 0 |35.9|Living Room|22.2| | … | … | … | … | … | [](#select-data-from-a-specific-time-range) Select data from a specific time range ```sql SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T08:00:00Z| 0 |35.9| Kitchen | 21 | |2022-01-01T08:00:00Z| 0 |35.9|Living Room|21.1| |2022-01-01T09:00:00Z| 0 |36.2| Kitchen | 23 | |2022-01-01T09:00:00Z| 0 |35.9|Living Room|21.4| |2022-01-01T10:00:00Z| 0 |36.1| Kitchen |22.7| |2022-01-01T10:00:00Z| 0 | 36 |Living Room|21.8| [](#select-data-from-a-relative-time-range) Select data from a relative time range ```sql SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-----------|----| |2022-01-01T18:00:00Z|18 |36.9| Kitchen |23.3| |2022-01-01T18:00:00Z| 9 |36.2|Living Room|22.8| |2022-01-01T19:00:00Z|22 |36.6| Kitchen |23.1| |2022-01-01T19:00:00Z|14 |36.3|Living Room|22.5| |2022-01-01T20:00:00Z|26 |36.5| Kitchen |22.7| |2022-01-01T20:00:00Z|17 |36.4|Living Room|22.2| [](#select-field-values-above-a-threshold) Select field values above a threshold ```sql SELECT co FROM home WHERE co > 9 ``` name: home | time |co | |--------------------|---| |2022-01-01T18:00:00Z|18 | |2022-01-01T19:00:00Z|14 | |2022-01-01T19:00:00Z|22 | |2022-01-01T20:00:00Z|17 | |2022-01-01T20:00:00Z|26 | [](#select-specific-field-values) Select specific field values ```sql SELECT room, co FROM home WHERE co = 9 ``` name: home | time | room |co | |--------------------|-----------|---| |2022-01-01T17:00:00Z| Kitchen | 9 | |2022-01-01T18:00:00Z|Living Room| 9 | [](#select-field-values-based-on-arithmetic) Select field values based on arithmetic ```sql SELECT room, co FROM home WHERE co - 10 > 5 ``` name: home | time | room |co | |--------------------|-----------|---| |2022-01-01T18:00:00Z| Kitchen |18 | |2022-01-01T19:00:00Z| Kitchen |22 | |2022-01-01T20:00:00Z|Living Room|17 | |2022-01-01T20:00:00Z| Kitchen |26 | [](#select-data-with-field-values-above-a-threshold-and-a-specific-tag-value) Select data with field values above a threshold and a specific tag value ```sql SELECT * FROM home WHERE temp > 22.7 AND room = 'Kitchen' ``` name: home | time |co |hum | room |temp| |--------------------|---|----|-------|----| |2022-01-01T09:00:00Z| 0 |36.2|Kitchen| 23 | |2022-01-01T13:00:00Z| 1 |36.5|Kitchen|22.8| |2022-01-01T14:00:00Z| 1 |36.3|Kitchen|22.8| |2022-01-01T18:00:00Z|18 |36.9|Kitchen|23.3| |2022-01-01T19:00:00Z|22 |36.6|Kitchen|23.1| [](#select-data-based-on-the-relationship-between-columns) Select data based on the relationship between columns ```sql SELECT co, temp FROM home WHERE co > temp ``` name: home | time |co |temp| |--------------------|---|----| |2022-01-01T20:00:00Z|26 |22.7| ## Notable behaviors * [Single and double quotes](#single-and-double-quotes) * [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) ### Single and double quotes In InfluxQL, single quotation marks (`'`) and double quotation marks (`"`) work differently and can alter the way a `WHERE` clause functions. Single quotes are used in [string](/influxdb3/core/reference/influxql/#strings)and [timestamp](/influxdb3/core/reference/influxql/#dates--times) literals. Double quotes are used to quote [identifiers](/influxdb3/core/reference/influxql/#identifiers), (time, field, and tag column names). For example, the following conditional expression compares the value of the`location` *column* to the *literal string*, `London`: ```sql "location" = 'London' ``` The following conditional expression compares the value of the `location` *column*to the value of the `London` *column*: ```sql "location" = "London" ``` Misused double and single quotes in the `WHERE` clause often results in unexpected empty query results. For more information about quotation marks, see[InfluxQL quotation](/influxdb3/core/reference/influxql/quoting/). ### Cannot query multiple time ranges InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. For example, the following query returns no results: ```sql SELECT * FROM home WHERE (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') ``` | Operator | Meaning | Supported data types | | --- | --- | --- | | Operator | Meaning | Supported data types | | = | Equal to | all | | <> | Not equal to | all | | != | Not equal to | all | | > | Greater than | numeric, timestamp | | >= | Greater than or equal to | numeric, timestamp | | < | Less than | numeric, timestamp | | <= | Less than or equal to | numeric, timestamp | | =~ | Matches a regular expression | strings | | !~ | Doesn’t match a regular expression | strings | | Operator | Meaning | | --- | --- | | Operator | Meaning | | AND | Returns true if both operands are true . Otherwise, returns false . | | OR | Returns true if any operand is true . Otherwise, returns false . | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | | 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | | 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | | 2022-01-01T11:00:00Z | 0 | 36 | Living Room | 22.2 | | 2022-01-01T12:00:00Z | 0 | 35.9 | Living Room | 22.2 | | … | … | … | … | … | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | | 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | | 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | | 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | | 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | | 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | | 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | | 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | | 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | | time | co | | --- | --- | | time | co | | 2022-01-01T18:00:00Z | 18 | | 2022-01-01T19:00:00Z | 14 | | 2022-01-01T19:00:00Z | 22 | | 2022-01-01T20:00:00Z | 17 | | 2022-01-01T20:00:00Z | 26 | | time | room | co | | --- | --- | --- | | time | room | co | | 2022-01-01T17:00:00Z | Kitchen | 9 | | 2022-01-01T18:00:00Z | Living Room | 9 | | time | room | co | | --- | --- | --- | | time | room | co | | 2022-01-01T18:00:00Z | Kitchen | 18 | | 2022-01-01T19:00:00Z | Kitchen | 22 | | 2022-01-01T20:00:00Z | Living Room | 17 | | 2022-01-01T20:00:00Z | Kitchen | 26 | | time | co | hum | room | temp | | --- | --- | --- | --- | --- | | time | co | hum | room | temp | | 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | | 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | | 2022-01-01T14:00:00Z | 1 | 36.3 | Kitchen | 22.8 | | 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | | 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | | time | co | temp | | --- | --- | --- | | time | co | temp | | 2022-01-01T20:00:00Z | 26 | 22.7 | --- # InfluxDB 3 Core internals Source: https://docs.influxdata.com/influxdb3/core/reference/internals/ Learn about InfluxDB 3 Core internal systems and architecture. Understanding these internals can help with performance optimization, troubleshooting, and advanced integrations. ## [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/) InfluxDB 3 Core enforces database retention periods at query time. Retention periods are set when creating a database and cannot be changed afterward. ## [Storage engine](/influxdb3/core/reference/internals/storage-engine/) Learn about the InfluxDB 3 Core storage engine and how it differs from the optional upgraded storage engine available in InfluxDB 3 Enterprise. ## [InfluxDB 3 Core authentication and authorization](/influxdb3/core/reference/internals/authentication/) InfluxDB 3 Core uses an Attribute-Based Access Control (ABAC) model to manage permissions for authentication (authn) and authorization (authz). ## [Data durability](/influxdb3/core/reference/internals/durability/) Learn how InfluxDB 3 Core ensures data durability through a structured write path that balances performance, persistence, and query efficiency. --- # InfluxDB 3 Core authentication and authorization Source: https://docs.influxdata.com/influxdb3/core/reference/internals/authentication/ InfluxDB 3 Core uses an Attribute-Based Access Control (ABAC) model to manage permissions and supports multiple token types for different authentication scenarios. The ABAC model includes the following components: * **Authentication (authn)**: The process through which a user verifies their identity. In InfluxDB 3 Core, this occurs when a token is validated. Users may be human or machine (for example, through automation). InfluxDB 3 Core tokens represent previously verified authenticated users that facilitate automation. * **Authorization (authz)**: The process that determines if an authenticated user can perform a requested action. In InfluxDB 3 Core, authorization evaluates whether a token has permissions to perform actions on specific resources. * **Context**: The system may use contextual information, such as location or time, when evaluating permissions. * **Subject**: The identity requesting access to the system. In InfluxDB 3 Core, the subject is a *token* (similar to an “API key” in other systems). Tokens include attributes such as identifier, name, description, and expiration date. * **Action**: The operations (for example, CRUD) that subjects may perform on resources. * **Permissions**: The set of actions that a specific subject can perform on a specific resource. Authorization compares the incoming request against the permissions set to decide if the request is allowed or not. In InfluxDB 3 Core, *admin* tokens have all permissions. * **Resource**: The objects that can be accessed or manipulated. Resources have attributes such as identifier and name. In InfluxDB 3 Core, resources include databases and system information endpoints. #### Related * [Manage tokens](/influxdb3/core/admin/tokens/) --- # Data retention in InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/reference/internals/data-retention/ InfluxDB 3 Core enforces database retention periods at query time. Any points with timestamps beyond a retention period are filtered out of query results, even though the data may still exist in storage. * [Database retention period](#database-retention-period) * [Retention period duration formats](#retention-period-duration-formats) * [Set database retention period](#set-database-retention-period) ## Database retention period A **database retention period** is the duration of time that a database retains data. Retention periods are designed to automatically delete expired data and optimize storage without any user intervention. By default, data does not expire. When you [create a database](/influxdb3/core/admin/databases/create/), you can optionally set a retention period. Retention periods can be as short as an hour or infinite (`none`). [Points](/influxdb3/core/reference/glossary/#point) in a database with timestamps beyond the defined retention period (relative to now) are not queryable, but may still exist in storage until fully deleted by the retention enforcement service . ## Retention period duration formats Retention periods are specified as [duration](/influxdb3/core/reference/glossary/#duration)values using a numeric value plus a duration unit. The retention period value cannot be negative or contain whitespace. ### Valid duration units |Unit| Description | |----|---------------| |`h` | hour | |`d` | day | |`w` | week | |`mo`|month (30 days)| |`y` |year (365 days)| > [!Note] > Minute (`m`) and second (`s`) units are not supported for retention periods. > [!Warning] > #### Retention period constraints > > * **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). > * **Zero-duration periods**: Setting a retention period to `0` (for example,`0d` or `0h`) is allowed but marks all data for immediate deletion at query time.*This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention.* > * **Infinite retention**: Use `none` to set an infinite retention period. ### Example retention period values |Value | Description | |------|-----------------------------| | `1h` | 1 hour | |`24h` | 24 hours (1 day) | | `7d` | 7 days | | `4w` | 4 weeks (28 days) | |`1mo` | 1 month (30 days) | |`90d` | 90 days | | `1y` | 1 year (365 days) | |`none`|Infinite - data never expires| You can combine multiple duration units in a single value: | Value | Description | |--------|--------------------------------| |`30d12h`|30 days and 12 hours (30.5 days)| | `2w3d` | 2 weeks and 3 days (17 days) | |`1y6mo` | 1 year and 6 months (545 days) | ### Set database retention period Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/) or the [/api/v3/configure/database](/influxdb3/core/api/database/#operation/PostConfigureDatabase) HTTP API endpoint to create a database with a retention period: #### influxdb3 CLI #### ```bash # Create a database with a 30-day retention period influxdb3 create database --retention-period 30d DATABASE_NAME # Create a database with infinite retention influxdb3 create database --retention-period none DATABASE_NAME # Create a database with a 90-day retention period using authentication influxdb3 create database \ --retention-period 90d \ --token AUTH_TOKEN \ DATABASE_NAME ``` ```bash # Create a database with a 30-day retention period curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "30d" }' # Create a database with infinite retention curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "none" }' # Create a database with a 90-day retention period curl --request POST "http://localhost:8181/api/v3/configure/database" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "db": "DATABASE_NAME", "retention_period": "90d" }' ``` Replace the following: * `DATABASE_NAME`: the name of the database * `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/) > [!Note] > #### Retention periods are immutable in Core > > In InfluxDB 3 Core, retention periods can only be set when[creating a database](/influxdb3/core/admin/databases/create/) and cannot be > changed afterward. If you need to change a retention period, you must create a > new database with the desired retention period and migrate your data. > > #### Upgrade to InfluxDB 3 Enterprise for advanced retention features > > With InfluxDB 3 Enterprise, you can set table-level retention policies and update > retention periods after creation. For more information, see[InfluxDB 3 Enterprise data retention](/influxdb3/enterprise/reference/internals/data-retention/). #### Related * [Create a database](/influxdb3/core/admin/databases/create/) * [influxdb3 create database](/influxdb3/core/reference/cli/influxdb3/create/database/) * [Create database API](/influxdb3/core/api/database/#operation/PostConfigureDatabase) [internals](/influxdb3/core/tags/internals/)[retention](/influxdb3/core/tags/retention/) | Unit | Description | | --- | --- | | Unit | Description | | h | hour | | d | day | | w | week | | mo | month (30 days) | | y | year (365 days) | | Value | Description | | --- | --- | | Value | Description | | 1h | 1 hour | | 24h | 24 hours (1 day) | | 7d | 7 days | | 4w | 4 weeks (28 days) | | 1mo | 1 month (30 days) | | 90d | 90 days | | 1y | 1 year (365 days) | | none | Infinite - data never expires | | Value | Description | | --- | --- | | Value | Description | | 30d12h | 30 days and 12 hours (30.5 days) | | 2w3d | 2 weeks and 3 days (17 days) | | 1y6mo | 1 year and 6 months (545 days) | --- # InfluxDB 3 Core internals Source: https://docs.influxdata.com/influxdb3/core/reference/internals/durability/ ## How data flows through InfluxDB 3 Core When data is written to InfluxDB 3 Core, it progresses through multiple stages to ensure durability, optimize performance, and enable efficient querying. Configuration options at each stage affect system behavior, balancing reliability and resource usage. ## Data flow for writes As written data moves through InfluxDB 3 Core, it follows a structured path to ensure durability, efficient querying, and optimized storage. Ingest path and data flow for InfluxDB 3 Core & EnterpriseFigure: Write request, response, and ingest flow for InfluxDB 3 Core and Enterprise 1. [Write validation and memory buffer](#write-validation-and-memory-buffer) 2. [Write-ahead log (WAL) persistence](#write-ahead-log-wal-persistence) 3. [Query availability](#query-availability) 4. [Parquet storage](#parquet-storage) 5. [In-memory cache](#in-memory-cache) ### Write validation and memory buffer * **Process**: InfluxDB validates incoming data before accepting it into the system. * **Impact**: Prevents malformed or unsupported data from entering the database. * **Details**: The database validates incoming data and stores it in the write buffer (in memory). If `no_sync=true`, the server sends a response to acknowledge the write [without waiting for persistence](/influxdb3/core/reference/cli/influxdb3/write/#write-line-protocol-and-immediately-return-a-response). ### Write-ahead log (WAL) persistence * **Process**: The database flushes the write buffer to the WAL every second (default). * **Impact**: Ensures durability by persisting data to object storage. * **Tradeoff**: More frequent flushing improves durability but increases I/O overhead. * **Details**: Every second (default), the database flushes the write buffer to the Write-Ahead Log (WAL) for persistence in the object store. If `no_sync=false` (default), the server sends a response to acknowledge the write. ### Query availability * **Process**: The system moves data to the queryable buffer after WAL persistence. * **Impact**: Enables fast queries on recent data. * **Tradeoff**: A larger buffer speeds up queries but increases memory usage. * **Details**: After WAL persistence completes, data moves to the queryable buffer where it becomes available for queries. By default, the server keeps up to 900 WAL files (15 minutes of data) buffered. ### Parquet storage * **Process**: Every ten minutes (default), data is persisted to Parquet files in object storage. * **Impact**: Provides durable, long-term storage. * **Tradeoff**: More frequent persistence reduces reliance on the WAL but increases I/O costs. * **Memory usage**: The persistence process uses memory from the configured memory pool ([`exec-mem-pool-size`](/influxdb3/core/reference/config-options/#exec-mem-pool-size)) when converting data to Parquet format. For write-heavy workloads, ensure adequate memory is allocated. * **Details**: Every ten minutes (default), InfluxDB 3 Core persists the oldest data from the queryable buffer to the object store in Parquet format, and keeps the remaining data (the most recent 5 minutes) in memory. ### WAL tail The *WAL tail* is the most recent data in the WAL that InfluxDB 3 Core has not yet durably persisted beyond the WAL. Because InfluxDB 3 Core flushes the WAL to object storage every second, the WAL tail is durable, but it remains in the WAL until the next Parquet persistence captures it. ### In-memory cache * **Process**: Recently persisted Parquet files are cached in memory. * **Impact**: Reduces query latency by minimizing object storage access. * **Details**: InfluxDB 3 Core puts Parquet files into an in-memory cache so that queries against the most recently persisted data don’t have to go to object storage. --- # Storage engine Source: https://docs.influxdata.com/influxdb3/core/reference/internals/storage-engine/ InfluxDB 3 Core always writes and stores data using the Parquet storage engine—see [Data durability](/influxdb3/core/reference/internals/durability/)for how data flows from write to Parquet persistence. InfluxDB 3 Enterprise also offers an upgraded storage engine as an alternative; InfluxDB 3 Core does not include it. #### Related * [InfluxDB 3 Core internals](/influxdb3/core/reference/internals/durability/) * [Enterprise storage engine](/influxdb3/enterprise/reference/internals/storage-engine/) [storage](/influxdb3/core/tags/storage/)[internals](/influxdb3/core/tags/internals/) --- # Line protocol reference Source: https://docs.influxdata.com/influxdb3/core/reference/line-protocol/ InfluxDB 3 Core uses line protocol to write data points. It is a text-based format that provides the table, tag set, field set, and timestamp of a data point. * [Elements of line protocol](#elements-of-line-protocol) * [Data types and format](#data-types-and-format) * [Quotes](#quotes) * [Special characters](#special-characters) * [Comments](#comments) * [Naming restrictions](#naming-restrictions) * [Duplicate points](#duplicate-points) ```text # Syntax
[,=[,=]] =[,=] [] ``` ```lp myTable,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000 ``` Lines separated by the newline character `\n` represent a single point in InfluxDB. Line protocol is whitespace-sensitive. > [!Note] > Line protocol does not support the newline character `\n` in tag or field values. ## Elements of line protocol myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 ### Table (Required) The table name. InfluxDB accepts one table per point.*Table names are case-sensitive and subject to [naming restrictions](#naming-restrictions).* ***Data type:** [String](#string)* > [!Note] > If familiar with previous InfluxDB versions, “**table**” is synonymous with > “**measurement**.” ### Tag set (***Optional***) All tag key-value pairs for the point. Key-value relationships are denoted with the `=` operand. Multiple tag key-value pairs are comma-delimited.*Tag keys and tag values are case-sensitive. Tag keys are subject to [naming restrictions](#naming-restrictions). Tag values cannot be empty; instead, omit the tag from the tag set.* ***Key data type:** [String](#string)* ***Value data type:** [String](#string)* ### Field set (Required) All field key-value pairs for the point. Points must have at least one field.*Field keys and string values are case-sensitive. Field keys are subject to [naming restrictions](#naming-restrictions).* ***Key data type:** [String](#string)* ***Value data type:** [Float](#float) | [Integer](#integer) | [UInteger](#uinteger) | [String](#string) | [Boolean](#boolean)* > [!Note] > *Always double quote string field values. More on quotes [below](#quotes).* > > ``` > tableName fieldKey="field string value" 1556813561098000000 > ``` ### Timestamp (***Optional***) The [Unix timestamp](/influxdb3/core/reference/glossary/#unix-timestamp) for the data point. InfluxDB accepts one timestamp per point. If no timestamp is provided, InfluxDB uses the system time (UTC) of its host machine. ***Data type:** [Unix timestamp](#unix-timestamp)* > [!Note] > #### Important notes about timestamps > > * To ensure a data point includes the time a metric is observed (not received by InfluxDB), > include the timestamp. > * If your timestamps are not in nanoseconds, specify the precision of your timestamps > when writing the data to InfluxDB 3 Core. ### Whitespace Whitespace in line protocol determines how InfluxDB interprets the data point. The **first unescaped space** delimits the table and the tag set from the field set. The **second unescaped space** delimits the field set from the timestamp. myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 ## Data types and format ### Float IEEE-754 64-bit floating-point numbers. Default numerical type.*InfluxDB supports scientific notation in float field values.* ##### Float field value examples ```lp myTable fieldKey=1.0 myTable fieldKey=1 myTable fieldKey=-1.234456e+78 ``` ### Integer Signed 64-bit integers. Trailing `i` on the number specifies an integer. | Minimum integer | Maximum integer | |-----------------------|----------------------| |`-9223372036854775808i`|`9223372036854775807i`| ##### Integer field value examples ```lp myTable fieldKey=1i myTable fieldKey=12485903i myTable fieldKey=-12485903i ``` ### UInteger Unsigned 64-bit integers. Trailing `u` on the number specifies an unsigned integer. |Minimum uinteger| Maximum uinteger | |----------------|-----------------------| | `0u` |`18446744073709551615u`| ##### UInteger field value examples ```lp myTable fieldKey=1u myTable fieldKey=12485903u ``` ### String Plain text string. | Element |Maximum length| |-----------------------------------------|--------------| |Table name, tag key, tag value, field key| 64KB | | Field value | 1MB | ##### String example ```lp # String table name, field key, and field value myTable fieldKey="this is a string" ``` ### Boolean Stores `true` or `false` values. |Boolean value| Accepted syntax | |-------------|-----------------------------------| | True | `t`, `T`, `true`, `True`, `TRUE` | | False |`f`, `F`, `false`, `False`, `FALSE`| ##### Boolean field value examples ```lp myTable fieldKey=true myTable fieldKey=false myTable fieldKey=t myTable fieldKey=f myTable fieldKey=TRUE myTable fieldKey=FALSE ``` > [!Note] > Do not quote boolean field values. > Quoted field values are interpreted as strings. ### Unix timestamp Unix timestamp in a [specified precision](/influxdb3/core/reference/glossary/#unix-timestamp). Default precision is nanoseconds (`ns`). | Minimum timestamp | Maximum timestamp | |----------------------|---------------------| |`-9223372036854775806`|`9223372036854775806`| ##### Unix timestamp example ```lp myTableName fieldKey="fieldValue" 1556813561098000000 ``` ## Quotes Line protocol supports single and double quotes as described in the following table: | Element | Double quotes | Single quotes | |-----------|---------------------------------------|---------------------------------------| | Table |*Limited* *|*Limited* *| | Tag key |*Limited* *|*Limited* *| | Tag value |*Limited* *|*Limited* *| | Field key |*Limited* *|*Limited* *| |Field value| **Strings only** | Never | | Timestamp | Never | Never | * *Line protocol accepts double and single quotes in table names, tag keys, tag values, and field keys, but interprets them as part of the name, key, or value.* ## Special Characters Line protocol supports special characters in [string elements](#string). In the following contexts, it requires escaping certain characters with a backslash (`\`): | Element | Escape characters | |-----------|-------------------------| | Table | Comma, Space | | Tag key |Comma, Equals Sign, Space| | Tag value |Comma, Equals Sign, Space| | Field key |Comma, Equals Sign, Space| |Field value| Double quote, Backslash | You do not need to escape other special characters. ##### Examples of special characters in line protocol ```lp # Table name with spaces my\ Table fieldKey="string value" # Double quotes in a string field value myTable fieldKey="\"string\" within a string" # Tag keys and values with spaces myTable,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100 # Emojis myTable,tagKey=🍭 fieldKey="Launch 🚀" 1556813561098000000 ``` ### Escaping backslashes Line protocol supports both literal backslashes and backslashes as an escape character. With two contiguous backslashes, the first is interpreted as an escape character. For example: |Backslashes|Interpreted as| |-----------|--------------| | `\` | `\` | | `\\` | `\` | | `\\\` | `\\` | | `\\\\` | `\\` | | `\\\\\` | `\\\` | | `\\\\\\` | `\\\` | ## Comments Line protocol interprets `#` at the beginning of a line as a comment character and ignores all subsequent characters until the next newline `\n`. ```lp # This is a comment myTable fieldKey="string value" 1556813561098000000 ``` ## Naming restrictions Table names, tag keys, and field keys are alphanumeric and must begin with a letter or a number. They can contain dashes (`-`) and underscores (`_`). ## Duplicate points A point is uniquely identified by the table name, tag set, and timestamp. If you submit line protocol with the same table, tag set, and timestamp, but with a different field set, the field set becomes the union of the old field set and the new field set, where any conflicts favor the new field set. Overwrite behavior is product-specific. Read the following warning before relying on overwrites to maintain a last-value view. > [!Warning] > #### Overwrites are not deterministic > > Overwriting a point is not reliable in InfluxDB 3 Core, regardless of the > delay between writes: queries may return either version, and either version may > be permanently stored. > > To maintain a last-value view, use the [append-only patterns](#recommended-patterns-for-last-value-tracking)instead of overwrites. ### Recommended patterns for last-value tracking To reliably maintain a last-value view of your data, use one of these append-only patterns: #### Append-only with unique timestamps (recommended) Write each change as a new point with a unique timestamp using the actual event time. Query for the most recent point to get the current value. **Line protocol example**: ```text device_status,device_id=sensor01 status="active",temperature=72.5 1700000000000000000 device_status,device_id=sensor01 status="active",temperature=73.1 1700000300000000000 device_status,device_id=sensor01 status="inactive",temperature=73.1 1700000600000000000 ``` **SQL query to get latest state**: ```sql SELECT device_id, status, temperature, time FROM device_status WHERE time >= now() - INTERVAL '7 days' AND device_id = 'sensor01' ORDER BY time DESC LIMIT 1 ``` **InfluxQL query to get latest state**: ```influxql SELECT LAST(status), LAST(temperature) FROM device_status WHERE device_id = 'sensor01' AND time >= now() - 7d GROUP BY device_id ``` #### Append-only with change tracking field If you need to filter by “changes since a specific time,” add a dedicated `last_change_timestamp` field. **Line protocol example**: ```text device_status,device_id=sensor01 status="active",temperature=72.5,last_change_timestamp=1700000000000000000i 1700000000000000000 device_status,device_id=sensor01 status="active",temperature=73.1,last_change_timestamp=1700000300000000000i 1700000300000000000 device_status,device_id=sensor01 status="inactive",temperature=73.1,last_change_timestamp=1700000600000000000i 1700000600000000000 ``` **SQL query to get changes since a specific time**: ```sql SELECT device_id, status, temperature, time FROM device_status WHERE last_change_timestamp >= 1700000000000000000 ORDER BY time DESC ``` ### Anti-patterns to avoid The following patterns will produce non-deterministic results when duplicate points are flushed together: #### Don’t overwrite the same (time, tags) point If points with the same time and tag set are flushed to storage together, any of the values might be retained. For example, **don’t do this**: ```text -- All writes use the same timestamp device_status,device_id=sensor01 status="active",temperature=72.5 1700000000000000000 device_status,device_id=sensor01 status="active",temperature=73.1 1700000000000000000 device_status,device_id=sensor01 status="inactive",temperature=73.1 1700000000000000000 ``` #### Don’t add a field while overwriting data (time, tags) Adding a field doesn’t make points unique. Points with the same time and tag set are still considered duplicates–for example,**don’t do this**: ```text -- All writes use the same timestamp, but add a version field device_status,device_id=sensor01 status="active",temperature=72.5,version=1i 1700000000000000000 device_status,device_id=sensor01 status="active",temperature=73.1,version=2i 1700000000000000000 device_status,device_id=sensor01 status="inactive",temperature=73.1,version=3i 1700000000000000000 ``` #### Don’t rely on short write delays to force ordering Short delays don’t guarantee that duplicate points won’t be flushed together. The flush interval depends on buffer size, ingestion rate, and system load. In InfluxDB 3 Core, overwrite timing is never deterministic, regardless of delay length; use the append-only patterns instead. For example, **don’t do this**: ```text -- Writing with delays between each write device_status,device_id=sensor01 status="active" 1700000000000000000 # Wait 10 seconds... device_status,device_id=sensor01 status="inactive" 1700000000000000000 ``` Append-only patterns increase row count. See [Create a database](/influxdb3/core/admin/databases/create/) to configure shorter retention for last-value data. For query and storage guidance, see [Performance tuning](/influxdb3/core/admin/performance-tuning/). #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/write-data/) [write](/influxdb3/core/tags/write/)[line protocol](/influxdb3/core/tags/line-protocol/)[syntax](/influxdb3/core/tags/syntax/) | Minimum integer | Maximum integer | | --- | --- | | Minimum integer | Maximum integer | | -9223372036854775808i | 9223372036854775807i | | Minimum uinteger | Maximum uinteger | | --- | --- | | Minimum uinteger | Maximum uinteger | | 0u | 18446744073709551615u | | Element | Maximum length | | --- | --- | | Element | Maximum length | | Table name, tag key, tag value, field key | 64KB | | Field value | 1MB | | Boolean value | Accepted syntax | | --- | --- | | Boolean value | Accepted syntax | | True | t , T , true , True , TRUE | | False | f , F , false , False , FALSE | | Minimum timestamp | Maximum timestamp | | --- | --- | | Minimum timestamp | Maximum timestamp | | -9223372036854775806 | 9223372036854775806 | | Element | Double quotes | Single quotes | | --- | --- | --- | | Element | Double quotes | Single quotes | | Table | Limited * | Limited * | | Tag key | Limited * | Limited * | | Tag value | Limited * | Limited * | | Field key | Limited * | Limited * | | Field value | Strings only | Never | | Timestamp | Never | Never | | Element | Escape characters | | --- | --- | | Element | Escape characters | | Table | Comma, Space | | Tag key | Comma, Equals Sign, Space | | Tag value | Comma, Equals Sign, Space | | Field key | Comma, Equals Sign, Space | | Field value | Double quote, Backslash | | Backslashes | Interpreted as | | --- | --- | | Backslashes | Interpreted as | | \ | \ | | \\ | \ | | \\\ | \\ | | \\\\ | \\ | | \\\\\ | \\\ | | \\\\\\ | \\\ | --- # Naming restrictions and conventions Source: https://docs.influxdata.com/influxdb3/core/reference/naming-restrictions/ InfluxDB 3 has specific naming restrictions and conventions that apply to databases, tables, tags, fields, and other identifiers. Understanding these restrictions helps ensure your data model works correctly with all query languages and avoids naming conflicts. ## Database names Database names must follow these restrictions: * **Length**: Maximum 64 characters * **Allowed characters**: Only alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`), and forward-slash (`/`) * **Prohibited characters**: Cannot contain whitespace, punctuation, or other special characters * **Starting character**: Should start with a letter or number and should not start with underscore (`_`) * **Case sensitivity**: Database names are case-sensitive ### Examples **Valid database names:** ```text mydb sensor_data prod-metrics logs/application webserver123 ``` **Invalid database names:** ```text my database # Contains whitespace sensor.data # Contains period app@server # Contains special character _internal # Starts with underscore (not recommended) very_long_database_name_that_exceeds_sixty_four_character_limit # Too long ``` ## Table (measurement) names Table names in InfluxDB 3 Core follow line protocol measurement naming rules: * **Length**: No explicit limit, but practical limits apply for performance * **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`) * **Starting character**: Should start with a letter or number and should not start with underscore (`_`) * **Case sensitivity**: Table names are case-sensitive * **Quoting**: Use double quotes when names contain special characters or whitespace ### Examples **Valid table names:** ```text temperature cpu_usage http-requests sensor123 웹서버_메트릭스 # UTF-8 characters ``` **Names requiring quotes in queries:** ```text "my table" # Contains whitespace "cpu.usage" # Contains period "http@requests" # Contains special character ``` **Invalid table names:** ```text _internal # Starts with underscore (not recommended) ``` ## Tag keys and field keys Tag keys and field keys follow these restrictions: * **Length**: No explicit limit, but shorter names improve performance * **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`) * **Starting character**: Should start with a letter or number and should not start with underscore (`_`) * **Case sensitivity**: Tag and field keys are case-sensitive * **Quoting**: Use double quotes when names contain special characters or whitespace ### Examples **Valid tag and field keys:** ```text host region temperature cpu_usage http-status sensor123 ``` **Keys requiring quotes in queries:** ```text "host name" # Contains whitespace "cpu.usage" # Contains period "http@status" # Contains special character ``` **Invalid tag and field keys:** ```text _internal # Starts with underscore (not recommended) ``` ## Tag values and field values Tag and field values have different restrictions: ### Tag values * **Type**: Must be strings * **Length**: No explicit limit * **Characters**: Any UTF-8 characters allowed * **Case sensitivity**: Tag values are case-sensitive * **Null values**: Allowed (excluded from primary key) ### Field values * **Type**: Can be integers, floats, strings, booleans, or unsigned integers * **Length**: No explicit limit for strings * **Characters**: Any UTF-8 characters allowed for strings * **Case sensitivity**: String field values are case-sensitive * **Null values**: Allowed (but at least one field must be non-null per row) ## Query language specific considerations Different query languages have additional naming requirements: ### SQL identifiers When using SQL to query InfluxDB 3 Core: * **Unquoted identifiers**: Must start with letter or underscore, contain only letters, digits, or underscores * **Quoted identifiers**: Use double quotes (`"`) for names with special characters, whitespace, or to preserve case * **Case sensitivity**: Unquoted identifiers are case-insensitive, quoted identifiers are case-sensitive * **Reserved keywords**: [SQL keywords](/influxdb3/clustered/reference/sql/#keywords) must be quoted when used as identifiers ### InfluxQL identifiers When using InfluxQL to query InfluxDB 3 Core: * **Unquoted identifiers**: Must start with ASCII letter or underscore, contain only ASCII letters, digits, or underscores * **Quoted identifiers**: Use double quotes (`"`) for names with special characters or whitespace * **Case sensitivity**: All identifiers are case-sensitive * **Reserved keywords**: [InfluxQL keywords](/influxdb3/clustered/reference/influxql/#keywords) must be quoted when used as identifiers * **Character encoding**: UTF-8 encoding supported ## Reserved namespaces ### System reserved prefixes The following prefixes may be reserved for system use: * **`_`** (underscore): May be reserved for system databases, measurements, and field keys * **`iox_`**: Reserved for InfluxDB internal metadata > [!Caution] > #### Using underscore-prefixed names > > While InfluxDB might not explicitly reject names starting with underscore (`_`), > using them risks conflicts with current or future system features and may > result in unexpected behavior or data loss. ### Common reserved keywords Avoid using these common reserved keywords as identifiers without quoting: **SQL keywords** (partial list): * `SELECT`, `FROM`, `WHERE`, `GROUP`, `ORDER`, `BY` * `CREATE`, `DROP`, `ALTER`, `INSERT`, `UPDATE`, `DELETE` * `TABLE`, `DATABASE`, `INDEX`, `VIEW` * `TIME`, `TIMESTAMP`, `INTERVAL` **InfluxQL keywords** (partial list): * `SELECT`, `FROM`, `WHERE`, `GROUP`, `ORDER`, `BY` * `SHOW`, `DROP`, `CREATE`, `DELETE` * `MEASUREMENT`, `TAG`, `FIELD`, `TIME` * `LIMIT`, `OFFSET`, `SLIMIT`, `SOFFSET` For complete lists, see: * [SQL keywords](/influxdb3/clustered/reference/sql/#keywords) * [InfluxQL keywords](/influxdb3/clustered/reference/influxql/#keywords) ## Best practices ### Naming conventions 1. **Use descriptive names**: Choose names that clearly describe the data 2. **Keep names simple**: Avoid special characters when possible 3. **Use consistent casing**: Establish and follow a consistent case convention 4. **Avoid reserved keywords**: Don’t use SQL or InfluxQL keywords as identifiers 5. **Use underscores for separation**: Prefer `cpu_usage` over `cpu-usage` or `cpuUsage` ### Performance considerations 1. **Shorter names**: Shorter names improve query performance and reduce storage 2. **Avoid excessive tag cardinality**: Too many unique tag values can impact performance 3. **Limit column count**: Keep the number of columns (tags + fields) reasonable 4. **Consistent naming**: Use the same names across related tables ### Example naming strategy ```text # Database naming prod-metrics dev-logs sensor-data # Table naming cpu_usage memory_utilization http_requests disk_io # Tag keys host region service environment # Field keys value count duration_ms bytes_sent ``` ## Quoting identifiers When identifiers contain special characters, whitespace, or reserved keywords, they must be quoted in queries: ### SQL examples ```sql -- Quoted database and table names SELECT * FROM "my-database"."my table"; -- Quoted column names SELECT "cpu usage", "memory.available" FROM metrics; -- Reserved keyword as identifier SELECT "group" FROM "user-data"; ``` ### InfluxQL examples ```influxql -- Quoted measurement name SELECT * FROM "http requests"; -- Quoted tag key with special characters SELECT * FROM metrics WHERE "host.name" = 'server01'; -- Reserved keyword as field SELECT "time" FROM "system-metrics"; ``` ## Troubleshooting naming issues ### Common error patterns 1. **Unquoted special characters**: Use double quotes around identifiers with special characters 2. **Reserved keyword conflicts**: Quote reserved keywords when used as identifiers 3. **Case sensitivity issues**: Check case sensitivity rules for your query language 4. **Underscore prefix warnings**: Avoid starting names with underscore to prevent conflicts ### Validation tips 1. **Test names in queries**: Verify names work correctly in your target query language 2. **Check for reserved keywords**: Cross-reference names against keyword lists 3. **Validate character encoding**: Ensure UTF-8 characters are properly encoded 4. **Consider future compatibility**: Choose names that work across different query languages #### Related * [Create a database](/influxdb3/core/admin/databases/create/) * [Line protocol reference](/influxdb3/core/reference/line-protocol/) * [SQL reference documentation](/influxdb3/core/reference/sql/) * [InfluxQL reference documentation](/influxdb3/core/reference/influxql/) --- # Processing engine reference Source: https://docs.influxdata.com/influxdb3/core/reference/processing-engine/ The Processing engine is an embedded Python virtual machine that runs inside an InfluxDB 3 Core database server. It executes Python code in response to triggers and database events without requiring external application servers or middleware. ## Enable and disable the Processing Engine The Processing Engine activates when [`--plugin-dir`](/influxdb3/core/reference/config-options/#plugin-dir) or `INFLUXDB3_PLUGIN_DIR` is configured. When not configured, the Python environment and PyO3 bindings aren’t initialized, and the server runs without Processing Engine functionality. ### Default behavior by deployment type | Deployment |Default state| Configuration | |----------------|-------------|-----------------------------------------| | Docker images | **Enabled** | `INFLUXDB3_PLUGIN_DIR=/plugins` | |DEB/RPM packages| **Enabled** |`plugin-dir="/var/lib/influxdb3/plugins"`| | Binary/source | Disabled | No `plugin-dir` configured | ### Disable in Docker deployments Docker images set `INFLUXDB3_PLUGIN_DIR=/plugins` by default. > [!Warning] > Setting `INFLUXDB3_PLUGIN_DIR=""` (empty string) does **not** disable the Processing Engine. > You must unset the variable, not set it to empty. Use a custom entrypoint that unsets the variable: ```bash docker run --entrypoint /bin/sh influxdb:3-core -c 'unset INFLUXDB3_PLUGIN_DIR && exec influxdb3 serve --object-store memory' ``` ### Disable in systemd deployments (DEB/RPM) The post-install script sets `plugin-dir="/var/lib/influxdb3/plugins"` in the TOML configuration. To disable the Processing Engine: 1. Edit the configuration file: ``` sudo nano /etc/influxdb3/influxdb3-core.conf ``` 2. Comment out or remove the `plugin-dir` line: ``` # plugin-dir="/var/lib/influxdb3/plugins" ``` > [!Warning] > Do not set `plugin-dir=""` (empty string)—you must remove or comment out the line. 3. Restart the service: ``` sudo systemctl restart influxdb3-core ``` > [!Note] > The `/var/lib/influxdb3/plugins` directory can remain on disk. > The Processing Engine only activates based on the `plugin-dir` configuration, not directory existence. ### Benefits of disabling When the Processing Engine is disabled: * The Python environment and PyO3 bindings are not initialized * Plugin-related operations return a “No plugin directory configured” error * The server runs with reduced resource usage This is useful for deployments that don’t require plugin functionality and want a minimal server footprint. ## How it works ### Architecture The Processing engine runs Python code directly within a InfluxDB 3 Core server process. This design provides high performance and direct access to database resources. * **Embedded execution**: Code runs in the same process space as the database server * **Direct data access**: Zero-copy access to data * **Event-driven**: Responds to database writes, scheduled events, and HTTP requests * **Cache integration**: Access to system caches including Last values and Distinct values > [!Note] > The Processing engine runs all plugins in the same Python process. Changes made by one plugin can affect other plugins. ### Event processing flow When specific events occur in the database, the Processing engine handles them through a consistent sequence: 1. A **trigger** specific to the event type activates its plugin. The event types include: * Data writes to specific tables or all tables * Scheduled events (time-based or cron expressions) * HTTP requests to configured endpoints 2. The engine loads the associated **plugin** specified in the trigger configuration 3. The plugin receives context data specific to the trigger type: * Write triggers: the written data and table information * Schedule triggers: the scheduled call time * HTTP triggers: the request object with methods, headers, and body 4. The plugin processes the received data, can query the database, call external tools, and write and cache data in the database 5. Execution completes and the engine returns to waiting state ## Key components ### Trigger system Triggers connect database events to Python code execution based on specific conditions: * **Data write triggers**: Execute on WAL flush events, when data is written to the object store, for a specific table or all tables in a database * **Scheduled triggers**: Run at intervals or according to cron expressions * **HTTP triggers**: Respond to HTTP requests to custom endpoints ### Plugin registry The registry manages all Python code available to the Processing engine: * Indexes plugins by filename and location * Tracks which plugins are used by which triggers * Manages plugin versioning and dependencies ### Memory management The Processing engine implements specialized memory handling to ensure stability and performance: * **Execution isolation**: Each plugin runs in its own context * **Cache system**: Maintains state between executions * **Resource limits**: Controls memory usage and execution time ## Performance characteristics The Processing engine is designed for high-performance operation with minimal overhead: * **Low latency**: Activates triggers in sub-millisecond time * **Efficient access**: Accesses database directly without network overhead * **Controlled resources**: Limits memory and CPU usage through configuration * **Execution policies**: Offers synchronous or asynchronous processing options ## Reliability features The Processing engine includes multiple features to ensure consistent and dependable execution: * **Error handling**: Configures behaviors for failure scenarios (log, retry, or disable) * **Execution tracking**: Tracks plugin performance and resource usage * **State persistence**: Persists cache state across server restarts ## Extension capabilities Extend and customize the Processing engine through several built-in mechanisms: * **Package management**: Installs custom Python dependencies * **Plugin distribution**: Distributes plugins via Git repositories * **Shared API**: Provides consistent interface for database operations For a step-by-step guide to setting up and using the Processing engine, see the [Getting started with plugins](/influxdb3/core/plugins/) documentation. [plugin](/influxdb3/core/tags/plugin/)[database](/influxdb3/core/tags/database/)[python](/influxdb3/core/tags/python/) | Deployment | Default state | Configuration | | --- | --- | --- | | Deployment | Default state | Configuration | | Docker images | Enabled | INFLUXDB3_PLUGIN_DIR=/plugins | | DEB/RPM packages | Enabled | plugin-dir="/var/lib/influxdb3/plugins" | | Binary/source | Disabled | No plugin-dir configured | --- # Sample data Source: https://docs.influxdata.com/influxdb3/core/reference/sample-data/ Sample datasets are used throughout the InfluxDB 3 Core documentation to demonstrate functionality. Use the following sample datasets to replicate provided examples. * [Home sensor data](#home-sensor-data) * [Home sensor actions data](#home-sensor-actions-data) * [NOAA Bay Area weather data](#noaa-bay-area-weather-data) * [European Union wind data](#european-union-wind-data) * [Bitcoin price data](#bitcoin-price-data) * [Random numbers sample data](#random-numbers-sample-data) ## Home sensor data Includes simulated hourly home sensor data with anomalous sensor readings to demonstrate processing and alerting on time series data. To customize timestamps in the dataset, use the button in the lower right corner of the page. ##### Time Range **2022-01-01T08:00:00Z**to**2022-01-01T20:00:00Z***(Customizable)* ##### Schema * home *(table)* * **tags**: * room * Kitchen * Living Room * **fields**: * co *(integer)* * temp *(float)* * hum *(float)* [](#write-home-sensor-data-to-influxdb) Write home sensor data to InfluxDB #### Write the home sensor data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the home sensor sample data to InfluxDB 3 Core. #### influxdb3 #### ```bash influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' ``` ```bash curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1735549200 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1735549200 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1735552800 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1735552800 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1735556400 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1735556400 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1735560000 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1735560000 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1735563600 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1735563600 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1735567200 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1735567200 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1735570800 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1735570800 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1735574400 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1735574400 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1735578000 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1735578000 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1735581600 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1735581600 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1735585200 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1735585200 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1735588800 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1735588800" ``` ```bash curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary " home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 " ``` ```bash curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME&precision=s \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary " home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 " ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of [database](/influxdb3/core/admin/databases/) to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## Home sensor actions data Includes hypothetical actions triggered by data in the [home sensor data](#home-sensor-data)and is a companion dataset to that sample dataset. To customize timestamps in the dataset, use the button in the lower right corner of the page. This lets you modify the sample dataset to stay within the retention period of the database you write it to. ##### Time Range **2022-01-01T08:00:00Z**to**2022-01-01T20:00:00Z***(Customizable)* ##### Schema * home\_actions *(table)* * **tags**: * room * Kitchen * Living Room * action * alert * cool * level * ok * warn * **fields**: * description *(string)* [](#write-home-sensor-actions-data-to-influxdb) Write home sensor actions data to InfluxDB #### Write the home sensor actions data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the home sensor actions sample data to InfluxDB 3 Core. #### influxdb3 #### ```sh influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ 'home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23°C). Cooling to 22°C." 1641027600 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.3°C). Cooling to 22°C." 1641060000 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.1°C). Cooling to 22°C." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 18 ppm." 1641060000 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 22 ppm." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 26 ppm." 1641067200 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 14 ppm." 1641063600 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 17 ppm." 1641067200' ``` ```sh curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-raw "home_actions,room=Kitchen,action=cool,level=ok description=\"Temperature at or above 23°C (23°C). Cooling to 22°C.\" 1739437200 home_actions,room=Kitchen,action=cool,level=ok description=\"Temperature at or above 23°C (23.3°C). Cooling to 22°C.\" 1739469600 home_actions,room=Kitchen,action=cool,level=ok description=\"Temperature at or above 23°C (23.1°C). Cooling to 22°C.\" 1739473200 home_actions,room=Kitchen,action=alert,level=warn description=\"Carbon monoxide level above normal: 18 ppm.\" 1739469600 home_actions,room=Kitchen,action=alert,level=warn description=\"Carbon monoxide level above normal: 22 ppm.\" 1739473200 home_actions,room=Kitchen,action=alert,level=warn description=\"Carbon monoxide level above normal: 26 ppm.\" 1739476800 home_actions,room=Living Room,action=alert,level=warn description=\"Carbon monoxide level above normal: 14 ppm.\" 1739473200 home_actions,room=Living Room,action=alert,level=warn description=\"Carbon monoxide level above normal: 17 ppm.\" 1739476800" ``` ```sh curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary ' home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23°C). Cooling to 22°C." 1641027600 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.3°C). Cooling to 22°C." 1641060000 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.1°C). Cooling to 22°C." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 18 ppm." 1641060000 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 22 ppm." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 26 ppm." 1641067200 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 14 ppm." 1641063600 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 17 ppm." 1641067200 ' ``` ```sh curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME&precision=s \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary ' home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23°C). Cooling to 22°C." 1641027600 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.3°C). Cooling to 22°C." 1641060000 home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.1°C). Cooling to 22°C." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 18 ppm." 1641060000 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 22 ppm." 1641063600 home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 26 ppm." 1641067200 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 14 ppm." 1641063600 home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 17 ppm." 1641067200 ' ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## NOAA Bay Area weather data Includes daily weather metrics from three San Francisco Bay Area airports from**January 1, 2020 to December 31, 2022**. This sample dataset includes seasonal trends and is good for exploring time series use cases that involve seasonality. ##### Time Range **2020-01-01T00:00:00Z** to **2022-12-31T00:00:00Z** ##### Schema * weather *(table)* * **tags**: * location * Concord * Hayward * San Francisco * **fields** * precip *(float)* * temp\_avg *(float)* * temp\_max *(float)* * temp\_min *(float)* * wind\_avg *(float)* [](#write-the-noaa-bay-area-weather-data-to-influxdb) Write the NOAA Bay Area weather data to InfluxDB #### Write the NOAA Bay Area weather data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the NOAA Bay Area weather sample data to InfluxDB 3 Core. #### influxdb3 #### ```sh influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" ``` ```sh curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## European Union wind data The European Union (EU) wind sample dataset provides hourly measurements of wind speed and wind direction from various cities in the EU. The dataset includes a hierarchical tag set of country, county, and city. ##### Time Range **2025-10-01T00:00:00Z** to **2025-10-01T23:00:00Z** ##### Schema * wind\_data *(table)* * **tags**: * country * *20 countries* * county * *111 counties* * city * *129 cities* * **fields**: * wind\_speed *(float)* * wind\_direction *(integer)* [](#write-the-eu-wind-sample-data-to-influxdb) Write the EU wind sample data to InfluxDB #### Write the EU wind sample data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the EU wind sample data to InfluxDB 3 Core. #### influxdb3 #### ```sh influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ "$(curl --request GET https://docs.influxdata.com/downloads/eu-wind-data.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/eu-wind-data.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/eu-wind-data.lp)" ``` ```sh curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/eu-wind-data.lp)" ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## Bitcoin price data The Bitcoin price sample dataset provides Bitcoin prices from**2023-05-01T00:00:00Z to 2023-05-15T00:00:00Z**—*[Powered by CoinDesk](https://www.coindesk.com/price/bitcoin)*. ##### Time Range **2023-05-01T00:19:00Z** to **2023-05-14T23:48:00Z** ##### Schema * bitcoin *(table)* * **tags**: * code * EUR * GBP * USD * crypto * bitcoin * description * Euro * British Pound Sterling * United States Dollar * symbol * € *(€)* * £ *(£)* * $ *($)* * **fields** * price *(float)* [](#write-the-bitcoin-sample-data-to-influxdb) Write the Bitcoin sample data to InfluxDB #### Write the Bitcoin price sample data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the Bitcoin price sample data to InfluxDB 3 Core. #### influxdb3 #### ```sh influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" ``` ```sh curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) ## Random numbers sample data Includes two fields with randomly generated numbers reported every minute. Each field has a specific range of randomly generated numbers. This sample dataset is used to demonstrate mathematic operations and transformation functions. ##### Time Range **2023-01-01T00:00:00Z** to **2023-01-01T12:00:00Z** ##### Schema * numbers *(table)* * **fields** * a *(float between -1 and 1)* * b *(float between -3 and 3)* [](#write-the-random-number-sample-data-to-influxdb) Write the random number sample data to InfluxDB #### Write the random number sample data to InfluxDB Use the `influxdb3` CLI, InfluxDB v3 API, InfluxDB v2 API, or InfluxDB v1 API to write the random number sample data to InfluxDB 3 Core. #### influxdb3 #### ```sh influxdb3 write \ --token AUTH_TOKEN \ --database DATABASE_NAME \ "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v3/write_lp?db=DATABASE_NAME&precision=auto&accept_partial=false \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" ``` ```sh curl --request POST \ http://localhost:8181/api/v2/write?bucket=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" ``` ```sh curl --request POST \ http://localhost:8181/write?db=DATABASE_NAME \ --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" ``` Replace the following in the sample script: * `DATABASE_NAME`: the name of database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) --- # SQL reference documentation Source: https://docs.influxdata.com/influxdb3/core/reference/sql/ InfluxDB 3 Core uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. * [Identifiers](#identifiers) * [Quoting and case sensitivity](#quoting-and-case-sensitivity) * [Literals](#literals) * [Duration units](#duration-units) * [Operators](#operators) * [Keywords](#keywords) * [Conditional expressions](#conditional-expressions) * [Statements and clauses](#statements-and-clauses) * [Comments](#comments) * [Functions](#functions) ## Identifiers An identifier is a token which refers to the name of an InfluxDB database object, such as a **measurement** or a column name (**time**, **tag keys**, or **field keys**). ## Quoting Use double quotes on [identifiers](#identifiers) to treat them as case-sensitive. Use single quotes on string literals. General quoting guidelines: * Single quote RFC3339 and RFC3339-like time values. * Do *not* quote Unix epoch time values (integers cast to a timestamp). * Double-quote mixed case, [camel case](https://en.wikipedia.org/wiki/Camel_case) or case-sensitive identifiers. * Double-quote identifiers that contain special characters or whitespace characters. ##### Quoting examples ```sql -- Double-quote identifiers that contain whitespace SELECT "water temperature", "buoy location" FROM buoy -- Double-quote measurement names with special characters SELECT * FROM "h2o-temperature" -- Double-quote identifiers that should be treated as case-sensitive SELECT "pH" FROM "Water" ``` > [!Note] > **Note:** We recommend always double-quoting identifiers, regardless of case-sensitivity. Unquoted identifiers **are not** case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. For example, if you have two fields in a measurement named `ph` and `pH`, the unquoted identifier, `pH` will match both. To query in a case-sensitive manner, double-quote identifiers. ## Literals A literal is an explicit value not represented by an identifier. ### String literals String literals are surrounded by single quotes. ```sql 'santa_monica' 'pH' 'average temperature' ``` ### Numeric literals Number literals are positive or negative numbers that are either exact numbers or floats. ```sql -- Integers 10 +10 -10 -- Unsigned integers 10::BIGINT UNSIGNED +10::BIGINT UNSIGNED -- Floats 10.78654 -100.56 ``` ### Date and time literals The following date and time literals are supported: ``` '2022-01-31T06:30:30.123Z' -- (RFC3339) '2022-01-31T06:30:30.123' -- (RFC3339-like) '2022-01-31 06:30:30.123' -- (RFC3339-like) '2022-01-31 06:30:30' -- ((RFC3339-like, no fractional seconds) 1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp) ``` ### Boolean literals Boolean literals are either `TRUE` or `FALSE`. ## Duration units Interval literals specify a length or unit of time. ```sql INTERVAL '4 minutes' INTERVAL '12 days 6 hours 30 minutes' ``` The following units of time are supported: * nanoseconds * microseconds * milliseconds * seconds * minutes * hours * days * weeks * months * years * century ## Operators Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. ### Arithmetic operators Arithmetic operators take two numeric values (either literals or variables) and perform a calculation that returns a single numeric value. |Operator| Description |Example|Result| |--------|--------------|-------|------| | `+` | Addition |`2 + 2`| `4` | | `-` | Subtraction |`4 - 2`| `2` | | `*` |Multiplication|`2 * 3`| `6` | | `/` | Division |`6 / 3`| `2` | | `%` | Modulo |`7 % 2`| `1` | ### Comparison operators Comparison operators evaluate the relationship between the left and right operands and `TRUE` or `FALSE`. |Operator| Meaning | Example | |--------|--------------------------------------------------------|------------------| | `=` | Equal to | `123 = 123` | | `<>` | Not equal to | `123 <> 456` | | `!=` | Not equal to | `123 != 456` | | `>` | Greater than | `3 > 2` | | `>=` | Greater than or equal to | `3 >= 2` | | `<` | Less than | `1 < 2` | | `<=` | Less than or equal to | `1 <= 2` | | `~` | Matches a regular expression | `'abc' ~ 'a.*'` | | `~\*` | Matches a regular expression *(case-insensitive)* |`'Abc' ~\* 'A.*'` | | `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | | `!~\*` |Does not match a regular expression *(case-insensitive)*|`'Abc' !~\* 'a.*'`| ### Logical operators |Operator | Meaning | |---------|--------------------------------------------------------------------------| | `AND` | Returns true if both operands are true. Otherwise, returns false. | |`BETWEEN`|Returns true if the left operand is within the range of the right operand.| |`EXISTS` | Returns true if the operand is not null. | | `IN` | Returns true if the left operand is in the right operand list. | | `LIKE` |Returns true if the left operand matches the right operand pattern string.| | `NOT` | Negates the subsequent expression. | | `OR` | Returns true if any operand is true. Otherwise, returns false. | ### Bitwise operators Bitwise operators perform bitwise operations on bit patterns or binary numerals. |Operator| Meaning |Example |Result| |--------|-------------------|--------|------| | `&` | Bitwise and |`5 & 3` | `1` | | `|` | Bitwise or |`5 | 3` | `7` | | `^` | Bitwise xor |`5 ^ 3` | `6` | | `>>` |Bitwise shift right|`5 >> 3`| `0` | | `<<` |Bitwise shift left |`5 << 3`| `40` | ### Other operators | Operator | Meaning | Example | Result | |--------------|------------------------|-----------------------------------------------------------------------------|-------------| | `||` | Concatenates strings | `'Hello' || ' world'` |`Hello world`| |`AT TIME ZONE`|Apply a time zone offset|*[View example](/influxdb3/core/reference/sql/operators/other/#at-time-zone)*| | ## Keywords The following reserved keywords cannot be used as identifiers. ```sql AND ALL ANALYZE AS ASC AT TIME ZONE BETWEEN BOTTOM CASE DESC DISTINCT EXISTS EXPLAIN FROM GROUP BY HAVING IN INNER JOIN JOIN LEFT JOIN LIKE LIMIT NOT EXISTS NOT IN OR ORDER BY FULL OUTER JOIN RIGHT JOIN SELECT TOP TYPE UNION UNION ALL WHERE WITH ``` ## Conditional expressions Conditional expressions evaluate conditions based on input values. The following conditional expressions are supported: |Expression| Description | |----------|------------------------------------------------------------------| | CASE | Allows for use of WHEN-THEN-ELSE statements. | | COALESCE | Returns the first non-NULL expression in a specified list. | | NULLIF |Returns a NULL value if value1 = value2. Otherwise returns value1.| ## Statements and clauses InfluxDB SQL supports the following basic syntax for queries: ``` [ WITH with_query [, …] ] SELECT [ ALL | DISTINCT ] select_expr [, …] [ FROM from_item [, …] ] [ JOIN join_item [, …] ] [ WHERE condition ] [ GROUP BY grouping_element [, …] ] [ HAVING condition] [ UNION [ ALL ] ] [ ORDER BY expression [ ASC | DESC ][, …] ] [ LIMIT count ] ``` ### SELECT statement and FROM clause Use the SQL `SELECT` statement to query data from a specific measurement or measurements. The `FROM` clause always accompanies the `SELECT` statement. #### Examples ```sql SELECT * FROM "h2o_feet" ``` ### WHERE clause Use the `WHERE` clause to filter results based on `fields`, `tags`, and `timestamps`. Use predicates to evaluate each row. Rows that evaluate as `TRUE` are returned in the result set. Rows that evaluate as `FALSE` are omitted from the result set. #### Examples ```sql SELECT * FROM "h2o_feet" WHERE "water_level" <= 9 ``` ``` SELECT * FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" = 'below 3 feet' ``` ### JOIN clause Use the `JOIN` clause to join data from multiple measurements (tables). For more information about joins, see[JOIN clause](/influxdb3/core/reference/sql/join/). The following join types are supported: [ **INNER JOIN** ](#inner-join) [ **LEFT [OUTER] JOIN** ](#left-outer-join) [ **RIGHT [OUTER] JOIN** ](#right-outer-join) [ **FULL [OUTER] JOIN** ](#full-outer-join) [](#inner-join) INNER JOIN Inner joins combine rows from tables on the left and right side of the join based on common column values defined in the `ON` clause. Rows that don’t have matching column values are not included in the output table. ```sql SELECT * FROM home INNER JOIN home_actions ON home.room = home_actions.room AND home.time = home_actions.time; ``` [](#left-outer-join) LEFT [OUTER] JOIN A left outer join returns all rows from the left side of the join and only returns data from the right side of the join in rows with matching column values defined in the `ON` clause. ```sql SELECT * FROM home LEFT OUTER JOIN home_actions ON home.room = home_actions.room AND home.time = home_actions.time; ``` [](#right-outer-join) RIGHT [OUTER] JOIN A right outer join returns all rows from the right side of the join and only returns data from the left side of the join in rows with matching column values defined in the `ON` clause. ```sql SELECT * FROM home RIGHT OUTER JOIN home_actions ON home.room = home_actions.room AND home.time = home_actions.time; ``` [](#full-outer-join) FULL [OUTER] JOIN A full outer join returns all data from the left and right sides of the join and combines rows with matching column values defined in the `ON` clause. ```sql SELECT * FROM home FULL OUTER JOIN home_actions ON home.room = home_actions.room AND home.time = home_actions.time; ``` ### GROUP BY clause Use the `GROUP BY` clause to group query results based on specified column values. `GROUP BY` **requires** an aggregate or selector function in the `SELECT` statement. #### Examples ``` SELECT MEAN("water_level"), "location" FROM "h2o_feet" GROUP BY "location" ``` ### HAVING clause Use the `HAVING` clause to filter query results based on a specified condition. The `HAVING` clause must *follow* the `GROUP BY` clause, but *precede* the `ORDER BY` clause. #### Examples ``` SELECT MEAN("water_level"), "location" FROM "h2o_feet" GROUP BY "location" HAVING MEAN("water_level") > 4 ORDER BY "location" ``` ### UNION clause The `UNION` clause combines the results of two or more `SELECT` statements without returning any duplicate rows. `UNION ALL` returns all results, including duplicates. #### Examples ``` SELECT 'pH' FROM "h2o_pH" UNION ALL SELECT "location" FROM "h2o_quality" ``` ### ORDER BY clause The `ORDER BY` clause orders results by specified columns and order. Sort data based on fields, tags, and timestamps. The following orders are supported: * `ASC`: ascending *(default)* * `DESC`: descending #### Examples ``` SELECT "water_level", "location" FROM "h2o_feet" ORDER BY "location", "time" DESC ``` ### LIMIT clause The `LIMIT` clause limits the number of rows to return. The defined limit should be a non-negative integer. #### Examples ``` SELECT "water_level", "location" FROM "h2o_feet" LIMIT 10 ``` ### WITH clause The `WITH` clause provides a way to write auxiliary statements for use in a larger query. It can help break down large, complicated queries into simpler forms. ``` WITH summary_data as (SELECT degrees, location, time FROM average_temperature) SELECT * FROM summary_data ``` ### OVER clause The `OVER` clause is used with SQL window functions. A **window function** performs a calculation across a set of table rows that are related in some way to the current row. While similar to aggregate functions, window functions output results into rows retaining their separate identities. ``` SELECT time, water_level FROM ( SELECT time, "water_level", row_number() OVER ( order by water_level desc ) as rn FROM h2o_feet ) WHERE rn <= 3; ``` ## Comments Use comments to describe and add detail or notes to your queries. * Single line comments use the double hyphen `--` symbol. Single line comments end with a line break. * Multi-line comments begin with `/*` and end with `*/`. ``` -- Single-line comment /* * Multi-line comment */ ``` ## Schema information InfluxDB 3 Core supports the following metadata schema queries: ```sql SHOW tables SHOW columns FROM ``` ## Functions Following is a list of supported functions by type. ### Aggregate functions An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value. |Function| Description | |--------|----------------------------------------------------------| |COUNT() |Returns returns the number of rows from a field or tag key| | AVG() | Returns the average value of a column | | SUM() | Returns the summed value of a column | | MEAN() | Returns the mean value of a column | | MIN() | Returns the smallest value of the selected column | | MAX() | Returns the largest value of the selected column | #### Examples ``` SELECT COUNT("water_level") FROM "h2o_feet" SELECT AVG("water_level"), "location" FROM "h2o_feet" GROUP BY "location" SELECT SUM("water_level"), "location" FROM "h2o_feet" GROUP BY "location" ``` ### Window aggregate functions Window functions let you calculate running totals, moving averages, or other aggregate-like results without collapsing rows into groups (unlike non-window aggregate functions). Window aggregate functions include **all [aggregate functions](#aggregate-functions/)**and the [ranking functions](#ranking-functions). The SQL `OVER` clause syntactically distinguishes a window function from a non-window or aggregate function and defines how to group and order rows for the window operation. #### Examples: ```sql SELECT time, room, temp, avg(temp) OVER (PARTITION BY room) AS avg_room_temp FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T09:00:00Z' ORDER BY room, time ``` | time | room |temp|avg\_room\_temp| |-------------------|-----------|----|---------------| |2022-01-01T08:00:00| Kitchen |21.0| 22.0 | |2022-01-01T09:00:00| Kitchen |23.0| 22.0 | |2022-01-01T08:00:00|Living Room|21.1| 21.25 | |2022-01-01T09:00:00|Living Room|21.4| 21.25 | #### Ranking Functions | Function | Description | |---------------|---------------------------------------------------------------------------------| | CUME\_DIST() | Returns the cumulative distribution of a value within a group of values | | DENSE\_RANK() | Returns a rank for each row without gaps in the numbering | | NTILE() |Distributes the rows in an ordered partition into the specified number of groups | |PERCENT\_RANK()| Returns the percentage rank of the current row within its partition | | RANK() |Returns the rank of the current row in its partition, allowing gaps between ranks| | ROW\_NUMBER() | Returns the position of the current row in its partition | ### Selector functions Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. However, selectors are unique in that they return a **time value** in addition to the computed value. In short, selectors return an aggregated value along with a timestamp. | Function | Description | |-----------------|--------------------------------------------------------------| |SELECTOR\_FIRST()| Returns the first value of a selected column and timestamp. | |SELECTOR\_LAST() | Returns the last value of a selected column and timestamp. | | SELECTOR\_MIN() |Returns the smallest value of a selected column and timestamp.| | SELECTOR\_MAX() |Returns the largest value of a selected column and timestamp. | #### Examples ``` SELECT SELECTOR_MAX("pH", time)['value'], SELECTOR_MAX("pH", time)['time'] FROM "h2o_pH" SELECT SELECTOR_LAST("water_level", time)['value'], SELECTOR_LAST("water_level", time)['time'] FROM "h2o_feet" WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z' ``` ### Date and time functions | Function | Description | |-------------|-----------------------------------------------------------------------------------------------| | DATE\_BIN() | Bins the input timestamp into a specified interval. | |DATE\_TRUNC()|Truncates a timestamp expression based on the date part specified, such as hour, day, or month.| |DATE\_PART() | Returns the specified part of a date. | | NOW() | Returns the current time (UTC). | #### Examples ```sql SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time", SUM(water_level) FROM "h2o_feet" GROUP BY "_time" ``` ```sql SELECT DATE_TRUNC('month',time) AS "date", SUM(water_level) FROM "h2o_feet" GROUP BY time ``` ### Approximate functions | Function | Description | |--------------------------------------|---------------------------------------------------------------------------------------------| | APPROX\_MEDIAN | Returns the approximate median of input values. | | APPROX\_DISTINCT |Returns the approximate count of the number of distinct values. Implemented only for strings.| | APPROX\_PERCENTILE\_CONT | Returns the approximate percentile of input values. | |APPROX\_PERCENTILE\_CONT\_WITH\_WEIGHT| Returns the approximate percentile of input values with weight. | ### Math functions |Function| Description | |--------|--------------------------------------------------------------------------------| | ABS() | Absolute value | | ACOS() | Inverse cosine | | ASIN() | Inverse sine | | ATAN() | Inverse tangent | |ATAN2() | Inverse tangent of y / x | | CEIL() |Returns the smallest integer value greater than or equal to the specified number| | COS() | Cosine | | EXP() | Exponential | |FLOOR() | Nearest integer less than or equal to the specified number | | LN() | Natural logarithm | |LOG10() | Base 10 logarithm | | LOG2() | Base 2 logarithm | |POWER() | Returns the value of a number raised to the power of the number | |ROUND() | Round to the nearest integer | |SIGNUM()| Sign of the argument (-1, 0, +1) | | SINE() | Sine | | SQRT() | Returns the square root of a number | | TAN() | Tangent | |TRUNC() | Truncates a number to the specified number of decimal places | ### Conditional functions |Function| Description | |--------|----------------------------------------------------------------------------------------------------------| |COALESCE|Returns the first argument that is not null. If all arguments are null, then `COALESCE` will return nulls.| | NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | ### Regular expression functions | Function | Description | |---------------|-----------------------------------------------------------------------------| | REGEXP\_MATCH |Matches a regular expression against a string and returns matched substrings.| |REGEXP\_REPLACE| Replaces substrings that match a regular expression by a new substring. | #### Related | Operator | Description | Example | Result | | --- | --- | --- | --- | | Operator | Description | Example | Result | | + | Addition | 2 + 2 | 4 | | - | Subtraction | 4 - 2 | 2 | | * | Multiplication | 2 * 3 | 6 | | / | Division | 6 / 3 | 2 | | % | Modulo | 7 % 2 | 1 | | Operator | Meaning | Example | | --- | --- | --- | | Operator | Meaning | Example | | = | Equal to | 123 = 123 | | <> | Not equal to | 123 <> 456 | | != | Not equal to | 123 != 456 | | > | Greater than | 3 > 2 | | >= | Greater than or equal to | 3 >= 2 | | < | Less than | 1 < 2 | | <= | Less than or equal to | 1 <= 2 | | ~ | Matches a regular expression | 'abc' ~ 'a.*' | | ~\* | Matches a regular expression (case-insensitive) | 'Abc' ~\* 'A.*' | | !~ | Does not match a regular expression | 'abc' !~ 'd.*' | | !~\* | Does not match a regular expression (case-insensitive) | 'Abc' !~\* 'a.*' | | Operator | Meaning | | --- | --- | | Operator | Meaning | | AND | Returns true if both operands are true. Otherwise, returns false. | | BETWEEN | Returns true if the left operand is within the range of the right operand. | | EXISTS | Returns true if the operand is not null. | | IN | Returns true if the left operand is in the right operand list. | | LIKE | Returns true if the left operand matches the right operand pattern string. | | NOT | Negates the subsequent expression. | | OR | Returns true if any operand is true. Otherwise, returns false. | | Operator | Meaning | Example | Result | | --- | --- | --- | --- | | Operator | Meaning | Example | Result | | & | Bitwise and | 5 & 3 | 1 | | | | Bitwise or | 5 | 3 | 7 | | ^ | Bitwise xor | 5 ^ 3 | 6 | | >> | Bitwise shift right | 5 >> 3 | 0 | | << | Bitwise shift left | 5 << 3 | 40 | | Operator | Meaning | Example | Result | | --- | --- | --- | --- | | Operator | Meaning | Example | Result | | || | Concatenates strings | 'Hello' || ' world' | Hello world | | AT TIME ZONE | Apply a time zone offset | View example | | | Expression | Description | | --- | --- | | Expression | Description | | CASE | Allows for use of WHEN-THEN-ELSE statements. | | COALESCE | Returns the first non-NULL expression in a specified list. | | NULLIF | Returns a NULL value if value1 = value2. Otherwise returns value1. | | Function | Description | | --- | --- | | Function | Description | | COUNT() | Returns returns the number of rows from a field or tag key | | AVG() | Returns the average value of a column | | SUM() | Returns the summed value of a column | | MEAN() | Returns the mean value of a column | | MIN() | Returns the smallest value of the selected column | | MAX() | Returns the largest value of the selected column | | time | room | temp | avg_room_temp | | --- | --- | --- | --- | | time | room | temp | avg_room_temp | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 22.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 22.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 21.25 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.25 | | Function | Description | | --- | --- | | Function | Description | | CUME_DIST() | Returns the cumulative distribution of a value within a group of values | | DENSE_RANK() | Returns a rank for each row without gaps in the numbering | | NTILE() | Distributes the rows in an ordered partition into the specified number of groups | | PERCENT_RANK() | Returns the percentage rank of the current row within its partition | | RANK() | Returns the rank of the current row in its partition, allowing gaps between ranks | | ROW_NUMBER() | Returns the position of the current row in its partition | | Function | Description | | --- | --- | | Function | Description | | SELECTOR_FIRST() | Returns the first value of a selected column and timestamp. | | SELECTOR_LAST() | Returns the last value of a selected column and timestamp. | | SELECTOR_MIN() | Returns the smallest value of a selected column and timestamp. | | SELECTOR_MAX() | Returns the largest value of a selected column and timestamp. | | Function | Description | | --- | --- | | Function | Description | | DATE_BIN() | Bins the input timestamp into a specified interval. | | DATE_TRUNC() | Truncates a timestamp expression based on the date part specified, such as hour, day, or month. | | DATE_PART() | Returns the specified part of a date. | | NOW() | Returns the current time (UTC). | | Function | Description | | --- | --- | | Function | Description | | APPROX_MEDIAN | Returns the approximate median of input values. | | APPROX_DISTINCT | Returns the approximate count of the number of distinct values. Implemented only for strings. | | APPROX_PERCENTILE_CONT | Returns the approximate percentile of input values. | | APPROX_PERCENTILE_CONT_WITH_WEIGHT | Returns the approximate percentile of input values with weight. | | Function | Description | | --- | --- | | Function | Description | | ABS() | Absolute value | | ACOS() | Inverse cosine | | ASIN() | Inverse sine | | ATAN() | Inverse tangent | | ATAN2() | Inverse tangent of y / x | | CEIL() | Returns the smallest integer value greater than or equal to the specified number | | COS() | Cosine | | EXP() | Exponential | | FLOOR() | Nearest integer less than or equal to the specified number | | LN() | Natural logarithm | | LOG10() | Base 10 logarithm | | LOG2() | Base 2 logarithm | | POWER() | Returns the value of a number raised to the power of the number | | ROUND() | Round to the nearest integer | | SIGNUM() | Sign of the argument (-1, 0, +1) | | SINE() | Sine | | SQRT() | Returns the square root of a number | | TAN() | Tangent | | TRUNC() | Truncates a number to the specified number of decimal places | | Function | Description | | --- | --- | | Function | Description | | COALESCE | Returns the first argument that is not null. If all arguments are null, then COALESCE will return nulls. | | NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | | Function | Description | | --- | --- | | Function | Description | | REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | | REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | --- # SQL data types Source: https://docs.influxdata.com/influxdb3/core/reference/sql/data-types/ InfluxDB 3 Core uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)implementation of SQL. Data types define the type of values that can be stored in table columns. In InfluxDB’s SQL implementation, a **measurement** is structured as a table, and **tags**, **fields** and **timestamps** are exposed as columns. ## SQL and Arrow data types In SQL, each column, expression, and parameter has a data type. A data type is an attribute that specifies the type of data that the object can hold. DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). Both SQL and Arrow data types play an important role in how data is operated on during query execution and returned in query results. > [!Note] > When performing casting operations, cast to the SQL data type unless you use[`arrow_cast()`](/influxdb3/core/reference/sql/functions/misc/#arrow_cast)to cast to a specific Arrow type. > Names and identifiers in SQL are *case-insensitive* by default. For example: > > ``` > SELECT > '99'::BIGINT, > '2019-09-18T00:00:00Z'::timestamp > ``` * [String types](#string-types) * [Numeric types](#numeric-types) * [Integers](#integers) * [Unsigned integers](#unsigned-integers) * [Floats](#floats) * [Date and time data types](#date-and-time-data-types) * [Timestamp](#timestamp) * [Interval](#interval) * [Boolean types](#boolean-types) * [Unsupported SQL types](#unsupported-sql-types) * [Data types compatible with parameters](#data-types-compatible-with-parameters) ## String types |SQL data type|Arrow data type| Description | |-------------|---------------|---------------------------------| | STRING | UTF8 |Character string, variable-length| | CHAR | UTF8 | Character string, fixed-length | | VARCHAR | UTF8 |Character string, variable-length| | TEXT | UTF8 | Variable unlimited length | ##### Example string literals ```sql 'abcdefghijk' 'time' 'h2o_temperature' ``` ## Numeric types The following numeric types are supported: | SQL data type |Arrow data type| Description | |---------------|---------------|----------------------------------------------| | BIGINT | INT64 | 64-bit signed integer | |BIGINT UNSIGNED| UINT64 | 64-bit unsigned integer | | DOUBLE | FLOAT64 | 64-bit floating-point number (\~15 digits) | | FLOAT | FLOAT32 | 32-bit floating-point number (\~7 digits) | | REAL | FLOAT32 |32-bit floating-point number (alias for FLOAT)| ### Integers InfluxDB SQL supports the 64-bit signed integers: **Minimum signed integer**: `-9223372036854775808`**Maximum signed integer**: `9223372036854775807` ##### Example integer literals ```sql 234 -446 5 ``` ### Unsigned integers InfluxDB SQL supports the 64-bit unsigned integers: **Minimum unsigned integer**: `0`**Maximum unsigned integer**: `18446744073709551615` ##### Example unsigned integer literals Unsigned integer literals are comprised of an integer cast to the `BIGINT UNSIGNED` type: ```sql 234::BIGINT UNSIGNED 458374893::BIGINT UNSIGNED 5::BIGINT UNSIGNED ``` ### Floats InfluxDB SQL supports both 32-bit (single precision) and 64-bit (double precision) floating-point values. | Type |Precision|Significant Digits| Use Case | |------|---------|------------------|---------------------------------------------------------| |FLOAT | 32-bit | \~7 digits |Memory-efficient storage when full precision isn’t needed| |DOUBLE| 64-bit | \~15-16 digits | Default for most numeric operations | > [!Note] > InfluxDB stores float field values as 64-bit (FLOAT64) internally. > Casting to FLOAT (32-bit) may lose precision for values with more than \~7 significant digits. > Unlike PostgreSQL where FLOAT defaults to double precision, InfluxDB SQL treats FLOAT as single precision (32-bit). ##### Example float literals Float literals are stored as 64-bit double precision: ```sql 23.8 -446.89 5.00 0.033 ``` ##### Example float casting ```sql -- Cast to 32-bit float (may lose precision) SELECT 3.141592653589793::FLOAT; -- Returns: 3.1415927 (truncated to ~7 digits) -- Cast to 64-bit double (preserves precision) SELECT 3.141592653589793::DOUBLE; -- Returns: 3.141592653589793 ``` ## Date and time data types InfluxDB SQL supports the following DATE/TIME data types: |SQL data type| Arrow data type | Description | |-------------|------------------------------|---------------------------------------------| | TIMESTAMP | Timestamp(Nanosecond, None) |Nanosecond timestamp with no time zone offset| | INTERVAL |Interval(IntervalMonthDayNano)| Interval of time with a specified duration | ### Timestamp A time type is a single point in time using nanosecond precision. The following date and time formats are supported: ```sql YYYY-MM-DDT00:00:00.000Z YYYY-MM-DDT00:00:00.000-00:00 YYYY-MM-DD 00:00:00.000-00:00 YYYY-MM-DDT00:00:00Z YYYY-MM-DD 00:00:00.000 YYYY-MM-DD 00:00:00 ``` ##### Example timestamp literals ```sql '2023-01-02T03:04:06.000Z' '2023-01-02T03:04:06.000-00:00' '2023-01-02 03:04:06.000-00:00' '2023-01-02T03:04:06Z' '2023-01-02 03:04:06.000' '2023-01-02 03:04:06' ``` ### Interval The INTERVAL data type can be used with the following precision: * nanosecond * microsecond * millisecond * second * minute * hour * day * week * month * year * century ##### Example interval literals ```sql INTERVAL '10 minutes' INTERVAL '1 year' INTERVAL '2 days 1 hour 31 minutes' ``` ## Boolean types Booleans store TRUE or FALSE values. |SQL data type|Arrow data type| Description | |-------------|---------------|--------------------| | BOOLEAN | Boolean |True or false values| ##### Example boolean literals ```sql true TRUE false FALSE ``` ## Unsupported SQL types The following SQL types are not currently supported: * UUID * BLOB * CLOB * BINARY * VARBINARY * REGCLASS * NVARCHAR * CUSTOM * ARRAY * ENUM * SET * DATETIME * BYTEA ## Data types compatible with parameters For information about data types that can be substituted by parameters, see how to [use parameterized queries with SQL](/influxdb3/core/query-data/sql/parameterized-queries/). #### Related * [Cast values to different types](/influxdb3/core/query-data/sql/cast-types/) | SQL data type | Arrow data type | Description | | --- | --- | --- | | SQL data type | Arrow data type | Description | | STRING | UTF8 | Character string, variable-length | | CHAR | UTF8 | Character string, fixed-length | | VARCHAR | UTF8 | Character string, variable-length | | TEXT | UTF8 | Variable unlimited length | | SQL data type | Arrow data type | Description | | --- | --- | --- | | SQL data type | Arrow data type | Description | | BIGINT | INT64 | 64-bit signed integer | | BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | | DOUBLE | FLOAT64 | 64-bit floating-point number (~15 digits) | | FLOAT | FLOAT32 | 32-bit floating-point number (~7 digits) | | REAL | FLOAT32 | 32-bit floating-point number (alias for FLOAT) | | Type | Precision | Significant Digits | Use Case | | --- | --- | --- | --- | | Type | Precision | Significant Digits | Use Case | | FLOAT | 32-bit | ~7 digits | Memory-efficient storage when full precision isn’t needed | | DOUBLE | 64-bit | ~15-16 digits | Default for most numeric operations | | SQL data type | Arrow data type | Description | | --- | --- | --- | | SQL data type | Arrow data type | Description | | TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset | | INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | | SQL data type | Arrow data type | Description | | --- | --- | --- | | SQL data type | Arrow data type | Description | | BOOLEAN | Boolean | True or false values | --- # EXPLAIN command Source: https://docs.influxdata.com/influxdb3/core/reference/sql/explain/ The `EXPLAIN` command returns the [logical plan](/influxdb3/core/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb3/core/reference/internals/query-plan/#physical-plan) for the specified SQL statement. ```sql EXPLAIN [ANALYZE] [VERBOSE] statement ``` * [`EXPLAIN`](#explain) * [Example `EXPLAIN`](#example-explain) * [`EXPLAIN ANALYZE`](#explain-analyze) * [Example `EXPLAIN ANALYZE`](#example-explain-analyze) * [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose) * [Example `EXPLAIN ANALYZE VERBOSE`](#example-explain-analyze-verbose) ## `EXPLAIN` Returns the logical plan and physical (execution) plan of a statement. To output more details, use `EXPLAIN VERBOSE`. `EXPLAIN` doesn’t execute the statement. To execute the statement and view runtime metrics, use [`EXPLAIN ANALYZE`](#explain-analyze). ### Example `EXPLAIN` ```sql EXPLAIN SELECT room, avg(temp) AS temp FROM home GROUP BY room ``` [](#view-explain-example-output) View `EXPLAIN` example output | | plan\_type | plan | |---|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 |logical\_plan | Projection: home.room, AVG(home.temp) AS temp | | | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | | | | TableScan: home projection=[room, temp] | | 1 |physical\_plan| ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | | | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | | | | CoalesceBatchesExec: target\_batch\_size=8192 | | | | RepartitionExec: partitioning=Hash([room@0], 8), input\_partitions=8 | | | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | | | |ParquetExec: file\_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], …]}, projection=[room, temp]| ## `EXPLAIN ANALYZE` Executes a statement and returns the execution plan and runtime metrics of the statement. The report includes the [logical plan](/influxdb3/core/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb3/core/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution. If the plan requires reading lots of data files, `EXPLAIN` and `EXPLAIN ANALYZE` may truncate the list of files in the report. To output more information, including intermediate plans and paths for all scanned Parquet files, use [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose). ### Example `EXPLAIN ANALYZE` ```sql EXPLAIN ANALYZE SELECT room, avg(temp) AS temp FROM home WHERE time >= '2023-01-01' AND time <= '2023-12-31' GROUP BY room ``` [](#view-explain-analyze-example-output) View `EXPLAIN ANALYZE` example output | | plan\_type | plan | |---|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 |Plan with Metrics| ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output\_rows=2, elapsed\_compute=4.768µs] | | | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering\_mode=Sorted, metrics=[output\_rows=2, elapsed\_compute=140.405µs] | | | | CoalesceBatchesExec: target\_batch\_size=8192, metrics=[output\_rows=2, elapsed\_compute=6.821µs] | | | | RepartitionExec: partitioning=Hash([room@0], 8), input\_partitions=8, preserve\_order=true, sort\_exprs=room@0 ASC, metrics=[output\_rows=2, elapsed\_compute=18.408µs, repart\_time=59.698µs, fetch\_time=1.057882762s, send\_time=5.83µs] | | | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering\_mode=Sorted, metrics=[output\_rows=2, elapsed\_compute=137.577µs] | | | | RepartitionExec: partitioning=RoundRobinBatch(8), input\_partitions=6, preserve\_order=true, sort\_exprs=room@0 ASC, metrics=[output\_rows=46, elapsed\_compute=26.637µs, repart\_time=6ns, fetch\_time=399.971411ms, send\_time=6.658µs] | | | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output\_rows=46, elapsed\_compute=3.102µs] | | | | CoalesceBatchesExec: target\_batch\_size=8192, metrics=[output\_rows=46, elapsed\_compute=25.585µs] | | | | FilterExec: time@1 \>= 1672531200000000000 AND time@1 \<= 1703980800000000000, metrics=[output\_rows=46, elapsed\_compute=26.51µs] | | | |ParquetExec: file\_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], …]}, projection=[room, time, temp], output\_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 \>= 1672531200000000000 AND time@6 \<= 1703980800000000000, pruning\_predicate=time\_max@0 \>= 1672531200000000000 AND time\_min@1 \<= 1703980800000000000, required\_guarantees=[], metrics=[output\_rows=46, elapsed\_compute=6ns, predicate\_evaluation\_errors=0, bytes\_scanned=3279, row\_groups\_pruned\_statistics=0, file\_open\_errors=0, file\_scan\_errors=0, pushdown\_rows\_filtered=0, num\_predicate\_creation\_errors=0, row\_groups\_pruned\_bloom\_filter=0, page\_index\_rows\_filtered=0, time\_elapsed\_opening=398.462968ms, time\_elapsed\_processing=1.626106ms, time\_elapsed\_scanning\_total=1.36822ms, page\_index\_eval\_time=33.474µs, pushdown\_eval\_time=14.267µs, time\_elapsed\_scanning\_until\_data=1.27694ms]| ## `EXPLAIN ANALYZE VERBOSE` Executes a statement and returns the execution plan, runtime metrics, and additional details helpful for debugging the statement. The report includes the following: * the [logical plan](/influxdb3/core/reference/internals/query-plan/#logical-plan) * the [physical plan](/influxdb3/core/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution * Information truncated in the `EXPLAIN` report–for example, the paths for all [Parquet files retrieved for the query](/influxdb3/core/reference/internals/query-plan/#file_groups). * All intermediate physical plans that DataFusion and the [Querier](/influxdb3/core/reference/internals/storage-engine/#querier) generate before generating the final physical plan–helpful in debugging to see when an [`ExecutionPlan` node](/influxdb3/core/reference/internals/query-plan/#executionplan-nodes) is added or removed, and how InfluxDB optimizes the query. ### Example `EXPLAIN ANALYZE VERBOSE` ```SQL EXPLAIN ANALYZE VERBOSE SELECT temp FROM home WHERE time >= now() - INTERVAL '7 days' AND room = 'Kitchen' ORDER BY time ``` #### Related | | plan_type | plan | | --- | --- | --- | | | plan_type | plan | | 0 | logical_plan | Projection: home.room, AVG(home.temp) AS temp | | | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | | | | TableScan: home projection=[room, temp] | | 1 | physical_plan | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | | | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | | | | CoalesceBatchesExec: target_batch_size=8192 | | | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8 | | | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | | | | ParquetExec: file_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], …]}, projection=[room, temp] | | | plan_type | plan | | --- | --- | --- | | | plan_type | plan | | 0 | Plan with Metrics | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output_rows=2, elapsed_compute=4.768µs] | | | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=140.405µs] | | | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=2, elapsed_compute=6.821µs] | | | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=2, elapsed_compute=18.408µs, repart_time=59.698µs, fetch_time=1.057882762s, send_time=5.83µs] | | | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=137.577µs] | | | | RepartitionExec: partitioning=RoundRobinBatch(8), input_partitions=6, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=46, elapsed_compute=26.637µs, repart_time=6ns, fetch_time=399.971411ms, send_time=6.658µs] | | | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output_rows=46, elapsed_compute=3.102µs] | | | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=46, elapsed_compute=25.585µs] | | | | FilterExec: time@1 >= 1672531200000000000 AND time@1 <= 1703980800000000000, metrics=[output_rows=46, elapsed_compute=26.51µs] | | | | ParquetExec: file_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], …]}, projection=[room, time, temp], output_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 >= 1672531200000000000 AND time@6 <= 1703980800000000000, pruning_predicate=time_max@0 >= 1672531200000000000 AND time_min@1 <= 1703980800000000000, required_guarantees=[], metrics=[output_rows=46, elapsed_compute=6ns, predicate_evaluation_errors=0, bytes_scanned=3279, row_groups_pruned_statistics=0, file_open_errors=0, file_scan_errors=0, pushdown_rows_filtered=0, num_predicate_creation_errors=0, row_groups_pruned_bloom_filter=0, page_index_rows_filtered=0, time_elapsed_opening=398.462968ms, time_elapsed_processing=1.626106ms, time_elapsed_scanning_total=1.36822ms, page_index_eval_time=33.474µs, pushdown_eval_time=14.267µs, time_elapsed_scanning_until_data=1.27694ms] | --- # SQL functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/ ### [Aggregate functions](/influxdb3/core/reference/sql/functions/aggregate/) Aggregate data with SQL aggregate functions. ### [Selector functions](/influxdb3/core/reference/sql/functions/selector/) Select data with SQL selector functions. ### [Time and date functions](/influxdb3/core/reference/sql/functions/time-and-date/) Use time and date functions to work with time values and time series data. ### [Conditional functions](/influxdb3/core/reference/sql/functions/conditional/) Use conditional functions to conditionally handle null values in SQL queries. ### [Math functions](/influxdb3/core/reference/sql/functions/math/) Use math functions to perform mathematical operations in SQL queries. ### [String functions](/influxdb3/core/reference/sql/functions/string/) Use string functions to operate on string values in SQL queries. ### [Binary string functions](/influxdb3/core/reference/sql/functions/binary-string/) Use binary string functions to encode and decode binary string values in SQL queries. ### [Array functions](/influxdb3/core/reference/sql/functions/array/) Use array functions to create and operate on Arrow arrays or lists in SQL queries. ### [Map functions](/influxdb3/core/reference/sql/functions/map/) Use map functions to create and operate on Arrow maps in SQL queries. ### [Struct functions](/influxdb3/core/reference/sql/functions/struct/) Use struct functions to create Arrow structs in SQL queries. ### [Regular expression functions](/influxdb3/core/reference/sql/functions/regular-expression/) Use regular expression functions to operate on data in SQL queries. ### [Hashing functions](/influxdb3/core/reference/sql/functions/hashing/) Use hashing functions to hash string values in SQL queries using established hashing algorithms. ### [Miscellaneous functions](/influxdb3/core/reference/sql/functions/misc/) Use miscellaneous SQL functions to perform a variety of operations in SQL queries. ### [Cache functions](/influxdb3/core/reference/sql/functions/cache/) Retrieve cached data from InfluxDB 3 Core caches. ### [Window functions](/influxdb3/core/reference/sql/functions/window/) SQL window functions perform an operation across a set of rows related to the current row. --- # SQL aggregate functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/aggregate/ SQL aggregate functions aggregate values in a specified column for each group or SQL partition and return a single row per group containing the aggregate value. * [General aggregate functions](#general-aggregate-functions) * [array\_agg](#array_agg) * [avg](#avg) * [bit\_and](#bit_and) * [bit\_or](#bit_or) * [bit\_xor](#bit_xor) * [bool\_and](#bool_and) * [bool\_or](#bool_or) * [count](#count) * [first\_value](#first_value) * [grouping](#grouping) * [last\_value](#last_value) * [max](#max) * [mean](#mean) * [median](#median) * [min](#min) * [nth\_value](#nth_value) * [string\_agg](#string_agg) * [sum](#sum) * [Statistical aggregate functions](#statistical-aggregate-functions) * [corr](#corr) * [covar](#covar) * [covar\_pop](#covar_pop) * [covar\_samp](#covar_samp) * [regr\_avgx](#regr_avgx) * [regr\_avgy](#regr_avgy) * [regr\_count](#regr_count) * [regr\_intercept](#regr_intercept) * [regr\_r2](#regr_r2) * [regr\_slope](#regr_slope) * [regr\_sxx](#regr_sxx) * [regr\_syy](#regr_syy) * [regr\_sxy](#regr_sxy) * [stddev](#stddev) * [stddev\_pop](#stddev_pop) * [stddev\_samp](#stddev_samp) * [var](#var) * [var\_pop](#var_pop) * [var\_population](#var_population) * [var\_samp](#var_samp) * [var\_sample](#var_sample) * [Approximate aggregate functions](#approximate-aggregate-functions) * [approx\_distinct](#approx_distinct) * [approx\_median](#approx_median) * [approx\_percentile\_cont](#approx_percentile_cont) * [approx\_percentile\_cont\_with\_weight](#approx_percentile_cont_with_weight) ## General aggregate functions * [array\_agg](#array_agg) * [avg](#avg) * [bit\_and](#bit_and) * [bit\_or](#bit_or) * [bit\_xor](#bit_xor) * [bool\_and](#bool_and) * [bool\_or](#bool_or) * [count](#count) * [first\_value](#first_value) * [grouping](#grouping) * [last\_value](#last_value) * [max](#max) * [mean](#mean) * [median](#median) * [min](#min) * [nth\_value](#nth_value) * [string\_agg](#string_agg) * [sum](#sum) ### array\_agg Returns an array created from the expression elements. > [!Note] > `array_agg` returns a `LIST` Arrow type. Use bracket notation to reference the > index of an element in the returned array. Arrays are 1-indexed. ```sql array_agg(expression) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-array_agg-query-example) View `array_agg` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, array_agg(temp)[3] AS '3rd_temp' FROM home GROUP BY room ``` | room |3rd\_temp| |-----------|---------| | Kitchen | 22.7 | |Living Room| 21.8 | ### avg Returns the average of numeric values in the specified column. ```sql avg(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Aliases * `mean` [](#view-avg-query-example) View `avg` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, avg(precip) AS avg_precip FROM weather GROUP BY location ``` | location | avg\_precip | |-------------|--------------------| | Concord |0.027120658135283374| | Hayward |0.03708029197080292 | |San Francisco|0.03750912408759125 | ### bit\_and Computes the bitwise `AND` of all non-null input values. ```sql bit_and(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-bit_and-query-example) View `bit_and` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, bit_and(precip::BIGINT) AS precip_bit_and FROM weather GROUP BY location ``` | location |precip\_bit\_and| |-------------|----------------| | Concord | 0 | | Hayward | 0 | |San Francisco| 0 | ### bit\_or Computes the bitwise OR of all non-null input values. ```sql bit_or(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-bit_or-query-example) View `bit_or` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, bit_or(precip::BIGINT) AS precip_bit_or FROM weather GROUP BY location ``` | location |precip\_bit\_or| |-------------|---------------| | Concord | 7 | | Hayward | 7 | |San Francisco| 7 | ### bit\_xor Computes the bitwise exclusive OR of all non-null input values. ```sql bit_xor(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-bit_xor-query-example) View `bit_xor` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, bit_xor(precip::BIGINT) AS precip_bit_xor FROM weather GROUP BY location ``` | location |precip\_bit\_xor| |-------------|----------------| | Concord | 4 | | Hayward | 6 | |San Francisco| 4 | ### bool\_and Returns `true` if *all* non-null input values are `true`, otherwise returns `false`. ```sql bool_and(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-bool_and-query-example) View `bool_and` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, bool_and(precip > 0) AS precip_bool_and FROM weather GROUP BY location ``` | location |precip\_bool\_and| |-------------|-----------------| | Concord | false | | Hayward | false | |San Francisco| false | ### bool\_or Returns `true` if *any* non-null input value is `true`, otherwise returns `false`. ```sql bool_or(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-bool_or-query-example) View `bool_or` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, bool_or(precip > 0) AS precip_bool_or FROM weather GROUP BY location ``` | location |precip\_bool\_or| |-------------|----------------| | Concord | true | | Hayward | true | |San Francisco| true | ### count Returns the number of rows in the specified column. Count includes *null* values in the total count. To exclude *null* values from the total count, include ` IS NOT NULL`in the `WHERE` clause. ```sql count(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-count-query-example) View `count` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, count(precip) AS precip_count FROM weather GROUP BY location ``` | location |precip\_count| |-------------|-------------| | Concord | 1094 | | Hayward | 1096 | |San Francisco| 1096 | ### first\_value Returns the first element in an aggregation group according to the specified ordering. If no ordering is specified, returns an arbitrary element from the group. ```sql first_value(expression [ORDER BY expression]) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-first_value-query-example) View `first_value` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, first_value(temp_max ORDER BY time) AS temp_max_first_value FROM weather GROUP BY location ``` | location |temp\_max\_first\_value| |-------------|-----------------------| | Concord | 59 | | Hayward | 57 | |San Francisco| 66 | ### grouping Returns 1 if the data is aggregated across the specified column, or 0 if it is not aggregated in the result set. ```sql grouping(expression) ``` ##### Arguments * **expression**: Expression to evaluate whether data is aggregated across the specified column. Can be a constant, column, or function. [](#view-grouping-query-example) View `grouping` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, avg(temp_max) AS avg_max_temp, grouping(location) AS grouping FROM weather GROUP BY GROUPING SETS ((location), ()) ``` | location | avg\_max\_temp |grouping| |-------------|-----------------|--------| | Concord |75.54379562043796| 0 | | Hayward |69.12043795620438| 0 | |San Francisco|67.59945255474453| 0 | | |70.75456204379562| 1 | ### last\_value Returns the last element in an aggregation group according to the specified ordering. If no ordering is specified, returns an arbitrary element from the group. ```sql last_value(expression [ORDER BY expression]) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-last_value-query-example) View `last_value` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, last_value(temp_max ORDER BY time) AS temp_max_last_value FROM weather GROUP BY location ``` | location |temp\_max\_last\_value| |-------------|----------------------| | Concord | 59 | | Hayward | 58 | |San Francisco| 62 | ### max Returns the maximum value in the specified column. ```sql max(expression) ``` *To return both the maximum value and its associated timestamp, use[`selector_max`](/influxdb3/core/reference/sql/functions/selector/#selector_max).* ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-max-query-example) View `max` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, max(precip) AS max_precip FROM weather GROUP BY location ``` | location |max\_precip| |-------------|-----------| | Concord | 4.53 | | Hayward | 4.34 | |San Francisco| 4.02 | ### mean *Alias of [`avg`](#avg).* ### median Returns the median value in the specified column. ``` median(expression) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-median-query-example) View `median` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, median(temp_avg) AS median_temp_avg FROM weather GROUP BY location ``` | location |median\_temp\_avg| |-------------|-----------------| | Concord | 61.0 | | Hayward | 59.0 | |San Francisco| 58.0 | ### min Returns the minimum value in the specified column. ```sql min(expression) ``` *To return both the minimum value and its associated timestamp, use[`selector_max`](/influxdb3/core/reference/sql/functions/selector/#selector_min).* ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-min-query-example) View `min` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, min(temp_min) AS min_temp_min FROM weather GROUP BY location ``` | location |min\_temp\_min| |-------------|--------------| | Concord | 28.0 | | Hayward | 32.0 | |San Francisco| 35.0 | ### nth\_value Returns the nth value in a group of values. ```sql nth_value(expression, n [ORDER BY order_expression_1, ... order_expression_n]) ``` ##### arguments * **expression**: The column or expression to retrieve the nth value from. * **n**: The position (nth) of the value to retrieve, based on the ordering. * **order\_expression\_1, … order\_expression\_n**: Expressions to order by. Can be a column or function, and any combination of arithmetic operators. [](#view-nth_value-query-example) View `nth_value` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, nth_value(temp, 3 ORDER BY time) AS "3rd_temp" FROM home GROUP BY room ``` | room |3rd\_temp| |-----------|---------| |Living Room| 21.8 | | Kitchen | 22.7 | ### string\_agg Concatenates the values of string expressions and places separator values between them. ```sql string_agg(expression, delimiter) ``` ##### Arguments * **expression**: The string expression to concatenate. Can be a column or any valid string expression. * **delimiter**: A literal string to use as a separator between the concatenated values. [](#view-string_agg-query-example) View `string_agg` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, string_agg(temp_avg::STRING, ', ') AS string_agg FROM weather WHERE time > '2020-01-01T00:00:00Z' AND time < '2020-01-05T00:00:00Z' GROUP BY location ``` | location | string\_agg | |-------------|----------------| |San Francisco|54.0, 52.0, 54.0| | Hayward |51.0, 50.0, 51.0| | Concord |53.0, 49.0, 51.0| ### sum Returns the sum of all values in the specified column. ```sql sum(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-sum-query-example) View `sum` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, sum(precip) AS total_precip FROM weather GROUP BY location ``` | location | total\_precip | |-------------|------------------| | Concord |29.670000000000012| | Hayward | 40.64 | |San Francisco|41.110000000000014| ## Statistical aggregate functions * [corr](#corr) * [covar](#covar) * [covar\_pop](#covar_pop) * [covar\_samp](#covar_samp) * [regr\_avgx](#regr_avgx) * [regr\_avgy](#regr_avgy) * [regr\_count](#regr_count) * [regr\_intercept](#regr_intercept) * [regr\_r2](#regr_r2) * [regr\_slope](#regr_slope) * [regr\_sxx](#regr_sxx) * [regr\_syy](#regr_syy) * [regr\_sxy](#regr_sxy) * [stddev](#stddev) * [stddev\_pop](#stddev_pop) * [stddev\_samp](#stddev_samp) * [var](#var) * [var\_pop](#var_pop) * [var\_population](#var_population) * [var\_samp](#var_samp) * [var\_sample](#var_sample) ### corr Returns the coefficient of correlation between two numeric values. ```sql corr(expression1, expression2) ``` ##### Arguments * **expression1**: First column or literal value to operate on. * **expression2**: Second column or literal value to operate on. [](#view-corr-query-example) View `corr` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, corr(hum, temp) AS correlation FROM home GROUP BY room ``` | room | correlation | |-----------|-------------------| |Living Room|0.43665270457835725| | Kitchen |0.6741766954929539 | ### covar Returns the covariance of a set of number pairs. ```sql covar(expression1, expression2) ``` ##### Arguments * **expression1**: First column or literal value to operate on. * **expression2**: Second column or literal value to operate on. [](#view-covar-query-example) View `covar` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, covar(hum, temp) AS covar FROM home GROUP BY room ``` | room | covar | |-----------|-------------------| |Living Room|0.03346153846153959| | Kitchen |0.11134615384615432| ### covar\_pop Returns the population covariance of a set of number pairs. ```sql covar_pop(expression1, expression2) ``` ##### Arguments * **expression1**: First column or literal value to operate on. * **expression2**: Second column or literal value to operate on. [](#view-covar_pop-query-example) View `covar_pop` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, covar_pop(hum, temp) AS covar_pop FROM home GROUP BY room ``` | room | covar\_pop | |-----------|--------------------| | Kitchen |0.10278106508875783 | |Living Room|0.030887573964498087| ### covar\_samp Returns the sample covariance of a set of number pairs. ```sql covar_samp(expression1, expression2) ``` ##### Arguments * **expression1**: First column or literal value to operate on. * **expression2**: Second column or literal value to operate on. [](#view-covar_samp-query-example) View `covar_samp` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, covar_samp(hum, temp) AS covar_samp FROM home GROUP BY room ``` | room | covar\_samp | |-----------|-------------------| | Kitchen |0.11134615384615432| |Living Room|0.03346153846153959| ### regr\_avgx Computes the average of the independent variable (input), `expression_x`, for the non-null dependent variable, `expression_y`. ```sql regr_avgx(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_avgx-query-example) View `regr_avgx` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_avgx(temp_min, temp_max) AS temp_regr_avgx FROM weather GROUP BY location ``` | location |temp\_regr\_avgx | |-------------|-----------------| | Concord |75.54379562043796| | Hayward |69.14808043875686| |San Francisco|67.59945255474454| ### regr\_avgy Computes the average of the dependent variable (output), `expression_y`, for the non-null dependent variable, `expression_y`. ```sql regr_avgy(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_avgy-query-example) View `regr_avgy` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_avgy(temp_min, temp_max) AS temp_regr_avgy FROM weather GROUP BY location ``` | location | temp\_regr\_avgy | |-------------|------------------| | Concord |50.153284671532845| | Hayward |50.913162705667276| |San Francisco|51.52372262773722 | ### regr\_count Counts the number of non-null paired data points. ```sql regr_count(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_count-query-example) View `regr_count` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_count(temp_min, temp_max) AS temp_regr_count FROM weather GROUP BY location ``` | location |temp\_regr\_count| |-------------|-----------------| | Concord | 1096 | | Hayward | 1094 | |San Francisco| 1096 | ### regr\_intercept Computes the y-intercept of the linear regression line. For the equation `(y = kx + b)`, this function returns `b`. ```sql regr_intercept(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_intercept-query-example) View `regr_intercept` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_intercept(temp_min, temp_max) AS temp_regr_intercept FROM weather GROUP BY location ``` | location |temp\_regr\_intercept| |-------------|---------------------| | Concord | 11.636281392206769 | | Hayward | 12.876956842745152 | |San Francisco| 19.125237647086607 | ### regr\_r2 Computes the square of the correlation coefficient between the independent and dependent variables. ```sql regr_r2(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_r2-query-example) View `regr_r2` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_r2(temp_min, temp_max) AS temp_regr_r2 FROM weather GROUP BY location ``` | location | temp\_regr\_r2 | |-------------|------------------| | Concord |0.6474628308450441| | Hayward |0.5166296626320914| |San Francisco|0.5032317511200297| ### regr\_slope Returns the slope of the linear regression line for non-null pairs in aggregate columns. Given input column `Y` and `X`: `regr_slope(Y, X)` returns the slope (`k` in `Y = k*X + b`) using minimal RSS fitting. ```sql regr_slope(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Y expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: X expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_slope-query-example) View `regr_slope` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_slope(temp_min, temp_max) AS temp_regr_slope FROM weather GROUP BY location ``` | location |temp\_regr\_slope | |-------------|------------------| | Concord |0.5098632252058237| | Hayward |0.5500688612261629| |San Francisco|0.4792714105844738| ### regr\_sxx Computes the sum of squares of the independent variable. ```sql regr_sxx(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_sxx-query-example) View `regr_sxx` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_sxx(temp_min, temp_max) AS temp_regr_sxx FROM weather GROUP BY location ``` | location | temp\_regr\_sxx | |-------------|------------------| | Concord |210751.89781021897| | Hayward |99644.01096892142 | |San Francisco|77413.15967153282 | ### regr\_syy Computes the sum of squares of the dependent variable. ```sql regr_syy(expression_y, expression_x) ``` ##### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_syy-query-example) View `regr_syy` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_syy(temp_min, temp_max) AS temp_regr_syy FROM weather GROUP BY location ``` | location | temp\_regr\_syy | |-------------|------------------| | Concord |84618.24817518248 | | Hayward |58358.750457038404| |San Francisco|35335.38321167884 | ### regr\_sxy Computes the sum of products of paired data points. ```sql regr_sxy(expression_y, expression_x) ``` #### Arguments * **expression\_y**: Dependent variable. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Independent variable. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-regr_sxy-query-example) View `regr_sxy` query example *The following example uses the[NOAA Bay Area weather data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ``` SELECT location, regr_sxy(temp_min, temp_max) AS temp_regr_sxy FROM weather GROUP BY location ``` | location | temp\_regr\_sxy | |-------------|------------------| | Concord |107454.64233576645| | Hayward |54811.06764168191 | |San Francisco|37101.914233576645| ### stddev Returns the standard deviation of a set of numbers. ```sql stddev(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-stddev-query-example) View `stddev` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, stddev(co) AS stddev FROM home GROUP BY room ``` | room | stddev | |-----------|-----------------| |Living Room|5.885662718931967| | Kitchen |9.321879418735037| ### stddev\_pop Returns the population standard deviation of a set of numbers. ```sql stddev_pop(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-stddev_pop-query-example) View `stddev_pop` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, stddev_pop(co) AS stddev_pop FROM home GROUP BY room ``` | room | stddev\_pop | |-----------|-----------------| | Kitchen |8.956172047894082| |Living Room|5.654761830612032| ### stddev\_samp Returns the sample standard deviation of a set of numbers. ```sql stddev_samp(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-stddev_samp-query-example) View `stddev_samp` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, stddev_samp(co) AS stddev_samp FROM home GROUP BY room ``` | room | stddev\_samp | |-----------|-----------------| |Living Room|5.885662718931967| | Kitchen |9.321879418735037| ### var Returns the statistical variance of a set of numbers. ```sql var(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-var-query-example) View `var` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, var(co) AS var FROM home GROUP BY room ``` | room | var | |-----------|-----------------| |Living Room|34.64102564102564| | Kitchen |86.89743589743587| ### var\_pop Returns the statistical population variance of a set of numbers. ```sql var_pop(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Aliases * var\_population [](#view-var_pop-query-example) View `var_pop` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, var_pop(co) AS var_pop FROM home GROUP BY room ``` | room | var\_pop | |-----------|------------------| |Living Room|31.976331360946745| | Kitchen |80.21301775147927 | ### var\_population *Alias of [`var_pop`](#var_pop).* ### var\_samp Returns the statistical sample variance of a set of numbers. ```sql var_samp(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Aliases * var\_sample [](#view-var_samp-query-example) View `var_samp` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, var_samp(co) AS var_samp FROM home GROUP BY room ``` | room | var\_samp | |-----------|-----------------| | Kitchen |86.89743589743587| |Living Room|34.64102564102564| ### var\_sample *Alias of [var\_samp](#var_samp).* ## Approximate aggregate functions * [approx\_distinct](#approx_distinct) * [approx\_median](#approx_median) * [approx\_percentile\_cont](#approx_percentile_cont) * [approx\_percentile\_cont\_with\_weight](#approx_percentile_cont_with_weight) ### approx\_distinct Returns the approximate number of distinct input values calculated using the HyperLogLog algorithm. ```sql approx_distinct(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-approx_distinct-query-example) View `approx_distinct` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, approx_distinct(co::string) AS approx_distinct FROM home GROUP BY room ``` | room |approx\_distinct| |-----------|----------------| |Living Room| 7 | | Kitchen | 8 | ### approx\_median Returns the approximate median (50th percentile) of input values. It is an alias of `approx_percentile_cont(0.5) WITHIN GROUP (ORDER BY expression)`. ```sql approx_median(expression) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-approx_median-query-example) View `approx_median` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, approx_median(temp) AS approx_median FROM home GROUP BY room ``` | room |approx\_median| |-----------|--------------| | Kitchen | 22.7 | |Living Room| 22.3 | ### approx\_percentile\_cont Returns the approximate percentile of input values using the t-digest algorithm. ```sql approx_percentile_cont(percentile [, centroids]) WITHIN GROUP (ORDER BY expression) -- OR approx_percentile_cont(expression, percentile, centroids) ``` ##### Arguments * **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). * **centroids**: Number of centroids to use in the t-digest algorithm. *Default is 100*. A higher number results in more accurate approximation but requires more memory. * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. If there are this number or fewer unique values, you can expect an exact result. A higher number of centroids results in a more accurate approximation, but requires more memory to compute. [](#view-approx_percentile_cont-query-example) View `approx_percentile_cont` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, approx_percentile_cont(0.99) WITHIN GROUP (ORDER BY temp) AS "99th_percentile" FROM home GROUP BY room ``` | room |99th\_percentile| |-----------|----------------| | Kitchen | 23.3 | |Living Room| 22.8 | ### approx\_percentile\_cont\_with\_weight Returns the weighted approximate percentile of input values using the t-digest algorithm. ```sql approx_percentile_cont_with_weight(weight, percentile [, centroids]) WITHIN GROUP (ORDER BY expression) -- OR approx_percentile_cont_with_weight(expression, weight, percentile) ``` ##### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **weight**: Expression to use as weight. Can be a constant, column, or function, and any combination of arithmetic operators. * **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). * **centroids**: Number of centroids to use in the t-digest algorithm. *Default is 100.*A higher number results in more accurate approximation but requires more memory. [](#view-approx_percentile_cont_with_weight-query-example) View `approx_percentile_cont_with_weight` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, approx_percentile_cont_with_weight(co, 0.99) WITHIN GROUP (ORDER BY temp) AS "co_weighted_99th_percentile" FROM home GROUP BY room ``` | room |co\_weighted\_99th\_percentile| |-----------|------------------------------| | Kitchen | 23.3 | |Living Room| 22.8 | #### Related * [Aggregate data with SQL](/influxdb3/core/query-data/sql/aggregate-select/) | room | 3rd_temp | | --- | --- | | room | 3rd_temp | | Kitchen | 22.7 | | Living Room | 21.8 | | location | avg_precip | | --- | --- | | location | avg_precip | | Concord | 0.027120658135283374 | | Hayward | 0.03708029197080292 | | San Francisco | 0.03750912408759125 | | location | precip_bit_and | | --- | --- | | location | precip_bit_and | | Concord | 0 | | Hayward | 0 | | San Francisco | 0 | | location | precip_bit_or | | --- | --- | | location | precip_bit_or | | Concord | 7 | | Hayward | 7 | | San Francisco | 7 | | location | precip_bit_xor | | --- | --- | | location | precip_bit_xor | | Concord | 4 | | Hayward | 6 | | San Francisco | 4 | | location | precip_bool_and | | --- | --- | | location | precip_bool_and | | Concord | false | | Hayward | false | | San Francisco | false | | location | precip_bool_or | | --- | --- | | location | precip_bool_or | | Concord | true | | Hayward | true | | San Francisco | true | | location | precip_count | | --- | --- | | location | precip_count | | Concord | 1094 | | Hayward | 1096 | | San Francisco | 1096 | | location | temp_max_first_value | | --- | --- | | location | temp_max_first_value | | Concord | 59 | | Hayward | 57 | | San Francisco | 66 | | location | avg_max_temp | grouping | | --- | --- | --- | | location | avg_max_temp | grouping | | Concord | 75.54379562043796 | 0 | | Hayward | 69.12043795620438 | 0 | | San Francisco | 67.59945255474453 | 0 | | | 70.75456204379562 | 1 | | location | temp_max_last_value | | --- | --- | | location | temp_max_last_value | | Concord | 59 | | Hayward | 58 | | San Francisco | 62 | | location | max_precip | | --- | --- | | location | max_precip | | Concord | 4.53 | | Hayward | 4.34 | | San Francisco | 4.02 | | location | median_temp_avg | | --- | --- | | location | median_temp_avg | | Concord | 61.0 | | Hayward | 59.0 | | San Francisco | 58.0 | | location | min_temp_min | | --- | --- | | location | min_temp_min | | Concord | 28.0 | | Hayward | 32.0 | | San Francisco | 35.0 | | room | 3rd_temp | | --- | --- | | room | 3rd_temp | | Living Room | 21.8 | | Kitchen | 22.7 | | location | string_agg | | --- | --- | | location | string_agg | | San Francisco | 54.0, 52.0, 54.0 | | Hayward | 51.0, 50.0, 51.0 | | Concord | 53.0, 49.0, 51.0 | | location | total_precip | | --- | --- | | location | total_precip | | Concord | 29.670000000000012 | | Hayward | 40.64 | | San Francisco | 41.110000000000014 | | room | correlation | | --- | --- | | room | correlation | | Living Room | 0.43665270457835725 | | Kitchen | 0.6741766954929539 | | room | covar | | --- | --- | | room | covar | | Living Room | 0.03346153846153959 | | Kitchen | 0.11134615384615432 | | room | covar_pop | | --- | --- | | room | covar_pop | | Kitchen | 0.10278106508875783 | | Living Room | 0.030887573964498087 | | room | covar_samp | | --- | --- | | room | covar_samp | | Kitchen | 0.11134615384615432 | | Living Room | 0.03346153846153959 | | location | temp_regr_avgx | | --- | --- | | location | temp_regr_avgx | | Concord | 75.54379562043796 | | Hayward | 69.14808043875686 | | San Francisco | 67.59945255474454 | | location | temp_regr_avgy | | --- | --- | | location | temp_regr_avgy | | Concord | 50.153284671532845 | | Hayward | 50.913162705667276 | | San Francisco | 51.52372262773722 | | location | temp_regr_count | | --- | --- | | location | temp_regr_count | | Concord | 1096 | | Hayward | 1094 | | San Francisco | 1096 | | location | temp_regr_intercept | | --- | --- | | location | temp_regr_intercept | | Concord | 11.636281392206769 | | Hayward | 12.876956842745152 | | San Francisco | 19.125237647086607 | | location | temp_regr_r2 | | --- | --- | | location | temp_regr_r2 | | Concord | 0.6474628308450441 | | Hayward | 0.5166296626320914 | | San Francisco | 0.5032317511200297 | | location | temp_regr_slope | | --- | --- | | location | temp_regr_slope | | Concord | 0.5098632252058237 | | Hayward | 0.5500688612261629 | | San Francisco | 0.4792714105844738 | | location | temp_regr_sxx | | --- | --- | | location | temp_regr_sxx | | Concord | 210751.89781021897 | | Hayward | 99644.01096892142 | | San Francisco | 77413.15967153282 | | location | temp_regr_syy | | --- | --- | | location | temp_regr_syy | | Concord | 84618.24817518248 | | Hayward | 58358.750457038404 | | San Francisco | 35335.38321167884 | | location | temp_regr_sxy | | --- | --- | | location | temp_regr_sxy | | Concord | 107454.64233576645 | | Hayward | 54811.06764168191 | | San Francisco | 37101.914233576645 | | room | stddev | | --- | --- | | room | stddev | | Living Room | 5.885662718931967 | | Kitchen | 9.321879418735037 | | room | stddev_pop | | --- | --- | | room | stddev_pop | | Kitchen | 8.956172047894082 | | Living Room | 5.654761830612032 | | room | stddev_samp | | --- | --- | | room | stddev_samp | | Living Room | 5.885662718931967 | | Kitchen | 9.321879418735037 | | room | var | | --- | --- | | room | var | | Living Room | 34.64102564102564 | | Kitchen | 86.89743589743587 | | room | var_pop | | --- | --- | | room | var_pop | | Living Room | 31.976331360946745 | | Kitchen | 80.21301775147927 | | room | var_samp | | --- | --- | | room | var_samp | | Kitchen | 86.89743589743587 | | Living Room | 34.64102564102564 | | room | approx_distinct | | --- | --- | | room | approx_distinct | | Living Room | 7 | | Kitchen | 8 | | room | approx_median | | --- | --- | | room | approx_median | | Kitchen | 22.7 | | Living Room | 22.3 | | room | 99th_percentile | | --- | --- | | room | 99th_percentile | | Kitchen | 23.3 | | Living Room | 22.8 | | room | co_weighted_99th_percentile | | --- | --- | | room | co_weighted_99th_percentile | | Kitchen | 23.3 | | Living Room | 22.8 | --- # SQL array functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/array/ Use array functions to create and operate on Arrow arrays or lists in SQL queries. * [array\_any\_value](#array_any_value) * [array\_append](#array_append) * [array\_cat](#array_cat) * [array\_concat](#array_concat) * [array\_contains](#array_contains) * [array\_dims](#array_dims) * [array\_distance](#array_distance) * [array\_distinct](#array_distinct) * [array\_element](#array_element) * [array\_empty](#array_empty) * [array\_except](#array_except) * [array\_extract](#array_extract) * [array\_has](#array_has) * [array\_has\_all](#array_has_all) * [array\_has\_any](#array_has_any) * [array\_indexof](#array_indexof) * [array\_intersect](#array_intersect) * [array\_join](#array_join) * [array\_length](#array_length) * [array\_max](#array_max) * [array\_min](#array_min) * [array\_ndims](#array_ndims) * [array\_pop\_back](#array_pop_back) * [array\_pop\_front](#array_pop_front) * [array\_position](#array_position) * [array\_positions](#array_positions) * [array\_prepend](#array_prepend) * [array\_push\_back](#array_push_back) * [array\_push\_front](#array_push_front) * [array\_remove](#array_remove) * [array\_remove\_all](#array_remove_all) * [array\_remove\_n](#array_remove_n) * [array\_repeat](#array_repeat) * [array\_replace](#array_replace) * [array\_replace\_all](#array_replace_all) * [array\_replace\_n](#array_replace_n) * [array\_resize](#array_resize) * [array\_reverse](#array_reverse) * [array\_slice](#array_slice) * [array\_sort](#array_sort) * [array\_to\_string](#array_to_string) * [array\_union](#array_union) * [arrays\_overlap](#arrays_overlap) * [cardinality](#cardinality) * [empty](#empty) * [flatten](#flatten) * [generate\_series](#generate_series) * [list\_any\_value](#list_any_value) * [list\_append](#list_append) * [list\_cat](#list_cat) * [list\_concat](#list_concat) * [list\_contains](#list_contains) * [list\_dims](#list_dims) * [list\_distance](#list_distance) * [list\_distinct](#list_distinct) * [list\_element](#list_element) * [list\_empty](#list_empty) * [list\_except](#list_except) * [list\_extract](#list_extract) * [list\_has](#list_has) * [list\_has\_all](#list_has_all) * [list\_has\_any](#list_has_any) * [list\_indexof](#list_indexof) * [list\_intersect](#list_intersect) * [list\_join](#list_join) * [list\_length](#list_length) * [list\_max](#list_max) * [list\_ndims](#list_ndims) * [list\_pop\_back](#list_pop_back) * [list\_pop\_front](#list_pop_front) * [list\_position](#list_position) * [list\_positions](#list_positions) * [list\_prepend](#list_prepend) * [list\_push\_back](#list_push_back) * [list\_push\_front](#list_push_front) * [list\_remove](#list_remove) * [list\_remove\_all](#list_remove_all) * [list\_remove\_n](#list_remove_n) * [list\_repeat](#list_repeat) * [list\_replace](#list_replace) * [list\_replace\_all](#list_replace_all) * [list\_replace\_n](#list_replace_n) * [list\_resize](#list_resize) * [list\_reverse](#list_reverse) * [list\_slice](#list_slice) * [list\_sort](#list_sort) * [list\_to\_string](#list_to_string) * [list\_union](#list_union) * [make\_array](#make_array) * [make\_list](#make_list) * [range](#range) * [string\_to\_array](#string_to_array) * [string\_to\_list](#string_to_list) ## array\_any\_value Returns the first non-null element in the array. ```sql array_any_value(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_any_value` [](#view-array_any_value-example) View `array_any_value` example ```sql SELECT array_any_value([NULL, 1, 2, 3]) AS array_any_value ``` |array\_any\_value| |-----------------| | 1 | ## array\_append Appends an element to the end of an array. ```sql array_append(array, element) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to append to the array. #### Aliases * `list_append` * `array_push_back` * `list_push_back` [](#view-array_append-example) View `array_append` example ```sql SELECT array_append([1, 2, 3], 4) AS array_append ``` |array\_append| |-------------| |[1, 2, 3, 4] | ## array\_cat *Alias of [array\_concat](#array_concat).* ## array\_concat Concatenates multiple arrays into a single array. ```sql array_concat(array[, ..., array_n]) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **array\_n**: Subsequent array column or literal array to concatenate. #### Aliases * `array_cat` * `list_concat` * `list_cat` [](#view-array_concat-example) View `array_concat` example ```sql SELECT array_concat([1, 2], [3, 4], [5, 6]) AS array_concat ``` | array\_concat | |------------------| |[1, 2, 3, 4, 5, 6]| ## array\_contains *Alias of [array\_has](#array_has).* ## array\_dims Returns an array of the array’s dimensions. ```sql array_dims(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_dims` [](#view-array_dims-example) View `array_dims` example ```sql SELECT array_dims([[1, 2, 3], [4, 5, 6]]) AS array_dims ``` |array\_dims(List([1,2,3,4,5,6]))| |--------------------------------| | [2, 3] | ## array\_distance Returns the Euclidean distance between two input arrays of equal length. ```sql array_distance(array1, array2) ``` ### Arguments * **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_distance` [](#view-array_distance-example) View `array_distance` example ```sql SELECT array_distance([1, 2], [1, 4]) AS array_distance ``` |array\_distance| |---------------| | 2.0 | ## array\_distinct Returns distinct values from the array after removing duplicates. ```sql array_distinct(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_distinct` [](#view-array_distinct-example) View `array_distinct` example ```sql SELECT array_distinct([1, 3, 2, 3, 1, 2, 4]) AS array_distinct ``` |array\_distinct(List([1,2,3,4]))| |--------------------------------| | [1, 2, 3, 4] | ## array\_element Extracts the element with the index n from the array. ```sql array_element(array, index) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **index**: Index to use to extract the element from the array. #### Aliases * `array_extract` * `list_element` * `list_extract` [](#view-array_element-example) View `array_element` example ```sql SELECT array_element([1, 2, 3, 4], 3) AS array_element ``` |array\_element| |--------------| | 3 | ## array\_empty *Alias of [empty](#empty).* ## array\_except Returns an array containing elements from the first array that are not present in the second array. ```sql array_except(array1, array2) ``` ### Arguments * **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_except` [](#view-array_except-example) View `array_except` example ```sql SELECT array_except([1, 2, 3, 4], [5, 6, 3, 4]) AS array_except ``` |array\_except| |-------------| | [1, 2] | ## array\_extract *Alias of [array\_element](#array_element).* ## array\_has Returns `true` if the array contains the element. ```sql array_has(array, element) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Scalar or Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_has` * `array_contains` * `list_contains` [](#view-array_has-example) View `array_has` example ```sql SELECT array_has([1, 2, 3], 2) AS array_has ``` |array\_has| |----------| | true | ## array\_has\_all Returns `true` if all elements of sub-array exist in array. ```sql array_has_all(array, sub-array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **sub-array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_has_all` [](#view-array_has_all-example) View `array_has_all` example ```sql SELECT array_has_all([1, 2, 3, 4], [2, 3]) AS array_has_all ``` |array\_has\_all| |---------------| | true | ## array\_has\_any Returns `true` if at least one element appears in both arrays. ```sql array_has_any(array, sub-array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **sub-array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_has_any` * `arrays_overlap` [](#view-array_has_any-example) View `array_has_any` example ```sql SELECT array_has_any([1, 2, 3], [3, 4]) AS array_has_any ``` |array\_has\_any| |---------------| | true | ## array\_indexof *Alias of [array\_position](#array_position).* ## array\_intersect Returns an array containing only the elements that appear in both **array1** and **array2**. ```sql array_intersect(array1, array2) ``` ### Arguments * **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_intersect` [](#view-array_intersect-example-with-intersecting-arrays) View `array_intersect` example with intersecting arrays ```sql SELECT array_intersect([1, 2, 3, 4], [5, 6, 3, 4]) AS array_intersect ``` |array\_intersect| |----------------| | [3, 4] | [](#view-array_intersect-example-with-non-intersecting-arrays) View `array_intersect` example with non-intersecting arrays ```sql SELECT array_intersect([1, 2, 3, 4], [5, 6, 7, 8]) AS array_intersect ``` |array\_intersect| |----------------| | [] | ## array\_join *Alias of [array\_to\_string](#array_to_string).* ## array\_length Returns the length of the array dimension. ```sql array_length(array, dimension) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **dimension**: Array dimension. Default is `1`. #### Aliases * `list_length` [](#view-array_length-example-with-single-dimension-array) View `array_length` example with single-dimension array ```sql SELECT array_length([1, 2, 3, 4, 5]) AS array_length ``` |array\_length| |-------------| | 5 | [](#view-array_length-example-with-multi-dimension-array) View `array_length` example with multi-dimension array ```sql WITH vars AS ( SELECT [ [1, 2, 3, 4, 5], [5, 6, 7, 8, 9] ] AS example_array ) SELECT array_length(example_array, 1) AS 'dim1_length', array_length(example_array, 2) AS 'dim2_length' FROM vars ``` |dim1\_length|dim2\_length| |------------|------------| | 2 | 5 | ## array\_max Returns the maximum value in the array. ```sql array_max(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_max` [](#view-array_max-example) View `array_max` example ```sql SELECT array_max([3,1,4,2]) AS array_max ``` |array\_max| |----------| | 4 | ## array\_min Returns the minimum value in the array. ```sql array_min(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. [](#view-array_min-example) View `array_min` example ```sql SELECT array_min([3,1,4,2]) AS array_min ``` |array\_min| |----------| | 1 | ## array\_ndims Returns the number of dimensions of the array. ```sql array_ndims(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_ndims` [](#view-array_ndims-example) View `array_ndims` example ```sql SELECT array_ndims([[1, 2, 3], [4, 5, 6]]) AS array_ndims ``` |array\_ndims| |------------| | 2 | ## array\_pop\_back Returns the array without the last element. ```sql array_pop_back(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_pop_back` [](#view-array_pop_back-example) View `array_pop_back` example ```sql SELECT array_pop_back([1, 2, 3]) AS array_pop_back ``` |array\_pop\_back| |----------------| | [1, 2] | ## array\_pop\_front Returns the array without the first element. ```sql array_pop_front(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_pop_front` [](#view-array_pop_front-example) View `array_pop_front` example ```sql SELECT array_pop_front([1, 2, 3]) AS array_pop_front ``` |array\_pop\_front| |-----------------| | [2, 3] | ## array\_position Returns the position of the first occurrence of the specified element in the array, or *NULL* if not found. ```sql array_position(array, element, index) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to search for position in the array. * **index**: Index at which to start searching (1-indexed). Default is `1`. #### Aliases * `list_position` * `array_indexof` * `list_indexof` [](#view-array_position-example) View `array_position` example ```sql SELECT array_position([1, 2, 2, 3, 1, 4], 2) AS array_position ``` |array\_position| |---------------| | 2 | [](#view-array_position-example-with-index-offset) View `array_position` example with index offset ```sql SELECT array_position([1, 2, 2, 3, 1, 4], 2, 3) AS array_position ``` |array\_position| |---------------| | 3 | ## array\_positions Searches for an element in the array and returns the position or index of each occurrence. ```sql array_positions(array, element) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to search for position in the array. #### Aliases * `list_positions` [](#view-array_positions-example) View `array_positions` example ```sql SELECT array_positions(['John', 'Jane', 'James', 'John'], 'John') AS array_positions ``` |array\_positions| |----------------| | [1, 4] | ## array\_prepend Prepends an element to the beginning of an array. ```sql array_prepend(element, array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to prepend to the array. #### Aliases * `list_prepend` * `array_push_front` * `list_push_front` [](#view-array_prepend-example) View `array_prepend` example ```sql SELECT array_prepend(1, [2, 3, 4]) AS array_prepend ``` |array\_prepend| |--------------| | [1, 2, 3, 4] | ## array\_push\_back *Alias of [array\_append](#array_append).* ## array\_push\_front *Alias of [array\_prepend](#array_prepend).* ## array\_remove Removes the first element from the array equal to the given value. ```sql array_remove(array, element) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to remove from the array. #### Aliases * `list_remove` [](#view-array_remove-example) View `array_remove` example ```sql SELECT array_remove([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove ``` | array\_remove | |------------------| |[1, 2, 3, 2, 1, 4]| ## array\_remove\_all Removes all elements from the array equal to the specified value. ```sql array_remove_all(array, element) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to be removed from the array. #### Aliases * `list_remove_all` [](#view-array_remove_all-example) View `array_remove_all` example ```sql SELECT array_remove_all([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove_all ``` |array\_remove\_all| |------------------| | [1, 3, 1, 4] | ## array\_remove\_n Removes the first `max` elements from the array equal to the specified value. ```sql array_remove_n(array, element, max) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **element**: Element to remove from the array. * **max**: Maximum number of occurrences to remove. #### Aliases * `list_remove_n` [](#view-array_remove_n-example) View `array_remove_n` example ```sql SELECT array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2) AS array_remove_n ``` |array\_remove\_n| |----------------| |[1, 3, 2, 1, 4] | ## array\_repeat Returns an array containing element `count` times. ```sql array_repeat(element, count) ``` ### Arguments * **element**: Element expression. Can be a constant, column, or function, and any combination of array operators. * **count**: Number of times to repeat the element. #### Aliases * `list_repeat` [](#view-array_repeat-example-with-numeric-values) View `array_repeat` example with numeric values ```sql SELECT array_repeat(1, 3) AS array_repeat ``` |array\_repeat| |-------------| | [1, 1, 1] | [](#view-array_repeat-example-with-string-values) View `array_repeat` example with string values ```sql SELECT array_repeat('John', 3) AS array_repeat ``` | array\_repeat | |------------------| |[John, John, John]| [](#view-array_repeat-example-with-array-values) View `array_repeat` example with array values ```sql SELECT array_repeat([1, 2], 2) AS array_repeat ``` | array\_repeat | |----------------| |[[1, 2], [1, 2]]| ## array\_replace Replaces the first occurrence of the specified element with another specified element. ```sql array_replace(array, from, to) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **from**: Element to replace. * **to**: Replacement element. #### Aliases * `list_replace` [](#view-array_replace-example) View `array_replace` example ```sql SELECT array_replace(['John', 'Jane', 'James', 'John'], 'John', 'Joe') AS array_replace ``` | array\_replace | |------------------------| |[Joe, Jane, James, John]| ## array\_replace\_all Replaces all occurrences of the specified element with another specified element. ```sql array_replace_all(array, from, to) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **from**: Element to replace. * **to**: Replacement element. #### Aliases * `list_replace_all` [](#view-array_replace_all-example) View `array_replace_all` example ```sql SELECT array_replace_all(['John', 'Jane', 'James', 'John'], 'John', 'Joe') AS array_replace_all ``` | array\_replace\_all | |-----------------------| |[Joe, Jane, James, Joe]| ## array\_replace\_n Replaces the first `max` occurrences of the specified element with another specified element. ```sql array_replace_n(array, from, to, max) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **from**: Element to replace. * **to**: Replacement element. * **max**: Maximum number of occurrences to replace. #### Aliases * `list_replace_n` [](#view-array_replace_n-example) View `array_replace_n` example ```sql SELECT array_replace_n(['John', 'Jane', 'James', 'John', 'John'], 'John', 'Joe', 2) AS array_replace_n ``` | array\_replace\_n | |-----------------------------| |[Joe, Jane, James, Joe, John]| ## array\_resize Resizes the list to contain size elements. Initializes new elements with value Resizes the array to the specified size. If expanding, fills new elements with the specified value (or *NULL* if not provided). If shrinking, truncates excess elements. ```sql array_resize(array, size, value) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **size**: New size of the array. * **value**: Value to use for new elements. Default is *NULL*. #### Aliases * `list_resize` [](#view-array_resize-example) View `array_resize` example ```sql SELECT array_resize([1, 2, 3], 5, 0) AS array_resize ``` |array\_resize(List([1,2,3],5,0))| |--------------------------------| | [1, 2, 3, 0, 0] | ## array\_reverse Returns the array with the order of the elements reversed. ```sql array_reverse(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_reverse` [](#view-array_reverse-example) View `array_reverse` example ```sql SELECT array_reverse([1, 2, 3, 4]) AS array_reverse ``` |array\_reverse| |--------------| | [4, 3, 2, 1] | ## array\_slice Returns a slice of the array based on 1-indexed start and end positions. ```sql array_slice(array, begin, end) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **begin**: Index of the first element. If negative, it counts backward from the end of the array. * **end**: Index of the last element. If negative, it counts backward from the end of the array. * **stride**: Stride of the array slice. The default is `1`. #### Aliases * `list_slice` [](#view-array_slice-example) View `array_slice` example ```sql SELECT array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6) AS array_slice ``` |array\_slice| |------------| |[3, 4, 5, 6]| ## array\_sort Sorts elements in an array. If elements are numeric, it sorts elements in numerical order. If elements are strings, it sorts elements in lexicographical order. ```sql array_sort(array, sort_order, sort_nulls) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **sort\_order**: Sort order (`'ASC'` *(default)* or `'DESC'`). * **sort\_nulls**: Sort nulls first or last (`'NULLS FIRST'` *(default)* or `'NULLS LAST'`). #### Aliases * `list_sort` [](#view-array_sort-example-with-numeric-elements) View `array_sort` example with numeric elements ```sql SELECT array_sort([3, 1, 2]) AS array_sort ``` |array\_sort| |-----------| | [1, 2, 3] | [](#view-array_sort-example-with-string-elements) View `array_sort` example with string elements ```sql SELECT array_sort(['banana', 'apple', 'cherry'], 'DESC') AS array_sort ``` | array\_sort | |-----------------------| |[cherry, banana, apple]| [](#view-array_sort-example-with-_null_-elements) View `array_sort` example with *NULL* elements ```sql SELECT array_sort( ['banana', 'apple', NULL, 'cherry', NULL], 'ASC', 'NULLS LAST' ) AS array_sort ``` | array\_sort | |---------------------------| |[apple, banana, cherry, , ]| ## array\_to\_string Converts an array to a string by joining all elements with the specified delimiter. ```sql array_to_string(array, delimiter[, null_string]) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **delimiter**: Array element separator. * **null\_string**: Optional. String to replace *NULL* values in the array. If not provided, *NULL* elements are ignored. #### Aliases * `list_to_string` * `array_join` * `list_join` [](#view-array_to_string-example) View `array_to_string` example ```sql SELECT array_to_string([1,2,3,4,5,6,7,8], ',') AS array_to_string ``` |array\_to\_string| |-----------------| | 1,2,3,4,5,6,7,8 | [](#view-array_to_string-example-with-_null_-replacements) View `array_to_string` example with *NULL* replacements ```sql SELECT array_to_string([[1,2,3,4,5,NULL,7,8,NULL]], '-', '?') AS array_to_string ``` |array\_to\_string| |-----------------| |1-2-3-4-5-?-7-8-?| ## array\_union Returns an array of elements that are present in both arrays (all elements from Returns an array containing all unique elements from both input arrays, with duplicates removed. ```sql array_union(array1, array2) ``` ### Arguments * **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. * **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `list_union` [](#view-array_union-example) View `array_union` example ```sql SELECT array_union([1, 2, 3, 4], [5, 6, 3, 4]) AS array_union ``` | array\_union | |------------------| |[1, 2, 3, 4, 5, 6]| ## arrays\_overlap *Alias of [array\_has\_any](#array_has_any).* ## cardinality Returns the total number of elements in the array. ```sql cardinality(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. [](#view-cardinality-example) View `cardinality` example ```sql SELECT cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]) AS cardinality ``` |cardinality| |-----------| | 8 | ## empty Returns `true` for an empty array or `false` for a non-empty array. ```sql empty(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. #### Aliases * `array_empty` * `list_empty` [](#view-empty-example) View `empty` example ```sql SELECT empty(['apple']) AS empty ``` |empty| |-----| |false| ## flatten Flattens nested arrays into a single-level array. * Recursively flattens arrays at any depth of nesting * Returns unchanged if the array is already flat The result contains all elements from all nested arrays in a single flat array. ```sql flatten(array) ``` ### Arguments * **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. [](#view-flatten-example) View `flatten` example ```sql SELECT flatten([[1, 2], [3, 4]]) AS flattened ``` | flattened | |------------| |[1, 2, 3, 4]| ## generate\_series Returns an array with values between the specified **start** and **stop** values generated at the specified **step**. The range `start..stop` contains all values greater than or equal to **start**and less than or equal to **stop** (`start <= x <= stop`). If **start** is greater than or equal to **stop** (`start >= stop`), the function returns an empty array. *`generate_series` is similar to [range](#range), but includes the upper bound (**stop**) in the output array.* ```sql generate_series(start, stop, step) ``` ### Arguments * **start**: Start of the series. Supports integers, timestamps, dates, or string types that can be coerced to `Date32`. * **stop**: Upper bound of the series. Supports integers, timestamps, dates, or string types that can be coerced to `Date32`. The type must be the same as **start**. * **step**: Increase by step (cannot be `0`). Steps less than a day are only supported for ranges with the `TIMESTAMP` type. ##### Related functions [range](#range) [](#view-generate_series-example) View `generate_series` example ```sql SELECT generate_series(1,5) AS generate_series ``` |generate\_series| |----------------| |[1, 2, 3, 4, 5] | [](#view-range-example-with-dates) View `range` example with dates ```sql SELECT generate_series( DATE '2025-03-01', DATE '2025-08-01', INTERVAL '1 month' ) AS generate_series ``` | generate\_series | |------------------------------------------------------------------------| |[2025-03-01, 2025-04-01, 2025-05-01, 2025-06-01, 2025-07-01, 2025-08-01]| [](#view-generate_series-example-using-timestamps) View `generate_series` example using timestamps ```sql SELECT generate_series( '2025-01-01T00:00:00Z'::timestamp, '2025-01-01T06:00:00Z'::timestamp, INTERVAL '2 hours' ) AS generate_series ``` | generate\_series | |------------------------------------------------------------------------------------| |[2025-01-01T00:00:00, 2025-01-01T02:00:00, 2025-01-01T04:00:00, 2025-01-01T06:00:00]| ## list\_any\_value *Alias of [array\_any\_value](#array_any_value).* ## list\_append *Alias of [array\_append](#array_append).* ## list\_cat *Alias of [array\_concat](#array_concat).* ## list\_concat *Alias of [array\_concat](#array_concat).* ## list\_contains *Alias of [array\_has](#array_has).* ## list\_dims *Alias of [array\_dims](#array_dims).* ## list\_distance *Alias of [array\_distance](#array_distance).* ## list\_distinct *Alias of [array\_distinct](#array_distinct).* ## list\_element *Alias of [array\_element](#array_element).* ## list\_empty *Alias of [empty](#empty).* ## list\_except *Alias of [array\_except](#array_except).* ## list\_extract *Alias of [array\_element](#array_element).* ## list\_has *Alias of [array\_has](#array_has).* ## list\_has\_all *Alias of [array\_has\_all](#array_has_all).* ## list\_has\_any *Alias of [array\_has\_any](#array_has_any).* ## list\_indexof *Alias of [array\_position](#array_position).* ## list\_intersect *Alias of [array\_intersect](#array_intersect).* ## list\_join *Alias of [array\_to\_string](#array_to_string).* ## list\_length *Alias of [array\_length](#array_length).* ## list\_max *Alias of [array\_max](#array_max).* ## list\_ndims *Alias of [array\_ndims](#array_ndims).* ## list\_pop\_back *Alias of [array\_pop\_back](#array_pop_back).* ## list\_pop\_front *Alias of [array\_pop\_front](#array_pop_front).* ## list\_position *Alias of [array\_position](#array_position).* ## list\_positions *Alias of [array\_positions](#array_positions).* ## list\_prepend *Alias of [array\_prepend](#array_prepend).* ## list\_push\_back *Alias of [array\_append](#array_append).* ## list\_push\_front *Alias of [array\_prepend](#array_prepend).* ## list\_remove *Alias of [array\_remove](#array_remove).* ## list\_remove\_all *Alias of [array\_remove\_all](#array_remove_all).* ## list\_remove\_n *Alias of [array\_remove\_n](#array_remove_n).* ## list\_repeat *Alias of [array\_repeat](#array_repeat).* ## list\_replace *Alias of [array\_replace](#array_replace).* ## list\_replace\_all *Alias of [array\_replace\_all](#array_replace_all).* ## list\_replace\_n *Alias of [array\_replace\_n](#array_replace_n).* ## list\_resize *Alias of [array\_resize](#array_resize).* ## list\_reverse *Alias of [array\_reverse](#array_reverse).* ## list\_slice *Alias of [array\_slice](#array_slice).* ## list\_sort *Alias of [array\_sort](#array_sort).* ## list\_to\_string *Alias of [array\_to\_string](#array_to_string).* ## list\_union *Alias of [array\_union](#array_union).* ## make\_array Returns an array using the specified input expressions. ```sql make_array(expression1[, ..., expression_n]) ``` ### Arguments * **expression\_n**: Expression to include in the output array. Can be a constant, column, or function, and any combination of arithmetic or string operators. #### Aliases * `make_list` [](#view-make_array-example) View `make_array` example ```sql SELECT make_array(1, 2, 3, 4, 5) AS make_array ``` | make\_array | |---------------| |[1, 2, 3, 4, 5]| ## make\_list *Alias of [make\_array](#make_array).* ## range Returns an array with values between the specified **start** and **stop** values generated at the specified **step**. The range `start..stop` contains all values greater than or equal to **start**and less than **stop** (`start <= x < stop`). If **start** is greater than or equal to **stop** (`start >= stop`), the function returns an empty array. *`range` is similar to [generate\_series](#generate_series), but does not include the upper bound (**stop**) in the output array.* ```sql range(start, stop, step) ``` ### Arguments * **start**: Start of the series. Supports integers, timestamps, dates, or string types that can be coerced to `Date32`. * **stop**: Upper bound of the series. Supports integers, timestamps, dates, or string types that can be coerced to `Date32`. The type must be the same as **start**. * **step**: Increase by step (cannot be `0`). Steps less than a day are only supported for ranges with the `TIMESTAMP` type. ##### Related functions [generate\_series](#generate_series) [](#view-range-example) View `range` example ```sql SELECT range(1, 5, 1) AS range ``` | range | |------------| |[1, 2, 3, 4]| [](#view-range-example-with-dates) View `range` example with dates ```sql SELECT range( DATE '2025-03-01', DATE '2025-08-01', INTERVAL '1 month' ) AS range ``` | range | |------------------------------------------------------------| |[2025-03-01, 2025-04-01, 2025-05-01, 2025-06-01, 2025-07-01]| [](#view-range-example-with-timestamps) View range example with timestamps ```sql SELECT range( '2025-01-01T00:00:00Z'::timestamp, '2025-01-01T06:00:00Z'::timestamp, INTERVAL '2 hours' ) AS range ``` | range | |---------------------------------------------------------------| |[2025-01-01T00:00:00, 2025-01-01T02:00:00, 2025-01-01T04:00:00]| ## string\_to\_array Splits a string into an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with `NULL`. ```sql string_to_array(str, delimiter[, null_str]) ``` ### Arguments * **str**: String expression to split. * **delimiter**: Delimiter string to split on. * **null\_str**: *(Optional)* Substring values to replace with `NULL`. #### Aliases * `string_to_list` [](#view-string_to_array-example-with-comma-delimited-list) View `string_to_array` example with comma-delimited list ```sql SELECT string_to_array('abc, def, ghi', ', ') AS string_to_array ``` |string\_to\_array| |-----------------| | [abc, def, ghi] | [](#view-string_to_array-example-with-a-non-standard-delimiter) View `string_to_array` example with a non-standard delimiter ```sql SELECT string_to_array('abc##def', '##') AS string_to_array ``` |string\_to\_array| |-----------------| | [‘abc’, ‘def’] | [](#view-string_to_array-example-with-_null_-replacements) View `string_to_array` example with *NULL* replacements ```sql SELECT string_to_array('abc def', ' ', 'def') AS string_to_array ``` |string\_to\_array| |-----------------| | [‘abc’, NULL] | ## string\_to\_list *Alias of [string\_to\_array](#string_to_array).* | array_any_value | | --- | | array_any_value | | 1 | | array_append | | --- | | array_append | | [1, 2, 3, 4] | | array_concat | | --- | | array_concat | | [1, 2, 3, 4, 5, 6] | | array_dims(List([1,2,3,4,5,6])) | | --- | | array_dims(List([1,2,3,4,5,6])) | | [2, 3] | | array_distance | | --- | | array_distance | | 2.0 | | array_distinct(List([1,2,3,4])) | | --- | | array_distinct(List([1,2,3,4])) | | [1, 2, 3, 4] | | array_element | | --- | | array_element | | 3 | | array_except | | --- | | array_except | | [1, 2] | | array_has | | --- | | array_has | | true | | array_has_all | | --- | | array_has_all | | true | | array_has_any | | --- | | array_has_any | | true | | array_intersect | | --- | | array_intersect | | [3, 4] | | array_intersect | | --- | | array_intersect | | [] | | array_length | | --- | | array_length | | 5 | | dim1_length | dim2_length | | --- | --- | | dim1_length | dim2_length | | 2 | 5 | | array_max | | --- | | array_max | | 4 | | array_min | | --- | | array_min | | 1 | | array_ndims | | --- | | array_ndims | | 2 | | array_pop_back | | --- | | array_pop_back | | [1, 2] | | array_pop_front | | --- | | array_pop_front | | [2, 3] | | array_position | | --- | | array_position | | 2 | | array_position | | --- | | array_position | | 3 | | array_positions | | --- | | array_positions | | [1, 4] | | array_prepend | | --- | | array_prepend | | [1, 2, 3, 4] | | array_remove | | --- | | array_remove | | [1, 2, 3, 2, 1, 4] | | array_remove_all | | --- | | array_remove_all | | [1, 3, 1, 4] | | array_remove_n | | --- | | array_remove_n | | [1, 3, 2, 1, 4] | | array_repeat | | --- | | array_repeat | | [1, 1, 1] | | array_repeat | | --- | | array_repeat | | [John, John, John] | | array_repeat | | --- | | array_repeat | | [[1, 2], [1, 2]] | | array_replace | | --- | | array_replace | | [Joe, Jane, James, John] | | array_replace_all | | --- | | array_replace_all | | [Joe, Jane, James, Joe] | | array_replace_n | | --- | | array_replace_n | | [Joe, Jane, James, Joe, John] | | array_resize(List([1,2,3],5,0)) | | --- | | array_resize(List([1,2,3],5,0)) | | [1, 2, 3, 0, 0] | | array_reverse | | --- | | array_reverse | | [4, 3, 2, 1] | | array_slice | | --- | | array_slice | | [3, 4, 5, 6] | | array_sort | | --- | | array_sort | | [1, 2, 3] | | array_sort | | --- | | array_sort | | [cherry, banana, apple] | | array_sort | | --- | | array_sort | | [apple, banana, cherry, , ] | | array_to_string | | --- | | array_to_string | | 1,2,3,4,5,6,7,8 | | array_to_string | | --- | | array_to_string | | 1-2-3-4-5-?-7-8-? | | array_union | | --- | | array_union | | [1, 2, 3, 4, 5, 6] | | cardinality | | --- | | cardinality | | 8 | | empty | | --- | | empty | | false | | flattened | | --- | | flattened | | [1, 2, 3, 4] | | generate_series | | --- | | generate_series | | [1, 2, 3, 4, 5] | | generate_series | | --- | | generate_series | | [2025-03-01, 2025-04-01, 2025-05-01, 2025-06-01, 2025-07-01, 2025-08-01] | | generate_series | | --- | | generate_series | | [2025-01-01T00:00:00, 2025-01-01T02:00:00, 2025-01-01T04:00:00, 2025-01-01T06:00:00] | | make_array | | --- | | make_array | | [1, 2, 3, 4, 5] | | range | | --- | | range | | [1, 2, 3, 4] | | range | | --- | | range | | [2025-03-01, 2025-04-01, 2025-05-01, 2025-06-01, 2025-07-01] | | range | | --- | | range | | [2025-01-01T00:00:00, 2025-01-01T02:00:00, 2025-01-01T04:00:00] | | string_to_array | | --- | | string_to_array | | [abc, def, ghi] | | string_to_array | | --- | | string_to_array | | [‘abc’, ‘def’] | | string_to_array | | --- | | string_to_array | | [‘abc’, NULL] | --- # SQL binary string functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/binary-string/ Use binary string functions to encode and decode binary string values in SQL queries. * [decode](#decode) * [encode](#encode) ## decode Decode binary data from textual representation in string. ```sql decode(expression, format) ``` ### Arguments * **expression**: Expression containing encoded string data. Can be a constant, column, or function, and any combination of string operators. * **format**: Encoding format of the encoded string. Supported formats are: * base64 * hex ##### Related functions [encode](#encode) ## encode Encode binary data into a textual representation. ```sql encode(expression, format) ``` ### Arguments * **expression**: Expression containing string or binary data. Can be a constant, column, or function, and any combination of string operators. * **format**: Encoding format to use. Supported formats are: * base64 * hex ##### Related functions [decode](#decode) [](#view-encode-query-example) View `encode` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, encode(location::string, 'hex') AS location_encoded FROM weather ``` | location | location\_encoded | |-------------|--------------------------| | Concord | 436f6e636f7264 | | Hayward | 48617977617264 | |San Francisco|53616e204672616e636973636f| | location | location_encoded | | --- | --- | | location | location_encoded | | Concord | 436f6e636f7264 | | Hayward | 48617977617264 | | San Francisco | 53616e204672616e636973636f | --- # SQL cache functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/cache/ The InfluxDB 3 Core SQL implementation supports the following functions that return data from InfluxDB 3 Core caches. * [distinct\_cache](#distinct_cache) * [last\_cache](#last_cache) ## distinct\_cache Returns data from an InfluxDB 3 Core distinct value cache. ```sql distinct_cache(table_name, cache_name) ``` ### Arguments * **table\_name**: Name of the table associated with the distinct value cache*(formatted as a string literal)*. * **cache\_name**: Name of the distinct value cache to query*(formatted as a string literal)*. [](#view-distinct_cache-query-example) View `distinct_cache` query example ```sql SELECT * FROM distinct_cache('example_table', 'exampleCacheName') ``` ## last\_cache Returns data from an InfluxDB 3 Core last value cache. ```sql last_cache(table_name, cache_name) ``` ### Arguments * **table\_name**: Name of the table associated with the last value cache*(formatted as a string literal)*. * **cache\_name**: Name of the last value cache to query*(formatted as a string literal)*. [](#view-last_cache-query-example) View `last_cache` query example ```sql SELECT * FROM last_cache('example_table', 'exampleCacheName') ``` --- # SQL conditional functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/conditional/ The InfluxDB 3 Core SQL implementation supports the following conditional functions for conditionally handling *null* values: * [coalesce](#coalesce) * [greatest](#greatest) * [ifnull](#ifnull) * [least](#least) * [nullif](#nullif) * [nvl](#nvl) * [nvl2](#nvl2) ## coalesce Returns the first of its arguments that is not *null*. Returns *null* if all arguments are *null*. This function is often used to substitute a default value for *null* values. ```sql coalesce(expression1[, ..., expression_n]) ``` ##### Arguments * **expression1, expression\_n**: Expression to use if previous expressions are *null*. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. [](#view-coalesce-query-example) View `coalesce` query example ```sql SELECT val1, val2, val3, coalesce(val1, val2, val3, 'quz') AS coalesce FROM (values ('foo', 'bar', 'baz'), (NULL, 'bar', 'baz'), (NULL, NULL, 'baz'), (NULL, NULL, NULL) ) data(val1, val2, val3) ``` |val1|val2|val3|coalesce| |----|----|----|--------| |foo |bar |baz | foo | | |bar |baz | bar | | | |baz | baz | | | | | quz | ## greatest Returns the greatest value in a list of expressions. Returns *null* if all expressions are *null*. ```sql greatest(expression1[, ..., expression_n]) ``` ##### Arguments * **expression1, expression\_n**: Expressions to compare and return the greatest value. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. [](#view-greatest-query-example) View `greatest` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT time, greatest(a, b) AS greatest FROM numbers LIMIT 4 ``` | time | greatest | |-------------------|-------------------| |2023-01-01T01:20:00|\-0.515490223280789| |2023-01-01T01:21:00| 0.803201312042983 | |2023-01-01T01:22:00| 0.970938142399892 | |2023-01-01T01:23:00|0.0493748366311344 | ## ifnull *Alias of [nvl](#nvl).* ## least Returns the least value in a list of expressions. Returns *null* if all expressions are *null*. ```sql least(expression1[, ..., expression_n]) ``` ##### Arguments * **expression1, expression\_n**: Expressions to compare and return the least value. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. [](#view-least-query-example) View `least` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT time, least(a, b) AS least FROM numbers LIMIT 4 ``` | time | least | |-------------------|-------------------| |2023-01-01T00:10:00|\-1.08759833527982 | |2023-01-01T00:11:00|\-0.187620086586211| |2023-01-01T00:12:00|\-0.81371037157091 | |2023-01-01T00:13:00|\-0.339781659874945| ## nullif Returns *null* if *expression1* equals *expression2*; otherwise it returns *expression1*. This can be used to perform the inverse operation of [`coalesce`](#coalesce). ```sql nullif(expression1, expression2) ``` ##### Arguments * **expression1**: Expression to compare and return if equal to expression2. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression2**: Expression to compare to expression1. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-nullif-query-example) View `nullif` query example ```sql SELECT value, nullif(value, 'baz') AS nullif FROM (values ('foo'), ('bar'), ('baz') ) data(value) ``` |value|nullif| |-----|------| | foo | foo | | bar | bar | | baz | | ## nvl Returns *expression2* if *expression1* is *null*; otherwise it returns *expression1*. ```sql nvl(expression1, expression2) ``` ##### Arguments * **expression1**: Return this expression if not *null*. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression2**: Return this expression if *expression1* is *null*. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-nvl-query-example) View `nvl` query example ```sql SELECT value, nvl(value, 'baz') AS nvl FROM (values ('foo'), ('bar'), (NULL) ) data(value) ``` |value|nvl| |-----|---| | foo |foo| | bar |bar| | |baz| ## nvl2 Returns *expression2* if *expression1* is **not** *null*; otherwise it returns *expression3*. ```sql nvl2(expression1, expression2, expression3) ``` ##### Arguments * **expression1**: First expression to test for *null*. Can be a constant, column, or function, and any combination of operators. * **expression2**: Second expression to return if *expression1* is not *null*. Can be a constant, column, or function, and any combination of operators. * **expression3**: Expression to return if *expression1* is *null*. Can be a constant, column, or function, and any combination of operators. [](#view-nvl2-query-example) View `nvl2` query example ```sql SELECT val1, val2, val3, nvl2(val1, val2, val3) AS nvl2 FROM (values ('foo', 'bar', 'baz'), (NULL, 'bar', 'baz'), (NULL, NULL, 'baz'), ) data(val1, val2, val3) ``` |val1|val2|val3|nvl2| |----|----|----|----| |foo |bar |baz |bar | | |bar |baz |baz | | | |baz |baz | | val1 | val2 | val3 | coalesce | | --- | --- | --- | --- | | val1 | val2 | val3 | coalesce | | foo | bar | baz | foo | | | bar | baz | bar | | | | baz | baz | | | | | quz | | time | greatest | | --- | --- | | time | greatest | | 2023-01-01T01:20:00 | -0.515490223280789 | | 2023-01-01T01:21:00 | 0.803201312042983 | | 2023-01-01T01:22:00 | 0.970938142399892 | | 2023-01-01T01:23:00 | 0.0493748366311344 | | time | least | | --- | --- | | time | least | | 2023-01-01T00:10:00 | -1.08759833527982 | | 2023-01-01T00:11:00 | -0.187620086586211 | | 2023-01-01T00:12:00 | -0.81371037157091 | | 2023-01-01T00:13:00 | -0.339781659874945 | | value | nullif | | --- | --- | | value | nullif | | foo | foo | | bar | bar | | baz | | | value | nvl | | --- | --- | | value | nvl | | foo | foo | | bar | bar | | | baz | | val1 | val2 | val3 | nvl2 | | --- | --- | --- | --- | | val1 | val2 | val3 | nvl2 | | foo | bar | baz | bar | | | bar | baz | baz | | | | baz | baz | --- # SQL hashing functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/hashing/ Use hashing functions to hash string values in SQL queries using established hashing algorithms. * [digest](#digest) * [md5](#md5) * [sha224](#sha224) * [sha256](#sha256) * [sha384](#sha384) * [sha512](#sha512) ## digest Computes the binary hash of an expression using the specified algorithm. ```sql digest(expression, algorithm) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. * **algorithm**: String expression specifying algorithm to use. Must be one of the following: * md5 * sha224 * sha256 * sha384 * sha512 * blake2s * blake2b * blake3 [](#view-digest-query-example) View `digest` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, digest(location, 'sha256') AS location_digest FROM weather ``` | location | location\_digest | |-------------|----------------------------------------------------------------| | Concord |21e60acfb20fca2e38c5e51191d44235949de045912dca77e978333c1ec965a2| | Hayward |5d5b651a71084f3117cca3381ff7102efbc318c2026e1d09d5d4707354883102| |San Francisco|5aa34886f7f3741de8460690b636f4c8b7c2044df88e2e8adbb4f7e6f8534931| ## md5 Computes an MD5 128-bit checksum for a string expression. ```sql md5(expression) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-md5-query-example) View `md5` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, md5(location) AS location_md5 FROM weather ``` | location | location\_md5 | |-------------|--------------------------------| | Concord |7c6a8e5769c20331e6a1b93a44021dbc| | Hayward |5823ccc25b256955c4e97cb4a23865ee| |San Francisco|f4334fdfa1c728eae375fe781e2e2d9d| ## sha224 Computes the SHA-224 hash of a binary string. ```sql sha224(expression) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-sha224-query-example) View `sha224` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, sha224(location) AS location_sha224 FROM weather ``` | location | location\_sha224 | |-------------|--------------------------------------------------------| | Concord |3f6c0456de97d3d752672161db8e6f0df115979460a2276d64386114| | Hayward |767cfab6a1562e54f6906c8b5c9ee64583caa3f4b6c37a4298a7639f| |San Francisco|f723898f95bd53cdaf9c057b6f2cf0537b29e0bff077dabb39059b76| ## sha256 Computes the SHA-256 hash of a binary string. ```sql sha256(expression) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-sha256-query-example) View `sha256` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, sha256(location) AS location_sha256 FROM weather ``` | location | location\_sha256 | |-------------|----------------------------------------------------------------| | Concord |21e60acfb20fca2e38c5e51191d44235949de045912dca77e978333c1ec965a2| | Hayward |5d5b651a71084f3117cca3381ff7102efbc318c2026e1d09d5d4707354883102| |San Francisco|5aa34886f7f3741de8460690b636f4c8b7c2044df88e2e8adbb4f7e6f8534931| ## sha384 Computes the SHA-384 hash of a binary string. ```sql sha384(expression) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-sha384-query-example) View `sha384` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, sha384(location) AS location_sha384 FROM weather ``` | location | location\_sha384 | |-------------|------------------------------------------------------------------------------------------------| | Concord |19bf5ba95a6c4a28d2a997fa4e03e542d24b111593395b587a3b357af50cc687364f27b4e96935c234e2ae69236c7883| | Hayward |8b034ee0f7c8d191e145002722bf296a7f310f455458b9ffdbafcb2da2e2300d0f1e7868c6b1d512c81ae0c055979abd| |San Francisco|15c0c4a0e80f198e922235ee30a5c2b1e288c88f61bfc55ef9723903a0e948a7de04b65aa35b4ba46251b90460bab625| ## sha512 Computes the SHA-512 hash of a binary string. ```sql sha512(expression) ``` ### Arguments * **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-sha512-query-example) View `sha512` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT DISTINCT location, sha512(location) AS location_sha512 FROM weather ``` | location | location\_sha512 | |-------------|--------------------------------------------------------------------------------------------------------------------------------| | Concord |227e28fd661eebb39b10f49728d17b03e3a1f0cc2d2a413a9f124292d77249a2c0d7cf99941fd3d2eabea1b2894698bbd12c2cf3a7137ec67fca221ee57e0ca7| | Hayward |2db79fba2fc2888f9826d95ce6bb2605d95b841da61f049e8a92467de0d6ec3161f3919275208a3c385f6412d7848bfc957e81cde550f4f28cd834a332381142| |San Francisco|4c84f24d166978fb59d77779bf9a54ac112cba8e5f826c50440b2d3063fa0cbb0e2ccd30c93261a0f96805f71d15c3e726c9e00426161880e6a5dad267b2d883| | location | location_digest | | --- | --- | | location | location_digest | | Concord | 21e60acfb20fca2e38c5e51191d44235949de045912dca77e978333c1ec965a2 | | Hayward | 5d5b651a71084f3117cca3381ff7102efbc318c2026e1d09d5d4707354883102 | | San Francisco | 5aa34886f7f3741de8460690b636f4c8b7c2044df88e2e8adbb4f7e6f8534931 | | location | location_md5 | | --- | --- | | location | location_md5 | | Concord | 7c6a8e5769c20331e6a1b93a44021dbc | | Hayward | 5823ccc25b256955c4e97cb4a23865ee | | San Francisco | f4334fdfa1c728eae375fe781e2e2d9d | | location | location_sha224 | | --- | --- | | location | location_sha224 | | Concord | 3f6c0456de97d3d752672161db8e6f0df115979460a2276d64386114 | | Hayward | 767cfab6a1562e54f6906c8b5c9ee64583caa3f4b6c37a4298a7639f | | San Francisco | f723898f95bd53cdaf9c057b6f2cf0537b29e0bff077dabb39059b76 | | location | location_sha256 | | --- | --- | | location | location_sha256 | | Concord | 21e60acfb20fca2e38c5e51191d44235949de045912dca77e978333c1ec965a2 | | Hayward | 5d5b651a71084f3117cca3381ff7102efbc318c2026e1d09d5d4707354883102 | | San Francisco | 5aa34886f7f3741de8460690b636f4c8b7c2044df88e2e8adbb4f7e6f8534931 | | location | location_sha384 | | --- | --- | | location | location_sha384 | | Concord | 19bf5ba95a6c4a28d2a997fa4e03e542d24b111593395b587a3b357af50cc687364f27b4e96935c234e2ae69236c7883 | | Hayward | 8b034ee0f7c8d191e145002722bf296a7f310f455458b9ffdbafcb2da2e2300d0f1e7868c6b1d512c81ae0c055979abd | | San Francisco | 15c0c4a0e80f198e922235ee30a5c2b1e288c88f61bfc55ef9723903a0e948a7de04b65aa35b4ba46251b90460bab625 | | location | location_sha512 | | --- | --- | | location | location_sha512 | | Concord | 227e28fd661eebb39b10f49728d17b03e3a1f0cc2d2a413a9f124292d77249a2c0d7cf99941fd3d2eabea1b2894698bbd12c2cf3a7137ec67fca221ee57e0ca7 | | Hayward | 2db79fba2fc2888f9826d95ce6bb2605d95b841da61f049e8a92467de0d6ec3161f3919275208a3c385f6412d7848bfc957e81cde550f4f28cd834a332381142 | | San Francisco | 4c84f24d166978fb59d77779bf9a54ac112cba8e5f826c50440b2d3063fa0cbb0e2ccd30c93261a0f96805f71d15c3e726c9e00426161880e6a5dad267b2d883 | --- # SQL map functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/map/ Use map functions to create and operate on Arrow maps in SQL queries. * [element\_at](#element_at) * [make\_map](#make_map) * [map](#map) * [map\_extract](#map_extract) * [map\_keys](#map_keys) * [map\_values](#map_values) ## element\_at *Alias of [map\_extract](#map_extract).* ## make\_map Returns an Arrow map with the specified key and value. ```sql make_map(key, value) ``` ### Arguments * **key**: Expression to use for the key. Can be a constant, column, function, or any combination of arithmetic or string operators. * **value**: Expression to use for the value. Can be a constant, column, function, or any combination of arithmetic or string operators. [](#view-make_map-query-example) View `make_map` query example *The following example uses the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT make_map(room, temp) AS make_map FROM home LIMIT 4 ``` | make\_map | |-------------------| | {Kitchen: 22.4} | |{Living Room: 22.2}| | {Kitchen: 22.7} | |{Living Room: 22.2}| ## map Returns an Arrow map with the specified key-value pairs. Keys are mapped to values by their positions in each respective list. Each *key* must be unique and non-null. ```sql map(key_list, value_list) -- or map { key: value, ... } ``` ### Arguments * **key\_list**: List of keys to use in the map. Each key must be unique and non-null. * **value\_list**: List of values to map to the corresponding keys. [](#view-map-query-example) View `map` query example ```sql SELECT map( [400, 401, 402, 403, 404], ['Bad Request', 'Unauthorized', 'Payment Required', 'Forbidden', 'Not Found'] ) AS map ``` | map | |--------------------------------------------------------------------------------------------| |{400: Bad Request, 401: Unauthorized, 402: Payment Required, 403: Forbidden, 404: Not Found}| [](#view-map-query-example-with-alternate-syntax) View `map` query example with alternate syntax ```sql SELECT map { 400: 'Bad Request', 401: 'Unauthorized', 402: 'Payment Required', 403: 'Forbidden', 404: 'Not Found' } AS map ``` | map | |--------------------------------------------------------------------------------------------| |{400: Bad Request, 401: Unauthorized, 402: Payment Required, 403: Forbidden, 404: Not Found}| ## map\_extract Returns a list containing the value for the given key or an empty list if the Returns a list containing the value for the given key, or an empty list if the key is not present in the map. The returned list will contain exactly one element (the value) when the key is found. ```sql map_extract(map, key) ``` ### Arguments * **map**: Map expression. Can be a constant, column, or function, and any combination of map operators. * **key**: Key to extract from the map. Can be a constant, column, or function, any combination of arithmetic or string operators, or a named expression of the previously listed. #### Aliases * `element_at` ##### Related functions [get\_field](/influxdb3/core/reference/sql/functions/misc/#get_field) [](#view-map_extract-query-example) View `map_extract` query example The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data)to perform the a query that: * Defines a set of constants that includes a map that assigns integers to days of the week. * Queries the weather sample data and use `date_part` to extract an integer representing the day of the week of the row’s `time` value. * Uses `map_extract` and the output of `date_part` to return an array containing the name of the day of the week. * Uses bracket notation (`[i]`) to reference an element by index in the returned list (SQL arrays are 1-indexed, so `[1]` retrieves the first element). ``` WITH constants AS ( SELECT map( [0, 1, 2, 3, 4, 5, 6], ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] ) AS days_of_week ) SELECT weather.time, map_extract(c.days_of_week, date_part('dow', time))[1] AS day_of_week FROM weather, constants AS c ORDER BY weather.time LIMIT 6 ``` | time |day\_of\_week| |-------------------|-------------| |2020-01-01T00:00:00| Wednesday | |2020-01-01T00:00:00| Wednesday | |2020-01-01T00:00:00| Wednesday | |2020-01-02T00:00:00| Thursday | |2020-01-02T00:00:00| Thursday | |2020-01-02T00:00:00| Thursday | ## map\_keys Returns a list of all keys in the map. ```sql map_keys(map) ``` ### Arguments * **map**: Map expression. Can be a constant, column, or function, and any combination of map operators. ##### Related functions [get\_field](/influxdb3/core/reference/sql/functions/misc/#get_field) [](#view-map_keys-query-example) View `map_keys` query example ```sql SELECT map_keys(map {'a': 1, 'b': NULL, 'c': 3}) AS map_keys ``` |map\_keys| |---------| |[a, b, c]| ## map\_values Returns a list of all values in the map. ```sql map_values(map) ``` ### Arguments * **map**: Map expression. Can be a constant, column, or function, and any combination of map operators. [](#view-map_values-query-example) View `map_values` query example ```sql SELECT map_values(map {'a': 1, 'b': NULL, 'c': 3}) AS map_values ``` |map\_values| |-----------| | [1, , 3] | | make_map | | --- | | make_map | | {Kitchen: 22.4} | | {Living Room: 22.2} | | {Kitchen: 22.7} | | {Living Room: 22.2} | | map | | --- | | map | | {400: Bad Request, 401: Unauthorized, 402: Payment Required, 403: Forbidden, 404: Not Found} | | map | | --- | | map | | {400: Bad Request, 401: Unauthorized, 402: Payment Required, 403: Forbidden, 404: Not Found} | | time | day_of_week | | --- | --- | | time | day_of_week | | 2020-01-01T00:00:00 | Wednesday | | 2020-01-01T00:00:00 | Wednesday | | 2020-01-01T00:00:00 | Wednesday | | 2020-01-02T00:00:00 | Thursday | | 2020-01-02T00:00:00 | Thursday | | 2020-01-02T00:00:00 | Thursday | | map_keys | | --- | | map_keys | | [a, b, c] | | map_values | | --- | | map_values | | [1, , 3] | --- # SQL math functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/math/ The InfluxDB 3 Core SQL implementation supports the following math functions for performing mathematic operations: * [abs](#abs) * [acos](#acos) * [acosh](#acosh) * [asin](#asin) * [asinh](#asinh) * [atan](#atan) * [atanh](#atanh) * [atan2](#atan2) * [cbrt](#cbrt) * [ceil](#ceil) * [cos](#cos) * [cosh](#cosh) * [cot](#cot) * [degrees](#degrees) * [exp](#exp) * [factorial](#factorial) * [floor](#floor) * [gcd](#gcd) * [isnan](#isnan) * [iszero](#iszero) * [lcm](#lcm) * [ln](#ln) * [log](#log) * [log10](#log10) * [log2](#log2) * [nanvl](#nanvl) * [pi](#pi) * [power](#power) * [pow](#pow) * [radians](#radians) * [random](#random) * [round](#round) * [signum](#signum) * [sin](#sin) * [sinh](#sinh) * [sqrt](#sqrt) * [tan](#tan) * [tanh](#tanh) * [trunc](#trunc) ## abs Returns the absolute value of a number. ```sql abs(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-abs-query-example) View `abs` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT abs(temp) AS abs FROM home LIMIT 3 ``` |abs | |----| | 21 | | 23 | |22.7| ## acos Returns the arc cosine or inverse cosine of a number. ```sql acos(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-acos-query-example) View `acos` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT acos(temp * .01) AS acos FROM home LIMIT 3 ``` | acos | |------------------| |1.359221367036801 | |1.3387186439321834| |1.3418001704498232| ## acosh Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. ```sql acosh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-acosh-query-example) View `acosh` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT acosh(temp) AS acosh FROM home LIMIT 3 ``` | acosh | |------------------| |3.737102242198924 | |3.8281684713331012| |3.8150265878962055| ## asin Returns the arc sine or inverse sine of a number. ```sql asin(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-asin-query-example) View `asin` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT asin(temp * .01) AS asin FROM home LIMIT 3 ``` | asin | |-------------------| |0.2115749597580956 | |0.23207768286271319| |0.22899615634507337| ## asinh Returns the area hyperbolic sine or inverse hyperbolic sine of a number. ```sql asinh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-asinh-query-example) View `asinh` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT asinh(temp) AS asinh FROM home LIMIT 3 ``` | asinh | |------------------| |3.7382360302615427| |3.8291136516208812| |3.8159969160459988| ## atan Returns the arc tangent or inverse tangent of a number. ```sql atan(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-atan-query-example) View `atan` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT atan(temp * .01) AS atan FROM home LIMIT 3 ``` | atan | |-------------------| | 0.206992194219821 | |0.22606838799388393| |0.22321725383717603| ## atanh Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. ```sql atanh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-atanh-query-example) View `atanh` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT atanh(temp * .01) AS atanh FROM home LIMIT 3 ``` | atanh | |-------------------| |0.21317134656485978| |0.2341894667593668 | |0.23102419806174476| ## atan2 Returns the arc tangent or inverse tangent of `expression_y / expression_x`. ```sql atan2(expression_y, expression_x) ``` ### Arguments * **expression\_y**: First numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_x**: Second numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-atan2-query-example) View `atan2` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT atan2(temp, hum) AS atan2 FROM home LIMIT 3 ``` | atan2 | |------------------| |0.5292859396993504| |0.5660139100632452| |0.5613335864315844| ## cbrt Returns the cube root of a number. ```sql cbrt(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-cbrt-query-example) View `cbrt` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT cbrt(temp) AS cbrt FROM home LIMIT 3 ``` | cbrt | |------------------| |2.7589241763811208| |2.843866979851566 | |2.831448188528187 | ## ceil Returns the nearest integer greater than or equal to a number. ```sql ceil(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-ceil-query-example) View `ceil` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT ceil(temp) AS ceil FROM home LIMIT 3 ``` |ceil| |----| | 21 | | 23 | | 23 | ## cos Returns the cosine of a number. ```sql cos(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-cos-query-example) View `cos` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT cos(temp) AS cos FROM home LIMIT 3 ``` | cos | |--------------------| |\-0.5477292602242684| |\-0.5328330203333975| |\-0.7591100556583898| ## cosh Returns the hyperbolic cosine of a number. ```sql cosh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-cosh-query-example) View `cosh` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT cosh(temp) AS cosh FROM home LIMIT 3 ``` | cosh | |------------------| |659407867.2416073 | |4872401723.124452 | |3609563974.9715896| ## cot Returns the cotangent of a number. ```sql cot(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. [](#view-cot-query-example) View `cot` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT cot(a) AS cot FROM numbers LIMIT 3 ``` | cot | |-------------------| |2.9293528483724423 | | 3.705570308335524 | |\-3.314652247498361| ## degrees Converts radians to degrees. ```sql degrees(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-degrees-query-example) View `degrees` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT degrees(a) AS degrees FROM numbers LIMIT 3 ``` | degrees | |--------------------| | 19.428488139031185 | |\-44.403317464348774| |\-52.771542485064785| ## exp Returns the base-e exponential of a number. ```sql exp(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to use as the exponent. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-exp-query-example) View `exp` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT exp(temp) AS exp FROM home LIMIT 3 ``` | exp | |------------------| |1318815734.4832146| |9744803446.248903 | |7219127949.943179 | ## factorial Returns 1 if value is less than 2. ```sql factorial(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Must be an integer (`BIGINT`). Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-factorial-query-example) View `factorial` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT factorial((b + 2)::BIGINT) AS factorial FROM numbers LIMIT 3 ``` |factorial| |---------| | 1 | | 2 | | 1 | ## floor Returns the nearest integer less than or equal to a number. ```sql floor(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-floor-query-example) View `floor` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT floor(temp) AS floor FROM home LIMIT 3 ``` |floor| |-----| | 21 | | 23 | | 22 | ## gcd Returns the greatest common divisor of `expression_x` and `expression_y`. Returns `0` if both inputs are zero. ```sql gcd(expression_x, expression_y) ``` ### Arguments * **expression\_x**: First numeric expression to operate on. Must be an integer (`BIGINT`). Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_y**: Second numeric expression to operate on. Must be an integer (`BIGINT`). Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-gcd-query-example) View `gcd` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT gcd((a * 5)::BIGINT, (b * 5)::BIGINT) AS gcd FROM numbers LIMIT 3 ``` |gcd| |---| | 1 | | 3 | | 2 | ## isnan Returns `true` if a given number is ±NaN, otherwise returns `false`. ```sql isnan(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Must be a float (`DOUBLE`). Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-isnan-query-example) View `isnan` query example *The following example uses the[Table value constructor](/influxdb3/core/reference/sql/table-value-constructor/)to simulate sample data.* ```sql SELECT isnan(a) FROM (VALUES (4.56), ('NaN'::DOUBLE), (16.2) ) AS data(a) ``` |isnan| |-----| |false| |true | |false| ## iszero Returns `true` if the given number is ±0.0, otherwise returns `false`. ```sql iszero(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-iszero-query-example) View `iszero` query example *The following example uses the[Table value constructor](/influxdb3/core/reference/sql/table-value-constructor/)to simulate sample data.* ```sql SELECT iszero(a) FROM (VALUES (0), (1), (2) ) AS data(a) ``` |iszero| |------| | true | |false | |false | ## lcm Returns the least common multiple of `expression_x` and `expression_y`. Returns `0` if either input is zero. ```sql lcm(expression_x, expression_y) ``` ### Arguments * **expression\_x**: First numeric expression to operate on. Must be an integer (`BIGINT`). Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_y**: Second numeric expression to operate on. Must be an integer (`BIGINT`). Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-lcm-query-example) View `lcm` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT lcm((a * 10)::BIGINT, (b * 10)::BIGINT) AS lcm FROM numbers LIMIT 3 ``` |lcm| |---| | 3 | | 7 | |36 | ## ln Returns the natural logarithm of a number. ```sql ln(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-ln-query-example) View `ln` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT ln(temp) AS ln FROM home LIMIT 3 ``` | ln | |------------------| |3.044522437723423 | |3.1354942159291497| |3.122364924487357 | ## log Returns the base-x logarithm of a number. ``` log([base, ]numeric_expression) ``` #### Arguments * **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. Default is `10`. * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-log-query-example) View `log` query example *The following example uses the sample data set provided in the {{ influxdb3/home-sample-link }}.* ```sql SELECT temp, log(2, temp) AS temp_log2, log(4, temp) AS temp_log4, log(temp) AS temp_log10 FROM home LIMIT 3 ``` |temp| temp\_log2 | temp\_log4 | temp\_log10 | |----|-----------------|------------------|------------------| | 21 |4.392317422778761|2.1961587113893803|1.322219294733919 | | 23 |4.523561956057013|2.2617809780285065|1.3617278360175928| |22.7|4.504620392403553|2.2523101962017766|1.3560258571931225| ## log10 Returns the base-10 logarithm of a number. ```sql log10(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-log10-query-example) View `log10` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT log10(temp) AS log10 FROM home LIMIT 3 ``` | log10 | |------------------| |1.3222192947339193| |1.3617278360175928| |1.3560258571931227| ## log2 Returns the base-2 logarithm of a number. ```sql log2(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-log2-query-example) View `log2` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT log2(temp) AS log2 FROM home LIMIT 3 ``` | log2 | |-----------------| |4.392317422778761| |4.523561956057013| |4.504620392403552| ## nanvl Returns the first argument if it’s not `±NaN`. Otherwise returns the second argument. ```sql nanvl(expression_x, expression_y) ``` ### Arguments * **expression\_x**: Numeric expression to return if it’s not `NaN`. Can be a constant, column, or function, and any combination of arithmetic operators. * **expression\_y**: Numeric expression to return if the first expression is `NaN`. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-nanvl-query-example) View `nanvl` query example *The following example uses the[Table value constructor](/influxdb3/core/reference/sql/table-value-constructor/)to simulate sample data.* ```sql SELECT nanvl(a, 0.0) AS nanvl FROM (VALUES (4.56), ('NaN'::DOUBLE), (16.2) ) AS data(a) ``` |nanvl| |-----| |4.56 | | 0 | |16.2 | ## pi Returns an approximate value of π. ```sql pi() ``` [](#view-pi-query-example) View `pi` query example ```sql SELECT pi() AS pi ``` | pi | |-----------------| |3.141592653589793| ## power Returns a base expression raised to the power of an exponent. ```sql power(base, exponent) ``` ##### Aliases * `pow` ### Arguments * **base**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **exponent**: Exponent numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-power-query-example) View `power` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT power(temp, hum * .1) AS power FROM home LIMIT 3 ``` | power | |------------------| |55817.099910217476| |85007.01501569824 | |78569.38332452129 | ## `pow` *Alias of [power](#power).* ## radians Converts degrees to radians. ```sql radians(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-radians-query-example) View `radians` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT radians(b) AS radians FROM numbers LIMIT 3 ``` | radians | |----------------------| | \-0.0028561101762876 | |0.0023917008411179744 | |\-0.008428949313343818| ## random Returns a random float value between 0 and 1. The random seed is unique to each row. ```sql random() ``` [](#view-random-query-example) View `random` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT temp * random() AS random FROM home LIMIT 3 ``` > [!Note] > Due to the nature of the function, your results will not match the results below. | random | |------------------| |0.5030770374815072| |12.938847036567514| |2.8204596545385385| ## round Rounds a number to the nearest integer. ```sql round(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-round-query-example) View `round` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT round(temp) AS round FROM home LIMIT 3 ``` |round| |-----| | 21 | | 23 | | 23 | ## signum Returns the sign of a number. Negative numbers return `-1`. Zero and positive numbers return `1`. ```sql signum(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-signum-query-example) View `signum` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT signum(temp - 23) AS signum FROM home LIMIT 3 ``` |signum| |------| | \-1 | | 1 | | \-1 | ## sin Returns the sine of a number. ```sql sin(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-sin-query-example) View `sin` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT sin(temp) AS sin FROM home LIMIT 3 ``` | sin | |--------------------| | 0.8366556385360561 | |\-0.8462204041751706| |\-0.6509623056662469| ## sinh Returns the hyperbolic sine of a number. ```sql sinh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-sinh--query-example) View `sinh `query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT sinh(temp) AS sinh FROM home LIMIT 3 ``` | sinh | |------------------| |659407867.2416073 | |4872401723.124452 | |3609563974.9715896| ## sqrt Returns the square root of a number. ```sql sqrt(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-sqrt-query-example) View `sqrt` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT sqrt(temp) AS sqrt FROM home LIMIT 3 ``` | sqrt | |-----------------| |4.58257569495584 | |4.795831523312719| |4.764451699828638| ## tan Returns the tangent of a number. ```sql tan(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-tan-query-example) View `tan` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT tan(temp) AS tan FROM home LIMIT 3 ``` | tan | |--------------------| |\-1.5274985276366035| | 1.5881530833912738 | | 0.8575335036257101 | ## tanh Returns the hyperbolic tangent of a number. ```sql tanh(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-tanh-query-example) View `tanh` query example *The following example uses the[Random numbers sample dataset](/influxdb3/core/reference/sample-data/#random-numbers-sample-data).* ```sql SELECT tanh(a) AS tanh FROM numbers LIMIT 3 ``` | tanh | |--------------------| |0.32666571332086836 | |\-0.6498182711525403| |\-0.7263877015335474| ## trunc Truncates a number toward zero (at the decimal point). ```sql trunc(numeric_expression) ``` ### Arguments * **numeric\_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-trunc-query-example) View `trunc` query example *The following example uses the {{ influxdb3/home-sample-link }}.* ```sql SELECT trunc(temp) AS trunc FROM home LIMIT 3 ``` |trunc| |-----| | 21 | | 23 | | 22 | | abs | | --- | | abs | | 21 | | 23 | | 22.7 | | acos | | --- | | acos | | 1.359221367036801 | | 1.3387186439321834 | | 1.3418001704498232 | | acosh | | --- | | acosh | | 3.737102242198924 | | 3.8281684713331012 | | 3.8150265878962055 | | asin | | --- | | asin | | 0.2115749597580956 | | 0.23207768286271319 | | 0.22899615634507337 | | asinh | | --- | | asinh | | 3.7382360302615427 | | 3.8291136516208812 | | 3.8159969160459988 | | atan | | --- | | atan | | 0.206992194219821 | | 0.22606838799388393 | | 0.22321725383717603 | | atanh | | --- | | atanh | | 0.21317134656485978 | | 0.2341894667593668 | | 0.23102419806174476 | | atan2 | | --- | | atan2 | | 0.5292859396993504 | | 0.5660139100632452 | | 0.5613335864315844 | | cbrt | | --- | | cbrt | | 2.7589241763811208 | | 2.843866979851566 | | 2.831448188528187 | | ceil | | --- | | ceil | | 21 | | 23 | | 23 | | cos | | --- | | cos | | -0.5477292602242684 | | -0.5328330203333975 | | -0.7591100556583898 | | cosh | | --- | | cosh | | 659407867.2416073 | | 4872401723.124452 | | 3609563974.9715896 | | cot | | --- | | cot | | 2.9293528483724423 | | 3.705570308335524 | | -3.314652247498361 | | degrees | | --- | | degrees | | 19.428488139031185 | | -44.403317464348774 | | -52.771542485064785 | | exp | | --- | | exp | | 1318815734.4832146 | | 9744803446.248903 | | 7219127949.943179 | | factorial | | --- | | factorial | | 1 | | 2 | | 1 | | floor | | --- | | floor | | 21 | | 23 | | 22 | | gcd | | --- | | gcd | | 1 | | 3 | | 2 | | isnan | | --- | | isnan | | false | | true | | false | | iszero | | --- | | iszero | | true | | false | | false | | lcm | | --- | | lcm | | 3 | | 7 | | 36 | | ln | | --- | | ln | | 3.044522437723423 | | 3.1354942159291497 | | 3.122364924487357 | | temp | temp_log2 | temp_log4 | temp_log10 | | --- | --- | --- | --- | | temp | temp_log2 | temp_log4 | temp_log10 | | 21 | 4.392317422778761 | 2.1961587113893803 | 1.322219294733919 | | 23 | 4.523561956057013 | 2.2617809780285065 | 1.3617278360175928 | | 22.7 | 4.504620392403553 | 2.2523101962017766 | 1.3560258571931225 | | log10 | | --- | | log10 | | 1.3222192947339193 | | 1.3617278360175928 | | 1.3560258571931227 | | log2 | | --- | | log2 | | 4.392317422778761 | | 4.523561956057013 | | 4.504620392403552 | | nanvl | | --- | | nanvl | | 4.56 | | 0 | | 16.2 | | pi | | --- | | pi | | 3.141592653589793 | | power | | --- | | power | | 55817.099910217476 | | 85007.01501569824 | | 78569.38332452129 | | radians | | --- | | radians | | -0.0028561101762876 | | 0.0023917008411179744 | | -0.008428949313343818 | | random | | --- | | random | | 0.5030770374815072 | | 12.938847036567514 | | 2.8204596545385385 | | round | | --- | | round | | 21 | | 23 | | 23 | | signum | | --- | | signum | | -1 | | 1 | | -1 | | sin | | --- | | sin | | 0.8366556385360561 | | -0.8462204041751706 | | -0.6509623056662469 | | sinh | | --- | | sinh | | 659407867.2416073 | | 4872401723.124452 | | 3609563974.9715896 | | sqrt | | --- | | sqrt | | 4.58257569495584 | | 4.795831523312719 | | 4.764451699828638 | | tan | | --- | | tan | | -1.5274985276366035 | | 1.5881530833912738 | | 0.8575335036257101 | | tanh | | --- | | tanh | | 0.32666571332086836 | | -0.6498182711525403 | | -0.7263877015335474 | | trunc | | --- | | trunc | | 21 | | 23 | | 22 | --- # Miscellaneous SQL functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/misc/ The InfluxDB 3 Core SQL implementation supports the following miscellaneous functions for performing a variety of operations: * [arrow\_cast](#arrow_cast) * [arrow\_typeof](#arrow_typeof) * [get\_field](#get_field) * [interpolate](#interpolate) * [locf](#locf) * [version](#version) ## arrow\_cast Casts a value to a specific Arrow data type. ```sql arrow_cast(expression, datatype) ``` ### Arguments * **expression**: Expression to cast. Can be a constant, column, or function, and any combination of arithmetic or string operators. * **datatype**: [Arrow data type](/influxdb3/core/reference/sql/data-types/#sql-and-arrow-data-types)to cast to. [](#view-arrow_cast-query-example) View `arrow_cast` query example *The following example uses the sample data set provided in[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT arrow_cast(time, 'Int64') AS time, arrow_cast(temp, 'Utf8') AS temp, arrow_cast(co, 'Float64')AS co FROM home LIMIT 1 ``` | time |temp|co | |-------------------|----|---| |1641024000000000000|21.0| 0 | ## arrow\_typeof Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html)of the expression: ```sql arrow_typeof(expression) ``` ### Arguments * **expression**: Expression to evaluate. Can be a constant, column, or function, and any combination of arithmetic or string operators. [](#view-arrow_typeof-query-example) View `arrow_typeof` query example *The following example uses the sample data set provided in[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT arrow_typeof(time) AS time, arrow_typeof(room) AS room, arrow_typeof(temp) AS temp, arrow_typeof(co) AS co FROM home LIMIT 1 ``` | time | room | temp | co | |---------------------------|-----------------------|-------|-----| |Timestamp(Nanosecond, None)|Dictionary(Int32, Utf8)|Float64|Int64| ## get\_field Returns a field from a map or a struct with the specified key. > [!Note] > Typically, `get_field` is indirectly invoked via field access syntax such as`my_struct['field_name']` which results in the call:`get_field(my_struct, 'field_name')`. ```sql get_field(collection, field) ``` ### Arguments * **collection**: The map or struct to retrieve a field from. * **field**: The name of field the field to retrieve from the map or struct. Must evaluate to a string. [](#view-get_field-example-with-a-struct-column) View `get_field` example with a struct column ```sql SELECT get_field(influxdb_struct, 'version') AS influxdb_version FROM (VALUES (struct('influxdb' AS product, 'v1' AS version)), (struct('influxdb' AS product, 'v2' AS version)), (struct('influxdb' AS product, 'v3' AS version)) ) AS data(influxdb_struct) ``` |influxdb\_version| |-----------------| | v1 | | v2 | | v3 | [](#view-get_field-example-with-a-map-column) View `get_field` example with a map column ```sql SELECT get_field(influxdb_map, 'version') AS influxdb_version FROM (VALUES (map {'product': 'influxdb', 'version': 'v1'}), (map {'product': 'influxdb', 'version': 'v2'}), (map {'product': 'influxdb', 'version': 'v3'}) ) AS data(influxdb_map) ``` |influxdb\_version| |-----------------| | v1 | | v2 | | v3 | ## interpolate Fills null values in a specified aggregated column by interpolating values from existing values. Must be used with [`date_bin_gapfill`](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill). ```sql interpolate(aggregate_expression) ``` ### Arguments * **aggregate\_expression**: Aggregate operation on a specified expression. The operation can use any [aggregate function](/influxdb3/core/reference/sql/functions/aggregate/). The expression can be a constant, column, or function, and any combination of arithmetic operators supported by the aggregate function. ##### Related functions [date\_bin\_gapfill](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill),[locf](#locf) [](#view-interpolate-query-example) View `interpolate` query example *The following example uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as _time, room, interpolate(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY _time, room ``` | \_time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 22 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 22.85 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.25 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.6 | |2022-01-01T10:00:00Z|Living Room| 21.8 | ## locf Fills null values in a specified aggregated column by carrying the last observed value forward. Must be used with [`date_bin_gapfill`](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill). *LOCF is an initialism of “last observation carried forward.”* ```sql locf(aggregate_expression) ``` ### Arguments * **aggregate\_expression**: Aggregate operation on a specified expression. The operation can use any [aggregate function](/influxdb3/core/reference/sql/functions/aggregate/). The expression can be a constant, column, or function, and any combination of arithmetic operators supported by the aggregate function. ##### Related functions [date\_bin\_gapfill](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill),[interpolate](#interpolate) [](#view-locf-query-example) View `locf` query example *The following example uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as _time, room, locf(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY _time, room ``` | \_time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 21 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 23 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.1 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.4 | |2022-01-01T10:00:00Z|Living Room| 21.8 | ## version Returns the version of [DataFusion](https://datafusion.apache.org/) used by the query engine. > [!Note] > The `version()` function returns the DataFusion query engine version, not the > InfluxDB product version. > To identify your InfluxDB version, see [Identify version](/influxdb3/core/admin/identify-version/). ```sql version() ``` [](#view-version-query-example) View `version` query example ```sql SELECT version() ``` | version() | |------------------------------------------| |Apache DataFusion 49.0.2, aarch64 on linux| The output includes the DataFusion version, CPU architecture, and operating system. | time | temp | co | | --- | --- | --- | | time | temp | co | | 1641024000000000000 | 21.0 | 0 | | time | room | temp | co | | --- | --- | --- | --- | | time | room | temp | co | | Timestamp(Nanosecond, None) | Dictionary(Int32, Utf8) | Float64 | Int64 | | influxdb_version | | --- | | influxdb_version | | v1 | | v2 | | v3 | | influxdb_version | | --- | | influxdb_version | | v1 | | v2 | | v3 | | _time | room | AVG(home.temp) | | --- | --- | --- | | _time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 22 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 22.85 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.25 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.6 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | _time | room | AVG(home.temp) | | --- | --- | --- | | _time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 21 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 23 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.1 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.4 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | version() | | --- | | version() | | Apache DataFusion 49.0.2, aarch64 on linux | --- # SQL regular expression functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/regular-expression/ The InfluxDB 3 Core SQL implementation uses the[PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions)regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax)(excluding some features such as look-around and back-references) and supports the following regular expression functions: * [regexp\_count](#regexp_count) * [regexp\_like](#regexp_like) * [regexp\_match](#regexp_match) * [regexp\_replace](#regexp_replace) ## regexp\_count Returns the number of matches that a regular expression has in a string. ```sql regexp_count(str, regexp[, start, flags]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. * **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators. * **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function. * **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: * **i**: (insensitive) Ignore case when matching. * **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. * **s**: (single-line) `.` matches newline (`\n`). * **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. * **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. [](#view-regexp_count-query-example) View `regexp_count` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, regexp_count(room::STRING, '[Ro]', 1, 'i') AS regexp_count FROM home ``` | room |regexp\_count| |-----------|-------------| | Kitchen | 0 | |Living Room| 3 | ## regexp\_like True if a regular expression has at least one match in a string; false otherwise. ```sql regexp_like(str, regexp[, flags]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **regexp**: Regular expression to test against the string expression. Can be a constant, column, or function. * **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: * **i**: (insensitive) Ignore case when matching. * **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. * **s**: (single-line) `.` matches newline (`\n`). * **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. * **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. [](#view-regexp_like-query-example) View `regexp_like` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, regexp_like(room::STRING, 'R', 'i') AS regexp_like FROM home ``` | room |regexp\_like| |-----------|------------| | Kitchen | false | |Living Room| true | ## regexp\_match Returns a list of regular expression matches in a string. ```sql regexp_match(str, regexp, flags) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **regexp**: Regular expression to match against. Can be a constant, column, or function. * **flags**: Regular expression flags that control the behavior of the regular expression. The following flags are supported. * **i**: (insensitive) Ignore case when matching. [](#view-regexp_match-query-example) View `regexp_match` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* > [!Note] > `regexp_match` returns a *list* Arrow type. > Use *bracket notation* to reference a value in the list. > Lists use 1-based indexing. ```sql SELECT DISTINCT room, regexp_match(room::STRING, '.{3}')[1] AS regexp_match FROM home ``` | room |regexp\_match| |-----------|-------------| | Kitchen | Kit | |Living Room| Liv | ## regexp\_replace Replaces substrings in a string that match a regular expression. ```sql regexp_replace(str, regexp, replacement, flags) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **regexp**: Regular expression to match against. Can be a constant, column, or function. * **replacement**: Replacement string expression. Can be a constant, column, or function, and any combination of string operators. * **flags**: Regular expression flags that control the behavior of the regular expression. The following flags are supported. * **g**: (global) Search globally and don’t return after the first match. * **i**: (insensitive) Ignore case when matching. [](#view-regexp_replace-query-example) View `regexp_replace` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, regexp_replace(room::STRING, '\sRoom', '', 'gi') AS regexp_replace FROM home ``` | room |regexp\_replace| |-----------|---------------| | Kitchen | Kitchen | |Living Room| Living | [regular expressions](/influxdb3/core/tags/regular-expressions/)[sql](/influxdb3/core/tags/sql/) | room | regexp_count | | --- | --- | | room | regexp_count | | Kitchen | 0 | | Living Room | 3 | | room | regexp_like | | --- | --- | | room | regexp_like | | Kitchen | false | | Living Room | true | | room | regexp_match | | --- | --- | | room | regexp_match | | Kitchen | Kit | | Living Room | Liv | | room | regexp_replace | | --- | --- | | room | regexp_replace | | Kitchen | Kitchen | | Living Room | Living | --- # SQL selector functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/selector/ SQL selector functions are designed to work with time series data. They behave similarly to aggregate functions in that they take a collection of data and return a single value. However, selectors are unique in that they return a *struct* that contains a **time value** in addition to the computed value. * [How do selector functions work?](#how-do-selector-functions-work) * [Selector functions](#selector-functions) * [selector\_min](#selector_min) * [selector\_max](#selector_max) * [selector\_first](#selector_first) * [selector\_last](#selector_last) ## How do selector functions work? Each selector function returns an [Arrow *struct*](https://arrow.apache.org/docs/format/Columnar.html#struct-layout)(similar to a JSON object) representing a single time and value from the specified column in the each group. What time and value get returned depend on the logic in the selector function. For example, `selector_first` returns the value of specified column in the first row of the group.`selector_max` returns the maximum value of the specified column in the group. ### Selector struct schema The struct returned from a selector function has two properties: * **time**: `time` value in the selected row * **value**: value of the specified column in the selected row ```js {time: 2023-01-01T00:00:00Z, value: 72.1} ``` ### Selector functions in use In your `SELECT` statement, execute a selector function and use bracket notation to reference properties of the [returned struct](#selector-struct-schema) to populate the column value: ```sql SELECT selector_first(temp, time)['time'] AS time, selector_first(temp, time)['value'] AS temp, room FROM home GROUP BY room ``` ## Selector functions * [selector\_min](#selector_min) * [selector\_max](#selector_max) * [selector\_first](#selector_first) * [selector\_last](#selector_last) ### selector\_min Returns the smallest value of a selected column and a timestamp. ```sql selector_min(expression, timestamp) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of string or arithmetic operators. * **timestamp**: Time expression. Can be a constant, column, or function. [](#view-selector_min-query-example) View `selector_min` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT location, selector_min(temp_min, time)['time'] AS time, selector_min(temp_min, time)['value'] AS min_temp FROM weather GROUP BY location ``` | location | time | min\_temp | +—————+———————+———-+ | Concord | 2022-01-02T00:00:00 | 28.0 | | Hayward | 2021-01-26T00:00:00 | 32.0 | | San Francisco | 2022-01-02T00:00:00 | 35.0 | ### selector\_max Returns the largest value of a selected column and a timestamp. ```sql selector_max(expression, timestamp) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of string or arithmetic operators. * **timestamp**: Time expression. Can be a constant, column, or function. [](#view-selector_max-query-example) View `selector_max` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT location, selector_max(temp_max, time)['time'] AS time, selector_max(temp_max, time)['value'] AS max_temp FROM weather GROUP BY location ``` | location | time |max\_temp| |-------------|-------------------|---------| | Concord |2020-09-07T00:00:00| 112.0 | | Hayward |2022-09-06T00:00:00| 107.0 | |San Francisco|2020-09-06T00:00:00| 102.0 | ### selector\_first Returns the first value ordered by time ascending. ```sql selector_first(expression, timestamp) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of string or arithmetic operators. * **timestamp**: Time expression. Can be a constant, column, or function. [](#view-selector_first-query-example) View `selector_first` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT location, selector_first(precip, time)['time'] AS time, selector_first(precip, time)['value'] AS first_precip FROM (SELECT * FROM weather WHERE precip > 0) GROUP BY location ``` | location | time |first\_precip| |-------------|-------------------|-------------| | Concord |2020-01-08T00:00:00| 0.01 | | Hayward |2020-01-09T00:00:00| 0.17 | |San Francisco|2020-01-07T00:00:00| 0.03 | ### selector\_last Returns the last value ordered by time ascending. ```sql selector_last(expression, timestamp) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of string or arithmetic operators. * **timestamp**: Time expression. Can be a constant, column, or function. [](#view-selector_last-query-example) View `selector_last` query example *The following example uses the[NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data).* ```sql SELECT location, selector_last(precip, time)['time'] AS time, selector_last(precip, time)['value'] AS last_precip FROM (SELECT * FROM weather WHERE precip > 0) GROUP BY location ``` | location | time |last\_precip| |-------------|-------------------|------------| | Concord |2022-12-31T00:00:00| 3.04 | | Hayward |2022-12-31T00:00:00| 4.34 | |San Francisco|2022-12-31T00:00:00| 3.67 | #### Related * [Aggregate data with SQL](/influxdb3/core/query-data/sql/aggregate-select/) | location | time | max_temp | | --- | --- | --- | | location | time | max_temp | | Concord | 2020-09-07T00:00:00 | 112.0 | | Hayward | 2022-09-06T00:00:00 | 107.0 | | San Francisco | 2020-09-06T00:00:00 | 102.0 | | location | time | first_precip | | --- | --- | --- | | location | time | first_precip | | Concord | 2020-01-08T00:00:00 | 0.01 | | Hayward | 2020-01-09T00:00:00 | 0.17 | | San Francisco | 2020-01-07T00:00:00 | 0.03 | | location | time | last_precip | | --- | --- | --- | | location | time | last_precip | | Concord | 2022-12-31T00:00:00 | 3.04 | | Hayward | 2022-12-31T00:00:00 | 4.34 | | San Francisco | 2022-12-31T00:00:00 | 3.67 | --- # SQL string functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/string/ The InfluxDB 3 Core SQL implementation supports the following string functions for operating on string values: * [ascii](#ascii) * [bit\_length](#bit_length) * [btrim](#btrim) * [char\_length](#char_length) * [character\_length](#character_length) * [chr](#chr) * [concat](#concat) * [concat\_ws](#concat_ws) * [contains](#contains) * [ends\_with](#ends_with) * [find\_in\_set](#find_in_set) * [initcap](#initcap) * [instr](#instr) * [left](#left) * [length](#length) * [levenshtein](#levenshtein) * [lower](#lower) * [lpad](#lpad) * [ltrim](#ltrim) * [octet\_length](#octet_length) * [overlay](#overlay) * [position](#position) * [repeat](#repeat) * [replace](#replace) * [reverse](#reverse) * [right](#right) * [rpad](#rpad) * [rtrim](#rtrim) * [split\_part](#split_part) * [starts\_with](#starts_with) * [strpos](#strpos) * [substr](#substr) * [substr\_index](#substr_index) * [substring](#substring) * [substring\_index](#substring_index) * [to\_hex](#to_hex) * [translate](#translate) * [trim](#trim) * [upper](#upper) * [uuid](#uuid) ## ascii Returns the ASCII value of the first character in a string. > [!Note] > `ascii` returns a 32-bit integer. > To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb3/core/query-data/sql/cast-types/#cast-to-an-integer). ```sql ascii(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [chr](#chr) [](#view-ascii-query-example) View `ascii` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, ascii(room)::BIGINT AS ascii FROM home ``` | room |ascii| |-----------|-----| | Kitchen | 75 | |Living Room| 76 | ## bit\_length Returns the bit length of a string. > [!Note] > `bit_length` returns a 32-bit integer. > To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb3/core/query-data/sql/cast-types/#cast-to-an-integer). ```sql bit_length(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [length](#length), [octet\_length](#octet_length) [](#view-bit_length-query-example) View `bit_length` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, bit_length(room)::BIGINT AS bit_length FROM home ``` | room |bit\_length| |-----------|-----------| |Living Room| 88 | | Kitchen | 56 | ## btrim Trims the specified trim string from the start and end of a string. If no trim string is provided, all whitespace is removed from the start and end of the input string. ```sql btrim(str[, trim_str]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **trim\_str**: String expression to trim from the beginning and end of the input string. Can be a constant, column, or function, and any combination of arithmetic operators.*Default is whitespace characters*. ##### Related functions [ltrim](#ltrim),[rtrim](#rtrim),[trim](#trim) [](#view-btrim-query-example) View `btrim` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, btrim(room::STRING, ' Room') AS btrim FROM home ``` | room | btrim | |-----------|-------| |Living Room|Living | | Kitchen |Kitchen| ## char\_length *Alias of [length](#length).* ## character\_length *Alias of [length](#length).* ## chr Returns the character with the specified ASCII or Unicode code value. ``` chr(expression) ``` #### Arguments * **expression**: Expression containing the ASCII or Unicode code value to operate on. Can be a constant, column, or function, and any combination of arithmetic or string operators. ##### Related functions [ascii](#ascii) [](#view-chr-query-example) View `chr` query example ```sql SELECT ascii, chr(ascii) AS chr FROM (values (112), (75), (214) ) data(ascii) ``` |ascii|chr| |-----|---| | 112 | p | | 75 | K | | 214 | Ö | ## concat Concatenates multiple strings together. ```sql concat(str[, ..., str_n]) ``` ### Arguments * **str**: String expression to concatenate. Can be a constant, column, or function, and any combination of string operators. * **str\_n**: Subsequent string expression to concatenate. ##### Related functions [concat\_ws](#concat_ws) [](#view-concat-query-example) View `concat` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT concat('At ', time::STRING, ', the ', room, ' was ', temp::STRING, '°C.') AS concat FROM home LIMIT 3 ``` | concat | |-----------------------------------------------| |At 2022-01-01T08:00:00, the Kitchen was 21.0°C.| |At 2022-01-01T09:00:00, the Kitchen was 23.0°C.| |At 2022-01-01T10:00:00, the Kitchen was 22.7°C.| ## concat\_ws Concatenates multiple strings together with a specified separator. ```sql concat_ws(separator, str[, ..., str_n]) ``` ### Arguments * **separator**: Separator to insert between concatenated strings. * **str**: String expression to concatenate. Can be a constant, column, or function, and any combination of string operators. * **str\_n**: Subsequent string expression to concatenate. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [concat](#concat) [](#view-concat_ws-query-example) View `concat_ws` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT concat_ws(' -- ', time::STRING, room, temp::STRING) AS concat_ws FROM home LIMIT 3 ``` | concat\_ws | |--------------------------------------| |2022-01-01T08:00:00 -- Kitchen -- 21.0| |2022-01-01T09:00:00 -- Kitchen -- 23.0| |2022-01-01T10:00:00 -- Kitchen -- 22.7| ## contains Returns true if a string contains a search string (case-sensitive). ```sql contains(str, search_str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. * **search\_str**: The string to search for in *str*. ## ends\_with Tests if a string ends with a substring. ```sql ends_with(str, substr) ``` ### Arguments * **str**: String expression to test. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring to test for. [](#view-ends_with-query-example) View `ends_with` query example ```sql SELECT string, ends_with(string, 'USA') AS ends_with FROM (values ('New York, USA'), ('London, UK'), ('San Francisco, USA') ) data(string) ``` | string |ends\_with| |------------------|----------| | New York, USA | true | | London, UK | false | |San Francisco, USA| true | ## find\_in\_set Returns the position of a string in a comma-delimited list of substrings. Returns 0 if the string is not in the list of substrings. ```sql find_in_set(str, strlist) ``` ### Arguments * **str**: String expression to find in `strlist`. * **strlist**: A string containing a comma-delimited list of substrings. [](#view-find_in_set-query-example) View `find_in_set` query example ```sql SELECT string, find_in_set(string, 'Isaac,John,Sara') AS find_in_set FROM (values ('John'), ('Sarah'), ('Isaac') ) data(string) ``` |string|find\_in\_set| |------|-------------| | John | 2 | |Sarah | 0 | |Isaac | 1 | ## initcap Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters. ```sql initcap(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [lower](#lower),[upper](#upper) [](#view-initcap-query-example) View `initcap` query example ```sql SELECT string, initcap(string) AS initcap FROM (values ('hello world'), ('hello-world'), ('hello_world') ) data(string) ``` | string | initcap | |------------|------------| |hello world |Hello World | |hello-world |Hello-World | |hello\_world|Hello\_World| ## instr Returns the location where a substring first appears in a string (starting at 1). If the substring is not in the string, the function returns 0. ```sql instr(str, substr) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring expression to search for. Can be a constant, column, or function, and any combination of string operators. [](#view-instr-query-example) View `instr` query example ```sql SELECT string, instr(string, 'neighbor') AS instr FROM (values ('good neighbor'), ('bad neighbor'), ('next-door neighbor'), ('friend') ) data(string) ``` | string |instr| |------------------|-----| | good neighbor | 6 | | bad neighbor | 5 | |next-door neighbor| 11 | | friend | 0 | ## left Returns a specified number of characters from the left side of a string. ```sql left(str, n) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **n**: Number of characters to return. ##### Related functions [right](#right) [](#view-left-query-example) View `left` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, left(room::STRING, 3) AS left FROM home ``` | room |left| |-----------|----| | Kitchen |Kit | |Living Room|Liv | ## length Returns the number of characters in a string. > [!Note] > `char_length` returns a 32-bit integer. > To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb3/core/query-data/sql/cast-types/#cast-to-an-integer). ```sql length(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Aliases * char\_length * character\_length ##### Related functions [bit\_length](#bit_length),[octet\_length](#octet_length) [](#view-length-query-example) View `length` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, length(room)::BIGINT AS length FROM home ``` | room |length| |-----------|------| | Kitchen | 7 | |Living Room| 11 | ## levenshtein Returns the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance)between two strings. ```sql levenshtein(str1, str2) ``` ### Arguments * **str1**: First string expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **str2**: Second string expression to operate on. Can be a constant, column, or function, and any combination of string operators. [](#view-levenshtein-query-example) View `levenshtein` query example ```sql SELECT string1, string2, levenshtein(string1, string2) AS levenshtein FROM (values ('kitten', 'sitting'), ('puppy', 'jumping'), ('cow', 'lowing') ) data(string1, string2) ``` |string1|string2|levenshtein| |-------|-------|-----------| |kitten |sitting| 3 | | puppy |jumping| 5 | | cow |lowing | 4 | ## lower Converts a string to lower-case. ```sql lower(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [initcap](#initcap),[upper](#upper) [](#view-lower-query-example) View `lower` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, lower(room::STRING) AS lower FROM home ``` | room | lower | |-----------|-----------| | Kitchen | kitchen | |Living Room|living room| ## lpad Pads the left side of a string with another string to a specified string length. ```sql lpad(str, n[, padding_str]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **n**: String length to pad to. * **padding\_str**: String expression to pad with. Can be a constant, column, or function, and any combination of string operators.*Default is a space.* ##### Related functions [rpad](#rpad) [](#view-lpad-query-example) View `lpad` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, lpad(room::STRING, 14, '-') AS lpad FROM home ``` | room | lpad | |-----------|---------------| | Kitchen |\-------Kitchen| |Living Room|\---Living Room| ## ltrim Removes leading spaces from a string. ```sql ltrim(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [btrim](#btrim),[rtrim](#rtrim),[trim](#trim) [](#view-ltrim-query-example) View `ltrim` query example ```sql SELECT string, ltrim(string) AS ltrim FROM (values (' Leading spaces'), ('Trailing spaces '), (' Leading and trailing spaces ') ) data(string) ``` | string | ltrim | |---------------------------|---------------------------| | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | |Leading and trailing spaces|Leading and trailing spaces| ## octet\_length Returns the length of a string in bytes. > [!Note] > `length` returns a 32-bit integer. > To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb3/core/query-data/sql/cast-types/#cast-to-an-integer). ```sql octet_length(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [bit\_length](#bit_length),[length](#length) [](#view-octet_length-query-example) View `octet_length` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, octet_length(room)::BIGINT AS octet_length FROM home ``` | room |octet\_length| |-----------|-------------| |Living Room| 11 | | Kitchen | 7 | ## overlay Replaces part of a string with another substring using a specified starting position and number of characters to replace. ```sql overlay(str PLACING substr FROM pos [FOR count]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring to use to replace part of the specified string (`str`). Can be a constant, column, or function, and any combination of string operators. * **pos**: Start position of the substring replacement (`substr`). * **count**: Number of characters in the string (`str`) to replace with the substring (`substr`) beginning from the start position (`pos`). If not specified, the function uses the length of the substring. [](#view-overlay-query-example) View `overlay` query example ```sql SELECT string, overlay(string PLACING '****' FROM 1 FOR 12) AS overlay FROM (values ('2223000048410010'), ('2222420000001113'), ('4917484589897107') ) data(string) ``` | string | overlay | |----------------|------------| |2223000048410010|\*\*\*\*0010| |2222420000001113|\*\*\*\*1113| |4917484589897107|\*\*\*\*7107| ## position Returns the position of a substring in a string. ```sql position(substr IN str) ``` ### Arguments * **substr**: Substring expression to search for. Can be a constant, column, or function, and any combination of string operators. * **str**: String expression to search. Can be a constant, column, or function, and any combination of string operators. [](#view-position-query-example) View `position` query example ```sql SELECT string, position('oo' IN string) AS position FROM (values ('cool'), ('scoop'), ('ice cream') ) data(string) ``` | string |position| |---------|--------| | cool | 2 | | scoop | 3 | |ice cream| 0 | ## repeat Returns a string with an input string repeated a specified number of times. ```sql repeat(str, n) ``` ### Arguments * **str**: String expression to repeat. Can be a constant, column, or function, and any combination of string operators. * **n**: Number of times to repeat the input string. [](#view-repeat-query-example) View `repeat` query example ```sql SELECT string, repeat(string, 3) AS repeat FROM (values ('foo '), ('bar '), ('baz ') ) data(string) ``` |string| repeat | |------|-----------| | foo |foo foo foo| | bar |bar bar bar| | baz |baz baz baz| ## replace Replaces all occurrences of a specified substring in a string with a new substring. ```sql replace(str, substr, replacement) ``` ### Arguments * **str**: String expression to repeat. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring expression to replace in the input string. Can be a constant, column, or function, and any combination of string operators. * **replacement**: Replacement substring expression. Can be a constant, column, or function, and any combination of string operators. [](#view-replace-query-example) View `replace` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, replace(room::STRING, ' ', '_') AS replace FROM home ``` | room | replace | |-----------|------------| | Kitchen | Kitchen | |Living Room|Living\_Room| ## reverse Reverses the character order of a string. ```sql reverse(str) ``` ### Arguments * **str**: String expression to repeat. Can be a constant, column, or function, and any combination of string operators. [](#view-reverse-query-example) View `reverse` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, reverse(room::STRING) AS reverse FROM home ``` | room | reverse | |-----------|-----------| | Kitchen | nehctiK | |Living Room|mooR gniviL| ## right Returns a specified number of characters from the right side of a string. ```sql right(str, n) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **n**: Number of characters to return. ##### Related functions [left](#left) [](#view-right-query-example) View `right` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, right(room::STRING, 3) AS right FROM home ``` | room |right| |-----------|-----| |Living Room| oom | | Kitchen | hen | ## rpad Pads the right side of a string with another string to a specified string length. ```sql rpad(str, n[, padding_str]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **n**: String length to pad to. * **padding\_str**: String expression to pad with. Can be a constant, column, or function, and any combination of string operators.*Default is a space.* ##### Related functions [lpad](#lpad) [](#view-rpad-query-example) View `rpad` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, rpad(room::STRING, 14, '-') AS rpad FROM home ``` | room | rpad | |-----------|--------------| | Kitchen |Kitchen-------| |Living Room|Living Room---| ## rtrim Removes trailing spaces from a string. ```sql rtrim(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [btrim](#btrim),[ltrim](#ltrim),[trim](#trim) [](#view-rtrim-query-example) View `rtrim` query example ```sql SELECT string, rtrim(string) AS rtrim FROM (values (' Leading spaces'), ('Trailing spaces '), (' Leading and trailing spaces ') ) data(string) ``` | string | rtrim | |---------------------------|----------------------------| | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | |Leading and trailing spaces| Leading and trailing spaces| ## split\_part Splits a string based on a specified delimiter and returns the substring in the specified position. ```sql split_part(str, delimiter, pos) ``` ### Arguments * **str**: String expression to spit. Can be a constant, column, or function, and any combination of string operators. * **delimiter**: String or character to split on. * **pos**: Position of the part to return. [](#view-split_part-query-example) View `split_part` query example ```sql SELECT url, split_part(url, '.', 1) AS split_part FROM (values ('www.influxdata.com'), ('docs.influxdata.com'), ('community.influxdata.com') ) data(url) ``` | url |split\_part| |------------------------|-----------| | www.influxdata.com | www | | docs.influxdata.com | docs | |community.influxdata.com| community | ## starts\_with Tests if a string starts with a substring. ```sql starts_with(str, substr) ``` ### Arguments * **str**: String expression to test. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring to test for. [](#view-starts_with-query-example) View `starts_with` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, starts_with(room::STRING, 'Kit') AS starts_with FROM home ``` | room |starts\_with| |-----------|------------| | Kitchen | true | |Living Room| false | ## strpos Returns the starting position of a specified substring in a string. Positions begin at 1. If the substring does not exist in the string, the function returns 0. > [!Note] > `strpos` returns a 32-bit integer. > To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb3/core/query-data/sql/cast-types/#cast-to-an-integer). ```sql strpos(str, substr) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **substr**: Substring expression to search for. Can be a constant, column, or function, and any combination of string operators. [](#view-strpos-query-example) View `strpos` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, strpos(room::STRING, 'Room')::BIGINT AS strpos FROM home ``` | room |strpos| |-----------|------| | Kitchen | 0 | |Living Room| 8 | ## substr Extracts a substring of a specified number of characters from a specific starting position in a string. ```sql substr(str, start_pos[, length]) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **start\_pos**: Character position to start the substring at. The first character in the string has a position of 1. * **length**: Number of characters to extract. If not specified, returns the rest of the string after the start position. [](#view-substr-query-example) View `substr` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, substr(room::STRING, 3, 5) AS substr FROM home ``` | room |substr| |-----------|------| |Living Room| ving | | Kitchen |tchen | ## substr\_index Returns the substring that occurs before or after the specified number (`count`) of delimiter (`delimiter`) occurrences in a string (`str`). If the count is positive, the function returns everything to the left of the final delimiter (counting from the left). If the count is negative, the function returns everything to the right of the final delimiter (counting from the right). ```sql substr_index(str, delimiter, count) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **delimiter**: String expression to use to delimit substrings in the string (`str`). Can be a constant, column, or function, and any combination of string operators. * **count**: The Nth occurrence of the delimiter (`delimiter`) to split on. Can be a constant, column, or function, and any combination of arithmetic operators. Supports positive and negative numbers. [](#view-substr_index-query-example) View `substr_index` query example ```sql SELECT url, substr_index(url, '.', 1) AS subdomain, substr_index(url, '.', -1) AS tld FROM (values ('docs.influxdata.com'), ('community.influxdata.com'), ('cloud2.influxdata.com') ) data(url) ``` | url |subdomain|tld| |------------------------|---------|---| | docs.influxdata.com | docs |com| |community.influxdata.com|community|com| | arrow.apache.org | arrow |org| ## substring *Alias of [substr](#substr).* ## substring\_index *Alias of [substr\_index](#substr_index).* ## translate Translates characters in a string to specified translation characters. ```sql translate(str, chars, translation) ``` * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. * **chars**: Characters to translate. * **translation**: Translation characters. Translation characters replace only characters at the same position in the **chars** string. [](#view-translate-query-example) View `translate` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, translate(room::STRING, 'Rom', 'sOn') AS translate FROM home ``` | room | translate | |-----------|-----------| |Living Room|Living sOOn| | Kitchen | Kitchen | ## to\_hex Converts an integer to a hexadecimal string. ```sql to_hex(int) ``` ### Arguments * **int**: Integer expression to convert. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-to_hex-query-example) View `to_hex` query example ```sql SELECT int, to_hex(int) AS to_hex FROM (values (123), (345), (678) ) data(int) ``` |int|to\_hex| |---|-------| |123| 7b | |345| 159 | |678| 2a6 | ## trim Removes leading and trailing spaces from a string. ```sql trim(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [btrim](#btrim),[ltrim](#ltrim),[rtrim](#rtrim) [](#view-trim-query-example) View `trim` query example ```sql SELECT string, trim(string) AS trim FROM (values (' Leading spaces'), ('Trailing spaces '), (' Leading and trailing spaces ') ) data(string) ``` | string | trim | |---------------------------|---------------------------| | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | |Leading and trailing spaces|Leading and trailing spaces| ## upper Converts a string to upper-case. ```sql upper(str) ``` ### Arguments * **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. ##### Related functions [initcap](#initcap),[lower](#lower) [](#view-upper-query-example) View `upper` query example *The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT DISTINCT room, upper(room::STRING) AS upper FROM home ``` | room | upper | |-----------|-----------| |Living Room|LIVING ROOM| | Kitchen | KITCHEN | ## uuid Returns a UUID v4 string value that is unique per row. ```sql uuid() ``` [](#view-uuid-query-example) View `uuid` query example *The following example uses the sample data set provided in the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT room, uuid() AS uuid FROM (SELECT DISTINCT room FROM home) ``` | room | uuid | |-----------|------------------------------------| | Kitchen |f0b41da9-e334-4b7d-b925-a54ca6b082f3| |Living Room|c31be90e-c4ed-4304-b633-47b969ef3ab6| | room | ascii | | --- | --- | | room | ascii | | Kitchen | 75 | | Living Room | 76 | | room | bit_length | | --- | --- | | room | bit_length | | Living Room | 88 | | Kitchen | 56 | | room | btrim | | --- | --- | | room | btrim | | Living Room | Living | | Kitchen | Kitchen | | ascii | chr | | --- | --- | | ascii | chr | | 112 | p | | 75 | K | | 214 | Ö | | concat | | --- | | concat | | At 2022-01-01T08:00:00, the Kitchen was 21.0°C. | | At 2022-01-01T09:00:00, the Kitchen was 23.0°C. | | At 2022-01-01T10:00:00, the Kitchen was 22.7°C. | | concat_ws | | --- | | concat_ws | | 2022-01-01T08:00:00 -- Kitchen -- 21.0 | | 2022-01-01T09:00:00 -- Kitchen -- 23.0 | | 2022-01-01T10:00:00 -- Kitchen -- 22.7 | | string | ends_with | | --- | --- | | string | ends_with | | New York, USA | true | | London, UK | false | | San Francisco, USA | true | | string | find_in_set | | --- | --- | | string | find_in_set | | John | 2 | | Sarah | 0 | | Isaac | 1 | | string | initcap | | --- | --- | | string | initcap | | hello world | Hello World | | hello-world | Hello-World | | hello_world | Hello_World | | string | instr | | --- | --- | | string | instr | | good neighbor | 6 | | bad neighbor | 5 | | next-door neighbor | 11 | | friend | 0 | | room | left | | --- | --- | | room | left | | Kitchen | Kit | | Living Room | Liv | | room | length | | --- | --- | | room | length | | Kitchen | 7 | | Living Room | 11 | | string1 | string2 | levenshtein | | --- | --- | --- | | string1 | string2 | levenshtein | | kitten | sitting | 3 | | puppy | jumping | 5 | | cow | lowing | 4 | | room | lower | | --- | --- | | room | lower | | Kitchen | kitchen | | Living Room | living room | | room | lpad | | --- | --- | | room | lpad | | Kitchen | -------Kitchen | | Living Room | ---Living Room | | string | ltrim | | --- | --- | | string | ltrim | | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | | Leading and trailing spaces | Leading and trailing spaces | | room | octet_length | | --- | --- | | room | octet_length | | Living Room | 11 | | Kitchen | 7 | | string | overlay | | --- | --- | | string | overlay | | 2223000048410010 | ****0010 | | 2222420000001113 | ****1113 | | 4917484589897107 | ****7107 | | string | position | | --- | --- | | string | position | | cool | 2 | | scoop | 3 | | ice cream | 0 | | string | repeat | | --- | --- | | string | repeat | | foo | foo foo foo | | bar | bar bar bar | | baz | baz baz baz | | room | replace | | --- | --- | | room | replace | | Kitchen | Kitchen | | Living Room | Living_Room | | room | reverse | | --- | --- | | room | reverse | | Kitchen | nehctiK | | Living Room | mooR gniviL | | room | right | | --- | --- | | room | right | | Living Room | oom | | Kitchen | hen | | room | rpad | | --- | --- | | room | rpad | | Kitchen | Kitchen------- | | Living Room | Living Room--- | | string | rtrim | | --- | --- | | string | rtrim | | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | | Leading and trailing spaces | Leading and trailing spaces | | url | split_part | | --- | --- | | url | split_part | | www.influxdata.com | www | | docs.influxdata.com | docs | | community.influxdata.com | community | | room | starts_with | | --- | --- | | room | starts_with | | Kitchen | true | | Living Room | false | | room | strpos | | --- | --- | | room | strpos | | Kitchen | 0 | | Living Room | 8 | | room | substr | | --- | --- | | room | substr | | Living Room | ving | | Kitchen | tchen | | url | subdomain | tld | | --- | --- | --- | | url | subdomain | tld | | docs.influxdata.com | docs | com | | community.influxdata.com | community | com | | arrow.apache.org | arrow | org | | room | translate | | --- | --- | | room | translate | | Living Room | Living sOOn | | Kitchen | Kitchen | | int | to_hex | | --- | --- | | int | to_hex | | 123 | 7b | | 345 | 159 | | 678 | 2a6 | | string | trim | | --- | --- | | string | trim | | Leading spaces | Leading spaces | | Trailing spaces | Trailing spaces | | Leading and trailing spaces | Leading and trailing spaces | | room | upper | | --- | --- | | room | upper | | Living Room | LIVING ROOM | | Kitchen | KITCHEN | | room | uuid | | --- | --- | | room | uuid | | Kitchen | f0b41da9-e334-4b7d-b925-a54ca6b082f3 | | Living Room | c31be90e-c4ed-4304-b633-47b969ef3ab6 | --- # SQL struct functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/struct/ Use struct functions to create Arrow structs in SQL queries. * [named\_struct](#named_struct) * [row](#row) * [struct](#struct) ## named\_struct Returns an *Arrow struct* using the specified name and input expressions pairs. ```sql named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input]) ``` ### Arguments * **expression\_n\_name**: Name of the column field. Must be a constant string. * **expression\_n\_input**: Expression to include in the output struct. Can be a constant, column, or function, and any combination of arithmetic or string operators. ##### Related functions [get\_field](/influxdb3/core/reference/sql/functions/misc/#get_field) [](#view-named_struct-query-example) View `named_struct` query example *The following example uses the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT named_struct('time', time, 'temperature', temp, 'humidity', hum) AS named_struct FROM home WHERE room = 'Kitchen' LIMIT 4 ``` | named\_struct | |--------------------------------------------------------------| |{time: 2022-01-01T13:00:00, temperature: 22.8, humidity: 36.5}| |{time: 2022-01-01T12:00:00, temperature: 22.5, humidity: 36.0}| |{time: 2022-01-01T15:00:00, temperature: 22.7, humidity: 36.2}| |{time: 2022-01-01T18:00:00, temperature: 23.3, humidity: 36.9}| ## row *Alias of [`struct`](#struct).* ## struct Returns an *Arrow struct* using the specified input expressions optionally named. Fields in the returned struct use the optional name or the `cN` naming convention. Fields in the returned struct use the `cN` naming convention (for example: `c0`, `c1`, `c2`, etc.) unless you specify custom names using the `AS` operator within individual expressions. ```sql struct(expression1[, ..., expression_n]) ``` ### Arguments * **expression1, expression\_n**: Expression to include in the output struct. Can be a constant, column, or function, and any combination of arithmetic or string operators. ### Aliases * row ##### Related functions [get\_field](/influxdb3/core/reference/sql/functions/misc/#get_field) [](#view-struct-query-example) View `struct` query example *The following example uses the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT struct(time, temp, hum) AS struct FROM home WHERE room = 'Kitchen' LIMIT 4 ``` | struct | |---------------------------------------------| |{c0: 2022-01-01T13:00:00, c1: 22.8, c2: 36.5}| |{c0: 2022-01-01T12:00:00, c1: 22.5, c2: 36.0}| |{c0: 2022-01-01T15:00:00, c1: 22.7, c2: 36.2}| |{c0: 2022-01-01T18:00:00, c1: 23.3, c2: 36.9}| [](#view-struct-query-example-with-named-fields) View `struct` query example with named fields Use the `AS` operator in a `struct` expression argument to assign a name to the struct field. *The following example uses the[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data).* ```sql SELECT struct(time AS 'time', temp AS 'temperature', hum) AS struct FROM home WHERE room = 'Kitchen' LIMIT 4 ``` | struct | |--------------------------------------------------------| |{time: 2022-01-01T13:00:00, temperature: 22.8, c2: 36.5}| |{time: 2022-01-01T12:00:00, temperature: 22.5, c2: 36.0}| |{time: 2022-01-01T15:00:00, temperature: 22.7, c2: 36.2}| |{time: 2022-01-01T18:00:00, temperature: 23.3, c2: 36.9}| | named_struct | | --- | | named_struct | | {time: 2022-01-01T13:00:00, temperature: 22.8, humidity: 36.5} | | {time: 2022-01-01T12:00:00, temperature: 22.5, humidity: 36.0} | | {time: 2022-01-01T15:00:00, temperature: 22.7, humidity: 36.2} | | {time: 2022-01-01T18:00:00, temperature: 23.3, humidity: 36.9} | | struct | | --- | | struct | | {c0: 2022-01-01T13:00:00, c1: 22.8, c2: 36.5} | | {c0: 2022-01-01T12:00:00, c1: 22.5, c2: 36.0} | | {c0: 2022-01-01T15:00:00, c1: 22.7, c2: 36.2} | | {c0: 2022-01-01T18:00:00, c1: 23.3, c2: 36.9} | | struct | | --- | | struct | | {time: 2022-01-01T13:00:00, temperature: 22.8, c2: 36.5} | | {time: 2022-01-01T12:00:00, temperature: 22.5, c2: 36.0} | | {time: 2022-01-01T15:00:00, temperature: 22.7, c2: 36.2} | | {time: 2022-01-01T18:00:00, temperature: 23.3, c2: 36.9} | --- # SQL time and date functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/time-and-date/ The InfluxDB 3 Core SQL implementation supports time and date functions that are useful when working with time series data. * [current\_date](#current_date) * [current\_time](#current_time) * [current\_timestamp](#current_timestamp) * [date\_bin](#date_bin) * [date\_bin\_gapfill](#date_bin_gapfill) * [date\_bin\_wallclock](#date_bin_wallclock) * [date\_bin\_wallclock\_gapfill](#date_bin_wallclock_gapfill) * [date\_trunc](#date_trunc) * [datetrunc](#datetrunc) * [date\_format](#date_format) * [date\_part](#date_part) * [datepart](#datepart) * [extract](#extract) * [from\_unixtime](#from_unixtime) * [make\_date](#make_date) * [now](#now) * [today](#today) * [to\_char](#to_char) * [to\_date](#to_date) * [to\_local\_time](#to_local_time) * [to\_timestamp](#to_timestamp) * [to\_timestamp\_micros](#to_timestamp_micros) * [to\_timestamp\_millis](#to_timestamp_millis) * [to\_timestamp\_nanos](#to_timestamp_nanos) * [to\_timestamp\_seconds](#to_timestamp_seconds) * [to\_unixtime](#to_unixtime) * [tz](#tz) ## current\_date Returns the current UTC date. > [!Note] > `current_date` returns a `DATE32` Arrow type, which isn’t supported by InfluxDB. > To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb3/core/query-data/sql/cast-types/). The `current_date()` return value is determined at query time and returns the same date, no matter when in the query plan the function executes. ``` current_date() ``` [](#view-current_date-query-example) View `current_date` query example *The following example uses the sample data set provided in[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT time, temp, current_date()::TIMESTAMP AS current_date FROM home WHERE time > current_date()::TIMESTAMP - INTERVAL '5 years' LIMIT 3 ``` | time |temp| current\_date | |--------------------|----|--------------------| |2022-01-01T08:00:00Z| 21 |2026-08-26T00:00:00Z| |2022-01-01T09:00:00Z| 23 |2026-08-26T00:00:00Z| |2022-01-01T10:00:00Z|22.7|2026-08-26T00:00:00Z| ## current\_time Returns the current UTC time. The `current_time()` return value is determined at query time and returns the same time, no matter when in the query plan the function executes. ``` current_time() ``` [](#view-current_time-query-example) View `current_time` query example *The following example uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT time, temp, current_time() AS current_time FROM home LIMIT 3 ``` | time |temp| current\_time | |--------------------|----|--------------------| |2022-01-01T08:00:00Z| 21 |2021-01-01T00:00:00Z| |2022-01-01T09:00:00Z| 23 |2021-01-01T00:00:00Z| |2022-01-01T10:00:00Z|22.7|2021-01-01T00:00:00Z| ## current\_timestamp *Alias of [now](#now).* ## date\_bin Calculates time intervals and returns the start of the interval nearest to the specified timestamp. Use `date_bin` to downsample time series data by grouping rows into time-based “bins” or “windows” and applying an aggregate or selector function to each window. For example, if you “bin” or “window” data into 15-minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15-minute bin it is in: `2023-01-01T18:15:00Z`. ```sql date_bin(interval, expression[, origin_timestamp]) ``` ### Arguments * **interval**: Bin interval. Supports the following interval units: * nanoseconds * microseconds * milliseconds * seconds * minutes * hours * days * weeks * months * years * century * **expression**: Time expression to operate on. Can be a constant, column, or function. * **origin\_timestamp**: Starting point used to determine bin boundaries.*Default is the Unix epoch.* [](#view-date_bin-query-example) View `date_bin` query example The following query returns the daily average of water levels in the queried time range. ```sql SELECT date_bin(INTERVAL '1 day', time, TIMESTAMP '1970-01-01 00:00:00Z') AS time, avg("water_level") AS water_level_avg FROM "h2o_feet" WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-20T00:00:00Z' GROUP BY 1 ORDER BY time DESC ``` | time |water\_level\_avg | |------------------------|------------------| |2019-09-17T00:00:00.000Z|4.370175687443861 | |2019-09-16T00:00:00.000Z|4.6034785848437485| |2019-09-15T00:00:00.000Z|4.680651501506248 | |2019-09-14T00:00:00.000Z|4.857683652395836 | |2019-09-13T00:00:00.000Z|4.911051520291668 | |2019-09-12T00:00:00.000Z|4.763990784533338 | |2019-09-11T00:00:00.000Z|4.6582452515041695| |2019-09-10T00:00:00.000Z|4.608425018785421 | ## date\_bin\_gapfill Calculates time intervals and returns the start of the interval nearest to the specified timestamp. If no rows exist in a time interval, a new row is inserted with a `time` value set to the interval start time, all columns in the `GROUP BY` clause populated, and null values in aggregate columns. Use `date_bin_gapfill` with [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate)or [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf) to[fill gaps in data](/influxdb3/core/query-data/sql/fill-gaps/)at specified time intervals. ```sql date_bin_gapfill(interval, expression[, origin_timestamp]) ``` > [!Note] > `date_bin_gapfill` requires [time bounds](/influxdb3/core/query-data/sql/basic-query/#query-data-within-time-boundaries)in the `WHERE` clause. ### Arguments * **interval**: Bin interval. Supports the following interval units: * nanoseconds * microseconds * milliseconds * seconds * minutes * hours * days * weeks The following intervals are not currently supported: * months * years * century * **expression**: Time expression to operate on. Can be a constant, column, or function. * **origin\_timestamp**: Starting point used to determine bin boundaries.*Default is the Unix epoch.* ##### Related functions [interpolate](/influxdb3/core/reference/sql/functions/misc/#interpolate),[locf](/influxdb3/core/reference/sql/functions/misc/#locf) [](#use-date_bin_gapfill-to-insert-rows-when-no-rows-exists) Use `date_bin_gapfill` to insert rows when no rows exists *The following example uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as _time, room, avg(temp) as temp FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY _time, room ``` | \_time | room |temp| |--------------------|-----------|----| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | | |2022-01-01T10:00:00Z| Kitchen |22.7| |2022-01-01T08:00:00Z|Living Room|21.1| |2022-01-01T08:30:00Z|Living Room| | |2022-01-01T09:00:00Z|Living Room|21.4| |2022-01-01T09:30:00Z|Living Room| | |2022-01-01T10:00:00Z|Living Room|21.8| [](#use-date_bin_gapfill-to-fill-gaps-in-data) Use `date_bin_gapfill` to fill gaps in data Use `interpolate` and `locf` to fill the null values in rows inserted by`date_bin_gapfill`. *The following examples use the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* #### interpolate #### The example below uses [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate)to fill null values by interpolating values between non-null values. ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as _time, room, interpolate(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY _time, room ``` | \_time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 22 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 22.85 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.25 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.6 | |2022-01-01T10:00:00Z|Living Room| 21.8 | The example below uses [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf)to fill null values by carrying the last observed value forward. ```sql SELECT date_bin_gapfill(INTERVAL '30 minutes', time) as _time, room, locf(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY _time, room ``` | \_time | room |AVG(home.temp)| |--------------------|-----------|--------------| |2022-01-01T08:00:00Z| Kitchen | 21 | |2022-01-01T08:30:00Z| Kitchen | 21 | |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T09:30:00Z| Kitchen | 23 | |2022-01-01T10:00:00Z| Kitchen | 22.7 | |2022-01-01T08:00:00Z|Living Room| 21.1 | |2022-01-01T08:30:00Z|Living Room| 21.1 | |2022-01-01T09:00:00Z|Living Room| 21.4 | |2022-01-01T09:30:00Z|Living Room| 21.4 | |2022-01-01T10:00:00Z|Living Room| 21.8 | ## date\_bin\_wallclock Calculates time intervals using the timezone of a specified time value and returns the start of the interval nearest to the specified timestamp. Use `date_bin_wallclock` to downsample time series data by grouping rows into time-based “bins” or “windows” that are based off “wall clock” times in a specific timezone and applying an aggregate or selector function to each window. ### Time zone shifts Many regions use time zone shifts (such as daylight saving time (DST)). If a wall clock time bin starts at a time that does not exist in the specified time zone, the timestamp is adjusted to the time that is the same offset from the start of the day in that time zone. If a wall clock time represents an ambiguous time in the region then the behavior depends on the size of the specified interval. If the interval is larger than the difference between the two possible timestamps, then the earlier timestamp is used. Otherwise, the function uses the timestamp that matches the UTC offset of the input timestamp. ```sql date_bin_wallclock(interval, expression[, origin_timestamp]) ``` ### Arguments * **interval**: Bin interval. Supports the following interval units: * nanoseconds * microseconds * milliseconds * seconds * minutes * hours * days * weeks > [!Note] > `date_bin_wallclock` does *not* support month-, year-, or century-based intervals. * **expression**: Time expression to operate on. Can be a constant, column, or function. The output timestamp uses the time zone from this time expression. * **origin\_timestamp**: Starting point used to determine bin boundaries. This must be a “wall clock” timestamp (no time zone).*Default is the Unix epoch.* #### Avoid bins in time zone discontinuities #### [Time zone shifts](#time-zone-shifts) result in *discontinuities*–breaks in the continuity of time intervals (losing an hour or gaining an hour)–that can result in unexpected timestamps when using `date_bin_wallclock`. Avoid using an `interval` and `origin_timestamp` combination that results in a bin falling inside a time discontinuity. As a general rule, use either the default `origin_timestamp` or an origin timestamp with an offset relative to the Unix epoch that is equal to your specified `interval`. [](#view-time-zone-discontinuity-example) View time zone discontinuity example The following query illustrates how two timestamps, only one minute apart, result in timestamps two hours apart when binned across a daylight saving boundary: ``` SELECT tz('2020-10-25T02:29:00+01:00', 'Europe/Paris') AS original_time, date_bin_wallclock( INTERVAL '1 hour', tz('2020-10-25T02:29:00+01:00', 'Europe/Paris'), '1970-01-01T00:30:00' ) AT TIME ZONE 'UTC' AS utc_bin_time UNION SELECT tz('2020-10-25T02:30:00+01:00', 'Europe/Paris') AS original_time, date_bin_wallclock( INTERVAL '1 hour', tz('2020-10-25T02:30:00+01:00', 'Europe/Paris'), '1970-01-01T00:30:00' ) AT TIME ZONE 'UTC' AS utc_bin_time ORDER BY original_time; ``` | original\_time | utc\_bin\_time | |-------------------------|--------------------| |2020-10-25T02:29:00+01:00|2020-10-24T23:30:00Z| |2020-10-25T02:30:00+01:00|2020-10-25T01:30:00Z| [](#view-date_bin_wallclock-query-example) View `date_bin_wallclock` query example The following query uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol)and returns the 12-hour average temperature for each room using times in the`America/Los_Angeles` time zone. ```sql SELECT date_bin_wallclock(INTERVAL '12 hours', tz(time, 'America/Los_Angeles')) AS time, room, avg(temp) AS avg_temp FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' GROUP BY 1, room ``` | time | room | avg\_temp | |-------------------------|-----------|------------------| |2022-01-01T00:00:00-08:00| Kitchen |22.61666666666667 | |2022-01-01T12:00:00-08:00| Kitchen | 22.7 | |2022-01-01T00:00:00-08:00|Living Room|22.166666666666668| |2022-01-01T12:00:00-08:00|Living Room| 22.2 | ## date\_bin\_wallclock\_gapfill Calculates time intervals using the timezone of a specified time value and returns the start of the interval nearest to the specified timestamp. If no rows exist in a time interval, a new row is inserted with a `time` value set to the interval start time, all columns in the `GROUP BY` clause populated, and null values in aggregate columns. Use `date_bin_wallclock_gapfill` with [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate)or [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf) to[fill gaps in data](/influxdb3/core/query-data/sql/fill-gaps/)at specified time intervals in a specified time zone. ### Time zone shifts Many regions use time zone shifts (such as daylight saving time (DST)). If a wall clock time bin starts at a time that does not exist in the specified time zone, the timestamp is adjusted to the time that is the same offset from the start of the day in that time zone. If a wall clock time represents an ambiguous time in the region then the behavior depends on the size of the specified interval. If the interval is larger than the difference between the two possible timestamps, then the earlier timestamp is used. Otherwise, the function uses the timestamp that matches the UTC offset of the input timestamp. ```sql date_bin_wallclock_gapfill(interval, expression[, origin_timestamp]) ``` > [!Note] > `date_bin_wallclock_gapfill` requires [time bounds](/influxdb3/core/query-data/sql/basic-query/#query-data-within-time-boundaries)in the `WHERE` clause. ### Arguments * **interval**: Bin interval. Supports the following interval units: * nanoseconds * microseconds * milliseconds * seconds * minutes * hours * days * weeks > [!Note] > `date_bin_wallclock_gapfill` does *not* support month-, year-, or century-based intervals. * **expression**: Time expression to operate on. Can be a constant, column, or function. The output timestamp uses the time zone from this time expression. * **origin\_timestamp**: Starting point used to determine bin boundaries. This must be a “wall clock” timestamp (no time zone).*Default is the Unix epoch.* #### Avoid bins in time zone discontinuities #### [Time zone shifts](#time-zone-shifts) result in *discontinuities*–breaks in the continuity of time intervals (losing an hour or gaining an hour)–that can result in unexpected timestamps when using `date_bin_wallclock_gapfill`. Avoid using an `interval` and `origin_timestamp` combination that results in a bin falling inside a time discontinuity. As a general rule, use either the default `origin_timestamp` or an origin timestamp with an offset relative to the Unix epoch that is equal to your specified `interval`. [View time zone discontinuity example](#view-time-zone-discontinuity-example) ##### Related functions [interpolate](/influxdb3/core/reference/sql/functions/misc/#interpolate),[locf](/influxdb3/core/reference/sql/functions/misc/#locf) [](#use-date_bin_wallclock_gapfill-to-insert-rows-when-no-rows-exists) Use `date_bin_wallclock_gapfill` to insert rows when no rows exists *The following example uses the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ```sql SELECT date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, room, avg(temp) as temp FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` | time | room |temp| |-------------------------|-----------|----| |2022-01-01T00:00:00-08:00| Kitchen | 21 | |2022-01-01T00:30:00-08:00| Kitchen | | |2022-01-01T01:00:00-08:00| Kitchen | 23 | |2022-01-01T01:30:00-08:00| Kitchen | | |2022-01-01T02:00:00-08:00| Kitchen |22.7| |2022-01-01T00:00:00-08:00|Living Room|21.1| |2022-01-01T00:30:00-08:00|Living Room| | |2022-01-01T01:00:00-08:00|Living Room|21.4| |2022-01-01T01:30:00-08:00|Living Room| | |2022-01-01T02:00:00-08:00|Living Room|21.8| [](#use-date_bin_wallclock_gapfill-to-fill-gaps-in-data) Use `date_bin_wallclock_gapfill` to fill gaps in data Use `interpolate` and `locf` to fill the null values in rows inserted by`date_bin_wallclock_gapfill`. *The following examples use the sample data set provided in the[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* #### interpolate #### The example below uses [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate)to fill null values by interpolating values between non-null values. ```sql SELECT date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, room, interpolate(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` | time | room |interpolate(avg(home.temp))| |-------------------------|-----------|---------------------------| |2022-01-01T00:00:00-08:00| Kitchen | 21 | |2022-01-01T00:30:00-08:00| Kitchen | 22 | |2022-01-01T01:00:00-08:00| Kitchen | 23 | |2022-01-01T01:30:00-08:00| Kitchen | 22.85 | |2022-01-01T02:00:00-08:00| Kitchen | 22.7 | |2022-01-01T00:00:00-08:00|Living Room| 21.1 | |2022-01-01T00:30:00-08:00|Living Room| 21.25 | |2022-01-01T01:00:00-08:00|Living Room| 21.4 | |2022-01-01T01:30:00-08:00|Living Room| 21.6 | |2022-01-01T02:00:00-08:00|Living Room| 21.8 | The example below uses [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf)to fill null values by carrying the last observed value forward. ```sql SELECT date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, room, locf(avg(temp)) FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' GROUP BY 1, room ``` | time | room |locf(avg(home.temp))| |-------------------------|-----------|--------------------| |2022-01-01T00:00:00-08:00| Kitchen | 21 | |2022-01-01T00:30:00-08:00| Kitchen | 21 | |2022-01-01T01:00:00-08:00| Kitchen | 23 | |2022-01-01T01:30:00-08:00| Kitchen | 23 | |2022-01-01T02:00:00-08:00| Kitchen | 22.7 | |2022-01-01T00:00:00-08:00|Living Room| 21.1 | |2022-01-01T00:30:00-08:00|Living Room| 21.1 | |2022-01-01T01:00:00-08:00|Living Room| 21.4 | |2022-01-01T01:30:00-08:00|Living Room| 21.4 | |2022-01-01T02:00:00-08:00|Living Room| 21.8 | ## date\_trunc Truncates a timestamp value to a specified precision. ```sql date_trunc(precision, expression) ``` ### Arguments * **precision**: Time precision to truncate to. The following precisions are supported: * year * month * week * day * hour * minute * second * **expression**: Time expression to operate on. Can be a constant, column, or function. ##### Aliases * `datetrunc` [](#view-date_trunc-query-examples) View `date_trunc` query examples #### Use date\_trunc to return hourly averages ```sql SELECT avg(water_level) AS level, date_trunc('hour', time) AS hour FROM h2o_feet WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-12T00:00:00Z' GROUP BY hour ORDER BY hour ``` | hour | level | |------------------------|------------------| |2019-09-10T00:00:00.000Z|3.7248000000000006| |2019-09-10T01:00:00.000Z|3.8561499999999995| |2019-09-10T02:00:00.000Z|4.5405999999999995| |2019-09-10T03:00:00.000Z|5.5548072072500005| |2019-09-10T04:00:00.000Z|6.433900000000001 | |2019-09-10T05:00:00.000Z|6.810949999999998 | #### Use date\_trunc to return weekly averages ```sql SELECT mean(water_level) as level, date_trunc('week',time) AS week FROM h2o_feet WHERE time >= timestamp '2019-08-01T00:00:00Z' AND time <= timestamp '2019-10-31T00:00:00Z' GROUP BY week ORDER BY week ``` | level | week | |------------------|------------------------| |4.3314415259020835|2019-08-12T00:00:00.000Z| |4.234838403584523 |2019-08-19T00:00:00.000Z| |4.4184818559633925|2019-08-26T00:00:00.000Z| |4.405153386766021 |2019-09-02T00:00:00.000Z| |4.725866897257734 |2019-09-09T00:00:00.000Z| |4.499938596774042 |2019-09-16T00:00:00.000Z| ## datetrunc *Alias of [date\_trunc](#date_trunc).* ## date\_format *Alias of [to\_char](#to_char).* ## date\_part Returns the specified part of the date as an integer. ```sql date_part(part, expression) ``` ### Arguments * **part**: Part of the date to return. The following date parts are supported: * year * month * week *(week of the year)* * day *(day of the month)* * hour * minute * second * millisecond * microsecond * nanosecond * dow *(day of the week)* * doy *(day of the year)* * **expression**: Time expression to operate on. Can be a constant, column, or function. ##### Aliases * `datepart` [](#view-date_part-query-examples) View `date_part` query examples ``` SELECT date_part('hour', time) AS hour, time, "level description", location FROM h2o_feet WHERE time >= timestamp '2019-08-17T02:54:00Z' AND time <= timestamp '2019-08-17T03:06:00Z' ORDER BY time ``` |hour| time | level description | location | |----|--------------------|--------------------|-------------| | 2 |2019-08-17T02:54:00Z|between 3 and 6 feet|coyote\_creek| | 2 |2019-08-17T02:54:00Z|between 3 and 6 feet|santa\_monica| | 3 |2019-08-17T03:00:00Z|between 3 and 6 feet|coyote\_creek| | 3 |2019-08-17T03:00:00Z|between 3 and 6 feet|santa\_monica| | 3 |2019-08-17T03:06:00Z|between 3 and 6 feet|coyote\_creek| | 3 |2019-08-17T03:06:00Z|between 3 and 6 feet|santa\_monica| ## datepart *Alias of [date\_part](#date_part).* ## extract Returns a sub-field from a time value as an integer. Similar to `date_part`, but with different arguments. ```sql extract(field FROM source) ``` ### Arguments * **field**: Part or field of the date to return. The following date fields are supported: * year * month * week *(week of the year)* * day *(day of the month)* * hour * minute * second * millisecond * microsecond * nanosecond * dow *(day of the week)* * doy *(day of the year)* * **source**: Source time expression to operate on. Can be a constant, column, or function. [](#view-extract-query-example) View `extract` query example ``` SELECT extract(day from time) AS day FROM h2o_feet LIMIT 1 ``` |day| |---| |25 | ## from\_unixtime Converts an integer (Unix timestamp in seconds) to a timestamp value. The underlying result is a timestamp (`Timestamp(TimeUnit::Second, None)`). If you output query results as JSON (default for the API), CSV, or pretty (default for the CLI), the timestamp is formatted as an ISO 8601 string (`YYYY-MM-DDTHH:MM:SS`, without a timezone indicator). When output to Parquet, the raw integer value (for example, `1641042000`) is preserved. ```sql from_unixtime(expression) ``` ### Arguments * **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Related functions [to\_unixtime](#to_unixtime) [](#view-from_unixtime-query-example) View `from_unixtime` query example ```sql SELECT from_unixtime(1672531200000000000) AS RFC3339 ``` | RFC3339 | |--------------------| |2023-01-01T00:00:00Z| ## make\_date Returns a date using the component parts (year, month, day). > [!Note] > `make_date` returns a `DATE32` Arrow type, which isn’t supported by InfluxDB. > To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb3/core/query-data/sql/cast-types/). ```sql make_date(year, month, day) ``` ### Arguments * **year**: Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators. * **month**: Month to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators. * **day**: Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators [](#view-make_date-query-example) View `make_date` query example ```sql SELECT make_date(2024, 01, 01)::STRING AS date ``` | date | |----------| |2023-01-01| ## now Returns the current UTC timestamp. The `now()` return value is determined at query time and returns the same timestamp, no matter when in the query plan the function executes. ```sql now() ``` ##### Aliases * [current\_timestamp](#current_timestamp) [](#view-now-query-example) View `now` query example ```sql SELECT "water_level", "time" FROM h2o_feet WHERE time <= now() - interval '12 minutes' ``` ## today *Alias of [current\_date](#current_date).* ## to\_char Returns the string representation of a date, time, timestamp, or duration based on a [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). > [!Note] > Unlike the PostgreSQL `TO_CHAR()` function, this function does not support > numeric formatting. ```sql to_char(expression, format) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration. * **format**: [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)to use to convert the expression. ##### Aliases * [date\_format](#date_format) [](#view-to_char-query-example) View `to_char` query example ```sql SELECT to_char('2024-01-01T12:22:01Z'::TIMESTAMP, '%a %e-%b-%Y %H:%M:%S') AS datestring ``` | datestring | |-----------------------| |Mon 1-Jan-2024 12:22:01| ## to\_date Converts a value to a date (`YYYY-MM-DD`). Supports strings and numeric types as input. Strings are parsed as `YYYY-MM-DD` unless another format is specified. Numeric values are interpreted as days since the[Unix epoch](/influxdb3/core/reference/glossary/#unix-epoch). > [!Note] > `to_date` returns a `DATE32` Arrow type, which isn’t supported by InfluxDB. > To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb3/core/query-data/sql/cast-types/). ```sql to_date(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. [](#view-to_date-query-example) View `to_date` query example ```sql SELECT to_date('1-Jan-2024', '%e-%b-%Y')::STRING AS date ``` | date | |----------| |2024-01-01| ## to\_local\_time Converts a timestamp with a timezone to a timestamp without a timezone (no offset or timezone information). This function accounts for time shifts like daylight saving time (DST). > [!Note] > Use `to_local_time()` with [`date_bin()`](#date_bin) and[`date_bin_gapfill`](#date_bin_gapfill) to generate window boundaries based the > local time zone rather than UTC. ```sql to_local_time(expression) ``` ### Arguments * **expression**: Time expression to operate on. Can be a constant, column, or function. [](#view-to_local_time-query-example) View `to_local_time` query example ```sql SELECT to_local_time('2024-01-01 00:00:00'::TIMESTAMP) AS "local time"; ``` | local time | |--------------------| |2024-01-01T00:00:00Z| [](#view-to_local_time-query-example-with-a-time-zone-offset) View `to_local_time` query example with a time zone offset ```sql SELECT to_local_time((arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))')) AT TIME ZONE 'America/Los_Angeles') AS "local time" ``` | local time | |--------------------| |2023-12-31T16:00:00Z| [](#view-to_local_time-query-example-with-date_bin) View `to_local_time` query example with `date_bin` ```sql SELECT date_bin(interval '1 day', time, to_local_time(0::TIMESTAMP)) AT TIME ZONE 'America/Los_Angeles' AS time, avg(f1), avg(f2) FROM (VALUES (arrow_cast('2024-01-01 12:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 1.23, 4.56), (arrow_cast('2024-01-01 13:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 2.46, 8.1), (arrow_cast('2024-01-01 14:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 4.81, 16.2) ) AS data(time, f1, f2) GROUP BY 1 ``` | time | avg(data.f1) |avg(data.f2)| |-------------------------|------------------|------------| |2023-12-31T16:00:00-08:00|2.8333333333333335| 9.62 | ## to\_timestamp Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as[Unix nanosecond timestamps](/influxdb3/core/reference/glossary/#unix-timestamp)and return the corresponding RFC3339 timestamp. ```sql to_timestamp(expression) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. [](#view-to_timestamp-query-example) View `to_timestamp` query example ```sql SELECT to_timestamp(1704067200000000000) ``` |to\_timestamp(Int64(1704067200000000000))| |-----------------------------------------| | 2024-01-01T00:00:00Z | ## to\_timestamp\_micros Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as[Unix microsecond timestamps](/influxdb3/core/reference/glossary/#unix-timestamp)and return the corresponding RFC3339 timestamp. ```sql to_timestamp_micros(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. [](#view-to_timestamp_micros-query-example) View `to_timestamp_micros` query example ```sql SELECT to_timestamp_micros(1704067200000001) ``` |to\_timestamp\_micros(Int64(1704067200000001))| |----------------------------------------------| | 2024-01-01T00:00:00.000001Z | [](#view-to_timestamp_micros-example-with-string-format-parsing) View `to_timestamp_micros` example with string format parsing ```sql SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond ``` | microsecond | |---------------------------| |2024-01-01T01:01:59.123456Z| ## to\_timestamp\_millis Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as[Unix millisecond timestamps](/influxdb3/core/reference/glossary/#unix-timestamp)and return the corresponding RFC3339 timestamp. ```sql to_timestamp_millis(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. [](#view-to_timestamp_millis-query-example) View `to_timestamp_millis` query example ```sql SELECT to_timestamp_millis(1704067200001) AS time ``` Results |to\_timestamp\_millis(Int64(1704067200001))| |-------------------------------------------| | 2024-01-01T00:00:00.001Z | [](#view-to_timestamp_millis-example-with-string-format-parsing) View `to_timestamp_millis` example with string format parsing ```sql SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond ``` | millisecond | |------------------------| |2024-01-01T01:01:59.123Z| ## to\_timestamp\_nanos Converts a value to RFC3339 nanosecond timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as[Unix nanosecond timestamps](/influxdb3/core/reference/glossary/#unix-timestamp)and return the corresponding RFC3339 timestamp. ```sql to_timestamp_nanos(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. [](#view-to_timestamp_nanos-query-example) View `to_timestamp_nanos` query example ```sql SELECT to_timestamp_nanos(1704067200000000001) ``` |to\_timestamp\_nanos(Int64(1704067200000000001))| |------------------------------------------------| | 2024-01-01T00:00:00.000000001Z | [](#view-to_timestamp_nanos-example-with-string-format-parsing) View `to_timestamp_nanos` example with string format parsing ```sql SELECT to_timestamp_nanos('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS nanosecond ``` | nanosecond | |------------------------------| |2024-01-01T01:01:59.123456789Z| ## to\_timestamp\_seconds Converts a value to RFC3339 second timestamp format (`YYYY-MM-DDT00:00:00Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as[Unix second timestamps](/influxdb3/core/reference/glossary/#unix-timestamp)and return the corresponding RFC3339 timestamp. ```sql to_timestamp_seconds(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. [](#view-to_timestamp_seconds-query-example) View `to_timestamp_seconds` query example ```sql SELECT to_timestamp_seconds(1704067201) ``` |to\_timestamp\_seconds(Int64(1704067201))| |-----------------------------------------| | 2024-01-01T00:00:01Z | [](#view-to_timestamp_seconds-example-with-string-format-parsing) View `to_timestamp_seconds` example with string format parsing ```sql SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS second ``` | second | |--------------------| |2024-01-01T01:01:59Z| ## to\_unixtime Converts a value to seconds since the [Unix epoch](/influxdb3/core/reference/glossary/#unix-epoch). Supports strings, timestamps, and floats as input. Strings are parsed as [RFC3339Nano timestamps](/influxdb3/core/reference/glossary/#rfc3339nano-timestamp) if no[Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)are provided. ```sql to_unixtime(expression[, ..., format_n]) ``` ### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **format\_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)pattern to use to parse the *string* expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. ##### Related functions [from\_unixtime](#from_unixtime) [](#view-to_unixtime-query-example) View `to_unixtime` query example ```sql SELECT to_unixtime('2024-01-01T01:01:59.123456789Z') AS unixtime ``` | unixtime | |----------| |1704070919| [](#view-to_unixtime-example-with-string-format-parsing) View `to_unixtime` example with string format parsing ```sql SELECT to_unixtime('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS unixtime ``` | unixtime | |----------| |1704070919| ## tz Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC. ```sql tz(time_expression[, timezone]) ``` ### Arguments * **time\_expression**: time to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. * **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)to cast the value into. Default is `'UTC'`. The function returns the timestamp cast to the specified timezone. If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error. [](#view-tz-query-example) View `tz` query example ```sql SELECT tz('2024-01-01T01:00:00Z', 'America/New_York') AS time_tz ``` | time\_tz | |-------------------------| |2024-10-01T02:00:00-04:00| [](#view-tz-query-example-from-getting-started-data) View `tz` query example from Getting Started data ```sql SELECT tz(time, 'Australia/Sydney') AS time_tz, time FROM home ORDER BY time LIMIT 3; ``` | time\_tz | time | |-----------------------------------|------------------------------| |1970-01-01T10:00:01.728979200+10:00|1970-01-01T00:00:01.728979200Z| |1970-01-01T10:00:01.728979200+10:00|1970-01-01T00:00:01.728979200Z| |1970-01-01T10:00:01.728982800+10:00|1970-01-01T00:00:01.728982800Z| ##### Differences between tz and AT TIME ZONE `tz` and [`AT TIME ZONE`](/influxdb3/core/reference/sql/operators/other/#at-time-zone)differ when the input timestamp **does not** have a timezone. * When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the`AT TIME ZONE` operator, the operator returns the same timestamp, but with a timezone offset (also known as the “wall clock” time)–for example: ``` '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' -- Returns 2024-01-01T00:00:00-08:00 ``` * When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE`operator return the timestamp converted to the time in the specified timezone–for example: ``` '2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles' tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles') -- Both return 2023-12-31T16:00:00-08:00 ``` * `tz()` always converts the input timestamp to the specified time zone. If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp–for example: ``` tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles') -- Returns 2023-12-31T16:00:00-08:00 ``` ``` tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles') -- Returns 2023-12-31T15:00:00-08:00 ``` [](#view-tz-and-timestamp-comparison) View `tz` and `::timestamp` comparison ```sql SELECT '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp, tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz; ``` | time\_timestamp | time\_tz | |-------------------------|-------------------------| |2024-04-01T00:00:20+02:00|2024-04-01T02:00:20+02:00| | time | temp | current_date | | --- | --- | --- | | time | temp | current_date | | 2022-01-01T08:00:00Z | 21 | 2026-08-26T00:00:00Z | | 2022-01-01T09:00:00Z | 23 | 2026-08-26T00:00:00Z | | 2022-01-01T10:00:00Z | 22.7 | 2026-08-26T00:00:00Z | | time | temp | current_time | | --- | --- | --- | | time | temp | current_time | | 2022-01-01T08:00:00Z | 21 | 2021-01-01T00:00:00Z | | 2022-01-01T09:00:00Z | 23 | 2021-01-01T00:00:00Z | | 2022-01-01T10:00:00Z | 22.7 | 2021-01-01T00:00:00Z | | time | water_level_avg | | --- | --- | | time | water_level_avg | | 2019-09-17T00:00:00.000Z | 4.370175687443861 | | 2019-09-16T00:00:00.000Z | 4.6034785848437485 | | 2019-09-15T00:00:00.000Z | 4.680651501506248 | | 2019-09-14T00:00:00.000Z | 4.857683652395836 | | 2019-09-13T00:00:00.000Z | 4.911051520291668 | | 2019-09-12T00:00:00.000Z | 4.763990784533338 | | 2019-09-11T00:00:00.000Z | 4.6582452515041695 | | 2019-09-10T00:00:00.000Z | 4.608425018785421 | | _time | room | temp | | --- | --- | --- | | _time | room | temp | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | _time | room | AVG(home.temp) | | --- | --- | --- | | _time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 22 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 22.85 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.25 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.6 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | _time | room | AVG(home.temp) | | --- | --- | --- | | _time | room | AVG(home.temp) | | 2022-01-01T08:00:00Z | Kitchen | 21 | | 2022-01-01T08:30:00Z | Kitchen | 21 | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T09:30:00Z | Kitchen | 23 | | 2022-01-01T10:00:00Z | Kitchen | 22.7 | | 2022-01-01T08:00:00Z | Living Room | 21.1 | | 2022-01-01T08:30:00Z | Living Room | 21.1 | | 2022-01-01T09:00:00Z | Living Room | 21.4 | | 2022-01-01T09:30:00Z | Living Room | 21.4 | | 2022-01-01T10:00:00Z | Living Room | 21.8 | | original_time | utc_bin_time | | --- | --- | | original_time | utc_bin_time | | 2020-10-25T02:29:00+01:00 | 2020-10-24T23:30:00Z | | 2020-10-25T02:30:00+01:00 | 2020-10-25T01:30:00Z | | time | room | avg_temp | | --- | --- | --- | | time | room | avg_temp | | 2022-01-01T00:00:00-08:00 | Kitchen | 22.61666666666667 | | 2022-01-01T12:00:00-08:00 | Kitchen | 22.7 | | 2022-01-01T00:00:00-08:00 | Living Room | 22.166666666666668 | | 2022-01-01T12:00:00-08:00 | Living Room | 22.2 | | time | room | temp | | --- | --- | --- | | time | room | temp | | 2022-01-01T00:00:00-08:00 | Kitchen | 21 | | 2022-01-01T00:30:00-08:00 | Kitchen | | | 2022-01-01T01:00:00-08:00 | Kitchen | 23 | | 2022-01-01T01:30:00-08:00 | Kitchen | | | 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | | 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | | 2022-01-01T00:30:00-08:00 | Living Room | | | 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | | 2022-01-01T01:30:00-08:00 | Living Room | | | 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | | time | room | interpolate(avg(home.temp)) | | --- | --- | --- | | time | room | interpolate(avg(home.temp)) | | 2022-01-01T00:00:00-08:00 | Kitchen | 21 | | 2022-01-01T00:30:00-08:00 | Kitchen | 22 | | 2022-01-01T01:00:00-08:00 | Kitchen | 23 | | 2022-01-01T01:30:00-08:00 | Kitchen | 22.85 | | 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | | 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | | 2022-01-01T00:30:00-08:00 | Living Room | 21.25 | | 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | | 2022-01-01T01:30:00-08:00 | Living Room | 21.6 | | 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | | time | room | locf(avg(home.temp)) | | --- | --- | --- | | time | room | locf(avg(home.temp)) | | 2022-01-01T00:00:00-08:00 | Kitchen | 21 | | 2022-01-01T00:30:00-08:00 | Kitchen | 21 | | 2022-01-01T01:00:00-08:00 | Kitchen | 23 | | 2022-01-01T01:30:00-08:00 | Kitchen | 23 | | 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | | 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | | 2022-01-01T00:30:00-08:00 | Living Room | 21.1 | | 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | | 2022-01-01T01:30:00-08:00 | Living Room | 21.4 | | 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | | hour | level | | --- | --- | | hour | level | | 2019-09-10T00:00:00.000Z | 3.7248000000000006 | | 2019-09-10T01:00:00.000Z | 3.8561499999999995 | | 2019-09-10T02:00:00.000Z | 4.5405999999999995 | | 2019-09-10T03:00:00.000Z | 5.5548072072500005 | | 2019-09-10T04:00:00.000Z | 6.433900000000001 | | 2019-09-10T05:00:00.000Z | 6.810949999999998 | | level | week | | --- | --- | | level | week | | 4.3314415259020835 | 2019-08-12T00:00:00.000Z | | 4.234838403584523 | 2019-08-19T00:00:00.000Z | | 4.4184818559633925 | 2019-08-26T00:00:00.000Z | | 4.405153386766021 | 2019-09-02T00:00:00.000Z | | 4.725866897257734 | 2019-09-09T00:00:00.000Z | | 4.499938596774042 | 2019-09-16T00:00:00.000Z | | hour | time | level description | location | | --- | --- | --- | --- | | hour | time | level description | location | | 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | coyote_creek | | 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | santa_monica | | 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | coyote_creek | | 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | santa_monica | | 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | coyote_creek | | 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | santa_monica | | day | | --- | | day | | 25 | | RFC3339 | | --- | | RFC3339 | | 2023-01-01T00:00:00Z | | date | | --- | | date | | 2023-01-01 | | datestring | | --- | | datestring | | Mon 1-Jan-2024 12:22:01 | | date | | --- | | date | | 2024-01-01 | | local time | | --- | | local time | | 2024-01-01T00:00:00Z | | local time | | --- | | local time | | 2023-12-31T16:00:00Z | | time | avg(data.f1) | avg(data.f2) | | --- | --- | --- | | time | avg(data.f1) | avg(data.f2) | | 2023-12-31T16:00:00-08:00 | 2.8333333333333335 | 9.62 | | to_timestamp(Int64(1704067200000000000)) | | --- | | to_timestamp(Int64(1704067200000000000)) | | 2024-01-01T00:00:00Z | | to_timestamp_micros(Int64(1704067200000001)) | | --- | | to_timestamp_micros(Int64(1704067200000001)) | | 2024-01-01T00:00:00.000001Z | | microsecond | | --- | | microsecond | | 2024-01-01T01:01:59.123456Z | | to_timestamp_millis(Int64(1704067200001)) | | --- | | to_timestamp_millis(Int64(1704067200001)) | | 2024-01-01T00:00:00.001Z | | millisecond | | --- | | millisecond | | 2024-01-01T01:01:59.123Z | | to_timestamp_nanos(Int64(1704067200000000001)) | | --- | | to_timestamp_nanos(Int64(1704067200000000001)) | | 2024-01-01T00:00:00.000000001Z | | nanosecond | | --- | | nanosecond | | 2024-01-01T01:01:59.123456789Z | | to_timestamp_seconds(Int64(1704067201)) | | --- | | to_timestamp_seconds(Int64(1704067201)) | | 2024-01-01T00:00:01Z | | second | | --- | | second | | 2024-01-01T01:01:59Z | | unixtime | | --- | | unixtime | | 1704070919 | | unixtime | | --- | | unixtime | | 1704070919 | | time_tz | | --- | | time_tz | | 2024-10-01T02:00:00-04:00 | | time_tz | time | | --- | --- | | time_tz | time | | 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | | 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | | 1970-01-01T10:00:01.728982800+10:00 | 1970-01-01T00:00:01.728982800Z | | time_timestamp | time_tz | | --- | --- | | time_timestamp | time_tz | | 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 | --- # SQL window functions Source: https://docs.influxdata.com/influxdb3/core/reference/sql/functions/window/ Window functions let you calculate running totals, moving averages, or other aggregate-like results without collapsing rows into groups. They perform their calculations over a “window” of rows, which you can partition and order in various ways, and return a calculated value for each row in the set. Unlike non-window [aggregate functions](/influxdb3/core/reference/sql/functions/aggregate/) that combine each group into a single row, window functions preserve each row’s identity and calculate an additional value for every row in the partition. For example, the following query uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data)and returns each temperature reading with the average temperature per room over the queried time range: ```sql SELECT time, room, temp, avg(temp) OVER (PARTITION BY room) AS avg_room_temp FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T09:00:00Z' ORDER BY room, time ``` | time | room |temp|avg\_room\_temp| |-------------------|-----------|----|---------------| |2022-01-01T08:00:00| Kitchen |21.0| 22.0 | |2022-01-01T09:00:00| Kitchen |23.0| 22.0 | |2022-01-01T08:00:00|Living Room|21.1| 21.25 | |2022-01-01T09:00:00|Living Room|21.4| 21.25 | * [Window frames](#window-frames) * [OVER clause](#over-clause) * [PARTITION BY clause](#partition-by-clause) * [ORDER BY clause](#order-by-clause) * [Frame clause](#frame-clause) * [Frame units](#frame-units) * [Frame boundaries](#frame-boundaries) * [WINDOW clause](#window-clause) * [Aggregate functions](#aggregate-functions) * [Ranking Functions](#ranking-functions) * [cume\_dist](#cume_dist) * [dense\_rank](#dense_rank) * [ntile](#ntile) * [percent\_rank](#percent_rank) * [rank](#rank) * [row\_number](#row_number) * [Analytical Functions](#analytical-functions) * [first\_value](#first_value) * [lag](#lag) * [last\_value](#last_value) * [lead](#lead) * [nth\_value](#nth_value) ## Window frames As window functions operate on a row, there is a set of rows in the row’s partition that the window function uses to perform the operation. This set of rows is called the *window frame*. Window frame boundaries can be defined using`RANGE`, `ROW`, or `GROUPS` frame units, each relative to the current row–for example: #### RANGE #### ```sql SELECT time, temp, avg(temp) OVER ( ORDER BY time RANGE INTERVAL '3 hours' PRECEDING ) AS 3h_moving_avg FROM home WHERE room = 'Kitchen' ``` ```sql SELECT time, temp, avg(temp) OVER ( ROWS 3 PRECEDING ) AS moving_avg FROM home WHERE room = 'Kitchen' ``` ```sql SELECT time, room, temp, avg(temp) OVER ( ORDER BY room GROUPS 1 PRECEDING ) AS moving_avg FROM home ``` *For more information about how window frames work, see the [frame clause](#frame-clause).* If you don’t specify window frames, window functions use all rows in the current partition to perform their operation. ```sql function([expr]) OVER( [PARTITION BY expr[, …]] [ORDER BY expr [ ASC | DESC ][, …]] [ frame_clause ] ) ``` ### OVER clause Window functions use an `OVER` clause that directly follows the window function’s name and arguments. The `OVER` clause syntactically distinguishes a window function from a non-window or aggregate function and defines how to group and order rows for the window operation. ### PARTITION BY clause The `PARTITION BY` clause in the `OVER` clause divides the rows into groups, or partitions, that share the same values of the `PARTITION BY` expressions. The window function operates on all the rows in the same partition as the current row. ### ORDER BY clause The `ORDER BY` clause inside of the `OVER` clause controls the order that the window function processes rows in each partition. When a window clause contains an `ORDER BY` clause, the window frame boundaries may be explicit or implicit, limiting a window frame size in both directions relative to the current row. > [!Note] > The `ORDER BY` clause in an `OVER` clause determines the processing order for > rows in each partition and is separate from the `ORDER BY`clause of the query. ### Frame clause The *frame clause* defines window frame boundaries and can be one of the following: ```sql { RANGE | ROWS | GROUPS } frame_start { RANGE | ROWS | GROUPS } BETWEEN frame_start AND frame_end ``` * [Frame units](#frame-units) * [RANGE](#range) * [ROWS](#rows) * [GROUPS](#groups) * [Frame boundaries](#frame-boundaries) * [UNBOUNDED PRECEDING](#unbounded-preceding) * [offset PRECEDING](#offset-preceding) * [CURRENT ROW](#current-row) * [offset FOLLOWING](#offset-following) * [UNBOUNDED FOLLOWING](#unbounded-following) #### Frame units When defining window frames, you can use one of the following frame units: * [RANGE](#range) * [ROWS](#rows) * [GROUPS](#groups) ##### RANGE Defines frame boundaries using rows with values for columns specified in the [`ORDER BY` clause](#order-by-clause) within a value range relative to the current row value. > [!Important] > When using `RANGE` frame units, you must include an `ORDER BY` clause with*exactly one column*. The offset is the difference between the current row value and surrounding row values. `RANGE` supports the following offset types: * Numeric *(non-negative)* * Numeric string *(non-negative)* * Interval [](#see-how-range-frame-units-work-with-numeric-offsets) See how `RANGE` frame units work with numeric offsets To use a numeric offset with the `RANGE` frame unit, you must sort partitions by a numeric-type column. ```sql ... OVER ( ORDER BY wind_direction RANGE BETWEEN 45 PRECEDING AND 45 FOLLOWING ) ``` The window frame includes rows with sort column values between 45 below and 45 above the current row’s value: | time |city|wind\_direction| |-------------------|----|---------------| |2025-02-17T13:00:00|Rome| 33 | |2025-02-17T08:00:00|Rome| 34 | |2025-02-17T23:00:00|Rome| 49 | |2025-02-17T17:00:00|Rome| 86 | |2025-02-17T11:00:00|Rome| 93 | |2025-02-17T12:00:00|Rome| 115 | |2025-02-17T10:00:00|Rome| 156 | [](#see-how-range-frame-units-work-with-interval-offsets) See how `RANGE` frame units work with interval offsets To use an interval offset with the `RANGE` frame unit, you must sort partitions by `time` or a timestamp-type column. ```sql ... OVER ( ORDER BY time RANGE BETWEEN INTERVAL '3 hours' PRECEDING AND INTERVAL '1 hour' FOLLOWING ) ``` The window frame includes rows with timestamps between three hours before and one hour after the current row’s timestamp: | time | room |temp| |-------------------|-------|----| |2022-01-01T08:00:00|Kitchen|21.0| |2022-01-01T09:00:00|Kitchen|23.0| |2022-01-01T10:00:00|Kitchen|22.7| |2022-01-01T11:00:00|Kitchen|22.4| |2022-01-01T12:00:00|Kitchen|22.5| |2022-01-01T13:00:00|Kitchen|22.8| |2022-01-01T14:00:00|Kitchen|22.8| |2022-01-01T15:00:00|Kitchen|22.7| ##### ROWS Defines window frame boundaries using row positions relative to the current row. The offset is the difference in row position from the current row.`ROWS` supports the following offset types: * Numeric *(non-negative)* * Numeric string *(non-negative)* [](#see-how-rows-frame-units-work) See how `ROWS` frame units work When using the `ROWS` frame unit, row positions relative to the current row determine frame boundaries–for example: ```sql ... OVER ( ROWS BETWEEN 2 PRECEDING AND 1 FOLLOWING ) ``` The window frame includes the two rows before and the one row after the current row: | time |city|wind\_direction| |-------------------|----|---------------| |2025-02-17T08:00:00|Rome| 34 | |2025-02-17T10:00:00|Rome| 156 | |2025-02-17T11:00:00|Rome| 93 | |2025-02-17T12:00:00|Rome| 115 | |2025-02-17T13:00:00|Rome| 33 | |2025-02-17T17:00:00|Rome| 86 | |2025-02-17T23:00:00|Rome| 49 | ##### GROUPS Defines window frame boundaries using row groups. Rows with the same values for the columns in the [`ORDER BY` clause](#order-by-clause)comprise a row group. > [!Important] > When using `GROUPS` frame units, include an `ORDER BY` clause. The offset is the difference in row group position relative to the current row group.`GROUPS` supports the following offset types: * Numeric *(non-negative)* * Numeric string *(non-negative)* [](#see-how-groups-frame-units-work) See how `GROUPS` frame units work When using the `GROUPS` frame unit, unique combinations column values specified in the `ORDER BY` clause determine each row group. For example, if you sort partitions by `country` and `city`: ```sql ... OVER ( ORDER BY country, city GROUPS ... ) ``` The query defines row groups in the following way: | time |country| city |wind\_direction| |-------------------|-------|----------|---------------| |2025-02-17T00:00:00|France |Strasbourg| 181 | |2025-02-17T01:00:00|France |Strasbourg| 228 | |2025-02-17T02:00:00|France |Strasbourg| 289 | |2025-02-17T00:00:00|France | Toulouse | 24 | |2025-02-17T01:00:00|France | Toulouse | 210 | |2025-02-17T02:00:00|France | Toulouse | 206 | |2025-02-17T00:00:00| Italy | Bari | 2 | |2025-02-17T01:00:00| Italy | Bari | 57 | |2025-02-17T00:00:00| Italy | Bologna | 351 | |2025-02-17T01:00:00| Italy | Bologna | 232 | |2025-02-17T02:00:00| Italy | Bologna | 29 | You can then use group offsets to determine frame boundaries: ```sql ... OVER ( ORDER BY country, city GROUPS 2 PRECEDING ) ``` The window function uses all rows in the current row group and the two preceding row groups to perform the operation: | time |country| city |wind\_direction| |-------------------|-------|----------|---------------| |2025-02-17T00:00:00|France |Strasbourg| 181 | |2025-02-17T01:00:00|France |Strasbourg| 228 | |2025-02-17T02:00:00|France |Strasbourg| 289 | |2025-02-17T00:00:00|France | Toulouse | 24 | |2025-02-17T01:00:00|France | Toulouse | 210 | |2025-02-17T02:00:00|France | Toulouse | 206 | |2025-02-17T00:00:00| Italy | Bari | 2 | |2025-02-17T01:00:00| Italy | Bari | 57 | |2025-02-17T00:00:00| Italy | Bologna | 351 | |2025-02-17T01:00:00| Italy | Bologna | 232 | |2025-02-17T02:00:00| Italy | Bologna | 29 | #### Frame boundaries Frame boundaries (**frame\_start** and **frame\_end**) define the boundaries of each frame that the window function operates on. * [UNBOUNDED PRECEDING](#unbounded-preceding) * [offset PRECEDING](#offset-preceding) * [CURRENT\_ROW](#current-row) * [offset FOLLOWING](#offset-following) * [UNBOUNDED FOLLOWING](#unbounded-following) ##### UNBOUNDED PRECEDING Starts at the first row of the partition and ends at the current row. ```sql UNBOUNDED PRECEDING ``` ##### offset PRECEDING Starts at `offset` [frame units](#frame-units) before the current row and ends at the current row. For example, `3 PRECEDING` includes 3 rows before the current row. ```sql PRECEDING ``` ##### CURRENT ROW Both starts and ends at the current row when used as a boundary. ```sql CURRENT ROW ``` ##### offset FOLLOWING Starts at the current row and ends at `offset` [frame units](#frame-units) after the current row. For example, `3 FOLLOWING` includes 3 rows after the current row. ```sql FOLLOWING ``` ##### UNBOUNDED FOLLOWING Use the current row to the end of the current partition the frame boundary. ```sql UNBOUNDED FOLLOWING ``` ### WINDOW clause Use the `WINDOW` clause to define a reusable alias for a window specification. This is useful when multiple window functions in your query share the same window definition. Instead of repeating the same OVER clause for each function, define the window once and reference it by alias–for example: ```sql SELECT sum(net_gain) OVER w, avg(net_net) OVER w FROM finance WINDOW w AS ( PARTITION BY ticker ORDER BY time DESC); ``` ## Aggregate functions All [aggregate functions](/influxdb3/cloud-dedicated/reference/sql/functions/aggregate/)can be used as window functions. ## Ranking Functions * [cume\_dist](#cume_dist) * [dense\_rank](#dense_rank) * [ntile](#ntile) * [percent\_rank](#percent_rank) * [rank](#rank) * [row\_number](#row_number) ### cume\_dist Returns the cumulative distribution of a value within a group of values. The returned value is greater than 0 and less than or equal to 1 and represents the relative rank of the value in the set of values. The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause is used to correctly calculate the cumulative distribution of the current row value. ```sql cume_dist() ``` > [!Important] > When using `cume_dist`, include an [`ORDER BY` clause](#order-by-clause) in the `OVER` clause. [](#view-cume_dist-query-example) View `cume_dist` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, cume_dist() OVER ( PARTITION BY room ORDER BY temp ) AS cume_dist FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T12:00:00Z' ``` | time | room |temp|cume\_dist| |-------------------|-----------|----|----------| |2022-01-01T08:00:00|Living Room|21.1| 0.25 | |2022-01-01T09:00:00|Living Room|21.4| 0.5 | |2022-01-01T10:00:00|Living Room|21.8| 0.75 | |2022-01-01T11:00:00|Living Room|22.2| 1.0 | |2022-01-01T08:00:00| Kitchen |21.0| 0.25 | |2022-01-01T11:00:00| Kitchen |22.4| 0.5 | |2022-01-01T10:00:00| Kitchen |22.7| 0.75 | |2022-01-01T09:00:00| Kitchen |23.0| 1.0 | ### dense\_rank Returns the rank of the current row in its partition. Ranking is consecutive; assigns duplicate values the same rank number and the rank sequence continues with the next distinct value (unlike [`rank()`](#rank)). The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause determines ranking order. ```sql dense_rank() ``` [](#view-dense_rank-query-example) View `dense_rank` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, dense_rank() OVER ( PARTITION BY room ORDER BY temp ) AS dense_rank FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T12:00:00Z' ``` | time | room |temp|dense\_rank| |-------------------|-----------|----|-----------| |2022-01-01T08:00:00| Kitchen |21.0| 1 | |2022-01-01T11:00:00| Kitchen |22.4| 2 | |2022-01-01T10:00:00| Kitchen |22.7| 3 | |2022-01-01T09:00:00| Kitchen |23.0| 4 | |2022-01-01T08:00:00|Living Room|21.1| 1 | |2022-01-01T09:00:00|Living Room|21.4| 2 | |2022-01-01T10:00:00|Living Room|21.8| 3 | |2022-01-01T11:00:00|Living Room|22.2| 4 | [](#compare-dense_rank-rank-and-row_number-functions) Compare `dense_rank`, `rank`, and `row_number` functions Consider a table with duplicate ID values. The following query shows how each ranking function handles duplicate values: ```sql SELECT id, rank() OVER(ORDER BY id), dense_rank() OVER(ORDER BY id), row_number() OVER(ORDER BY id) FROM my_table; ``` |ID |rank|dense\_rank|row\_number| |---|----|-----------|-----------| | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | Key differences: * [`rank()`](#rank) assigns the same rank to equal values but skips ranks for subsequent values * [`dense_rank()`](#dense_rank) assigns the same rank to equal values and uses consecutive ranks * [`row_number()`](#row_number) assigns unique sequential numbers regardless of value (non-deterministic) ### ntile Distributes the rows in an ordered partition into the specified number of groups. Each group is numbered, starting at one. For each row, `ntile` returns the group number to which the row belongs. Group numbers range from 1 to the `expression` value, dividing the partition as equally as possible. The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause determines ranking order. ```sql ntile(expression) ``` #### Arguments * **expression**: An integer. The number of groups to split the partition into. [](#view-ntile-query-example) View `ntile` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, temp, ntile(4) OVER ( ORDER BY time ) AS ntile FROM home WHERE room = 'Kitchen' AND time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T15:00:00Z' ``` | time |temp|ntile| |-------------------|----|-----| |2022-01-01T08:00:00|21.0| 1 | |2022-01-01T09:00:00|23.0| 1 | |2022-01-01T10:00:00|22.7| 2 | |2022-01-01T11:00:00|22.4| 2 | |2022-01-01T12:00:00|22.5| 3 | |2022-01-01T13:00:00|22.8| 3 | |2022-01-01T14:00:00|22.8| 4 | ### percent\_rank Returns the percentage rank of the current row within its partition. The returned value is between `0` and `1`, computed as: ``` (rank - 1) / (total_rows - 1) ``` The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause determines the ranking order. ```sql percent_rank() ``` [](#view-percent_rank-query-example) View `percent_rank` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, percent_rank() OVER ( PARTITION BY room ORDER BY temp ) AS percent_rank FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ``` | time | room |temp|percent\_rank| |-------------------|-----------|----|-------------| |2022-01-01T08:00:00| Kitchen |21.0| 0.0 | |2022-01-01T10:00:00| Kitchen |22.7| 0.5 | |2022-01-01T09:00:00| Kitchen |23.0| 1.0 | |2022-01-01T08:00:00|Living Room|21.1| 0.0 | |2022-01-01T09:00:00|Living Room|21.4| 0.5 | |2022-01-01T10:00:00|Living Room|21.8| 1.0 | ### rank Returns the rank of the current row in its partition. For duplicate values, `rank` assigns them the same rank number, skips subsequent ranks (unlike [`dense_rank()`](#dense_rank)), and then continues ranking with the next distinct value. The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause determines ranking order. ```sql rank() ``` [](#view-rank-query-example) View `rank` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, rank() OVER ( PARTITION BY room ORDER BY temp ) AS rank FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ``` | time | room |temp|rank| |-------------------|-----------|----|----| |2022-01-01T08:00:00|Living Room|21.1| 1 | |2022-01-01T09:00:00|Living Room|21.4| 2 | |2022-01-01T10:00:00|Living Room|21.8| 3 | |2022-01-01T08:00:00| Kitchen |21.0| 1 | |2022-01-01T10:00:00| Kitchen |22.7| 2 | |2022-01-01T09:00:00| Kitchen |23.0| 3 | [](#compare-dense_rank-rank-and-row_number-functions) Compare `dense_rank`, `rank`, and `row_number` functions Consider a table with duplicate ID values. The following query shows how each ranking function handles duplicate values: ```sql SELECT id, rank() OVER(ORDER BY id), dense_rank() OVER(ORDER BY id), row_number() OVER(ORDER BY id) FROM my_table; ``` |ID |rank|dense\_rank|row\_number| |---|----|-----------|-----------| | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | Key differences: * [`rank()`](#rank) assigns the same rank to equal values but skips ranks for subsequent values * [`dense_rank()`](#dense_rank) assigns the same rank to equal values and uses consecutive ranks * [`row_number()`](#row_number) assigns unique sequential numbers regardless of value (non-deterministic) ### row\_number Returns the position of the current row in its partition, counting from 1. The [`ORDER BY` clause](#order-by-clause) in the `OVER` clause determines row order. ```sql row_number() ``` [](#view-row_number-query-example) View `row_number` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, row_number() OVER ( PARTITION BY room ORDER BY temp ) AS row_number FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ``` | time | room |temp|row\_number| |-------------------|-----------|----|-----------| |2022-01-01T08:00:00|Living Room|21.1| 1 | |2022-01-01T09:00:00|Living Room|21.4| 2 | |2022-01-01T10:00:00|Living Room|21.8| 3 | |2022-01-01T08:00:00| Kitchen |21.0| 1 | |2022-01-01T10:00:00| Kitchen |22.7| 2 | |2022-01-01T09:00:00| Kitchen |23.0| 3 | [](#compare-dense_rank-rank-and-row_number-functions) Compare `dense_rank`, `rank`, and `row_number` functions Consider a table with duplicate ID values. The following query shows how each ranking function handles duplicate values: ```sql SELECT id, rank() OVER(ORDER BY id), dense_rank() OVER(ORDER BY id), row_number() OVER(ORDER BY id) FROM my_table; ``` |ID |rank|dense\_rank|row\_number| |---|----|-----------|-----------| | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | Key differences: * [`rank()`](#rank) assigns the same rank to equal values but skips ranks for subsequent values * [`dense_rank()`](#dense_rank) assigns the same rank to equal values and uses consecutive ranks * [`row_number()`](#row_number) assigns unique sequential numbers regardless of value (non-deterministic) ## Analytical Functions * [first\_value](#first_value) * [lag](#lag) * [last\_value](#last_value) * [lead](#lead) * [nth\_value](#nth_value) ### first\_value Returns the value from the first row of the window frame. ```sql first_value(expression) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Related functions [last\_value](#last_value) [](#view-first_value-query-example) View `first_value` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ``` SELECT time, room, temp, first_value(temp) OVER ( PARTITION BY room ORDER BY time ) AS first_value FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|first\_value| |-------------------|-----------|----|------------| |2022-01-01T08:00:00| Kitchen |21.0| 21.0 | |2022-01-01T09:00:00| Kitchen |23.0| 21.0 | |2022-01-01T10:00:00| Kitchen |22.7| 21.0 | |2022-01-01T08:00:00|Living Room|21.1| 21.1 | |2022-01-01T09:00:00|Living Room|21.4| 21.1 | |2022-01-01T10:00:00|Living Room|21.8| 21.1 | ### lag Returns the value from the row that is at the specified offset before the current row in the partition. If the offset row is outside the partition, the function returns the specified default. ```sql lag(expression, offset, default) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic or string operators. * **offset**: How many rows *before* the current row to retrieve the value of*expression* from. Default is `1`. * **default**: The default value to return if the offset is in the partition. Must be of the same type as *expression*. ##### Related functions [lead](#lead) [](#view-lag-query-example) View `lag` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT time, room, temp, lag(temp, 1, 0) OVER ( PARTITION BY room ORDER BY time ) AS previous_value FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|previous\_value| |-------------------|-----------|----|---------------| |2022-01-01T08:00:00| Kitchen |21.0| 0.0 | |2022-01-01T09:00:00| Kitchen |23.0| 21.0 | |2022-01-01T10:00:00| Kitchen |22.7| 23.0 | |2022-01-01T08:00:00|Living Room|21.1| 0.0 | |2022-01-01T09:00:00|Living Room|21.4| 21.1 | |2022-01-01T10:00:00|Living Room|21.8| 21.4 | [](#calculate-the-difference-from-a-previous-value) Calculate the difference from a previous value Use `LAG` with arithmetic to calculate the difference between the current value and a previous value. This is useful for detecting changes over time. The following query calculates the temperature change from the previous reading: ```sql SELECT time, room, temp, temp - lag(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS temp_change FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|temp\_change| |-------------------|-----------|----|------------| |2022-01-01T08:00:00| Kitchen |21.0| NULL | |2022-01-01T09:00:00| Kitchen |23.0| 2.0 | |2022-01-01T10:00:00| Kitchen |22.7| \-0.3 | |2022-01-01T08:00:00|Living Room|21.1| NULL | |2022-01-01T09:00:00|Living Room|21.4| 0.3 | |2022-01-01T10:00:00|Living Room|21.8| 0.4 | [](#calculate-the-difference-from-a-value-at-a-specific-time-offset) Calculate the difference from a value at a specific time offset For regularly spaced data, use `LAG` with an offset to compare values from a specific time period ago. The following query compares temperature values that are 1 hour apart (assuming hourly data): ```sql SELECT time, room, temp, lag(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS temp_1h_ago, temp - lag(temp, 1) OVER ( PARTITION BY room ORDER BY time ) AS hourly_change FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T12:00:00Z' ORDER BY room, time ``` [](#use-a-self-join-for-irregularly-spaced-data) Use a self-join for irregularly spaced data For irregularly spaced time series data where you need to compare values from an exact time offset (like exactly 1 hour ago), use a self-join with interval arithmetic: ```sql SELECT current.time, current.room, current.temp AS current_temp, previous.temp AS temp_1h_ago, current.temp - previous.temp AS hourly_diff FROM home AS current LEFT JOIN home AS previous ON current.room = previous.room AND previous.time = current.time - INTERVAL '1 hour' WHERE current.time >= '2022-01-01T08:00:00Z' AND current.time < '2022-01-01T12:00:00Z' ORDER BY current.room, current.time ``` This approach works when your data points don’t fall at regular intervals, or when you need to compare against a specific time offset regardless of when the previous data point occurred. ### last\_value Returns the value from the last row of the window frame. ```sql last_value(expression) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. ##### Related functions [first\_value](#first_value) [](#view-last_value-query-example) View `last_value` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT time, room, temp, last_value(temp) OVER ( PARTITION BY room ORDER BY time ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING ) AS last_value FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|last\_value| |-------------------|-----------|----|-----------| |2022-01-01T08:00:00| Kitchen |21.0| 22.7 | |2022-01-01T09:00:00| Kitchen |23.0| 22.7 | |2022-01-01T10:00:00| Kitchen |22.7| 22.7 | |2022-01-01T08:00:00|Living Room|21.1| 21.8 | |2022-01-01T09:00:00|Living Room|21.4| 21.8 | |2022-01-01T10:00:00|Living Room|21.8| 21.8 | ### lead Returns the value from the row that is at the specified offset after the current row in the partition. If the offset row is outside the partition, the function returns the specified default. ```sql lead(expression, offset, default) ``` #### Arguments * **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic or string operators. * **offset**: How many rows *before* the current row to retrieve the value of*expression* from. Default is `1`. * **default**: The default value to return if the offset is in the partition. Must be of the same type as *expression*. ##### Related functions [lag](#lag) [](#view-lead-query-example) View `lead` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT time, room, temp, lead(temp, 1, 0) OVER ( PARTITION BY room ORDER BY time ) AS next_value FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time < '2022-01-01T11:00:00Z' ORDER BY room, time ``` | time | room |temp|next\_value| |-------------------|-----------|----|-----------| |2022-01-01T08:00:00| Kitchen |21.0| 23.0 | |2022-01-01T09:00:00| Kitchen |23.0| 22.7 | |2022-01-01T10:00:00| Kitchen |22.7| 0.0 | |2022-01-01T08:00:00|Living Room|21.1| 21.4 | |2022-01-01T09:00:00|Living Room|21.4| 21.8 | |2022-01-01T10:00:00|Living Room|21.8| 0.0 | ### nth\_value Returns the value from the row that is the nth row of the window frame (counting from 1). If the nth row doesn’t exist, the function returns *null*. ```sql nth_value(expression, n) ``` #### Arguments * **expression**: The expression to operator on. Can be a constant, column, or function, and any combination of arithmetic or string operators. * **n**: Specifies the row number in the current frame and partition to reference. [](#view-lead-query-example) View `lead` query example The following example uses the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data). ```sql SELECT time, room, temp, nth_value(temp, 2) OVER ( PARTITION BY room ) AS second_temp FROM home WHERE time >= '2025-02-10T08:00:00Z' AND time < '2025-02-10T11:00:00Z' ``` | time | room |temp|second\_temp| |-------------------|-----------|----|------------| |2025-02-10T08:00:00| Kitchen |21.0| 22.7 | |2025-02-10T10:00:00| Kitchen |22.7| 22.7 | |2025-02-10T09:00:00| Kitchen |23.0| 22.7 | |2025-02-10T08:00:00|Living Room|21.1| 21.8 | |2025-02-10T10:00:00|Living Room|21.8| 21.8 | |2025-02-10T09:00:00|Living Room|21.4| 21.8 | | time | room | temp | avg_room_temp | | --- | --- | --- | --- | | time | room | temp | avg_room_temp | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 22.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 22.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 21.25 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.25 | | time | city | wind_direction | | --- | --- | --- | | time | city | wind_direction | | 2025-02-17T13:00:00 | Rome | 33 | | 2025-02-17T08:00:00 | Rome | 34 | | 2025-02-17T23:00:00 | Rome | 49 | | 2025-02-17T17:00:00 | Rome | 86 | | 2025-02-17T11:00:00 | Rome | 93 | | 2025-02-17T12:00:00 | Rome | 115 | | 2025-02-17T10:00:00 | Rome | 156 | | time | room | temp | | --- | --- | --- | | time | room | temp | | 2022-01-01T08:00:00 | Kitchen | 21.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | | 2022-01-01T11:00:00 | Kitchen | 22.4 | | 2022-01-01T12:00:00 | Kitchen | 22.5 | | 2022-01-01T13:00:00 | Kitchen | 22.8 | | 2022-01-01T14:00:00 | Kitchen | 22.8 | | 2022-01-01T15:00:00 | Kitchen | 22.7 | | time | city | wind_direction | | --- | --- | --- | | time | city | wind_direction | | 2025-02-17T08:00:00 | Rome | 34 | | 2025-02-17T10:00:00 | Rome | 156 | | 2025-02-17T11:00:00 | Rome | 93 | | 2025-02-17T12:00:00 | Rome | 115 | | 2025-02-17T13:00:00 | Rome | 33 | | 2025-02-17T17:00:00 | Rome | 86 | | 2025-02-17T23:00:00 | Rome | 49 | | time | country | city | wind_direction | | --- | --- | --- | --- | | time | country | city | wind_direction | | 2025-02-17T00:00:00 | France | Strasbourg | 181 | | 2025-02-17T01:00:00 | France | Strasbourg | 228 | | 2025-02-17T02:00:00 | France | Strasbourg | 289 | | 2025-02-17T00:00:00 | France | Toulouse | 24 | | 2025-02-17T01:00:00 | France | Toulouse | 210 | | 2025-02-17T02:00:00 | France | Toulouse | 206 | | 2025-02-17T00:00:00 | Italy | Bari | 2 | | 2025-02-17T01:00:00 | Italy | Bari | 57 | | 2025-02-17T00:00:00 | Italy | Bologna | 351 | | 2025-02-17T01:00:00 | Italy | Bologna | 232 | | 2025-02-17T02:00:00 | Italy | Bologna | 29 | | time | country | city | wind_direction | | --- | --- | --- | --- | | time | country | city | wind_direction | | 2025-02-17T00:00:00 | France | Strasbourg | 181 | | 2025-02-17T01:00:00 | France | Strasbourg | 228 | | 2025-02-17T02:00:00 | France | Strasbourg | 289 | | 2025-02-17T00:00:00 | France | Toulouse | 24 | | 2025-02-17T01:00:00 | France | Toulouse | 210 | | 2025-02-17T02:00:00 | France | Toulouse | 206 | | 2025-02-17T00:00:00 | Italy | Bari | 2 | | 2025-02-17T01:00:00 | Italy | Bari | 57 | | 2025-02-17T00:00:00 | Italy | Bologna | 351 | | 2025-02-17T01:00:00 | Italy | Bologna | 232 | | 2025-02-17T02:00:00 | Italy | Bologna | 29 | | time | room | temp | cume_dist | | --- | --- | --- | --- | | time | room | temp | cume_dist | | 2022-01-01T08:00:00 | Living Room | 21.1 | 0.25 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 0.5 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 0.75 | | 2022-01-01T11:00:00 | Living Room | 22.2 | 1.0 | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 0.25 | | 2022-01-01T11:00:00 | Kitchen | 22.4 | 0.5 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 0.75 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 1.0 | | time | room | temp | dense_rank | | --- | --- | --- | --- | | time | room | temp | dense_rank | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 1 | | 2022-01-01T11:00:00 | Kitchen | 22.4 | 2 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 3 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 4 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 1 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 2 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 3 | | 2022-01-01T11:00:00 | Living Room | 22.2 | 4 | | ID | rank | dense_rank | row_number | | --- | --- | --- | --- | | ID | rank | dense_rank | row_number | | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | | time | temp | ntile | | --- | --- | --- | | time | temp | ntile | | 2022-01-01T08:00:00 | 21.0 | 1 | | 2022-01-01T09:00:00 | 23.0 | 1 | | 2022-01-01T10:00:00 | 22.7 | 2 | | 2022-01-01T11:00:00 | 22.4 | 2 | | 2022-01-01T12:00:00 | 22.5 | 3 | | 2022-01-01T13:00:00 | 22.8 | 3 | | 2022-01-01T14:00:00 | 22.8 | 4 | | time | room | temp | percent_rank | | --- | --- | --- | --- | | time | room | temp | percent_rank | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 0.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 0.5 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 1.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 0.0 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 0.5 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 1.0 | | time | room | temp | rank | | --- | --- | --- | --- | | time | room | temp | rank | | 2022-01-01T08:00:00 | Living Room | 21.1 | 1 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 2 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 3 | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 1 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 2 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 3 | | ID | rank | dense_rank | row_number | | --- | --- | --- | --- | | ID | rank | dense_rank | row_number | | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | | time | room | temp | row_number | | --- | --- | --- | --- | | time | room | temp | row_number | | 2022-01-01T08:00:00 | Living Room | 21.1 | 1 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 2 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 3 | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 1 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 2 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 3 | | ID | rank | dense_rank | row_number | | --- | --- | --- | --- | | ID | rank | dense_rank | row_number | | 1 | 1 | 1 | 1 | | 1 | 1 | 1 | 2 | | 1 | 1 | 1 | 3 | | 2 | 4 | 2 | 4 | | time | room | temp | first_value | | --- | --- | --- | --- | | time | room | temp | first_value | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 21.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 21.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 21.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 21.1 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.1 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 21.1 | | time | room | temp | previous_value | | --- | --- | --- | --- | | time | room | temp | previous_value | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 0.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 21.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 23.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 0.0 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.1 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 21.4 | | time | room | temp | temp_change | | --- | --- | --- | --- | | time | room | temp | temp_change | | 2022-01-01T08:00:00 | Kitchen | 21.0 | NULL | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 2.0 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | -0.3 | | 2022-01-01T08:00:00 | Living Room | 21.1 | NULL | | 2022-01-01T09:00:00 | Living Room | 21.4 | 0.3 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 0.4 | | time | room | temp | last_value | | --- | --- | --- | --- | | time | room | temp | last_value | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 22.7 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 22.7 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 22.7 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 21.8 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.8 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 21.8 | | time | room | temp | next_value | | --- | --- | --- | --- | | time | room | temp | next_value | | 2022-01-01T08:00:00 | Kitchen | 21.0 | 23.0 | | 2022-01-01T09:00:00 | Kitchen | 23.0 | 22.7 | | 2022-01-01T10:00:00 | Kitchen | 22.7 | 0.0 | | 2022-01-01T08:00:00 | Living Room | 21.1 | 21.4 | | 2022-01-01T09:00:00 | Living Room | 21.4 | 21.8 | | 2022-01-01T10:00:00 | Living Room | 21.8 | 0.0 | | time | room | temp | second_temp | | --- | --- | --- | --- | | time | room | temp | second_temp | | 2025-02-10T08:00:00 | Kitchen | 21.0 | 22.7 | | 2025-02-10T10:00:00 | Kitchen | 22.7 | 22.7 | | 2025-02-10T09:00:00 | Kitchen | 23.0 | 22.7 | | 2025-02-10T08:00:00 | Living Room | 21.1 | 21.8 | | 2025-02-10T10:00:00 | Living Room | 21.8 | 21.8 | | 2025-02-10T09:00:00 | Living Room | 21.4 | 21.8 | --- # GROUP BY clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/group-by/ Use the `GROUP BY` clause to group data by values. `GROUP BY` is an optional clause used to group rows that have the same values for all columns and expressions in the list. To output an aggregation for each group, include an aggregate or selector function in the `SELECT` statement. When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list or in aggregate expressions. > [!Note] > #### Group by aliases > > * `GROUP BY` can use column aliases that are defined in the `SELECT` clause. > * `GROUP BY` won’t use an aliased value if the alias is the same as the > original column name. `GROUP BY` uses the original value of the column, > not the transformed, aliased value. We recommended using column ordinals in > in the `GROUP BY` clause to group by transformed values and maintain the > alias identifier. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT AGGREGATE_FN(field1), tag1 FROM measurement GROUP BY tag1 ``` ## Examples ### Group data by tag values ```sql SELECT AVG(water_level) AS avg_water_level, location FROM h2o_feet GROUP BY location ``` [](#view-example-results) View example results |avg\_water\_level| location | |-----------------|-------------| |5.359142420303919|coyote\_creek| |3.530712094245885|santa\_monica| ### Group data into 15 minute time intervals by tag ``` SELECT location, DATE_BIN(INTERVAL '15 minutes', time) AS time, COUNT(water_level) AS count FROM h2o_feet WHERE time >= timestamp '2019-09-17T00:00:00Z' AND time <= timestamp '2019-09-17T01:00:00Z' GROUP BY 1, location ORDER BY location, 1 ``` [](#view-example-results) View example results The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. Results are then ordered by location and time. | location | time |count| |-------------|--------------------|-----| |coyote\_creek|2019-09-16T23:45:00Z| 1 | |coyote\_creek|2019-09-17T00:00:00Z| 2 | |coyote\_creek|2019-09-17T00:15:00Z| 3 | |coyote\_creek|2019-09-17T00:30:00Z| 2 | |coyote\_creek|2019-09-17T00:45:00Z| 3 | |santa\_monica|2019-09-16T23:45:00Z| 1 | |santa\_monica|2019-09-17T00:00:00Z| 2 | |santa\_monica|2019-09-17T00:15:00Z| 3 | |santa\_monica|2019-09-17T00:30:00Z| 2 | |santa\_monica|2019-09-17T00:45:00Z| 3 | | avg_water_level | location | | --- | --- | | avg_water_level | location | | 5.359142420303919 | coyote_creek | | 3.530712094245885 | santa_monica | | location | time | count | | --- | --- | --- | | location | time | count | | coyote_creek | 2019-09-16T23:45:00Z | 1 | | coyote_creek | 2019-09-17T00:00:00Z | 2 | | coyote_creek | 2019-09-17T00:15:00Z | 3 | | coyote_creek | 2019-09-17T00:30:00Z | 2 | | coyote_creek | 2019-09-17T00:45:00Z | 3 | | santa_monica | 2019-09-16T23:45:00Z | 1 | | santa_monica | 2019-09-17T00:00:00Z | 2 | | santa_monica | 2019-09-17T00:15:00Z | 3 | | santa_monica | 2019-09-17T00:30:00Z | 2 | | santa_monica | 2019-09-17T00:45:00Z | 3 | --- # HAVING clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/having/ The `HAVING` clause places conditions on results created by an aggregate operation on groups. The `HAVING` clause must follow the `GROUP BY` clause and precede the `ORDER BY` clause. > [!Note] > The `WHERE` clause filters rows based on specified conditions *before* the aggregate operation. > The `HAVING` clause filters rows based on specified conditions *after* the aggregate operation has taken place. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] ``` ## Examples ### Return rows with an aggregate value greater than a specified number ``` SELECT MEAN("water_level") AS "mean_water_level", "location" FROM "h2o_feet" GROUP BY "location" HAVING "mean_water_level" > 5 ``` [](#view-example-results) View example results The query returns on rows with values in the `mean_water_level` greater than 5 *after* the aggregate operation. | location |mean\_water\_level| |-------------|------------------| |coyote\_creek|5.359142420303919 | ### Return the average result greater than a specified number from a specific time range ``` SELECT AVG("water_level") AS "avg_water_level", "time" FROM "h2o_feet" WHERE time >= '2019-09-01T00:00:00Z' AND time <= '2019-09-02T00:00:00Z' GROUP BY "time" HAVING "avg_water_level" > 6.82 ORDER BY "time" ``` [](#view-example-results) View example results The query calculates the average water level per time and only returns rows with an average greater than 6.82 during the specified time range. | time |avg\_water\_level | |--------------------|------------------| |2019-09-01T22:06:00Z| 6.8225 | |2019-09-01T22:12:00Z|6.8405000000000005| |2019-09-01T22:30:00Z| 6.8505 | |2019-09-01T22:36:00Z| 6.8325 | #### Related * [Subqueries](/influxdb3/core/reference/sql/subqueries/) | location | mean_water_level | | --- | --- | | location | mean_water_level | | coyote_creek | 5.359142420303919 | | time | avg_water_level | | --- | --- | | time | avg_water_level | | 2019-09-01T22:06:00Z | 6.8225 | | 2019-09-01T22:12:00Z | 6.8405000000000005 | | 2019-09-01T22:30:00Z | 6.8505 | | 2019-09-01T22:36:00Z | 6.8325 | --- # Information schema Source: https://docs.influxdata.com/influxdb3/core/reference/sql/information-schema/ The underlying query engine for the InfluxDB SQL implementation,[DataFusion](https://arrow.apache.org/datafusion/index.html), provides commands that return metadata related to your data schema. To access this information, use the `SHOW TABLES`, `SHOW COLUMNS`, and`SHOW ALL` commands or query views in the [ISO](https://www.iso.org/) SQL`information_schema` schema. In the context of InfluxDB, a [measurement](/influxdb3/core/reference/glossary/#measurement)is represented as a table. Time, [tags](/influxdb3/core/reference/glossary/#tag), and [fields](/influxdb3/core/reference/glossary/#field) are each represented by columns in a table. * [SHOW TABLES](#show-tables) * [Example SHOW TABLES output](#example-show-tables-output) * [SHOW COLUMNS](#show-columns) * [Example SHOW COLUMNS output](#example-show-columns-output) * [SHOW ALL](#show-all) * [Example SHOW ALL output](#view-show-all-example-output) ## SHOW TABLES Returns information about tables (measurements) in an InfluxDB bucket. ```sql SHOW TABLES ``` You can also query the `information_schema.tables` view: ```sql SELECT * FROM information_schema.tables ``` #### Example SHOW TABLES output *Measurements are those that use the **`iox` table schema**.* |table\_catalog| table\_schema |table\_name |table\_type| |--------------|-------------------|------------|-----------| | public | iox | home |BASE TABLE | | public | system | queries |BASE TABLE | | public |information\_schema| tables | VIEW | | public |information\_schema| views | VIEW | | public |information\_schema| columns | VIEW | | public |information\_schema|df\_settings| VIEW | ## SHOW COLUMNS Returns information about the schema of a table (measurement) in an InfluxDB bucket. ```sql SHOW COLUMNS FROM example_table ``` You can also query the `information_schema.columns` view: ```sql SELECT table_catalog, table_schema, table_name, column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'example_table' ``` #### Example SHOW COLUMNS output |table\_catalog|table\_schema|table\_name|column\_name| data\_type |is\_nullable| |--------------|-------------|-----------|------------|---------------------------|------------| | public | iox | home | co | Int64 | YES | | public | iox | home | hum | Float64 | YES | | public | iox | home | room | Dictionary(Int32, Utf8) | YES | | public | iox | home | temp | Float64 | YES | | public | iox | home | time |Timestamp(Nanosecond, None)| NO | ## SHOW ALL Returns the configuration options of the current session. ```sql SHOW ALL ``` You can also query the `information_schema.df_settings` view: ```sql SELECT * FROM information_schema.df_settings ``` [](#view-show-all-example-output) View `SHOW ALL` example output | name |setting | |-------------------------------------------------------------|--------| | datafusion.catalog.create\_default\_catalog\_and\_schema | true | | datafusion.catalog.default\_catalog | public | | datafusion.catalog.default\_schema | iox | | datafusion.catalog.format | | | datafusion.catalog.has\_header | false | | datafusion.catalog.information\_schema | true | | datafusion.catalog.location | | | datafusion.execution.batch\_size | 8192 | | datafusion.execution.coalesce\_batches | true | | datafusion.execution.collect\_statistics | false | | datafusion.execution.parquet.enable\_page\_index | false | | datafusion.execution.parquet.metadata\_size\_hint | | | datafusion.execution.parquet.pruning | true | | datafusion.execution.parquet.pushdown\_filters | true | | datafusion.execution.parquet.reorder\_filters | true | | datafusion.execution.parquet.skip\_metadata | true | | datafusion.execution.target\_partitions | 4 | | datafusion.execution.time\_zone |\+00:00 | | datafusion.explain.logical\_plan\_only | false | | datafusion.explain.physical\_plan\_only | false | | datafusion.optimizer.enable\_round\_robin\_repartition | true | | datafusion.optimizer.filter\_null\_join\_keys | false | |datafusion.optimizer.hash\_join\_single\_partition\_threshold|1048576 | | datafusion.optimizer.max\_passes | 3 | | datafusion.optimizer.prefer\_hash\_join | true | | datafusion.optimizer.repartition\_aggregations | true | | datafusion.optimizer.repartition\_file\_min\_size |10485760| | datafusion.optimizer.repartition\_file\_scans | true | | datafusion.optimizer.repartition\_joins | true | | datafusion.optimizer.repartition\_sorts | false | | datafusion.optimizer.repartition\_windows | true | | datafusion.optimizer.skip\_failed\_rules | true | | datafusion.optimizer.top\_down\_join\_key\_reordering | true | | datafusion.sql\_parser.enable\_ident\_normalization | true | | datafusion.sql\_parser.parse\_float\_as\_decimal | false | | table_catalog | table_schema | table_name | table_type | | --- | --- | --- | --- | | table_catalog | table_schema | table_name | table_type | | public | iox | home | BASE TABLE | | public | system | queries | BASE TABLE | | public | information_schema | tables | VIEW | | public | information_schema | views | VIEW | | public | information_schema | columns | VIEW | | public | information_schema | df_settings | VIEW | | table_catalog | table_schema | table_name | column_name | data_type | is_nullable | | --- | --- | --- | --- | --- | --- | | table_catalog | table_schema | table_name | column_name | data_type | is_nullable | | public | iox | home | co | Int64 | YES | | public | iox | home | hum | Float64 | YES | | public | iox | home | room | Dictionary(Int32, Utf8) | YES | | public | iox | home | temp | Float64 | YES | | public | iox | home | time | Timestamp(Nanosecond, None) | NO | | name | setting | | --- | --- | | name | setting | | datafusion.catalog.create_default_catalog_and_schema | true | | datafusion.catalog.default_catalog | public | | datafusion.catalog.default_schema | iox | | datafusion.catalog.format | | | datafusion.catalog.has_header | false | | datafusion.catalog.information_schema | true | | datafusion.catalog.location | | | datafusion.execution.batch_size | 8192 | | datafusion.execution.coalesce_batches | true | | datafusion.execution.collect_statistics | false | | datafusion.execution.parquet.enable_page_index | false | | datafusion.execution.parquet.metadata_size_hint | | | datafusion.execution.parquet.pruning | true | | datafusion.execution.parquet.pushdown_filters | true | | datafusion.execution.parquet.reorder_filters | true | | datafusion.execution.parquet.skip_metadata | true | | datafusion.execution.target_partitions | 4 | | datafusion.execution.time_zone | +00:00 | | datafusion.explain.logical_plan_only | false | | datafusion.explain.physical_plan_only | false | | datafusion.optimizer.enable_round_robin_repartition | true | | datafusion.optimizer.filter_null_join_keys | false | | datafusion.optimizer.hash_join_single_partition_threshold | 1048576 | | datafusion.optimizer.max_passes | 3 | | datafusion.optimizer.prefer_hash_join | true | | datafusion.optimizer.repartition_aggregations | true | | datafusion.optimizer.repartition_file_min_size | 10485760 | | datafusion.optimizer.repartition_file_scans | true | | datafusion.optimizer.repartition_joins | true | | datafusion.optimizer.repartition_sorts | false | | datafusion.optimizer.repartition_windows | true | | datafusion.optimizer.skip_failed_rules | true | | datafusion.optimizer.top_down_join_key_reordering | true | | datafusion.sql_parser.enable_ident_normalization | true | | datafusion.sql_parser.parse_float_as_decimal | false | --- # JOIN clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/join/ Use the `JOIN` clause to join data from different tables together based on logical relationships. * [Syntax](#syntax) * [Join types](#join-types) * [INNER JOIN](#inner-join) * [LEFT [OUTER] JOIN](#left-outer-join) * [RIGHT [OUTER] JOIN](#right-outer-join) * [FULL [OUTER] JOIN](#full-outer-join) * [Troubleshoot joins](#troubleshoot-joins) ## Syntax ```sql SELECT_clause FROM [INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER]] JOIN ON [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] ``` ### Arguments * **left\_join\_items**: One or more tables specified in the `FROM` clause that represent the left side of the join. * **right\_join\_items**: One or more tables specified in the `JOIN` clause that represent the right side of the join. * **join\_condition**: A predicate expression in the `ON` clause that uses the`=` (equal to) comparison operator to compare column values from the left side of the join to column values on the right side of the join. Rows with values that match the defined predicate are joined using the specified[join type](#join-types). > [!Note] > If both sides of the join include columns with the same name, you need to > use the fully-qualified reference to prevent ambiguity. > A *fully-qualified reference* uses dot notation to reference both the table name > and the column name–for example: `table_name.column_name` ## Join types The following joins types are supported: [ **INNER JOIN** ](#inner-join) [ **LEFT [OUTER] JOIN** ](#left-outer-join) [ **RIGHT [OUTER] JOIN** ](#right-outer-join) [ **FULL [OUTER] JOIN** ](#full-outer-join) #### Join sample tables The examples below illustrate join methods using the following tables: ##### prod\_line | time |station|produced| |--------------------|-------|--------| |2022-01-01T08:00:00Z| B1 | 26 | |2022-01-01T09:00:00Z| B1 | 54 | |2022-01-01T10:00:00Z| B1 | 56 | |2022-01-01T11:00:00Z| B1 | | |2022-01-01T12:00:00Z| B1 | 82 | ##### errors | time |station|level| message | |--------------------|-------|-----|--------------------| |2022-01-01T10:00:00Z| B1 |warn |Maintenance required| |2022-01-01T11:00:00Z| B1 |crit | Station offline | ### INNER JOIN Inner joins combine rows from tables on the left and right side of the join based on common column values defined in the `ON` clause. Rows that don’t have matching column values are not included in the output table. #### Inner join example [View sample tables](#join-sample-tables) ```sql SELECT * FROM prod_line RIGHT JOIN errors ON prod_line.time = errors.time AND prod_line.station = errors.station ORDER BY prod_line.time ``` ##### Inner join results | time |station|produced| time |station|level| message | |--------------------|-------|--------|--------------------|-------|-----|--------------------| |2022-01-01T10:00:00Z| B1 | 56 |2022-01-01T10:00:00Z| B1 |warn |Maintenance required| |2022-01-01T11:00:00Z| B1 | |2022-01-01T11:00:00Z| B1 |crit | Station offline | ### LEFT [OUTER] JOIN A left outer join returns all rows from the left side of the join and only returns data from the right side of the join in rows with matching column values defined in the `ON` clause. #### Left outer join example [View sample tables](#join-sample-tables) ```sql SELECT * FROM prod_line LEFT JOIN errors ON prod_line.time = errors.time AND prod_line.station = errors.station ORDER BY prod_line.time ``` ##### Left outer join results | time |station|produced| time |station|level| message | |--------------------|-------|--------|--------------------|-------|-----|--------------------| |2022-01-01T08:00:00Z| B1 | 26 | | | | | |2022-01-01T09:00:00Z| B1 | 54 | | | | | |2022-01-01T10:00:00Z| B1 | 56 |2022-01-01T10:00:00Z| B1 |warn |Maintenance required| |2022-01-01T11:00:00Z| B1 | |2022-01-01T11:00:00Z| B1 |crit | Station offline | |2022-01-01T12:00:00Z| B1 | 82 | | | | | ### RIGHT [OUTER] JOIN A right outer join returns all rows from the right side of the join and only returns data from the left side of the join in rows with matching column values defined in the `ON` clause. #### Right outer join example [View sample tables](#join-sample-tables) ```sql SELECT * FROM prod_line RIGHT JOIN errors ON prod_line.time = errors.time AND prod_line.station = errors.station ORDER BY prod_line.time ``` ##### Right outer join results | time |station|produced| time |station|level| message | |--------------------|-------|--------|--------------------|-------|-----|--------------------| |2022-01-01T10:00:00Z| B1 | 56 |2022-01-01T10:00:00Z| B1 |warn |Maintenance required| |2022-01-01T11:00:00Z| B1 | |2022-01-01T11:00:00Z| B1 |crit | Station offline | ### FULL [OUTER] JOIN A full outer join returns all data from the left and right sides of the join and combines rows with matching column values defined in the `ON` clause. Data that is not available on each respective side of the join is NULL. #### Full outer join example [View sample tables](#join-sample-tables) ```sql SELECT * FROM prod_line FULL JOIN errors ON prod_line.time = errors.time AND prod_line.station = errors.station ORDER BY time ``` ##### Full outer join results | time |station|produced| time |station|level| message | |--------------------|-------|--------|--------------------|-------|-----|--------------------| |2022-01-01T08:00:00Z| B1 | 26 | | | | | |2022-01-01T09:00:00Z| B1 | 54 | | | | | |2022-01-01T10:00:00Z| B1 | 56 |2022-01-01T10:00:00Z| B1 |warn |Maintenance required| |2022-01-01T11:00:00Z| B1 | |2022-01-01T11:00:00Z| B1 |crit | Station offline | |2022-01-01T12:00:00Z| B1 | 82 | | | | | ## Troubleshoot joins ### Ambiguous reference to unqualified field If a column exists on both sides of the join and is used in the `SELECT`,`ON`, `WHERE`, `HAVING`, `GROUP BY`, or `ORDER BY` clause, you must use a[fully-qualified reference](#fully-qualified-reference). For example, if both sides of the join have a `time` column and you want to explicitly select a time column, you must specifiy which side of the join to use the time column from: ```sql SELECT prod_line.time, produced, message, FROM prod_line INNER JOIN errors ON -- ... ``` | time | station | produced | | --- | --- | --- | | time | station | produced | | 2022-01-01T08:00:00Z | B1 | 26 | | 2022-01-01T09:00:00Z | B1 | 54 | | 2022-01-01T10:00:00Z | B1 | 56 | | 2022-01-01T11:00:00Z | B1 | | | 2022-01-01T12:00:00Z | B1 | 82 | | time | station | level | message | | --- | --- | --- | --- | | time | station | level | message | | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | | time | station | produced | time | station | level | message | | --- | --- | --- | --- | --- | --- | --- | | time | station | produced | time | station | level | message | | 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | | 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | | time | station | produced | time | station | level | message | | --- | --- | --- | --- | --- | --- | --- | | time | station | produced | time | station | level | message | | 2022-01-01T08:00:00Z | B1 | 26 | | | | | | 2022-01-01T09:00:00Z | B1 | 54 | | | | | | 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | | 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | | 2022-01-01T12:00:00Z | B1 | 82 | | | | | | time | station | produced | time | station | level | message | | --- | --- | --- | --- | --- | --- | --- | | time | station | produced | time | station | level | message | | 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | | 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | | time | station | produced | time | station | level | message | | --- | --- | --- | --- | --- | --- | --- | | time | station | produced | time | station | level | message | | 2022-01-01T08:00:00Z | B1 | 26 | | | | | | 2022-01-01T09:00:00Z | B1 | 54 | | | | | | 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | | 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | | 2022-01-01T12:00:00Z | B1 | 82 | | | | | --- # LIMIT clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/limit/ The `LIMIT` clause limits the number of rows returned by a query to a specified non-negative integer. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` ## Examples ### Limit results to a maximum of five rows ``` SELECT "water_level","location", "time" FROM "h2o_feet" LIMIT 5 ``` [](#view-example-results) View example results The query returns a maximum of 5 results. | location | time |water\_level| |-------------|------------------------|------------| |coyote\_creek|2019-08-28T00:00:00.000Z| 4.206 | |coyote\_creek|2019-08-28T00:06:00.000Z| 4.052 | |coyote\_creek|2019-08-28T00:12:00.000Z| 3.901 | |coyote\_creek|2019-08-28T00:18:00.000Z| 3.773 | |coyote\_creek|2019-08-28T00:24:00.000Z| 3.632 | ### Sort and limit results Use the `ORDER BY` and `LIMIT` clauses to first sort results by specified columns, then limit the sorted results by a specified number. ``` SELECT "water_level", "location", "time" FROM "h2o_feet" ORDER BY "water_level" DESC LIMIT 3 ``` [](#view-example-results) View example results The query returns the highest 3 `water_level` readings in the `h2o_feet` measurement. | location | time |water\_level| |-------------|------------------------|------------| |coyote\_creek|2019-08-27T13:42:00.000Z| \-0.561 | |coyote\_creek|2019-08-29T15:24:00.000Z| \-0.571 | |coyote\_creek|2019-08-28T14:24:00.000Z| \-0.587 | | location | time | water_level | | --- | --- | --- | | location | time | water_level | | coyote_creek | 2019-08-28T00:00:00.000Z | 4.206 | | coyote_creek | 2019-08-28T00:06:00.000Z | 4.052 | | coyote_creek | 2019-08-28T00:12:00.000Z | 3.901 | | coyote_creek | 2019-08-28T00:18:00.000Z | 3.773 | | coyote_creek | 2019-08-28T00:24:00.000Z | 3.632 | | location | time | water_level | | --- | --- | --- | | location | time | water_level | | coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | | coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | | coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | --- # SQL operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/ SQL operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. * [Arithmetic operators](#arithmetic-operators) * [Comparison operators](#comparison-operators) * [Logical operators](#logical-operators) * [Bitwise operators](#bitwise-operators) * [Other operators](#other-operators) ## [Arithmetic operators](/influxdb3/core/reference/sql/operators/arithmetic/) Arithmetic operators take two numeric values (either literals or variables) and perform a calculation that returns a single numeric value. |Operator| Description |Example|Result| |--------|--------------|-------|------| | `+` | Addition |`2 + 2`| `4` | | `-` | Subtraction |`4 - 2`| `2` | | `*` |Multiplication|`2 * 3`| `6` | | `/` | Division |`6 / 3`| `2` | | `%` | Modulo |`7 % 2`| `1` | ## [Comparison operators](/influxdb3/core/reference/sql/operators/comparison/) Comparison operators evaluate the relationship between the left and right operands and return `true` or `false`. | Operator | Meaning | Example | |----------------------|--------------------------------------------------------|--------------------------| | `=` | Equal to | `123 = 123` | | `<>` | Not equal to | `123 <> 456` | | `!=` | Not equal to | `123 != 456` | | `>` | Greater than | `3 > 2` | | `>=` | Greater than or equal to | `3 >= 2` | | `<` | Less than | `1 < 2` | | `<=` | Less than or equal to | `1 <= 2` | | `IS DISTINCT FROM` | Is distinct from | `0 IS DISTINCT FROM 1` | |`IS NOT DISTINCT FROM`| Is not distinct from |`0 IS NOT DISTINCT FROM 1`| | `~` | Matches a regular expression | `'abc' ~ 'a.*'` | | `~*` | Matches a regular expression *(case-insensitive)* | `'Abc' ~* 'A.*'` | | `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | | `!~*` |Does not match a regular expression *(case-insensitive)*| `'Abc' !~* 'a.*'` | ## [Logical operators](/influxdb3/core/reference/sql/operators/logical/) Logical operators combine or manipulate conditions in a SQL query. |Operator | Meaning | |---------|--------------------------------------------------------------------------| | `AND` | Returns true if both operands are true. Otherwise, returns false. | |`BETWEEN`|Returns true if the left operand is within the range of the right operand.| |`EXISTS` | Returns true if the results of a subquery are not empty. | | `IN` | Returns true if the left operand is in the right operand list. | | `LIKE` |Returns true if the left operand matches the right operand pattern string.| | `NOT` | Negates the subsequent expression. | | `OR` | Returns true if any operand is true. Otherwise, returns false. | ## [Bitwise operators](/influxdb3/core/reference/sql/operators/bitwise/) Bitwise operators perform bitwise operations on bit patterns or binary numerals. |Operator| Meaning |Example |Result| |--------|-------------------|--------|------| | `&` | Bitwise and |`5 & 3` | `1` | | `|` | Bitwise or |`5 | 3` | `7` | | `^` | Bitwise xor |`5 ^ 3` | `6` | | `>>` |Bitwise shift right|`5 >> 3`| `0` | | `<<` |Bitwise shift left |`5 << 3`| `40` | ## [Other operators](/influxdb3/core/reference/sql/operators/other/) SQL supports other miscellaneous operators that perform various operations. | Operator | Meaning | Example | Result | |--------------|------------------------|-----------------------------------------------------------------------------|-------------| | `||` | Concatenate strings | `'Hello' || ' world'` |`Hello world`| |`AT TIME ZONE`|Apply a time zone offset|*[View example](/influxdb3/core/reference/sql/operators/other/#at-time-zone)*| | | Operator | Description | Example | Result | | --- | --- | --- | --- | | Operator | Description | Example | Result | | + | Addition | 2 + 2 | 4 | | - | Subtraction | 4 - 2 | 2 | | * | Multiplication | 2 * 3 | 6 | | / | Division | 6 / 3 | 2 | | % | Modulo | 7 % 2 | 1 | | Operator | Meaning | Example | | --- | --- | --- | | Operator | Meaning | Example | | = | Equal to | 123 = 123 | | <> | Not equal to | 123 <> 456 | | != | Not equal to | 123 != 456 | | > | Greater than | 3 > 2 | | >= | Greater than or equal to | 3 >= 2 | | < | Less than | 1 < 2 | | <= | Less than or equal to | 1 <= 2 | | IS DISTINCT FROM | Is distinct from | 0 IS DISTINCT FROM 1 | | IS NOT DISTINCT FROM | Is not distinct from | 0 IS NOT DISTINCT FROM 1 | | ~ | Matches a regular expression | 'abc' ~ 'a.*' | | ~* | Matches a regular expression (case-insensitive) | 'Abc' ~* 'A.*' | | !~ | Does not match a regular expression | 'abc' !~ 'd.*' | | !~* | Does not match a regular expression (case-insensitive) | 'Abc' !~* 'a.*' | | Operator | Meaning | | --- | --- | | Operator | Meaning | | AND | Returns true if both operands are true. Otherwise, returns false. | | BETWEEN | Returns true if the left operand is within the range of the right operand. | | EXISTS | Returns true if the results of a subquery are not empty. | | IN | Returns true if the left operand is in the right operand list. | | LIKE | Returns true if the left operand matches the right operand pattern string. | | NOT | Negates the subsequent expression. | | OR | Returns true if any operand is true. Otherwise, returns false. | | Operator | Meaning | Example | Result | | --- | --- | --- | --- | | Operator | Meaning | Example | Result | | & | Bitwise and | 5 & 3 | 1 | | | | Bitwise or | 5 | 3 | 7 | | ^ | Bitwise xor | 5 ^ 3 | 6 | | >> | Bitwise shift right | 5 >> 3 | 0 | | << | Bitwise shift left | 5 << 3 | 40 | | Operator | Meaning | Example | Result | | --- | --- | --- | --- | | Operator | Meaning | Example | Result | | || | Concatenate strings | 'Hello' || ' world' | Hello world | | AT TIME ZONE | Apply a time zone offset | View example | | --- # SQL arithmetic operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/arithmetic/ Arithmetic operators take two numeric values (either literals or variables) and perform a calculation that returns a single numeric value. |Operator| Description | | |--------|--------------|-------------------| | `+` | Addition | [](#addition) | | `-` | Subtraction | [](#subtraction) | | `*` |Multiplication|[](#multiplication)| | `/` | Division | [](#division) | | `%` | Modulo | [](#modulo) | ## \+ The `+` operator adds two operands together and returns the sum. ```sql SELECT 1 + 2 ``` |int64(1) + int64(2)| |-------------------| | 3 | ## \- The `-` operator subtracts the right operand from the left operand and returns the difference. ```sql SELECT 4 - 2 ``` |int64(4) - int64(2)| |-------------------| | 2 | ## \* The `*` operator multiplies two operands together and returns the product. ```sql SELECT 2 * 3 ``` |int64(2) \* int64(3)| |--------------------| | 6 | / ---------- The `/` operator divides the left operand by the right operand and returns the quotient. ```sql SELECT 6 / 3 ``` |int64(6) / int64(3)| |-------------------| | 2 | % ---------- The `%` (modulo) operator divides the left operand by the right operand and returns the remainder. If the left operand is not divisible by the right operand, it returns the left operand. ```sql SELECT 8 % 3 ``` |Int64(8) % Int64(3)| |-------------------| | 2 | ```sql SELECT 3 % 8 ``` |Int64(3) % Int64(8)| |-------------------| | 3 | | Operator | Description | | | --- | --- | --- | | Operator | Description | | | + | Addition | | | - | Subtraction | | | * | Multiplication | | | / | Division | | | % | Modulo | | | int64(1) + int64(2) | | --- | | int64(1) + int64(2) | | 3 | | int64(4) - int64(2) | | --- | | int64(4) - int64(2) | | 2 | | int64(2) * int64(3) | | --- | | int64(2) * int64(3) | | 6 | | int64(6) / int64(3) | | --- | | int64(6) / int64(3) | | 2 | | Int64(8) % Int64(3) | | --- | | Int64(8) % Int64(3) | | 2 | | Int64(3) % Int64(8) | | --- | | Int64(3) % Int64(8) | | 3 | --- # SQL bitwise operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/bitwise/ Bitwise operators perform bitwise operations on bit patterns or binary numerals. |Operator| Meaning | | |--------|-------------------|------------------------| | `&` | Bitwise and | [](#bitwise-and) | | `|` | Bitwise or | [](#bitwise-or) | | `^` | Bitwise xor | [](#bitwise-xor) | | `>>` |Bitwise shift right|[](#bitwise-shift-right)| | `<<` |Bitwise shift left |[](#bitwise-shift-left) | & ---------- The `&` (bitwise AND) operator compares each bit of the left operand to the corresponding bit of the right operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. ```sql SELECT 5 & 3 ``` |Int64(5) & Int64(3)| |-------------------| | 1 | | ---------- The `|` (bitwise OR or inclusive OR) operator compares each bit of the left operand to the corresponding bit of the right operand. If either bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. ```sql SELECT 5 | 3 ``` |Int64(5) | Int64(3)| |-------------------| | 7 | ^ ---------- The `^` (bitwise XOR or exclusive OR) operator compares each bit of the left operand to the corresponding bit of the right operand. If the bit in one of the operands is 0 and the bit in the other operand is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. ```sql SELECT 5 ^ 3 ``` |Int64(5) BIT\_XOR Int64(3)| |--------------------------| | 6 | ## \>\> The `>>` (bitwise shift right) operator shifts the bits in the left operand to the right by the number of positions specified in the right operand. For unsigned numbers, bit positions vacated by the shift operation are filled with 0. For signed numbers, the sign bit is used to fill the vacated bit positions. If the number is positive, the bit position is filled with 0. If the number is negative, the bit position is filled with 1. ```sql SELECT 5 >> 3 ``` |Int64(5) \>\> Int64(3)| |----------------------| | 0 | ## \<\< The `<<` (bitwise shift left) operator shifts the bits in the left operand to the left by the number of positions specified in the right operand. Bit positions vacated by the shift operation are filled with 0. Bits that shift off the end are discarded, including the sign bit. ```sql SELECT 5 << 3 ``` |Int64(5) \<\< Int64(3)| |----------------------| | 40 | | Operator | Meaning | | | --- | --- | --- | | Operator | Meaning | | | & | Bitwise and | | | | | Bitwise or | | | ^ | Bitwise xor | | | >> | Bitwise shift right | | | << | Bitwise shift left | | | Int64(5) & Int64(3) | | --- | | Int64(5) & Int64(3) | | 1 | | Int64(5) | Int64(3) | | --- | | Int64(5) | Int64(3) | | 7 | | Int64(5) BIT_XOR Int64(3) | | --- | | Int64(5) BIT_XOR Int64(3) | | 6 | | Int64(5) >> Int64(3) | | --- | | Int64(5) >> Int64(3) | | 0 | | Int64(5) << Int64(3) | | --- | | Int64(5) << Int64(3) | | 40 | --- # SQL comparison operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/comparison/ Comparison operators evaluate the relationship between the left and right operands and returns `true` or `false`. | Operator | Meaning | | |----------------------|--------------------------------------------------------|------------------------------------| | `=` | Equal to | [](#equal-to) | | `<>` | Not equal to | [](#not-equal-to) | | `!=` | Not equal to | [](#not-equal-to) | | `>` | Greater than | [](#greater-than) | | `>=` | Greater than or equal to | [](#greater-than-or-equal) | | `<` | Less than | [](#less-than) | | `<=` | Less than or equal to | [](#less-than-or-equal) | | `IS DISTINCT FROM` | Is distinct from | [](#is-distinct-from) | |`IS NOT DISTINCT FROM`| Is not distinct from | [](#is-not-distinct-from) | | `~` | Matches a regular expression | [](#regexp-match) | | `~*` | Matches a regular expression *(case-insensitive)* | [](#regexp-match-case-insensitive) | | `!~` | Does not match a regular expression | [](#regexp-nomatch) | | `!~*` |Does not match a regular expression *(case-insensitive)*|[](#regexp-nomatch-case-insensitive)| ## \= The `=` operator compares the left and right operands and, if equal, returns `true`. Otherwise returns `false`. ```sql SELECT 123 = 123 ``` |Int64(123) = Int64(123)| |-----------------------| | true | ## !=, \<\> The `!=` and `<>` operators compare the left and right operands and, if not equal, returns `true`. Otherwise returns `false`. ```sql SELECT 123 != 456 ``` |Int64(123) != Int64(456)| |------------------------| | true | ```sql SELECT 123 <> 456 ``` |Int64(123) != Int64(456)| |------------------------| | true | ## \> The `>` operator compares the left and right operands and, if the left operand is greater than the right operand, returns `true`. Otherwise returns `false`. ```sql SELECT 3 > 2 ``` |Int64(3) \> Int64(2)| |--------------------| | true | ## \>= The `>=` operator compares the left and right operands and, if the left operand is greater than or equal to the right operand, returns `true`. Otherwise returns `false`. ```sql SELECT 3 >= 2 ``` |Int64(3) \>= Int64(2)| |---------------------| | true | ## \< The `<` operator compares the left and right operands and, if the left operand is less than the right operand, returns `true`. Otherwise returns `false`. ```sql SELECT 1 < 2 ``` |Int641(1) \< Int64(2)| |---------------------| | true | ## \<= The `<=` operator compares the left and right operands and, if the left operand is less than or equal to the right operand, returns `true`. Otherwise returns `false`. ```sql SELECT 1 <= 2 ``` |Int641(1) \<= Int64(2)| |----------------------| | true | ## IS DISTINCT FROM The `IS DISTINCT FROM` operator is a *NULL*-safe operator that returns`true` if both operands are not equal; otherwise, it returns `false`. This operator guarantees the result of a comparison is `true` or `false` and not an empty set. ```sql SELECT 0 IS DISTINCT FROM NULL ``` |Int64(0) IS DISTINCT FROM NULL| |------------------------------| | true | ## IS NOT DISTINCT FROM The `IS NOT DISTINCT FROM` operator is a *NULL*-safe operator that returns`true` if both operands are equal or *NULL*; otherwise, it returns `false`. This operator negates [`IS DISTINCT FROM`](#is-distinct-from). ```sql SELECT NULL IS NOT DISTINCT FROM NULL ``` |NULL IS NOT DISTINCT FROM NULL| |------------------------------| | true | ## \~ The `~` operator compares the left string operand to the right regular expression operand and, if it matches (case-sensitive), returns `true`. Otherwise returns `false`. ```sql SELECT 'abc' ~ 'a.*' ``` |Utf8(“abc”) \~ Utf8(“a.\*”)| |---------------------------| | true | ## \~\* The `~*` operator compares the left string operand to the right regular expression operand and, if it matches (case-insensitive), returns `true`. Otherwise returns `false`. ```sql SELECT 'Abc' ~* 'A.*' ``` |Utf8(“Abc”) \~\* Utf8(“A.\*”)| |-----------------------------| | true | ## !\~ The `!~` operator compares the left string operand to the right regular expression operand and, if it does not match (case-sensitive), returns `true`. Otherwise returns `false`. ```sql SELECT 'abc' !~ 'd.*' ``` |Utf8(“abc”) !\~ Utf8(“d.\*”)| |----------------------------| | true | ## !\~\* The `!~*` operator compares the left string operand to the right regular expression operand and, if it does not match (case-insensitive), returns `true`. Otherwise returns `false`. ```sql SELECT 'Abc' !~* 'a.*' ``` |Utf8(“Abc”) !\~\* Utf8(“a.\*”)| |------------------------------| | false | | Operator | Meaning | | | --- | --- | --- | | Operator | Meaning | | | = | Equal to | | | <> | Not equal to | | | != | Not equal to | | | > | Greater than | | | >= | Greater than or equal to | | | < | Less than | | | <= | Less than or equal to | | | IS DISTINCT FROM | Is distinct from | | | IS NOT DISTINCT FROM | Is not distinct from | | | ~ | Matches a regular expression | | | ~* | Matches a regular expression (case-insensitive) | | | !~ | Does not match a regular expression | | | !~* | Does not match a regular expression (case-insensitive) | | | Int64(123) = Int64(123) | | --- | | Int64(123) = Int64(123) | | true | | Int64(123) != Int64(456) | | --- | | Int64(123) != Int64(456) | | true | | Int64(123) != Int64(456) | | --- | | Int64(123) != Int64(456) | | true | | Int64(3) > Int64(2) | | --- | | Int64(3) > Int64(2) | | true | | Int64(3) >= Int64(2) | | --- | | Int64(3) >= Int64(2) | | true | | Int641(1) < Int64(2) | | --- | | Int641(1) < Int64(2) | | true | | Int641(1) <= Int64(2) | | --- | | Int641(1) <= Int64(2) | | true | | Int64(0) IS DISTINCT FROM NULL | | --- | | Int64(0) IS DISTINCT FROM NULL | | true | | NULL IS NOT DISTINCT FROM NULL | | --- | | NULL IS NOT DISTINCT FROM NULL | | true | | Utf8(“abc”) ~ Utf8(“a.*”) | | --- | | Utf8(“abc”) ~ Utf8(“a.*”) | | true | | Utf8(“Abc”) ~* Utf8(“A.*”) | | --- | | Utf8(“Abc”) ~* Utf8(“A.*”) | | true | | Utf8(“abc”) !~ Utf8(“d.*”) | | --- | | Utf8(“abc”) !~ Utf8(“d.*”) | | true | | Utf8(“Abc”) !~* Utf8(“a.*”) | | --- | | Utf8(“Abc”) !~* Utf8(“a.*”) | | false | --- # SQL logical operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/logical/ Logical operators combine or manipulate conditions in a SQL query. |Operator | Meaning | | |---------|--------------------------------------------------------------------------|------------| | `AND` | Returns true if both operands are true. Otherwise, returns false. | [](#and) | |`BETWEEN`|Returns true if the left operand is within the range of the right operand.|[](#between)| |`EXISTS` | Returns true if the results of a subquery are not empty. |[](#exists) | | `IN` | Returns true if the left operand is in the right operand list. | [](#in) | | `LIKE` |Returns true if the left operand matches the right operand pattern string.| [](#like) | | `NOT` | Negates the subsequent expression. | [](#not) | | `OR` | Returns true if any operand is true. Otherwise, returns false. | [](#or) | > [!Note] > #### Sample data > > Query examples on this page use the following sample data sets: > > * [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data) > * [Home sensor actions sample data](/influxdb3/core/reference/sample-data/#home-sensor-actions-data) ## AND The `AND` operand returns `true` if both operands are `true`. Otherwise, it returns false. This operator is typically used in the [`WHERE` clause](/influxdb3/core/reference/sql/where/)to combine multiple conditions. ```sql SELECT true AND false AS "AND condition" ``` |AND condition| |-------------| | false | ##### Examples [](#and-operator-in-the-where-clause) `AND` operator in the `WHERE` clause ```sql SELECT * FROM home WHERE co > 10 AND room = 'Kitchen' ``` |co |hum | room |temp| time | |---|----|-------|----|--------------------| |18 |36.9|Kitchen|23.3|2022-01-01T18:00:00Z| |22 |36.6|Kitchen|23.1|2022-01-01T19:00:00Z| |26 |36.5|Kitchen|22.7|2022-01-01T20:00:00Z| ## BETWEEN The `BETWEEN` operator returns `true` if the left numeric operand is within the range specified in the right operand. Otherwise, it returns `false` ```sql SELECT 6 BETWEEN 5 AND 8 AS "BETWEEN condition" ``` |BETWEEN condition| |-----------------| | true | ##### Examples [](#between-operator-in-the-where-clause) `BETWEEN` operator in the `WHERE` clause ```sql SELECT * FROM home WHERE co BETWEEN 5 AND 10 ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 7 | 36 | Kitchen |22.4|2022-01-01T16:00:00Z| | 9 | 36 | Kitchen |22.7|2022-01-01T17:00:00Z| | 5 |35.9|Living Room|22.6|2022-01-01T17:00:00Z| | 9 |36.2|Living Room|22.8|2022-01-01T18:00:00Z| ## EXISTS The `EXISTS` operator returns `true` if result of a[correlated subquery](/influxdb3/core/reference/sql/subqueries/#correlated-subqueries)is not empty. Otherwise it returns `false`. *See [SQL subquery operators](/influxdb3/core/reference/sql/subqueries/#subquery-operators).* ##### Examples [](#exists-operator-with-a-subquery-in-the-where-clause) `EXISTS` operator with a subquery in the `WHERE` clause ```sql SELECT * FROM home home_actions WHERE EXISTS ( SELECT * FROM home WHERE home.co = home_actions.co - 1 ) ORDER BY time ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 1 |36.5| Kitchen |22.8|2022-01-01T13:00:00Z| | 1 |36.3| Kitchen |22.8|2022-01-01T14:00:00Z| | 1 |36.1|Living Room|22.3|2022-01-01T15:00:00Z| | 4 | 36 |Living Room|22.4|2022-01-01T16:00:00Z| | 5 |35.9|Living Room|22.6|2022-01-01T17:00:00Z| |18 |36.9| Kitchen |23.3|2022-01-01T18:00:00Z| ## IN The `IN` operator returns `true` if the left operand is in the right operand list or subquery result. Otherwise, it returns `false`. ```sql SELECT 'John' IN ('Jane', 'John') AS "IN condition" ``` |IN condition| |------------| | true | *See [SQL subquery operators](/influxdb3/core/reference/sql/subqueries/#subquery-operators).* ##### Examples [](#in-operator-with-a-list-in-the-where-clause) `IN` operator with a list in the `WHERE` clause ```sql SELECT * FROM home WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') LIMIT 4 ``` |co |hum | room |temp| time | |---|----|-------|----|--------------------| | 0 |35.9|Kitchen| 21 |2022-01-01T08:00:00Z| | 0 |36.2|Kitchen| 23 |2022-01-01T09:00:00Z| | 0 |36.1|Kitchen|22.7|2022-01-01T10:00:00Z| | 0 | 36 |Kitchen|22.4|2022-01-01T11:00:00Z| [](#in-operator-with-a-subquery-in-the-where-clause) `IN` operator with a subquery in the `WHERE` clause ```sql SELECT * FROM home WHERE room IN ( SELECT DISTINCT room FROM home_actions ) ORDER BY time LIMIT 4 ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 0 |35.9|Living Room|21.1|2022-01-01T08:00:00Z| | 0 |35.9| Kitchen | 21 |2022-01-01T08:00:00Z| | 0 |35.9|Living Room|21.4|2022-01-01T09:00:00Z| | 0 |36.2| Kitchen | 23 |2022-01-01T09:00:00Z| ## LIKE The `LIKE` operator returns `true` if the left operand matches the string pattern specified in the right operand.`LIKE` expressions support [SQL wildcard characters](#sql-wildcard-characters). ```sql SELECT 'John' LIKE 'J_%n' AS "LIKE condition" ``` |LIKE condition| |--------------| | true | [](#like-operator-in-the-where-clause) `LIKE` operator in the `WHERE` clause ```sql SELECT * FROM home WHERE room LIKE '%Room' LIMIT 4 ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 0 |35.9|Living Room|21.1|2022-01-01T08:00:00Z| | 0 |35.9|Living Room|21.4|2022-01-01T09:00:00Z| | 0 | 36 |Living Room|21.8|2022-01-01T10:00:00Z| | 0 | 36 |Living Room|22.2|2022-01-01T11:00:00Z| ### SQL wildcard characters The InfluxDB SQL implementation supports the following wildcard characters when using the `LIKE` operator to match strings to a pattern. |Character| Description | |---------|----------------------------------| | `%` |Represents zero or more characters| | `_` | Represents any single character | ## NOT The `NOT` operator negates the subsequent expression. ```sql SELECT NOT true AS "NOT condition" ``` |NOT condition| |-------------| | false | ##### Examples [](#not-in) `NOT IN` ```sql SELECT * FROM home WHERE room NOT IN ('Kitchen', 'Bathroom') LIMIT 4 ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 0 |35.9|Living Room|21.1|2022-01-01T08:00:00Z| | 0 |35.9|Living Room|21.4|2022-01-01T09:00:00Z| | 0 | 36 |Living Room|21.8|2022-01-01T10:00:00Z| | 0 | 36 |Living Room|22.2|2022-01-01T11:00:00Z| [](#not-exists) `NOT EXISTS` ```sql SELECT * FROM home home_actions WHERE NOT EXISTS ( SELECT * FROM home WHERE home.co = home_actions.co + 4 ) ORDER BY time ``` |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 7 | 36 | Kitchen |22.4|2022-01-01T16:00:00Z| | 4 | 36 |Living Room|22.4|2022-01-01T16:00:00Z| | 9 | 36 | Kitchen |22.7|2022-01-01T17:00:00Z| | 9 |36.2|Living Room|22.8|2022-01-01T18:00:00Z| |17 |36.4|Living Room|22.2|2022-01-01T20:00:00Z| |26 |36.5| Kitchen |22.7|2022-01-01T20:00:00Z| [](#not-between) `NOT BETWEEN` ```sql SELECT * FROM home WHERE co NOT BETWEEN 1 AND 22 AND room = 'Kitchen' ``` |co |hum | room |temp| time | |---|----|-------|----|--------------------| | 0 |35.9|Kitchen| 21 |2022-01-01T08:00:00Z| | 0 |36.2|Kitchen| 23 |2022-01-01T09:00:00Z| | 0 |36.1|Kitchen|22.7|2022-01-01T10:00:00Z| | 0 | 36 |Kitchen|22.4|2022-01-01T11:00:00Z| | 0 | 36 |Kitchen|22.5|2022-01-01T12:00:00Z| |26 |36.5|Kitchen|22.7|2022-01-01T20:00:00Z| ## OR The `OR` operator returns `true` if any operand is `true`. Otherwise, it returns `false`. This operator is typically used in the [`WHERE` clause](/influxdb3/core/reference/sql/where/)to combine multiple conditions. ```sql SELECT true OR false AS "OR condition" ``` |OR condition| |------------| | true | ##### Examples [](#or-in-the-where-clause) `OR` in the `WHERE` clause ```sql SELECT * FROM home WHERE co > 20 OR temp > 23 ``` |co |hum | room |temp| time | |---|----|-------|----|--------------------| |18 |36.9|Kitchen|23.3|2022-01-01T18:00:00Z| |22 |36.6|Kitchen|23.1|2022-01-01T19:00:00Z| |26 |36.5|Kitchen|22.7|2022-01-01T20:00:00Z| #### Related * [WHERE clause](/influxdb3/core/reference/sql/where/) * [Subquery operators](/influxdb3/core/reference/sql/subqueries/#subquery-operators) | Operator | Meaning | | | --- | --- | --- | | Operator | Meaning | | | AND | Returns true if both operands are true. Otherwise, returns false. | | | BETWEEN | Returns true if the left operand is within the range of the right operand. | | | EXISTS | Returns true if the results of a subquery are not empty. | | | IN | Returns true if the left operand is in the right operand list. | | | LIKE | Returns true if the left operand matches the right operand pattern string. | | | NOT | Negates the subsequent expression. | | | OR | Returns true if any operand is true. Otherwise, returns false. | | | AND condition | | --- | | AND condition | | false | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | | 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | | BETWEEN condition | | --- | | BETWEEN condition | | true | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | | 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | | 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | | 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | | 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | | 1 | 36.1 | Living Room | 22.3 | 2022-01-01T15:00:00Z | | 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | | 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | | 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | | IN condition | | --- | | IN condition | | true | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | | 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | | 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | | 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | | 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | | 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | | 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | | LIKE condition | | --- | | LIKE condition | | true | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | | 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | | 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | | 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | | Character | Description | | --- | --- | | Character | Description | | % | Represents zero or more characters | | _ | Represents any single character | | NOT condition | | --- | | NOT condition | | false | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | | 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | | 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | | 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | | 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | | 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | | 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | | 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | | 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | | 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | | 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | | 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | | OR condition | | --- | | OR condition | | true | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | | 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | --- # Other SQL operators Source: https://docs.influxdata.com/influxdb3/core/reference/sql/operators/other/ SQL supports miscellaneous operators that perform various operations. |Operator| Meaning | | |--------|-------------------|------------------------| | `||` |Concatenate strings|[](#concatenate-strings)| || ---------- The `||` operator concatenates two string operands into a single string. ```sql SELECT 'Hello' || ' world' AS "Concatenated" ``` |Concatenated| |------------| |Hello world | ## AT TIME ZONE The `AT TIME ZONE` operator takes the timestamp in the left operand and returns an equivalent timestamp with the updated time and offset of the time zone specified in the right operand. If no time zone is included in the input timestamp’s[Arrow data type](/influxdb3/core/reference/sql/data-types/#sql-and-arrow-data-types), the operator assumes the time is in the time zone specified. Time zone offsets are provided by the operating system time zone database. ```sql SELECT time AT TIME ZONE 'America/Los_Angeles' FROM home ``` [](#convert-a-utc-timestamp-to-a-specified-timezone) Convert a UTC timestamp to a specified timezone ```sql SELECT arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))') AT TIME ZONE 'America/Los_Angeles' AS 'Time with TZ offset' ``` | Time with TZ offset | |-------------------------| |2023-12-31T16:00:00-08:00| [](#add-a-time-zone-offset-to-a-timestamp-without-a-specified-timezone) Add a time zone offset to a timestamp without a specified timezone ```sql SELECT '2024-01-01 00:00:00' AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` |Local time with TZ offset| |-------------------------| |2024-01-01T00:00:00-08:00| | Operator | Meaning | | | --- | --- | --- | | Operator | Meaning | | | || | Concatenate strings | | | Concatenated | | --- | | Concatenated | | Hello world | | Time with TZ offset | | --- | | Time with TZ offset | | 2023-12-31T16:00:00-08:00 | | Local time with TZ offset | | --- | | Local time with TZ offset | | 2024-01-01T00:00:00-08:00 | --- # ORDER BY clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/order-by/ The `ORDER BY` clause sort results by specified columns and order. Sort data based on fields, tags, and timestamps. The following orders are supported: * `ASC`: ascending *(default)* * `DESC`: descending * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql [SELECT CLAUSE] [FROM CLAUSE] [ ORDER BY expression [ ASC | DESC ][, …] ] ``` > [!Note] > **Note:** If your query includes a `GROUP BY` clause, the `ORDER BY` clause > must appear **after** the `GROUP BY` clause. ## Examples ### Sort data by time with the most recent first ``` SELECT "water_level", "time" FROM "h2o_feet" WHERE "location" = 'coyote_creek' ORDER BY time DESC ``` [](#view-example-results) View example results | time |water\_level| |------------------------|------------| |2019-09-17T16:24:00.000Z| 3.235 | |2019-09-17T16:18:00.000Z| 3.314 | |2019-09-17T16:12:00.000Z| 3.402 | |2019-09-17T16:06:00.000Z| 3.497 | |2019-09-17T16:00:00.000Z| 3.599 | |2019-09-17T15:54:00.000Z| 3.704 | ### Sort data by tag or field values ``` SELECT "water_level", "time", "location" FROM "h2o_feet" ORDER BY "location", "water_level" DESC ``` ### Sort data by selection order ```sql SELECT "location","water_level", "time" FROM "h2o_feet" ORDER BY 1, 2 ``` [](#view-example-results) View example results The query sorts results the location of a column in the `SELECT` statement: first by `location` (1), and second by `water_level` (2). | location | time |water\_level| |-------------|------------------------|------------| |coyote\_creek|2019-08-28T14:30:00.000Z| \-0.61 | |coyote\_creek|2019-08-29T15:18:00.000Z| \-0.594 | |coyote\_creek|2019-08-28T14:36:00.000Z| \-0.591 | |coyote\_creek|2019-08-28T14:24:00.000Z| \-0.587 | |coyote\_creek|2019-08-29T15:24:00.000Z| \-0.571 | |coyote\_creek|2019-08-27T13:42:00.000Z| \-0.561 | | time | water_level | | --- | --- | | time | water_level | | 2019-09-17T16:24:00.000Z | 3.235 | | 2019-09-17T16:18:00.000Z | 3.314 | | 2019-09-17T16:12:00.000Z | 3.402 | | 2019-09-17T16:06:00.000Z | 3.497 | | 2019-09-17T16:00:00.000Z | 3.599 | | 2019-09-17T15:54:00.000Z | 3.704 | | location | time | water_level | | --- | --- | --- | | location | time | water_level | | coyote_creek | 2019-08-28T14:30:00.000Z | -0.61 | | coyote_creek | 2019-08-29T15:18:00.000Z | -0.594 | | coyote_creek | 2019-08-28T14:36:00.000Z | -0.591 | | coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | | coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | | coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | --- # SELECT statement Source: https://docs.influxdata.com/influxdb3/core/reference/sql/select/ Use the `SELECT` statement to query data from an InfluxDB measurement. The `SELECT` clause is required when querying data in SQL. * [Syntax](#syntax) * [Examples](#examples) ### Syntax ```sql SELECT a, b, "time" FROM ``` The SELECT clause supports the following: * `SELECT *` - return all tags, fields and timestamps. * `SELECT DISTINCT` to return all distinct (different) values. * `SELECT <"field" or "tag">` - returns a specified field or tag. * `SELECT <"field" or "tag">, <"field" or "tag">` - returns more than one tag or field. * `SELECT <"field"> AS a `- return the field as the alias. ## Examples The following examples use data from the NOAA database. To download the NOAA test data see [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). ### Select all fields and tags from a measurement ```sql SELECT * FROM h2o_feet LIMIT 10 ``` [](#view-example-results) View example results | level description | location | time |water\_level| |-------------------------|-------------|------------------------|------------| |at or greater than 9 feet|coyote\_creek|2019-09-01T00:00:00.000Z|9.126144144 | |at or greater than 9 feet|coyote\_creek|2019-09-01T00:06:00.000Z| 9.009 | | between 6 and 9 feet |coyote\_creek|2019-09-01T00:12:00.000Z| 8.862 | | between 6 and 9 feet |coyote\_creek|2019-09-01T00:18:00.000Z| 8.714 | ### Select specific tags and fields from a measurement ```sql SELECT "location", "water_level" FROM "h2o_feet" ``` [](#view-example-results-1) View example results | location |water\_level| |-------------|------------| |coyote\_creek|9.126144144 | |coyote\_creek| 9.009 | |coyote\_creek| 8.862 | |coyote\_creek| 8.714 | |coyote\_creek| 8.547 | ### Select a field, tag and timestamp from a measurement ```sql SELECT "water_level", "location", "time" FROM "h2o_feet" ``` [](#view-example-results-2) View example results | location | time |water\_level| |-------------|------------------------|------------| |coyote\_creek|2019-08-20T00:00:00.000Z| 8.638 | |coyote\_creek|2019-08-20T00:06:00.000Z| 8.658 | |coyote\_creek|2019-08-20T00:12:00.000Z| 8.678 | ### Select a field and perform basic arithmetic The following query takes the value of water\_level, multiplies it by 3 and adds 5 to the result. ```sql SELECT ("water_level" * 3) + 5 FROM "h2o_feet" ``` [](#view-example-results-3) View example results | water\_level | |------------------| | 30.128 | |30.641000000000002| |31.142000000000003| | 31.586 | | 32.027 | | 32.378432432 | #### Related * [Subqueries](/influxdb3/core/reference/sql/subqueries/) | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | at or greater than 9 feet | coyote_creek | 2019-09-01T00:00:00.000Z | 9.126144144 | | at or greater than 9 feet | coyote_creek | 2019-09-01T00:06:00.000Z | 9.009 | | between 6 and 9 feet | coyote_creek | 2019-09-01T00:12:00.000Z | 8.862 | | between 6 and 9 feet | coyote_creek | 2019-09-01T00:18:00.000Z | 8.714 | | location | water_level | | --- | --- | | location | water_level | | coyote_creek | 9.126144144 | | coyote_creek | 9.009 | | coyote_creek | 8.862 | | coyote_creek | 8.714 | | coyote_creek | 8.547 | | location | time | water_level | | --- | --- | --- | | location | time | water_level | | coyote_creek | 2019-08-20T00:00:00.000Z | 8.638 | | coyote_creek | 2019-08-20T00:06:00.000Z | 8.658 | | coyote_creek | 2019-08-20T00:12:00.000Z | 8.678 | | water_level | | --- | | water_level | | 30.128 | | 30.641000000000002 | | 31.142000000000003 | | 31.586 | | 32.027 | | 32.378432432 | --- # Subqueries Source: https://docs.influxdata.com/influxdb3/core/reference/sql/subqueries/ Subqueries (also known as inner queries or nested queries) are queries within a query. Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. * [Subquery operators](#subquery-operators) * [[ NOT ] EXISTS](#-not--exists) * [[ NOT ] IN](#-not--in) * [SELECT clause subqueries](#select-clause-subqueries) * [FROM clause subqueries](#from-clause-subqueries) * [WHERE clause subqueries](#where-clause-subqueries) * [HAVING clause subqueries](#having-clause-subqueries) * [Subquery categories](#subquery-categories) * [Correlated subqueries](#correlated-subqueries) * [Non-correlated subqueries](#non-correlated-subqueries) * [Scalar subqueries](#scalar-subqueries) * [Non-scalar subqueries](#non-scalar-subqueries) > [!Note] > #### Sample data > > Query examples on this page use the following sample data sets: > > * [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data) > * [Home sensor actions sample data](/influxdb3/core/reference/sample-data/#home-sensor-actions-data) > * [NOAA Bay Area weather sample data](/influxdb3/core/reference/sample-data/#noaa-bay-area-weather-data) ## Subquery operators * [[ NOT ] EXISTS](#-not--exists) * [[ NOT ] IN](#-not--in) ### [ NOT ] EXISTS The `EXISTS` operator returns all rows where a*[correlated subquery](#correlated-subqueries)* produces one or more matches for that row. `NOT EXISTS` returns all rows where a *correlated subquery* produces zero matches for that row. Only *correlated subqueries* are supported. #### Syntax ```sql [NOT] EXISTS (subquery) ``` ### [ NOT ] IN The `IN` operator returns all rows where a given expression’s value can be found in the results of a *[correlated subquery](#correlated-subqueries)*.`NOT IN` returns all rows where a given expression’s value cannot be found in the results of a subquery or list of values. #### Syntax ```sql expression [NOT] IN (subquery|list-literal) ``` #### Examples [](#view-in-examples-using-a-query) View `IN` examples using a query #### IN #### ```sql SELECT time, room, temp FROM home WHERE room IN ( SELECT DISTINCT room FROM home_actions ) ``` ```sql SELECT time, room, temp FROM home WHERE room NOT IN ( SELECT DISTINCT room FROM home_actions ) ``` [](#view-in-examples-using-a-list-literal) View `IN` examples using a list literal #### IN #### ```sql SELECT time, room, temp FROM home WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') ``` ```sql SELECT time, room, temp FROM home WHERE room NOT IN ('Bathroom', 'Bedroom', 'Kitchen') ``` ## SELECT clause subqueries `SELECT` clause subqueries use values returned from the inner query as part of the outer query’s `SELECT` list. The `SELECT` clause only supports [scalar subqueries](#scalar-subqueries) that return a single value per execution of the inner query. The returned value can be unique per row. ### Syntax ```sql SELECT [expression1[, expression2, ..., expressionN],] () ``` > [!Note] > `SELECT` clause subqueries can be used as an alternative to `JOIN` operations. ### Examples [](#select-clause-with-correlated-subquery) `SELECT` clause with correlated subquery ```sql SELECT time, room, co, ( SELECT MAX(description) FROM home_actions WHERE time = home.time AND room = home.room AND level != 'ok' ) AS "Alert Description" FROM home ORDER BY room, time ``` #### Inner query results Because the inner query is a [correlated subquery](#correlated-subqueries), the result depends on the values of `room` and `time` columns in the outer query. The results below represent the action description for each `room` and `time`combination with a `level` value that does not equal `ok`. | time | room | MAX(home\_actions.description) | |--------------------|-----------|-------------------------------------------| |2022-01-01T18:00:00Z| Kitchen |Carbon monoxide level above normal: 18 ppm.| |2022-01-01T19:00:00Z| Kitchen |Carbon monoxide level above normal: 22 ppm.| |2022-01-01T20:00:00Z| Kitchen |Carbon monoxide level above normal: 26 ppm.| |2022-01-01T19:00:00Z|Living Room|Carbon monoxide level above normal: 14 ppm.| |2022-01-01T20:00:00Z|Living Room|Carbon monoxide level above normal: 17 ppm.| #### Outer query results | time | room |co | Alert Description | |--------------------|-----------|---|-------------------------------------------| |2022-01-01T08:00:00Z| Kitchen | 0 | | |2022-01-01T09:00:00Z| Kitchen | 0 | | |2022-01-01T10:00:00Z| Kitchen | 0 | | |2022-01-01T11:00:00Z| Kitchen | 0 | | |2022-01-01T12:00:00Z| Kitchen | 0 | | |2022-01-01T13:00:00Z| Kitchen | 1 | | |2022-01-01T14:00:00Z| Kitchen | 1 | | |2022-01-01T15:00:00Z| Kitchen | 3 | | |2022-01-01T16:00:00Z| Kitchen | 7 | | |2022-01-01T17:00:00Z| Kitchen | 9 | | |2022-01-01T18:00:00Z| Kitchen |18 |Carbon monoxide level above normal: 18 ppm.| |2022-01-01T19:00:00Z| Kitchen |22 |Carbon monoxide level above normal: 22 ppm.| |2022-01-01T20:00:00Z| Kitchen |26 |Carbon monoxide level above normal: 26 ppm.| |2022-01-01T08:00:00Z|Living Room| 0 | | |2022-01-01T09:00:00Z|Living Room| 0 | | |2022-01-01T10:00:00Z|Living Room| 0 | | |2022-01-01T11:00:00Z|Living Room| 0 | | |2022-01-01T12:00:00Z|Living Room| 0 | | |2022-01-01T13:00:00Z|Living Room| 0 | | |2022-01-01T14:00:00Z|Living Room| 0 | | |2022-01-01T15:00:00Z|Living Room| 1 | | |2022-01-01T16:00:00Z|Living Room| 4 | | |2022-01-01T17:00:00Z|Living Room| 5 | | |2022-01-01T18:00:00Z|Living Room| 9 | | |2022-01-01T19:00:00Z|Living Room|14 |Carbon monoxide level above normal: 14 ppm.| |2022-01-01T20:00:00Z|Living Room|17 |Carbon monoxide level above normal: 17 ppm.| ## FROM clause subqueries `FROM` clause subqueries return a set of results that is then queried and operated on by the outer query. ### Syntax ```sql SELECT expression1[, expression2, ..., expressionN] FROM () ``` ### Examples [](#view-from-clause-subquery-example) View `FROM` clause subquery example The following query returns the average of maximum values per room. The inner query returns the maximum value for each field from each room. The outer query uses the results of the inner query and returns the average maximum value for each field. ```sql SELECT AVG(max_co) AS avg_max_co, AVG(max_hum) AS avg_max_hum, AVG(max_temp) AS avg_max_temp FROM ( SELECT room, MAX(co) AS max_co, MAX(hum) AS max_hum, MAX(temp) AS max_temp FROM home GROUP BY room ) ``` #### Inner query results | room |max\_co|max\_hum|max\_temp| |-----------|-------|--------|---------| |Living Room| 17 | 36.4 | 22.8 | | Kitchen | 26 | 36.9 | 23.3 | #### Outer query results |avg\_max\_co|avg\_max\_hum|avg\_max\_temp| |------------|-------------|--------------| | 21.5 | 36.7 | 23.1 | ## WHERE clause subqueries [`WHERE` clause](/influxdb3/core/reference/sql/where/) subqueries compare an expression to the result of the subquery and return *true* or *false*. Rows that evaluate to *false* or NULL are filtered from results. The `WHERE` clause supports correlated and non-correlated subqueries as well as scalar and non-scalar subqueries (depending on the the operator used in the predicate expression). ### Syntax ```sql SELECT expression1[, expression2, ..., expressionN] FROM WHERE expression operator () ``` > [!Note] > `WHERE` clause subqueries can be used as an alternative to `JOIN` operations. ### Examples [](#where-clause-with-scalar-subquery) `WHERE` clause with scalar subquery The following query returns all points with `temp` values above the average of all `temp` values. The subquery returns the average `temp` value. ```sql SELECT * FROM home WHERE temp > ( SELECT AVG(temp) FROM home ) ``` #### Inner query result | AVG(home.temp) | |------------------| |22.396153846153844| #### Outer query result |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 0 |36.2| Kitchen | 23 |2022-01-01T09:00:00Z| | 0 |36.1| Kitchen |22.7|2022-01-01T10:00:00Z| | 0 | 36 | Kitchen |22.4|2022-01-01T11:00:00Z| | 0 | 36 | Kitchen |22.5|2022-01-01T12:00:00Z| | 1 |36.5| Kitchen |22.8|2022-01-01T13:00:00Z| | 1 |36.3| Kitchen |22.8|2022-01-01T14:00:00Z| | 3 |36.2| Kitchen |22.7|2022-01-01T15:00:00Z| | 7 | 36 | Kitchen |22.4|2022-01-01T16:00:00Z| | 9 | 36 | Kitchen |22.7|2022-01-01T17:00:00Z| |18 |36.9| Kitchen |23.3|2022-01-01T18:00:00Z| |22 |36.6| Kitchen |23.1|2022-01-01T19:00:00Z| |26 |36.5| Kitchen |22.7|2022-01-01T20:00:00Z| | 0 | 36 |Living Room|22.4|2022-01-01T13:00:00Z| | 4 | 36 |Living Room|22.4|2022-01-01T16:00:00Z| | 5 |35.9|Living Room|22.6|2022-01-01T17:00:00Z| | 9 |36.2|Living Room|22.8|2022-01-01T18:00:00Z| |14 |36.3|Living Room|22.5|2022-01-01T19:00:00Z| [](#where-clause-with-non-scalar-subquery) `WHERE` clause with non-scalar subquery Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and can only return a single column. The values in the returned column are evaluated as a list. The following query returns all points in the `home` measurement associated with the same timestamps as `warn` level alerts in the `home_actions` measurement. ```sql SELECT * FROM home WHERE time IN ( SELECT DISTINCT time FROM home_actions WHERE level = 'warn' ) ``` #### Inner query result | time | |--------------------| |2022-01-01T18:00:00Z| |2022-01-01T19:00:00Z| |2022-01-01T20:00:00Z| #### Outer query result |co |hum | room |temp| time | |---|----|-----------|----|--------------------| |18 |36.9| Kitchen |23.3|2022-01-01T18:00:00Z| | 9 |36.2|Living Room|22.8|2022-01-01T18:00:00Z| |26 |36.5| Kitchen |22.7|2022-01-01T20:00:00Z| |17 |36.4|Living Room|22.2|2022-01-01T20:00:00Z| |22 |36.6| Kitchen |23.1|2022-01-01T19:00:00Z| |14 |36.3|Living Room|22.5|2022-01-01T19:00:00Z| [](#where-clause-with-correlated-subquery) `WHERE` clause with correlated subquery The following query returns rows with temperature values greater than the median temperature value for each room. The subquery in the `WHERE` clause uses the`room` value from the outer query to return the median `temp` value for that specific room. ```sql SELECT time, room, temp FROM home outer_query WHERE temp > ( SELECT median(temp) AS temp FROM home WHERE room = outer_query.room GROUP BY room ) ORDER BY room, time ``` #### Inner query result The result of the inner query depends on the value of `room` in the outer query, but the following table contains the median `temp` value for each room. | room |temp| |-----------|----| |Living Room|22.3| | Kitchen |22.7| #### Outer query result | time | room |temp| |--------------------|-----------|----| |2022-01-01T09:00:00Z| Kitchen | 23 | |2022-01-01T13:00:00Z| Kitchen |22.8| |2022-01-01T14:00:00Z| Kitchen |22.8| |2022-01-01T18:00:00Z| Kitchen |23.3| |2022-01-01T19:00:00Z| Kitchen |23.1| |2022-01-01T13:00:00Z|Living Room|22.4| |2022-01-01T16:00:00Z|Living Room|22.4| |2022-01-01T17:00:00Z|Living Room|22.6| |2022-01-01T18:00:00Z|Living Room|22.8| |2022-01-01T19:00:00Z|Living Room|22.5| ## HAVING clause subqueries [`HAVING` clause](/influxdb3/core/reference/sql/having/) subqueries compare an expression that uses aggregate values returned by aggregate functions in the `SELECT` clause to the result of the subquery and return *true* or *false*. Rows that evaluate to *false* or NULL are filtered from results. The `HAVING` clause supports correlated and non-correlated subqueries as well as scalar and non-scalar subqueries (depending on the the operator used in the predicate expression). ### Syntax ```sql SELECT aggregate_expression1[, aggregate_expression2, ..., aggregate_expressionN] FROM WHERE GROUP BY column_expression1[, column_expression2, ..., column_expressionN] HAVING expression operator () ``` ### Examples [](#having-clause-with-scalar-subquery) `HAVING` clause with scalar subquery The following query returns all two hour blocks of time with average `temp` values greater then the median `temp` value. ```sql SELECT DATE_BIN(INTERVAL '2 hours', time) AS "2-hour block", AVG(temp) AS avg_temp FROM home GROUP BY 1 HAVING avg_temp > ( SELECT MEDIAN(temp) FROM home ) ``` #### Inner query result |MEDIAN(home.temp)| |-----------------| | 22.45 | #### Outer query result | 2-hour block |avg\_temp| |--------------------|---------| |2022-01-01T12:00:00Z| 22.475 | |2022-01-01T16:00:00Z| 22.525 | |2022-01-01T18:00:00Z| 22.925 | |2022-01-01T14:00:00Z| 22.525 | [](#having-clause-with-non-scalar-subquery) `HAVING` clause with non-scalar subquery Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and can only return a single column. The values in the returned column are evaluated as a list. The following query returns the maximum `co` and `temp` values within 2-hour windows of time where the `time` value associated with time window is also associated with a warning in the `home_actions` measurement. ```sql SELECT date_bin(INTERVAL '2 hours', time) AS "2-hour block", max(co) AS max_co, max(temp) as max_temp FROM home GROUP BY 1, room HAVING "2-hour block" IN ( SELECT DISTINCT time FROM home_actions WHERE level = 'warn' ) ``` #### Inner query result | time | |--------------------| |2022-01-01T18:00:00Z| |2022-01-01T19:00:00Z| |2022-01-01T20:00:00Z| #### Outer query result | 2-hour block |max\_co|max\_temp| |--------------------|-------|---------| |2022-01-01T18:00:00Z| 14 | 22.8 | |2022-01-01T18:00:00Z| 22 | 23.3 | |2022-01-01T20:00:00Z| 17 | 22.2 | |2022-01-01T20:00:00Z| 26 | 22.7 | [](#having-clause-with-correlated-subquery) `HAVING` clause with correlated subquery The following query returns 2-hour windows of time with average `temp` values greater than the median `temp` value for each room. The subquery in the `HAVING`clause uses the `room` value from the outer query to return the median `temp` value for that specific room. ```sql SELECT time, room, temp FROM home outer_query WHERE temp > ( SELECT median(temp) AS temp FROM home WHERE room = outer_query.room GROUP BY room ) ORDER BY room, time ``` #### Inner query result The result of the inner query depends on the value of `room` in the outer query, but the following table contains the median `temp` value for each room. | room |temp| |-----------|----| |Living Room|22.3| | Kitchen |22.7| #### Outer query result | 2-hour block | room | avg\_temp | |--------------------|-----------|------------------| |2022-01-01T14:00:00Z| Kitchen | 22.75 | |2022-01-01T18:00:00Z| Kitchen |23.200000000000003| |2022-01-01T16:00:00Z|Living Room| 22.5 | |2022-01-01T18:00:00Z|Living Room| 22.65 | ## Subquery categories SQL subqueries can be categorized as one or more of the following based on the behavior of the subquery: * [correlated](#correlated-subqueries) or [non-correlated](#non-correlated-subqueries) * [scalar](#scalar-subqueries) or [non-scalar](#non-scalar-subqueries) ### Correlated subqueries In a **correlated** subquery, the inner query depends on the values of the current row being processed. In the query below, the inner query (`SELECT temp_avg FROM weather WHERE location = home.room`) depends on data (`home.room`) from the outer query (`SELECT time, room, temp FROM home`) and is therefore a *correlated* subquery. ```sql SELECT time, room, temp FROM home WHERE temp = ( SELECT temp_avg FROM weather WHERE location = home.room ) ``` > [!Important] > #### Correlated subquery performance > > Because correlated subqueries depend on the outer query and typically must > execute for each row returned by the outer query, correlated subqueries are**less performant** than non-correlated subqueries. ### Non-correlated subqueries In a **non-correlated** subquery, the inner query *doesn’t* depend on the outer query and executes independently. The inner query executes first, and then passes the results to the outer query. In the query below, the inner query (`SELECT MIN(temp_avg) FROM weather`) can run independently from the outer query (`SELECT time, temp FROM home`) and is therefore a *non-correlated* subquery. ```sql SELECT time, temp FROM home WHERE temp < ( SELECT MIN(temp_avg) FROM weather ) ``` ### Scalar subqueries A **scalar** subquery returns a single value (one column of one row). If no rows are returned, the subquery returns NULL. The example subquery below returns the average value of a specified column. This value is a single scalar value. ```sql SELECT * FROM home WHERE co > (SELECT avg(co) FROM home) ``` ### Non-scalar subqueries A **non-scalar** subquery returns 0, 1, or multiple rows, each of which may contain 1 or multiple columns. For each column, if there is no value to return, the subquery returns NULL. If no rows qualify to be returned, the subquery returns 0 rows. The example subquery below returns all distinct values in a column. Multiple values are returned. ```sql SELECT * FROM home WHERE room IN (SELECT DISTINCT room FROM home_actions) ``` #### Related * [Query data with SQL](/influxdb3/core/query-data/sql/) * [SELECT statement](/influxdb3/core/reference/sql/select/) * [WHERE clause](/influxdb3/core/reference/sql/where/) * [HAVING clause](/influxdb3/core/reference/sql/having/) | time | room | MAX(home_actions.description) | | --- | --- | --- | | time | room | MAX(home_actions.description) | | 2022-01-01T18:00:00Z | Kitchen | Carbon monoxide level above normal: 18 ppm. | | 2022-01-01T19:00:00Z | Kitchen | Carbon monoxide level above normal: 22 ppm. | | 2022-01-01T20:00:00Z | Kitchen | Carbon monoxide level above normal: 26 ppm. | | 2022-01-01T19:00:00Z | Living Room | Carbon monoxide level above normal: 14 ppm. | | 2022-01-01T20:00:00Z | Living Room | Carbon monoxide level above normal: 17 ppm. | | time | room | co | Alert Description | | --- | --- | --- | --- | | time | room | co | Alert Description | | 2022-01-01T08:00:00Z | Kitchen | 0 | | | 2022-01-01T09:00:00Z | Kitchen | 0 | | | 2022-01-01T10:00:00Z | Kitchen | 0 | | | 2022-01-01T11:00:00Z | Kitchen | 0 | | | 2022-01-01T12:00:00Z | Kitchen | 0 | | | 2022-01-01T13:00:00Z | Kitchen | 1 | | | 2022-01-01T14:00:00Z | Kitchen | 1 | | | 2022-01-01T15:00:00Z | Kitchen | 3 | | | 2022-01-01T16:00:00Z | Kitchen | 7 | | | 2022-01-01T17:00:00Z | Kitchen | 9 | | | 2022-01-01T18:00:00Z | Kitchen | 18 | Carbon monoxide level above normal: 18 ppm. | | 2022-01-01T19:00:00Z | Kitchen | 22 | Carbon monoxide level above normal: 22 ppm. | | 2022-01-01T20:00:00Z | Kitchen | 26 | Carbon monoxide level above normal: 26 ppm. | | 2022-01-01T08:00:00Z | Living Room | 0 | | | 2022-01-01T09:00:00Z | Living Room | 0 | | | 2022-01-01T10:00:00Z | Living Room | 0 | | | 2022-01-01T11:00:00Z | Living Room | 0 | | | 2022-01-01T12:00:00Z | Living Room | 0 | | | 2022-01-01T13:00:00Z | Living Room | 0 | | | 2022-01-01T14:00:00Z | Living Room | 0 | | | 2022-01-01T15:00:00Z | Living Room | 1 | | | 2022-01-01T16:00:00Z | Living Room | 4 | | | 2022-01-01T17:00:00Z | Living Room | 5 | | | 2022-01-01T18:00:00Z | Living Room | 9 | | | 2022-01-01T19:00:00Z | Living Room | 14 | Carbon monoxide level above normal: 14 ppm. | | 2022-01-01T20:00:00Z | Living Room | 17 | Carbon monoxide level above normal: 17 ppm. | | room | max_co | max_hum | max_temp | | --- | --- | --- | --- | | room | max_co | max_hum | max_temp | | Living Room | 17 | 36.4 | 22.8 | | Kitchen | 26 | 36.9 | 23.3 | | avg_max_co | avg_max_hum | avg_max_temp | | --- | --- | --- | | avg_max_co | avg_max_hum | avg_max_temp | | 21.5 | 36.7 | 23.1 | | AVG(home.temp) | | --- | | AVG(home.temp) | | 22.396153846153844 | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | | 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | | 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | | 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | | 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | | 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | | 3 | 36.2 | Kitchen | 22.7 | 2022-01-01T15:00:00Z | | 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | | 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | | 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | | 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | | 0 | 36 | Living Room | 22.4 | 2022-01-01T13:00:00Z | | 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | | 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | | 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | | 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | | time | | --- | | time | | 2022-01-01T18:00:00Z | | 2022-01-01T19:00:00Z | | 2022-01-01T20:00:00Z | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | | 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | | 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | | 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | | 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | | 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | | room | temp | | --- | --- | | room | temp | | Living Room | 22.3 | | Kitchen | 22.7 | | time | room | temp | | --- | --- | --- | | time | room | temp | | 2022-01-01T09:00:00Z | Kitchen | 23 | | 2022-01-01T13:00:00Z | Kitchen | 22.8 | | 2022-01-01T14:00:00Z | Kitchen | 22.8 | | 2022-01-01T18:00:00Z | Kitchen | 23.3 | | 2022-01-01T19:00:00Z | Kitchen | 23.1 | | 2022-01-01T13:00:00Z | Living Room | 22.4 | | 2022-01-01T16:00:00Z | Living Room | 22.4 | | 2022-01-01T17:00:00Z | Living Room | 22.6 | | 2022-01-01T18:00:00Z | Living Room | 22.8 | | 2022-01-01T19:00:00Z | Living Room | 22.5 | | MEDIAN(home.temp) | | --- | | MEDIAN(home.temp) | | 22.45 | | 2-hour block | avg_temp | | --- | --- | | 2-hour block | avg_temp | | 2022-01-01T12:00:00Z | 22.475 | | 2022-01-01T16:00:00Z | 22.525 | | 2022-01-01T18:00:00Z | 22.925 | | 2022-01-01T14:00:00Z | 22.525 | | time | | --- | | time | | 2022-01-01T18:00:00Z | | 2022-01-01T19:00:00Z | | 2022-01-01T20:00:00Z | | 2-hour block | max_co | max_temp | | --- | --- | --- | | 2-hour block | max_co | max_temp | | 2022-01-01T18:00:00Z | 14 | 22.8 | | 2022-01-01T18:00:00Z | 22 | 23.3 | | 2022-01-01T20:00:00Z | 17 | 22.2 | | 2022-01-01T20:00:00Z | 26 | 22.7 | | room | temp | | --- | --- | | room | temp | | Living Room | 22.3 | | Kitchen | 22.7 | | 2-hour block | room | avg_temp | | --- | --- | --- | | 2-hour block | room | avg_temp | | 2022-01-01T14:00:00Z | Kitchen | 22.75 | | 2022-01-01T18:00:00Z | Kitchen | 23.200000000000003 | | 2022-01-01T16:00:00Z | Living Room | 22.5 | | 2022-01-01T18:00:00Z | Living Room | 22.65 | --- # Table value constructor Source: https://docs.influxdata.com/influxdb3/core/reference/sql/table-value-constructor/ The table value constructor (TVC) uses the `VALUES` keyword to specify a set of row value expressions to construct into a table. The TVC can be used in the `FROM` clause to build an ad hoc table at query time. ```sql VALUES (row_value_list)[,...n] ``` ##### Arguments * **row\_value\_list**: Comma-delimited list of column values. Enclose each list in parentheses and separate multiple lists with commas. Each list must have the same number of values and values must be in the same order as columns in the table. Each list must contain a value for each column. ## Usage ```sql SELECT expression[,...n] FROM (VALUES (row_value_list)[,...n]) [AS] table_name(column_name[,...n]) ``` > [!Note] > When using the TVC, the `AS` keyword is optional and implied when naming the > table and providing column names. ## Examples * [Select data from an ad hoc table](#select-data-from-an-ad-hoc-table) ### Select data from an ad hoc table ```sql SELECT * FROM (VALUES ('2023-01-01 12:00:00'::TIMESTAMP, 1.23, 4.56), ('2023-01-01 13:00:00'::TIMESTAMP, 2.46, 8.1), ('2023-01-01 13:00:00'::TIMESTAMP, 4.81, 16.2) ) AS data(time, f1, f2) ``` | time | f1 | f2 | |--------------------|----|----| |2023-01-01T12:00:00Z|1.23|4.56| |2023-01-01T13:00:00Z|2.46|8.1 | |2023-01-01T13:00:00Z|4.81|16.2| | time | f1 | f2 | | --- | --- | --- | | time | f1 | f2 | | 2023-01-01T12:00:00Z | 1.23 | 4.56 | | 2023-01-01T13:00:00Z | 2.46 | 8.1 | | 2023-01-01T13:00:00Z | 4.81 | 16.2 | --- # UNION clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/union/ The `UNION` clause combines the results of two or more `SELECT` statements into a single result set. By default, `UNION` only keeps unique rows. To keep all rows, including duplicates, use `UNION ALL`. * [Syntax](#syntax) * [Examples](#examples) **When using the `UNION` clause**: * The number of columns in each result set must be the same. * Columns must be in the same order and of the same or compatible data types. ## Syntax ```sql SELECT expression[,...n] FROM measurement_1 UNION [ALL] SELECT expression[,...n] FROM measurement_2 ``` ## Examples * [Union results from different measurements](#union-results-from-different-measurements) * [Return the highest and lowest three results in a single result set](#return-the-highest-and-lowest-three-results-in-a-single-result-set) * [Union query results with custom data](#union-query-results-with-custom-data) ### Union results from different measurements ```sql ( SELECT 'h2o_pH' AS measurement, time, "pH" AS "water_pH" FROM "h2o_pH" LIMIT 4 ) UNION ( SELECT 'h2o_quality' AS measurement, time, index FROM h2o_quality LIMIT 4 ) ``` [](#view-example-results) View example results |measurement | time |water\_pH| |------------|--------------------|---------| | h2o\_pH |2019-08-27T00:12:00Z| 7 | | h2o\_pH |2019-08-27T00:18:00Z| 8 | |h2o\_quality|2019-09-11T01:06:00Z| 89 | | h2o\_pH |2019-08-27T00:06:00Z| 7 | |h2o\_quality|2019-09-11T00:00:00Z| 26 | |h2o\_quality|2019-09-11T01:00:00Z| 19 | |h2o\_quality|2019-09-11T00:48:00Z| 65 | | h2o\_pH |2019-08-27T00:00:00Z| 8 | ### Return the highest and lowest three results in a single result set *The following example uses the sample data set provided in[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol).* ``` ( SELECT 'low' as type, time, co FROM home ORDER BY co ASC LIMIT 3 ) UNION ( SELECT 'high' as type, time, co FROM home ORDER BY co DESC LIMIT 3 ) ``` [](#view-example-results) View example results |type| time |co | |----|--------------------|---| |high|2022-01-01T20:00:00Z|26 | |high|2022-01-01T19:00:00Z|22 | |high|2022-01-01T18:00:00Z|18 | |low |2022-01-01T14:00:00Z| 0 | |low |2022-01-01T10:00:00Z| 0 | |low |2022-01-01T08:00:00Z| 0 | ### Union query results with custom data *The following example uses the sample data set provided in[Get started with InfluxDB tutorial](/influxdb3/core/get-started/write/#construct-line-protocol). It also uses the [table value constructor](/influxdb3/core/reference/sql/table-value-constructor/)to build a table with custom data.* ```sql SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T12:00:00Z' UNION SELECT * FROM (VALUES (0, 34.2, 'Bedroom', 21.1, '2022-01-01T08:00:00Z'::TIMESTAMP), (0, 34.5, 'Bedroom', 21.2, '2022-01-01T09:00:00Z'::TIMESTAMP), (0, 34.6, 'Bedroom', 21.5, '2022-01-01T10:00:00Z'::TIMESTAMP), (0, 34.5, 'Bedroom', 21.8, '2022-01-01T11:00:00Z'::TIMESTAMP), (0, 33.9, 'Bedroom', 22.0, '2022-01-01T12:00:00Z'::TIMESTAMP) ) newRoom(co, hum, room, temp, time) ORDER BY room, time ``` [](#view-example-results) View example results |co |hum | room |temp| time | |---|----|-----------|----|--------------------| | 0 |34.2| Bedroom |21.1|2022-01-01T08:00:00Z| | 0 |34.5| Bedroom |21.2|2022-01-01T09:00:00Z| | 0 |34.6| Bedroom |21.5|2022-01-01T10:00:00Z| | 0 |34.5| Bedroom |21.8|2022-01-01T11:00:00Z| | 0 |33.9| Bedroom | 22 |2022-01-01T12:00:00Z| | 0 |35.9| Kitchen | 21 |2022-01-01T08:00:00Z| | 0 |36.2| Kitchen | 23 |2022-01-01T09:00:00Z| | 0 |36.1| Kitchen |22.7|2022-01-01T10:00:00Z| | 0 | 36 | Kitchen |22.4|2022-01-01T11:00:00Z| | 0 | 36 | Kitchen |22.5|2022-01-01T12:00:00Z| | 0 |35.9|Living Room|21.1|2022-01-01T08:00:00Z| | 0 |35.9|Living Room|21.4|2022-01-01T09:00:00Z| | 0 | 36 |Living Room|21.8|2022-01-01T10:00:00Z| | 0 | 36 |Living Room|22.2|2022-01-01T11:00:00Z| | 0 |35.9|Living Room|22.2|2022-01-01T12:00:00Z| | measurement | time | water_pH | | --- | --- | --- | | measurement | time | water_pH | | h2o_pH | 2019-08-27T00:12:00Z | 7 | | h2o_pH | 2019-08-27T00:18:00Z | 8 | | h2o_quality | 2019-09-11T01:06:00Z | 89 | | h2o_pH | 2019-08-27T00:06:00Z | 7 | | h2o_quality | 2019-09-11T00:00:00Z | 26 | | h2o_quality | 2019-09-11T01:00:00Z | 19 | | h2o_quality | 2019-09-11T00:48:00Z | 65 | | h2o_pH | 2019-08-27T00:00:00Z | 8 | | type | time | co | | --- | --- | --- | | type | time | co | | high | 2022-01-01T20:00:00Z | 26 | | high | 2022-01-01T19:00:00Z | 22 | | high | 2022-01-01T18:00:00Z | 18 | | low | 2022-01-01T14:00:00Z | 0 | | low | 2022-01-01T10:00:00Z | 0 | | low | 2022-01-01T08:00:00Z | 0 | | co | hum | room | temp | time | | --- | --- | --- | --- | --- | | co | hum | room | temp | time | | 0 | 34.2 | Bedroom | 21.1 | 2022-01-01T08:00:00Z | | 0 | 34.5 | Bedroom | 21.2 | 2022-01-01T09:00:00Z | | 0 | 34.6 | Bedroom | 21.5 | 2022-01-01T10:00:00Z | | 0 | 34.5 | Bedroom | 21.8 | 2022-01-01T11:00:00Z | | 0 | 33.9 | Bedroom | 22 | 2022-01-01T12:00:00Z | | 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | | 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | | 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | | 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | | 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | | 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | | 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | | 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | | 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | | 0 | 35.9 | Living Room | 22.2 | 2022-01-01T12:00:00Z | --- # WHERE clause Source: https://docs.influxdata.com/influxdb3/core/reference/sql/where/ Use the `WHERE` clause to filter results based on fields, tags, or timestamps. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` > [!Note] > **Note:** Unlike InfluxQL, SQL **supports** `OR` in the `WHERE` clause to > specify multiple conditions, including time ranges. ## Examples Note that single quotes are required for string literals in the `WHERE` clause. ### Filter data based on field values ``` SELECT * FROM "h2o_feet" WHERE "water_level" >= 9.78 ``` [](#view-example-results) View example results The query returns data from the `h2o_feet` measurement with `water_level` field values that are greater than or equal to 9.78. | level description | location | time |water\_level| |-------------------------|-------------|------------------------|------------| |at or greater than 9 feet|coyote\_creek|2019-09-01T23:06:00.000Z| 9.8 | |at or greater than 9 feet|coyote\_creek|2019-09-01T23:12:00.000Z| 9.829 | |at or greater than 9 feet|coyote\_creek|2019-09-01T23:18:00.000Z| 9.862 | |at or greater than 9 feet|coyote\_creek|2019-09-01T23:24:00.000Z| 9.892 | |at or greater than 9 feet|coyote\_creek|2019-09-01T23:30:00.000Z| 9.902 | |at or greater than 9 feet|coyote\_creek|2019-09-01T23:36:00.000Z| 9.898 | ### Filter data based on specific tag and field values ``` SELECT * FROM "h2o_feet" WHERE "location" = 'santa_monica' and "level description" = 'below 3 feet' ``` [](#view-example-results) View example results The query returns all data from the `h2o_feet` measurement with the `location` tag key, `santa_monica`, and a `level description` field value that equals `below 3 feet`. |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |santa\_monica|2019-09-01T00:00:00.000Z| 1.529 | | below 3 feet |santa\_monica|2019-09-01T00:06:00.000Z| 1.444 | | below 3 feet |santa\_monica|2019-09-01T00:12:00.000Z| 1.335 | | below 3 feet |santa\_monica|2019-09-01T00:18:00.000Z| 1.345 | | below 3 feet |santa\_monica|2019-09-01T00:24:00.000Z| 1.27 | ### Filter data within a specific time period ``` SELECT * FROM h2o_feet WHERE "location" = 'santa_monica' AND "time" >= '2019-08-19T12:00:00Z' AND "time" <= '2019-08-19T13:00:00Z' ``` [](#view-example-results) View example results The query returns results with timestamps greater than or equal to `08-19-2019T12:00:00Z` and less than or equal to `08-19-2019T13:00:00Z`. |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |santa\_monica|2019-08-19T12:00:00.000Z| 2.533 | | below 3 feet |santa\_monica|2019-08-19T12:06:00.000Z| 2.543 | | below 3 feet |santa\_monica|2019-08-19T12:12:00.000Z| 2.385 | | below 3 feet |santa\_monica|2019-08-19T12:18:00.000Z| 2.362 | | below 3 feet |santa\_monica|2019-08-19T12:24:00.000Z| 2.405 | | below 3 feet |santa\_monica|2019-08-19T12:30:00.000Z| 2.398 | ### Filter data by dynamic date ranges Use date and time functions to filter data by relative time periods that automatically update. #### Get data from yesterday ``` SELECT * FROM h2o_feet WHERE "location" = 'santa_monica' AND time >= DATE_TRUNC('day', NOW() - INTERVAL '1 day') AND time < DATE_TRUNC('day', NOW()) ``` [](#view-example-results) View example results This query filters data to include only records from the previous calendar day: * `NOW() - INTERVAL '1 day'` calculates yesterday’s timestamp * `DATE_TRUNC('day', ...)` truncates to the start of that day (00:00:00) * The range spans from yesterday at 00:00:00 to today at 00:00:00 |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |santa\_monica|2019-08-18T12:00:00.000Z| 2.533 | | below 3 feet |santa\_monica|2019-08-18T12:06:00.000Z| 2.543 | | below 3 feet |santa\_monica|2019-08-18T12:12:00.000Z| 2.385 | | below 3 feet |santa\_monica|2019-08-18T12:18:00.000Z| 2.362 | | below 3 feet |santa\_monica|2019-08-18T12:24:00.000Z| 2.405 | | below 3 feet |santa\_monica|2019-08-18T12:30:00.000Z| 2.398 | #### Get data from the last 24 hours ``` SELECT * FROM h2o_feet WHERE time >= NOW() - INTERVAL '1 day' AND location = 'santa_monica' ``` [](#view-example-results) View example results This query returns data from exactly 24 hours before the current time. Unlike the “yesterday” example, this creates a rolling 24-hour window that moves with the current time. |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |santa\_monica|2019-08-18T18:00:00.000Z| 2.120 | | below 3 feet |santa\_monica|2019-08-18T18:06:00.000Z| 2.028 | | below 3 feet |santa\_monica|2019-08-18T18:12:00.000Z| 1.982 | | below 3 feet |santa\_monica|2019-08-19T06:00:00.000Z| 1.825 | | below 3 feet |santa\_monica|2019-08-19T06:06:00.000Z| 1.753 | | below 3 feet |santa\_monica|2019-08-19T06:12:00.000Z| 1.691 | #### Get data from the current week ``` SELECT * FROM h2o_feet WHERE time >= DATE_TRUNC('week', NOW()) AND location = 'santa_monica' ``` [](#view-example-results) View example results This query returns all data from the start of the current week (Monday at 00:00:00) to the current time. The DATE\_TRUNC(‘week’, NOW()) function truncates the current timestamp to the beginning of the week. |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |santa\_monica|2019-08-12T00:00:00.000Z| 2.064 | | below 3 feet |santa\_monica|2019-08-14T09:30:00.000Z| 2.116 | | below 3 feet |santa\_monica|2019-08-16T15:45:00.000Z| 1.952 | | below 3 feet |santa\_monica|2019-08-18T12:00:00.000Z| 2.533 | | below 3 feet |santa\_monica|2019-08-18T18:00:00.000Z| 2.385 | | below 3 feet |santa\_monica|2019-08-19T10:30:00.000Z| 1.691 | ### Filter data using the OR operator ```sql SELECT * FROM "h2o_feet" WHERE "level description" = 'less than 3 feet' OR "water_level" < 2.5 ``` [](#view-example-results) View example results The query returns results with a `level description` field value equal to `less than 3 feet` or a `water_level` field value less than 2.5. |level description| location | time |water\_level| |-----------------|-------------|------------------------|------------| | below 3 feet |coyote\_creek|2019-08-25T10:06:00.000Z| 2.398 | | below 3 feet |coyote\_creek|2019-08-25T10:12:00.000Z| 2.234 | | below 3 feet |coyote\_creek|2019-08-25T10:18:00.000Z| 2.064 | | below 3 feet |coyote\_creek|2019-08-25T10:24:00.000Z| 1.893 | #### Related * [Subqueries](/influxdb3/core/reference/sql/subqueries/) | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:06:00.000Z | 9.8 | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:12:00.000Z | 9.829 | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:18:00.000Z | 9.862 | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:24:00.000Z | 9.892 | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:30:00.000Z | 9.902 | | at or greater than 9 feet | coyote_creek | 2019-09-01T23:36:00.000Z | 9.898 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | santa_monica | 2019-09-01T00:00:00.000Z | 1.529 | | below 3 feet | santa_monica | 2019-09-01T00:06:00.000Z | 1.444 | | below 3 feet | santa_monica | 2019-09-01T00:12:00.000Z | 1.335 | | below 3 feet | santa_monica | 2019-09-01T00:18:00.000Z | 1.345 | | below 3 feet | santa_monica | 2019-09-01T00:24:00.000Z | 1.27 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | santa_monica | 2019-08-19T12:00:00.000Z | 2.533 | | below 3 feet | santa_monica | 2019-08-19T12:06:00.000Z | 2.543 | | below 3 feet | santa_monica | 2019-08-19T12:12:00.000Z | 2.385 | | below 3 feet | santa_monica | 2019-08-19T12:18:00.000Z | 2.362 | | below 3 feet | santa_monica | 2019-08-19T12:24:00.000Z | 2.405 | | below 3 feet | santa_monica | 2019-08-19T12:30:00.000Z | 2.398 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | santa_monica | 2019-08-18T12:00:00.000Z | 2.533 | | below 3 feet | santa_monica | 2019-08-18T12:06:00.000Z | 2.543 | | below 3 feet | santa_monica | 2019-08-18T12:12:00.000Z | 2.385 | | below 3 feet | santa_monica | 2019-08-18T12:18:00.000Z | 2.362 | | below 3 feet | santa_monica | 2019-08-18T12:24:00.000Z | 2.405 | | below 3 feet | santa_monica | 2019-08-18T12:30:00.000Z | 2.398 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | santa_monica | 2019-08-18T18:00:00.000Z | 2.120 | | below 3 feet | santa_monica | 2019-08-18T18:06:00.000Z | 2.028 | | below 3 feet | santa_monica | 2019-08-18T18:12:00.000Z | 1.982 | | below 3 feet | santa_monica | 2019-08-19T06:00:00.000Z | 1.825 | | below 3 feet | santa_monica | 2019-08-19T06:06:00.000Z | 1.753 | | below 3 feet | santa_monica | 2019-08-19T06:12:00.000Z | 1.691 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | santa_monica | 2019-08-12T00:00:00.000Z | 2.064 | | below 3 feet | santa_monica | 2019-08-14T09:30:00.000Z | 2.116 | | below 3 feet | santa_monica | 2019-08-16T15:45:00.000Z | 1.952 | | below 3 feet | santa_monica | 2019-08-18T12:00:00.000Z | 2.533 | | below 3 feet | santa_monica | 2019-08-18T18:00:00.000Z | 2.385 | | below 3 feet | santa_monica | 2019-08-19T10:30:00.000Z | 1.691 | | level description | location | time | water_level | | --- | --- | --- | --- | | level description | location | time | water_level | | below 3 feet | coyote_creek | 2019-08-25T10:06:00.000Z | 2.398 | | below 3 feet | coyote_creek | 2019-08-25T10:12:00.000Z | 2.234 | | below 3 feet | coyote_creek | 2019-08-25T10:18:00.000Z | 2.064 | | below 3 feet | coyote_creek | 2019-08-25T10:24:00.000Z | 1.893 | --- # Usage telemetry Source: https://docs.influxdata.com/influxdb3/core/reference/telemetry/ InfluxData collects information, or *telemetry data*, about the usage of InfluxDB 3 Core to help improve the product. Learn what data InfluxDB 3 Core collects and sends to InfluxData, how it’s used, and how you can opt out. ## What data is collected InfluxDB 3 Core collects the following telemetry data: ### System metrics * **CPU utilization**: Process-specific CPU usage * **Memory usage**: Process memory consumption in MB * **Cores**: Number of CPU cores in use * **OS**: Operating system information * **Version**: InfluxDB 3 Core version * **Uptime**: Server uptime in seconds ### Write metrics * **Write requests**: Number of write operations * **Write lines**: Number of lines written * **Write bytes**: Amount of data written in MB ### Query metrics * **Query requests**: Number of query operations ### Storage metrics * **Parquet file count**: Number of Parquet files * **Parquet file size**: Total size of Parquet files in MB * **Parquet row count**: Total number of rows in Parquet files ### Processing engine metrics * **WAL triggers**: Write-Ahead Log trigger counts * **Schedule triggers**: Scheduled processing trigger counts * **Request triggers**: Request-based processing trigger counts ### Instance information * **Instance ID**: Unique identifier for the server instance * **Cluster UUID**: Unique identifier for the cluster * **Storage type**: Type of object storage being used * **Invocation**: How the server was started * **Product type**: “Core” ## Collection frequency * **System metrics** (CPU, memory): Collected every 60 seconds * **Write and query metrics**: Collected per operation, rolled up every 60 seconds * **Storage and processing engine metrics**: Collected at snapshot time (when available) * **Instance information**: Static data collected once Telemetry data is transmitted once per hour. ## Disable telemetry To “opt-out” of collecting and sending InfluxDB 3 Core telemetry data, include the `--disable-telemetry-upload` flag or set the `INFLUXDB3_DISABLE_TELEMETRY_UPLOAD` environment variable when starting InfluxDB 3 Core. **Default:** `false` | influxdb3 flag | Environment variable | |----------------------------|------------------------------------| |`--disable-telemetry-upload`|`INFLUXDB3_DISABLE_TELEMETRY_UPLOAD`| #### Command line flag ```sh influxdb3 serve --disable-telemetry-upload ``` #### Environment variable ```sh export INFLUXDB3_DISABLE_TELEMETRY_UPLOAD=true ``` When telemetry is disabled, no usage data is collected or transmitted. ## Data handling The telemetry data is used by InfluxData to understand product usage patterns, improve product performance and reliability, prioritize feature development, and identify/resolve issues. No personally identifiable information (PII) is collected. ## Privacy and security All telemetry data is transmitted securely via HTTPS. No database contents, queries, or user data is collected; only operational metrics and system information is transmitted. All data collection follows InfluxData’s privacy policy. [telemetry](/influxdb3/core/tags/telemetry/)[monitoring](/influxdb3/core/tags/monitoring/)[metrics](/influxdb3/core/tags/metrics/)[observability](/influxdb3/core/tags/observability/) | influxdb3 flag | Environment variable | | --- | --- | | influxdb3 flag | Environment variable | | --disable-telemetry-upload | INFLUXDB3_DISABLE_TELEMETRY_UPLOAD | --- # InfluxDB 3 Core release notes Source: https://docs.influxdata.com/influxdb3/core/release-notes/ > [!Note] > #### InfluxDB 3 Core and Enterprise relationship > > InfluxDB 3 Enterprise is a superset of InfluxDB 3 Core. > All updates to Core are automatically included in Enterprise. > The Enterprise sections below only list updates exclusive to Enterprise. ## v3.11.2 ### Core #### Bug fixes * **Rows missing from queries during snapshot persistence**: Each persist job now drops only the buffer chunk whose Parquet file it published. Previously, the first job of a snapshot to finish evicted every sibling chunk, so whole time ranges vanished from query results until their persist job finished. * **Partial schema changes from a rejected line**: A line protocol line is now validated in full before the catalog is mutated, so a rejected line contributes nothing to it. Previously, with `accept_partial=true`, columns created earlier in the line were committed anyway, and a line rejected after its tags were processed merged them into the next valid line’s series key. * **Unnecessary node shutdown after a retried WAL write**: Each WAL file now carries a nonce in its object metadata, so a node recognizes its own write and shuts down only for a file written by another node. Previously, a conditional PUT that was applied but returned a 500 was retried, and the node read the resulting 412 as a second process holding the same `--node-id` and shut down, though the file was durable and correct. * **Panic querying `system.parquet_files` for an unknown table**: Filtering on a `table_name` that is not a current table, or querying after its database is dropped, now returns zero rows. Previously, both panicked the request thread and returned a truncated HTTP 200. * **Duplicate rows from a concurrent snapshot handoff**: Buffer chunks and persisted Parquet files are now read under a single lock. Previously, a read landing between the two saw a new Parquet file alongside the buffer chunks it was written from and returned those rows twice. Served queries masked this through deduplication, but paths that read record batches directly, such as the Processing Engine, did not. * **Restarted downloads of large manifests and checkpoints at startup**: Snapshot manifest and checkpoint reads larger than 128 MiB are now fetched as 16 MiB ranged reads, so a slow or failed transfer retries one range. Previously, a single whole-object GET restarted a multi-gigabyte download from byte 0. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Retry storage engine upgrade**: The new `influxdb3 manage retry-upgrade-to-pacha-tree` command resets a [storage engine upgrade](/influxdb3/enterprise/reference/internals/storage-engine/#upgrade-from-parquet), so it resumes the next time the compactor node starts with `--upgrade-pacha-tree`. Sources whose table, database, or objects are gone become skips, and anything still readable returns to the queue. Nothing is deleted, so the command is safe to run again. #### Bug fixes * **Compaction falls behind on a large snapshot backlog**: Snapshot compaction now caps outstanding plans relative to the compactor’s core count, batches snapshots in ingest-time order, and fetches each plan’s gen0 files once per worker. Previously, a deep backlog could accumulate thousands of outstanding plans, recompact the same time windows once per node, and delay the first plan by over 12 minutes. * **Compactor primacy livelock during a migration**: Primary lease reads and writes now bypass the process-wide object store concurrency limit. Previously, a migration’s bulk import could starve lease renewal, so the holder repeatedly demoted at its 30-second lease TTL and reacquired, pinning the migration indefinitely while object storage itself was healthy. * **Multi-window migration imports make no progress**: The migration baseline now clips each staged file’s contribution to its window’s time range, and migration imports the newest windows first. Previously, a file crossing a window boundary caused publish validation to refuse each consolidation, so the scheduler replanned the same work forever. * **Migration fails on an unreadable source**: A source Parquet file confirmed missing, or whose table or database has been dropped, is now recorded as a skip instead of failing the whole upgrade, and `system.upgrade_parquet` reports it as `skipped_source_missing` or `skipped_table_dropped`. Only confirmed-missing sources are skipped, so a transient `NotFound` stays retryable and a grouped job still converts its readable companions. * **Compaction and migration fail on stale gen1 references**: `leftover_gen1_files` references are now reconciled against the deletions that ingesters record in their snapshots, so a reference is dropped when its Parquet file is deleted regardless of retention configuration. Previously, references were pruned only against the current retention cutoff, so they accumulated indefinitely on a table with no retention period, and a storage engine upgrade then failed enumerating them. * **`Internal error` querying a last value or distinct value cache**: A query node now registers caches that were created on another node during startup, regardless of the cache’s node spec. Previously, a cache present in the catalog but missing from a node’s in-memory provider failed every query against it with `last cache crate is invalid` until the node was restarted. * **Duplicate rows from a replica snapshot handoff**: Each buffer on a node now has its chunks and Parquet files read under a single lock, and each replica advances the gen1 chunk order offset by its own chunk count. Previously, a snapshot handoff landing between the two read passes returned those rows twice, and on clusters with more than three replicas the old offset let local chunks reuse an order a replica had taken. * **Slow compaction catch-up behind a lagging node**: The compactor now accumulates the rerun signal across every node in a cycle. Previously it kept only the last node’s value, so a caught-up node could end the cycle after a single snapshot and leave a lagging node advancing one snapshot per check interval until restart. * **Catalog checkpoint persistence failures for large payloads**: Catalog checkpoint and month-rollover writes now fall back to a multipart upload for oversized payloads. Previously, both used a single PUT, so a checkpoint merging a month of snapshots could exceed object storage’s 5 GiB single-PUT limit and fail, silently losing the boot-time fast path. * **Warning flood during startup snapshot restore**: `removed_files` entries whose target database or table is no longer present are now reported in one aggregated warning per restore. Previously, each miss logged its own warning, which buried real startup errors and slowed restore. * Other bug fixes and performance improvements #### Breaking changes * **`--l1-hot-tail-target-size` is functional again**: The option (default `250mb`) caps live L1 tail rewrites during snapshot compaction, and a larger tail is handed to L1 consolidation to seal. It was previously accepted and ignored. * **`--l1-consolidation-min-age` and `--row-delete-max-jobs-per-tick` are now ignored**: L1 consolidation has no age gate, and row-delete work shares the weighted delete slot. Both options are still accepted. * **`--l1-consolidation-target-size` is now the established-L1 size boundary**: Consolidation consumes run sets at or below it, and promotion requires at least two L1 run sets larger than it. `--l1-consolidation-min-run-sets` and `--compactor-max-source-run-sets-per-promotion` now apply only to the legacy layout. * **`--replica-snapshot-manifest-load-concurrency` applies to both storage engines**: It now bounds the boot-time snapshot manifest load on the Parquet engine as well as the upgraded engine. When unset, each engine derives its own default. * **Compactor status log fields changed**: The `service_memory_*` fields are gone, and `pending_input_mb` is renamed to `charged_input_mb`. ## v3.11.1 ### Core #### Bug fixes * **Panic on oversized duration values**: Time arithmetic now saturates at the minimum or maximum representable timestamp instead of panicking when a duration is too large to represent. Previously, an oversized user-supplied duration produced a panic and could put the server into a startup panic loop. * **Duplicate admin token registration**: The catalog now rejects registering a token whose hashed value already exists. Previously, the server registered the duplicate under a new ID. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Remove migrated Parquet data after a storage engine upgrade**: The new `influxdb3 manage cleanup-parquet` command and `/api/v3/enterprise/upgrade/parquet_cleanup` API permanently delete the pre-upgrade Parquet data and compactor metadata from object storage after a [storage engine upgrade](/influxdb3/enterprise/reference/internals/storage-engine/#upgrade-from-parquet) completes. Use `--dry-run` to report what a cleanup would delete, and how much space it would reclaim, without deleting anything; `--wait` to poll until the cleanup completes; and `--status-only` to check the status of the current or most recent cleanup. The cleanup runs on the compactor node, resumes automatically after a restart, and reports progress in the new `system.upgrade_parquet_cleanup` system table. After a cleanup deletes data, [downgrading to Parquet](/influxdb3/enterprise/reference/internals/storage-engine/#downgrade-to-parquet) is no longer possible. #### Bug fixes * **Data missing from queries during a storage engine upgrade**: While a cluster migrates from Parquet to the upgraded storage engine, hybrid queries now serve the migrating node’s own not-yet-compacted gen1 data, and data imported during the migration is queryable in all-in-one mode. Previously, on a single-node cluster, rows that the Parquet compactor had not yet folded into compacted data were missing from query results for the duration of the migration. * **Compactor crash loop after primary re-election**: The catalog’s subscription registry now reclaims a subscription slot whose receiver was dropped and skips closed subscribers when broadcasting updates, and compactor teardown now completes before the next term re-subscribes. Previously, a compactor primary re-election within one process could panic on the stale slot and crash-loop the node, and a lingering stale slot could fail an unrelated catalog update. * **Compactor retention sweep stalls (upgraded storage engine)**: The retention sweep now checks each run set’s key span in memory, and remembers negative results, instead of re-reading every run-set index from object storage on every scheduler tick. Previously, one table with a short retention period alongside a large historical dataset could freeze compaction dispatch, completion handling, and status reporting for hours while the sweep serially re-read every index. * **Query node boot loop with a large snapshot backlog (upgraded storage engine)**: At startup, a query node now fetches peer snapshot manifests concurrently, bounded by `--replica-gen0-load-concurrency` (default `16`), and walks at most 10,000 manifests per node. If the cap is reached, the server logs an error noting that data in the skipped older snapshots stays unqueryable until compaction covers it. Previously, the walk fetched the entire backlog serially with no bound, so a large backlog behind a stalled compactor could run for hours, exhaust memory, and restart the node from zero in a permanent boot loop. * **Incorrect query results from out-of-order series scans (upgraded storage engine)**: A window scan that advertises series-key ordering now always merge-sorts its inputs. Previously, files could be chained together out of order while the query plan claimed sorted output, and downstream sort-merge operations silently produced incorrect results. * Other bug fixes and performance improvements ## v3.11.0 ### Core #### Features * **Async trigger concurrency limit**: The new `--async-trigger-concurrency-limit`option caps the number of concurrent invocations for an asynchronous processing engine trigger. The default is unlimited. * **Processing engine retry behavior for asynchronous triggers**: When`trigger_settings.run_async = true`, a failed trigger invocation now retries up to 5 times before being discarded. Previously, failed invocations retried indefinitely. * **WAL triggers skip empty flushes**: A WAL trigger no longer runs when the WAL flush it would process is empty. Previously, the trigger ran on every flush, including empty ones. * **Disabled trigger state persists across restarts**: When`trigger_settings.error_behavior = disable` disables a trigger, the disabled state now survives a server restart. Previously, a disabled trigger re-enabled itself on restart. * **`--disable-package-management`**: Use this option to prevent the server from creating or modifying a Python virtual environment or invoking `pip`. Package-install API calls are rejected while it’s set. * **Virtual `event_time` column on `system.processing_engine_logs`**: Queries that reference the former `event_time` column continue to work after the column was renamed to `time`. * **`--shutdown-timeout` graceful shutdown bound**: This new option (default`30s`) caps how long the server waits for active connections to drain during shutdown before forcibly closing them. Set it to `0s` to skip the drain. #### Bug fixes * **cgroup-aware resource sizing**: Containerized deployments now size memory-based defaults against the container’s cgroup limits instead of the host machine’s total resources. #### Breaking changes * **Size options require an explicit unit**: Options that accept a size value (for example, `--exec-mem-pool-size` and `--file-cache-size`) now reject a bare number. Append a unit suffix (`b`, `kb`, `mb`, `gb`, `tb`) or, where noted, a percentage (for example, `20%`). This avoids a silent change in meaning — historically, a bare number meant megabytes for some options and bytes for others. * **Three memory and cache options renamed, with a deprecated alias**:`--exec-mem-pool-bytes` is now `--exec-mem-pool-size`,`--parquet-mem-cache-size` is now `--file-cache-size`, and`--force-snapshot-mem-threshold` is now `--force-snapshot-mem-size`(`--parquet-mem-cache-query-path-duration` is now `--file-cache-recency`, and `--disable-parquet-mem-cache` is now `--disable-file-cache`). The deprecated old names, and their environment variables, still work and still accept a bare number as megabytes — their pre-3.11 meaning — but log a startup deprecation warning. * **`--max-http-request-size` keeps its name and its pre-3.11 meaning**: A bare number is still accepted as bytes, but now logs a startup warning. Prefer an explicit unit suffix, for example `10mb`. * **`--query-log-size` renamed to `--query-log-max-entries`**, with the old name and its environment variable kept as a deprecated, backward-compatible alias. * **Other options and environment variables renamed, with a deprecated alias**: legacy names still work and log a startup deprecation warning; if both the old and new name are set with different values, the new name wins. | Old | New | |----------------------------------------------------------|-----------------------------------------| |`--disable-parquet-mem-cache`, `--disable-data-file-cache`| `--disable-file-cache` | | `--wal-max-write-buffer-size` | `--wal-max-buffered-writes` | | `--wal-snapshot-size` | `--wal-files-per-snapshot` | | `INFLUXDB3_DB_DIR` | `INFLUXDB3_DATA_DIR` | | `INFLUXDB3_NODE_IDENTIFIER_PREFIX` | `INFLUXDB3_NODE_ID` | | `INFLUXDB3_NODE_IDENTIFIER_FROM_ENV` | `INFLUXDB3_NODE_ID_FROM_ENV` | | `INFLUXDB3_NUM_WAL_FILES_TO_KEEP` |`INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP`| | `INFLUXDB3_START_WITHOUT_AUTH` | `INFLUXDB3_WITHOUT_AUTH` | | `INFLUXDB3_TCP_LISTINER_FILE_PATH` (misspelling) | `INFLUXDB3_TCP_LISTENER_FILE_PATH` | | `INFLUXDB3_TELEMETRY_DISABLE_UPLOAD` | `INFLUXDB3_DISABLE_TELEMETRY_UPLOAD` | These renames apply to both Core and Enterprise. For the separate Enterprise-only `INFLUXDB3_ENTERPRISE_*` → `INFLUXDB3_*` environment variable renames, see Enterprise breaking changes below. * **Duplicate tag keys are rejected at write time**: A point that repeats a tag key (for example, `m,t=a,t=a f=1i`) is now rejected with a clear error, the same way duplicate field keys are. * **`/api/v2/write` returns 503 instead of 400 when the node is stopped**: Clients that key retry logic off the status code now correctly treat this response as retryable. * **`--hard-delete-default-duration` is confirmed to have no effect**: This option has never affected hard-delete behavior in any release — the server always uses its built-in default duration. The option is still accepted so existing configurations keep starting, but the server now logs a startup warning recommending you remove it. * **`--object-store-cache-endpoint` removed**: This option was parsed but consumed by dead code and never had an effect. The flag now fails to parse at startup, and the `INFLUXDB3_OBJECT_STORE_CACHE_ENDPOINT` /`OBJECT_STORE_CACHE_ENDPOINT` environment variables are ignored. Remove it from your configuration. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **The upgraded storage engine is now the default**: New clusters are created on the upgraded storage engine with no opt-in flag required. The engine is resolved from the catalog’s persisted storage mode, not from a flag: * A brand new cluster is stamped for the upgraded storage engine at catalog creation. There’s no user-facing opt-out. * An existing Parquet cluster keeps running Parquet after the binary upgrade. The persisted mode wins on load. * To migrate an existing Parquet cluster, pass `--upgrade-pacha-tree`(environment variable `INFLUXDB3_UPGRADE_PACHA_TREE`). This moves the catalog into a hybrid Parquet-and-upgraded-storage-engine mode and starts the migration. A catalog in the upgraded or migrating mode always runs the upgraded storage engine from then on. `--use-pacha-tree` still works and keeps its historical migration-starting semantics, but is deprecated and logs a warning at startup. Core remains Parquet-only. * **Compaction throughput improvements (upgraded storage engine)**: Time-disjoint two-level compaction and overlapping-L1 leading-edge parallelism are now the default. Previously, all leading-edge ingest funneled through a single hot-tail L1 run set. This capped leading-edge throughput at one in-flight compaction job. In 3.11, several concurrent L1 compaction jobs can serve the leading edge and any heavily-written range. This decouples ingest throughput from compactor reconciliation. New windows and shards use the time-disjoint layout. Existing checkpoints keep their recorded layout until you upgrade them. * **Integrated Explorer**: The InfluxDB 3 Web UI (Explorer) now ships inside the Enterprise binary as a WebAssembly guest, hosted in-process behind a WASI sandbox. Enable it with `--mode all,webui`. The Web UI is **not** included in plain `--mode all`, and a session secret is mandatory when `webui` mode is enabled: ``` mkdir -p ./plugins influxdb3 serve \ --cluster-id cluster0 \ --node-id node0 \ --mode all,webui \ --plugin-dir ./plugins \ --webui-session-secret "$(openssl rand -base64 24)" ``` You configure a connection to your local server (for example,`http://localhost:8181`), the same way you connect to a database server from the standalone Docker Explorer. It keeps a SQLite database that’s automatically synchronized to object storage per cluster. AI chat is included and can point at any OpenAI-compatible endpoint with `--webui-openai-base-url`. * **Thread defaults scale with your license on the upgraded storage engine**: On clusters running the upgraded storage engine (the default for new clusters), `--num-io-threads` and the DataFusion thread pool each default to your licensed core count, instead of the flat defaults used on Parquet-engine clusters. `--num-cores` validation runs after the server resolves the active storage engine, since the upgraded engine can license more cores than a Parquet-engine cluster does. A thread count set above the licensed core count is capped with a startup warning instead of rejected. * **Incremental backups**: Backup is no longer full-only. Each incremental backup names a parent, and restoring an incremental walks the manifest chain to produce a full restore. Deleting an incremental also deletes every child that depends on it. ``` influxdb3 create backup --name base --token $ADMIN_TOKEN influxdb3 create backup --name inc-1 --incremental --parent base --token $ADMIN_TOKEN influxdb3 create restore --backup inc-1 --token $ADMIN_TOKEN ``` * **Restore is now a point-in-time rollback**: Restore was previously additive. It’s now destructive: it truncates the WAL above the backup’s watermark so a restart doesn’t replay and resurrect post-backup data. * **In-place restore without a restart**: Restore can now apply to a running cluster. Supporting work includes gen0 buffer eviction, fencing peer writes on ingest-mode nodes during the restore, and evicting the query-node replica buffer so queriers stop serving the pre-restore view. * **Query performance (upgraded storage engine)**: `PachaTreeWindowExec` and`PachaTreeBufferExec` are now the default plan shape, giving visibility through `EXPLAIN` and `EXPLAIN ANALYZE`. Field family pruning skips loading field families that filters guarantee can’t affect the result. Scan predicate pushdown now extends across single-field-family scans, the union path, dedup and gap-leaf scans, and time predicates. * **Bulk import: remote sources and concurrency**: `influxdb3 import upload`now accepts an object store URL as a source, in addition to a local directory, and a `--concurrency` option to control how many files import at once (default 8). ``` influxdb3 import upload --database mydb --table events \ s3://my-bucket/exports/ \ --source-opt aws_region=us-west-2 \ --concurrency 16 ``` * **Five new system tables (upgraded storage engine)**: `system.pt_shards`,`system.pt_compaction_files`, `system.pt_storage_snapshots`,`system.pt_storage_checkpoints`, and `system.pt_storage_run_set_indexes`.`pt_ingest_wal` and `pt_ingest_files` gained `node_id` and `node_name`columns. * **`--user-auth-type` replaces `--without-user-auth`**: Configure the user authentication preview with a comma-separated list of `basic` and/or`oauth`, or `none` (the default). `--without-user-auth` is deprecated and hidden, but still takes precedence when explicitly set. * **Query group CLI commands (not yet operational)**: `influxdb3 create query_group`, `influxdb3 show query_groups`, `influxdb3 update query_group`, and `influxdb3 delete query_group` store query group definitions in the catalog, but the server doesn’t yet use those definitions to affect query routing, data placement, or replication. Creating a query group currently has no effect on query node behavior. #### Bug fixes * **Bulk import data loss window (checkpoint v13)**: Import watermarks are now embedded in the checkpoint itself, preventing data loss during a crash window. * **In-place restore stability**: Release-candidate validation found that live in-place restore could wedge queriers until restart, and that writing after a restore could trigger ID-recycling corruption. Both are fixed in this release. #### Breaking changes * **Upgraded storage engine options dropped the `pt-` prefix, with no aliases**: An old `--pt-*` flag now causes a startup error, and legacy`INFLUXDB3_PT_*` and `INFLUXDB3_ENTERPRISE_PT_*` environment variables are ignored — startup logs a warning for each one that’s still set. Review any saved command line, systemd unit, Docker Compose file, Helm chart, or packaged conf file before upgrading. Any `--pt-*` option not listed below simply drops the `pt-` prefix, and its environment variable follows the same pattern (`INFLUXDB3_PT_SNAPSHOT_SIZE`becomes `INFLUXDB3_SNAPSHOT_SIZE`). The following options changed beyond dropping the `pt-` prefix: | Old name | New name | |------------------------------|----------------------------| | `--pt-max-columns` | `--max-total-columns` | |`--pt-gen0-max-bytes-per-file`| `--gen0-max-file-size` | |`--pt-wal-replica-queue-size` |`--wal-replica-queue-length`| | `--pt-wal-max-buffer-size` | `--wal-buffer-size` | Every remaining upgraded-storage-engine byte-size flag ending in `-bytes`now ends in `-size` (the L1 through L4 tail and target-file flags). A few `--pt-*` flags map onto flag names shared with the Parquet engine, rather than getting their own new name — `--pt-wal-flush-interval` is now`--wal-flush-interval`, `--pt-wal-replication-interval` is now`--replication-interval`, `--pt-file-cache-size` is now `--file-cache-size`,`--pt-file-cache-recency` is now `--file-cache-recency`, and`--pt-disable-data-file-cache` is now `--disable-file-cache`.`--file-cache-size` is a total budget shared across both engines: during a storage engine upgrade with hybrid query enabled, the budget splits 50/50 between the two engine caches; otherwise the active engine gets the full budget. The upgraded storage engine’s flags no longer require `--use-pacha-tree`: in 3.10.x a `--pt-*` flag without `--use-pacha-tree` was a parse error, but with the upgraded storage engine as the default that constraint is gone. For the complete old-to-new name table, see[Migrate from `pt-` option names](/influxdb3/enterprise/performance-preview/configure/#migrate-from-pt-option-names). * **`INFLUXDB3_ENTERPRISE_*` environment variables become plain`INFLUXDB3_*`**: 35 Enterprise-specific environment variables dropped the`ENTERPRISE_` segment — for example, `INFLUXDB3_ENTERPRISE_CLUSTER_ID` is now `INFLUXDB3_CLUSTER_ID`, and `INFLUXDB3_ENTERPRISE_MODE` is now`INFLUXDB3_MODE`. The legacy `ENTERPRISE_` names remain supported as deprecated aliases; the server logs a deprecation warning at startup when it detects one, and if both names are set with different values, the new name wins. * **`--wait-for-running-ingestor` renamed to `--wait-for-running-ingester`**(the old name was a misspelling). The old option, and its`INFLUXDB3_WAIT_FOR_RUNNING_INGESTOR` /`INFLUXDB3_ENTERPRISE_WAIT_FOR_RUNNING_INGESTOR` environment variables, remain as deprecated, backward-compatible aliases. * **Metrics lost their per-database `db` label**: This breaks any dashboard or alert that groups by database. Affected series include`influxdb3_write_lines`, `influxdb3_write_lines_rejected`,`influxdb3_write_bytes`, `influxdb3_compactions`,`influxdb3_last_values_cache_query_duration`, and the upgraded-storage-engine`influxdb3_ingest_*` family (`lp_bytes_received`, `pre_snapshot_buffer_*`,`pre_wal_flush_buffer_*`, `write_concurrency`). * **`influxdb3 stop node` waits by default**: Previously, the server marked the node stopping and returned immediately, but the CLI claimed the node “has been stopped.” The CLI now polls until the node reads `stopped`.`--timeout` bounds the wait (default 5m), and `--no-wait` restores the old fire-and-forget behavior. On timeout, it prints the last observed state and recovery guidance, then exits non-zero. * **Parquet-only catalog limits are inert on the upgraded storage engine**: If`--num-database-limit`, `--num-table-limit`, or`--num-total-columns-per-table-limit` is set on a cluster running the upgraded storage engine, startup now warns that they’re ignored instead of hard-failing, since existing manifests carry them across the storage engine upgrade. Only the per-table column limit has an upgraded-engine counterpart (`--max-total-columns`). * **Four inert Enterprise options removed**: `--database-split-level`,`--table-split-level`, `--max-compact-destination`, and`--pt-enable-row-deletes` were parsed but never read; they are removed. The flags now fail to parse at startup and their environment variables are ignored. Remove them from your configuration. ## v3.10.5 ### Core #### Bug fixes * **Oversized buffer chunk persistence**: When a buffer chunk splits because a single string or tag column exceeds 2 GiB, each resulting chunk now persists to its own Parquet file. Previously, the split chunks all wrote to the same path. ### Enterprise All Core updates are included in Enterprise. ## v3.9.11 ### Core #### Bug fixes * **Oversized buffer chunk persistence**: When a buffer chunk splits because a single string or tag column exceeds 2 GiB, each resulting chunk now persists to its own Parquet file. Previously, the split chunks all wrote to the same path. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * Other bug fixes and performance improvements ## v3.10.4 ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Skip loading the compacted data file index**: The new `--compacted-data-skip-file-index` option (`INFLUXDB3_ENTERPRISE_COMPACTED_DATA_SKIP_FILE_INDEX` environment variable, default `false`) loads compacted data without materializing the file index, letting nodes start when the index has grown too large to fit in host memory. Queries remain correct, but will run slower in exchange for a lower memory footprint. #### Bug fixes * **Skipped gen1 files in recompaction plans**: Gen1 files pulled into a recompaction plan that was skipped for exceeding the file limit are now carried into later plans’ leftover lists. Previously, when the recompaction loop produced multiple plans for one table in a single cycle, those files were dropped from the final persisted compaction detail; the files remained in object storage, but no query path would serve them. * Other bug fixes and performance improvements ## v3.9.10 ### Core Maintenance release: v3.9.10 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Skipped gen1 files in recompaction plans**: Gen1 files pulled into a recompaction plan that was skipped for exceeding the file limit are now carried into later plans’ leftover lists. Previously, when the recompaction loop produced multiple plans for one table in a single cycle, those files were dropped from the final persisted compaction detail; the files remained in object storage, but no query path would serve them. * Other bug fixes and performance improvements ## v3.9.9 ### Core #### Bug fixes * **Object store errors at startup**: When the catalog checkpoint existence check fails at startup, the underlying object store error is now logged and included in the reported error. Previously, the process exited with an opaque status code and no indication of the cause. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Skip loading the compacted data file index**: The new `--compacted-data-skip-file-index` option (`INFLUXDB3_ENTERPRISE_COMPACTED_DATA_SKIP_FILE_INDEX` environment variable, default `false`) loads compacted data without materializing the file index, letting nodes start when the index has grown too large to fit in host memory. Queries remain correct, but will run slower in exchange for a lower memory footprint. #### Bug fixes * Other bug fixes and performance improvements ## v3.10.3 ### Core #### Bug fixes * **Duplicate tag key rejection**: Writes that repeat a tag key (for example, `m,t=a,t=a f=1i`) are now rejected with a clear error, the same way duplicate field keys are rejected. Previously, a point with a repeated tag key was accepted into the WAL and later caused a panic during snapshotting that crash-looped the node on WAL replay. * **Processing engine trigger cancellation**: Disabling or deleting a trigger now cancels its in-flight plugin run in Core, extending the Enterprise fix from v3.10.2. Previously, a synchronous scheduled trigger whose plugin run was still executing could block trigger `disable` and `delete --force` operations until the run finished. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Compacted data load concurrency limit**: The new `--compacted-data-load-concurrency-limit` option (`INFLUXDB3_ENTERPRISE_COMPACTED_DATA_LOAD_CONCURRENCY_LIMIT` environment variable, default `20`) bounds concurrent object store reads when a node loads compacted data at startup. Previously, nodes with large compaction indexes issued unbounded concurrent reads at startup, which could saturate the network, cause object store timeouts, and starve other subsystems of object store connections. #### Bug fixes * **Corrupt peer WAL and snapshot handling**: A durably corrupt WAL or snapshot file from a peer node is now logged, counted, and skipped so replication continues with later files. Previously, a corrupt peer WAL file stalled replication from that node—or prevented server startup—and a corrupt snapshot manifest silently halted snapshot replication from that peer. Transient errors, such as network failures, still retry as before. * Other bug fixes and performance improvements ## v3.9.8 ### Core #### Bug fixes * **Duplicate tag key rejection**: Writes that repeat a tag key (for example, `m,t=a,t=a f=1i`) are now rejected with a clear error, the same way duplicate field keys are rejected. Previously, a point with a repeated tag key was accepted into the WAL and later caused a panic during snapshotting that crash-looped the node on WAL replay. * **Processing engine trigger cancellation**: Disabling or deleting a trigger now cancels its in-flight plugin run in Core, extending the Enterprise fix from v3.9.7. Previously, a synchronous scheduled trigger (the default, created without `--run-asynchronous`) whose plugin run was still executing could block trigger `disable`, `delete --force`, and database deletion until the run finished. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Compacted data load concurrency limit**: The new `--compacted-data-load-concurrency-limit` option (`INFLUXDB3_ENTERPRISE_COMPACTED_DATA_LOAD_CONCURRENCY_LIMIT` environment variable, default `20`) bounds concurrent object store reads when a node loads compacted data at startup. Previously, nodes with large compaction indexes issued unbounded concurrent reads at startup, which could saturate the network, cause object store timeouts, and starve other subsystems of object store connections. #### Bug fixes * Other bug fixes and performance improvements ## v3.10.2 ### Core Maintenance release: v3.10.2 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Processing engine trigger cancellation**: Disabling or deleting a trigger now cancels its in-flight plugin run. Previously, a synchronous scheduled trigger whose plugin run was still executing could block trigger `disable` and `delete --force` operations until the run finished. * Other bug fixes and performance improvements ## v3.9.7 ### Core Maintenance release: v3.9.7 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Processing engine trigger cancellation**: Disabling or deleting a trigger now cancels its in-flight plugin run promptly. Previously, a synchronous scheduled trigger (the default, created without `--run-asynchronous`) whose plugin run was still executing could block trigger `disable`, `delete --force`, and even unrelated `create` operations until the run finished. * Other bug fixes and performance improvements ## v3.10.1 ### Core #### Bug fixes * **Snapshot manifest persistence**: Snapshot manifests are now persisted using multipart uploads, preventing errors when writing large manifests to object storage. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Compacted generation deduplication**: Overlapping compacted generations are now co-partitioned so the querier correctly deduplicates them. * **Performance upgrade preview file access**: A canceled file fetch no longer cascades cancellation to other waiters with the storage engine upgrade (`--use-pacha-tree`). * Other bug fixes and performance improvements ## v3.9.6 ### Core Maintenance release: v3.9.6 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Compacted generation deduplication**: Overlapping compacted generations are now co-partitioned so the querier correctly deduplicates them. * Other bug fixes and performance improvements ## v3.9.5 ### Core #### Bug fixes * **Snapshot manifest persistence**: Snapshot manifests are now persisted using multipart uploads, preventing errors when writing large manifests to object storage. ### Enterprise All Core updates are included in Enterprise. ## v3.10.0 > [!Important] > #### Upgrading to InfluxDB 3.10 is a one-way migration > > The first time you start InfluxDB 3.10, it automatically upgrades the on-disk > catalog format from v2 to v3. After migration, 3.9.x and older > binaries are unable to read the new catalog, and fail to start on the same > cluster data. > > Before upgrading, back up your current catalog. The paths depend on the version > you’re upgrading from: > > * **3.4.0 or later**: `{prefix}/catalog/v2/logs/` and `{prefix}/catalog/v2/snapshot` > * **Before 3.4.0**: `{prefix}/catalogs/` and `{prefix}/_catalog_checkpoint` > > Restoring these objects is the only way to roll back to 3.9.x. > > On a cluster running 3.4.0 or later, `{prefix}/catalogs/` and`{prefix}/_catalog_checkpoint` may still be present as leftovers from an earlier > catalog format. They aren’t current and aren’t a valid rollback source. ### Core #### Features * **Catalog format upgrade (catalog v2 → v3)**: InfluxDB 3.10 automatically migrates the on-disk catalog to v3 format on first startup. The v3 catalog uses a compact binary record format (\~5–6x smaller than v2). Migration is automatic, idempotent, and crash-safe. **Back up your current catalog before upgrading — the migration is one-way and 3.9.x binaries cannot read a v3 catalog.** If you’re upgrading from 3.4.0 or later, back up `{prefix}/catalog/v2/logs/` and `{prefix}/catalog/v2/snapshot`. If you’re upgrading from a version before 3.4.0, back up `{prefix}/catalogs/` and `{prefix}/_catalog_checkpoint`. * **`influxdb3 debug catalog` command**: Inspect catalog state offline directly from object storage — no running server required. Subcommands: `list`, `snapshot`, `sequence`. Available in both Core and Enterprise. * **`--max-concurrent-queries` flag**: Limit the number of queries that run concurrently. The limit can also be updated at runtime via `POST /api/v3/configure/query_concurrency_limit`. * **Processing engine: cross-database queries**: Plugins can now read data from any database using the optional `database=` keyword argument on `influxdb3_local.query()`. * **Processing engine: trigger lockdown flags**: Two new serve flags restrict plugin behavior. `--restrict-plugin-triggers-to` limits triggers to one or more of `wal`, `schedule`, or `request`. `--plugin-dir-only` (Enterprise) blocks plugin installation from any source other than the configured plugin directory. * **Observability: always-on heap profiling**: Heap profiling is now enabled at startup with negligible overhead (\~\<1% CPU). Access profiles at the existing pprof endpoint. To disable, set `MALLOC_CONF=prof:false` before starting the server. * **Observability: per-request query traces**: Query tracing is now opt-in per request rather than enabled for all queries. This reduces trace volume for high-throughput deployments. See the monitoring documentation for how to enable tracing on individual requests. * **Embedded Python updated to 3.13.14**: The Processing engine’s embedded Python is updated to 3.13.14, which includes upstream security fixes. #### Bug fixes * **`/api/v2/write` returns 403 for unauthorized tokens**: A valid token that lacks write permission on the target database now receives `403 Forbidden` instead of `401 Unauthorized`. Update client-side retry logic if it differentiates on these status codes. * **Line-protocol parse errors return 400**: Malformed line protocol sent to the v1 `/write` or v2 `/api/v2/write` endpoints now returns `400 Bad Request` instead of `500 Internal Server Error`. * **Invalid queries return HTTP 4xx**: A syntactically invalid query now returns an appropriate 4xx response rather than a 5xx error. * **Query log records `query_text` on terminal phases**: The query log now includes the `query_text` field for queries that have reached a terminal phase. #### Breaking changes * **Catalog format upgrade (catalog v2 → v3) is one-way**: The first startup of InfluxDB 3.10 migrates the catalog to v3. After migration, 3.9.x binaries cannot start against the same object store. Back up your current catalog before upgrading: `{prefix}/catalog/v2/logs/` and `{prefix}/catalog/v2/snapshot` if you’re upgrading from 3.4.0 or later, or `{prefix}/catalogs/` and `{prefix}/_catalog_checkpoint` if you’re upgrading from an earlier version. * **`influxdb3 write` output changed**: The write command now prints a throughput report on success instead of printing `success`. Scripts that parse the previous output should use `--quiet` (`-q`) to suppress all output. * **`/api/v2/write` returns 403 instead of 401**: See bug fixes above. Clients that treat 401 and 403 differently must be updated. * **Line-protocol parse errors return 400 instead of 500**: See bug fixes above. * **Heap profiling is always on**: The \~\<1% CPU overhead is present by default. Opt out with `MALLOC_CONF=prof:false`. * **Query traces are now per-request opt-in**: Observability pipelines that expect a trace for every query will see far fewer traces. Update your pipeline to request traces explicitly per query. ### Enterprise All Core updates are included in Enterprise. The following updates are exclusive to Enterprise. #### Features * **Wide-tag support**: Tag IDs have been widened from u8 to u16. This raises the practical limit to thousands of tables and millions of columns per database. Available with the storage engine upgrade (`--use-pacha-tree`). * **Row-level deletion**: Delete rows by time range and tag predicates using `influxdb3 delete rows` and `influxdb3 cancel row-delete`. Deletion is asynchronous — requests persist to object storage and the compactor applies them when rewriting run sets. Requires `--use-pacha-tree`. Monitor pending deletes with the `system.row_deletes` system table and 9 new `influxdb3_compactor_row_delete_*` metrics. * **Runtime query-concurrency limit**: Adjust the maximum number of concurrent queries at runtime via the `/api/v3/configure/query_concurrency_limit` API — `GET` to read the current limit, `PUT` to set it, and `DELETE` to reset it to the startup default. * **`GET /ready` endpoint**: Returns `200 OK` when the server can reach object storage, or `503 Service Unavailable` when it cannot. Use this endpoint for readiness probes in load balancers and orchestration systems. * **Backup and restore**: Create and manage full backups of Enterprise data with `influxdb3 create backup`, `influxdb3 status backup`, `influxdb3 show backups`, `influxdb3 delete backup`, and `influxdb3 cancel backup`. Initiate restore operations with `influxdb3 create restore`, `influxdb3 status restore`, `influxdb3 show restores`, and `influxdb3 cancel restore`. Backup and restore require `--use-pacha-tree` and a compactor node with an admin token. `create backup` refuses to overwrite an existing backup. Only one restore runs at a time across the cluster. After a restore completes, restart the node(s) for the in-memory view to update. API: `POST|GET|DELETE /api/v3/enterprise/backup[/{name}]` and `/api/v3/enterprise/restore[/{id}]`. * **Bulk import**: Import generic (non-IOx) Parquet files into Enterprise with `influxdb3 import upload`. Map Parquet columns to InfluxDB types (`i64`, `u64`, `f64`, `bool`, `string`, `time`, `tag`) using `--column` flags. Unmapped columns become fields. List in-progress and completed import jobs with `influxdb3 import list`. The target database and table must exist before importing. * **User auth and RBAC preview**: Multi-user authentication is now available as a preview feature. It is off by default (`--without-user-auth true`). When enabled, users authenticate with username and password to receive JWTs. Optional OAuth/OIDC is supported. Three built-in roles are available: Admin, Auditor, and Member. New CLI commands: `influxdb3 auth login`, `influxdb3 auth logout` (removes local credentials; does not revoke the signed JWT), `influxdb3 auth reset-password`, `influxdb3 create user`, `influxdb3 show users`, `influxdb3 update user`, `influxdb3 update user-roles`, `influxdb3 delete user`, `influxdb3 user require-password-reset`. New API endpoints: * `POST /api/v3/configure/user` — configure the initial user and create the operator token (also used by `influxdb3 manage init-admin`) * `POST /api/v3/authorize` — authenticate and obtain tokens * `POST /api/v3/authorize/refresh` — refresh an access token using a refresh token * `POST /api/v3/authorize/reset-password` — reset password using current credentials * `GET /api/v3/users`, `POST /api/v3/users` — list or create users (Enterprise) * `GET /api/v3/users/{id}`, `PATCH /api/v3/users/{id}`, `DELETE /api/v3/users/{id}` — get, update, or delete a user * `POST /api/v3/users/{id}/require-password-reset` — force password reset on next login * `GET /api/v3/users/{id}/roles`, `PUT /api/v3/users/{id}/roles` — read or replace a user’s roles * `GET /api/v3/roles` — list available roles * `GET /api/v3/auth/oauth/config` — discover OAuth configuration for device-code login New serve flags: `--without-user-auth`, `--jwt-key-id`, `--jwt-private-key`, `--jwt-issuer`, `--jwt-default-ttl-seconds`, `--oauth-issuer`, `--oauth-audience`, `--oauth-client-id`, `--oauth-scopes`, and `--rbac-authoring-disabled`. JWT keys must be PKCS#1 format (`openssl genrsa -traditional`). PKCS#8 format silently fails. * **`influxdb3 manage` command group**: A new `manage` subcommand groups offline administrative operations: `influxdb3 manage init-admin`, `influxdb3 manage add-admin-token`, and `influxdb3 manage downgrade-to-parquet`. The `downgrade-to-parquet` command has moved from the top level to this group (the old spelling still works but prints a deprecation warning). * **`influxdb3 remove node` command**: Remove a stopped node from the catalog. The compactor drains the node’s data before removal completes. * **Service-level logs**: Structured query and storage logging is now available for observability. Configure log output format and levels using new `serve` flags. * **Processing engine: internode gRPC for plugin writes**: Plugin writes from non-ingester nodes now route over internode gRPC rather than HTTP. This improves reliability in multi-node clusters. Requires `--internode-bind-addr` and `--conn-info` pointing at the gRPC port. * **Licensing: object-store portability**: Enterprise licenses are no longer bound to the object-store configuration (type, bucket, endpoint, region). Validation now enforces only JWT signature, expiry, and licensed core count. You can move to a different bucket or store with the same license. When moving to an empty store, copy `{cluster-id}/commercial_license` from the old store or restart with `--license-file`. * **Observability: 36 new compactor metrics**: 36 new `influxdb3_compactor_*` Prometheus metrics are now emitted. The primary health signal is `influxdb3_compactor_snapshot_lag_seconds`. A new `influxdb3_compaction_sequence_number` gauge tracks Parquet engine lag. * **`influxdb3 debug object-store-check` command**: Validate S3-compatible backend semantics before putting a store into production. Checks that the backend correctly implements the operations that InfluxDB relies on. #### Bug fixes * **Compaction stability**: Several compaction bugs are fixed, including: compaction incorrectly setting `ingest_time` (causing deduplication and row delete bugs), compactor deadlock and write amplification, stopped compactor nodes blocking storage engine upgrades, and compactor orphaning gen1 files. * **Tag case preserved during storage engine upgrades**: Tag names now preserve their original case when upgrading from Parquet to the new storage engine. * **Bulk import memory usage reduced**: Peak memory during multi-file bulk import operations is significantly reduced. * **Last cache delete deadlock fixed**: Deleting a last-value cache entry no longer causes a deadlock. * **Row delete: aborted requests no longer processed**: Row delete requests that were aborted are no longer picked up by the compactor. * **Table and database soft-delete name collision fixed**: Deleting a table or database and recreating it with the same name now works correctly. * **TLS CA flag cleanup**: The `serve` command no longer accepts `--tls-ca` — it was non-functional there. Client commands (such as `query` and `write`) still accept `--tls-ca` to trust a custom or self-signed CA, and the flag is now consistently bound to the `INFLUXDB3_TLS_CA` environment variable across commands that were previously missing the binding. The `cancel row-delete` command now also accepts TLS options. #### Breaking changes * **`influxdb3 row-delete` → `influxdb3 delete rows` and `influxdb3 cancel row-delete`**: The old `row-delete` top-level command is removed. Update scripts to use the new `delete rows` and `cancel row-delete` subcommands. * **`--conn-info` must point to the internode gRPC port for plugin writes**: In multi-node deployments, `--conn-info` must now reference the internode gRPC port (not the HTTP port) for plugin writes to reach the ingester. Update your cluster configuration before upgrading. * **PT compactor stale-job timeout changed from 5 minutes to 1 hour**: Compactor jobs that appear stuck take up to 1 hour to be retried (previously 5 minutes). This reduces false-positive preemption on slow storage backends. * **`--help-full` removed**: The `--help-full` flag is no longer available. Update any scripts that invoke `influxdb3 --help-full`. * **`--package-manager` flag deprecated**: The `uv` package manager has been removed. `pip` is always used for plugin package installation. The `--package-manager` flag still starts the server but prints a deprecation warning. Remove it from your startup configuration. * **`--pt-partition-count` renamed to `--pt-shard-count`**: The flag has no alias. Update any startup scripts that pass `--pt-partition-count` before upgrading to 3.10. * **System table columns renamed**: The following columns in storage engine system tables are renamed. Update any dashboards or queries that reference the old names: * `partition_id` → `shard_id` * `partition_start_time` → `shard_start_time` ### Known issues * **Row delete ghost rows**: After a row delete reports as “completed,” rows in the un-compacted ingest tail can survive and remain visible in queries. Workaround: re-issue the delete request after the affected data has been compacted and verify row counts. * **`system.row_deletes` returns HTTP 500 for predicate-less `--all-time` deletes**: Querying the `system.row_deletes` system table after a delete issued with `--all-time` and no tag predicate may return HTTP 500. Workaround: use `GET /api/v3/row_delete_requests` instead. * **Multi-shard data loss with `--use-pacha-tree`**: When the `--use-pacha-tree` storage engine is enabled, running with more than one shard (`--pt-shard-count > 1`) can cause data loss and a bootstrap deadlock. Workaround: keep `--pt-shard-count` at `1`. * **Backup does not capture row-delete state**: Backup (beta) doesn’t currently pick up row-delete state files in object storage, so row deletes may persist across a restore. * **Built-in roles grant narrower access than their descriptions suggest**: With the user authentication preview enabled, the Auditor and Member roles enforce less access than their role descriptions imply. Auditor users can list databases but cannot query data or read users or roles. Member users can read and write data but cannot list users or roles. Workaround: use an Admin-role user or an admin token for user and role management. ## v3.9.3 ### Core Maintenance release: v3.9.3 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Query chunk deduplication**: Fixed an issue where the same file could reach the query path from both the compactor and the ingester, causing affected queries to abort. * **Large file uploads during compaction**: Index files written during compaction now use adaptive uploads, preventing errors when writing large files to object storage. * Other bug fixes and performance improvements ## v3.9.2 ### Core Maintenance release: v3.9.2 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Bug fixes * **Gen1 file deduplication in compactor**: Fixed an issue where stale snapshot markers after `CompactionSummary` recovery could leave duplicate gen1 file entries and cause recompaction to abort. * **Empty series key handling**: Fixed compaction for tables with no tags (empty series key). * **Catalog token hash lookup**: Fixed a case where a failed `add_token` insert could leave a stale entry in the token hash lookup map. The lookup is now only updated after the underlying repository insert succeeds. * Other bug fixes and performance improvements ## v3.9.1 ### Core Maintenance release: v3.9.1 Core includes only build and dependency updates—no user-facing changes. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific updates: #### Features * **Configurable compactor snapshot loading**: The number of snapshots the Parquet compactor loads at startup is now externally configurable, making it easier to tune recovery behavior for large deployments. #### Bug Fixes and Performance Improvements * **Performance Improvements**: This release features faster multi-source query merges and improved retention scheduling with the new Performance Update Preview. * **Bug Fixes**: New updates fix issues where duplicate rows could be returned, Gen0 pruning safety, invalid status codes, and more. ## v3.9.0 ### Core #### Features * **DataFusion upgrade**: Upgraded the embedded DataFusion query engine for more efficient query execution. * **Python runtime upgrade**: Updated the bundled Python runtime for processing engine plugins with the latest security and bug fixes. * **Product identity in HTTP responses**: Metrics, HTTP response headers, and metadata now distinguish between Core and Enterprise builds. * **Database lifecycle hardening**: Background resources such as processing engine triggers are now cleanly decommissioned when a database is removed. #### Bug fixes * Additional bug fixes and performance improvements. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **Performance upgrade preview (beta)**: Preview major storage layer upgrades with the `--use-pacha-tree` flag. Includes a new columnar file format (`.pt` files), automatic Parquet migration with hybrid query mode, column families for efficient wide-table I/O, and bounded compaction. See [Performance upgrade preview](/influxdb3/enterprise/performance-preview/). The performance upgrade preview is a beta feature for staging and test environments only. Do not use for production workloads. * **Bulk data export**: Export compacted data as Parquet files for use with external tools. Use the new `influxdb3 export` subcommands to list databases, tables, and compacted time windows, then export selected data. See [Export to Parquet](/influxdb3/enterprise/performance-preview/#export-to-parquet). * **Automatic distinct value caching**: Enable automatic DVC creation for`SHOW TAG VALUES` queries and the `tag_values()` SQL function with`--pt-enable-auto-dvc`. Max cardinality and refresh intervals are configurable. * **Downgrade from performance preview**: Use`influxdb3 downgrade-to-parquet` to revert from the performance preview back to standard Parquet storage. Only data that existed before the upgrade (original Parquet files) is preserved. See [Downgrade to Parquet](/influxdb3/enterprise/performance-preview/#downgrade-to-parquet). * **Non-interactive delete confirmation**: Use the `--yes` (`-y`) flag with delete commands to skip interactive confirmation prompts in automated and headless environments. * **1MB default string field limit**: The maximum string field size defaults to 1MB (previously 64KB) to support v1 migration workloads. Writes exceeding 1MB are rejected with a validation error. #### Bug fixes * **Compaction stability**: Multiple fixes to compaction scheduling, priority handling, and resource management for improved stability in multi-node clusters. * Additional bug fixes and performance improvements. ## v3.8.4 ### Core No adjustments in this release. Core remains on v3.8.3. ### Enterprise #### Security * **Read and write tokens can no longer delete databases**: Authorization now evaluates both the HTTP method and the request path. Previously, tokens with read or write access to a database could also issue delete requests. #### Bug fixes * **Stale compactor blocking startup**: Fixed an issue where stopped (stale) compactor entries in the catalog prevented new compactor nodes from starting. Enterprise now only considers currently running compactor nodes for conflict checks. * **WAL replay**: Fixed an issue where combined-mode deployments silently ignored the `--wal-replay-concurrency-limit` flag and always used serial replay (concurrency of 1). The flag is now respected. * Other bug fixes and performance improvements. ## v3.8.3 ### Core #### Bug fixes * **WAL Buffer**: Fix an edge case that could potentially cause the WAL buffer to overflow ## v3.8.2 ### Core #### Features * **TLS: Skip certificate verification in CLI subcommands**: Use the new `--tls-no-verify` flag with any CLI subcommand to skip TLS certificate verification when connecting to a server. Useful for testing environments with self-signed certificates. * **Environment variable prefix standardization**: InfluxDB 3 specific environment variables use the `INFLUXDB3_` prefix for consistency. Legacy variable names continue to work (deprecated) for backward compatibility. > [!Important] > `INFLUXDB3_LOG_FILTER` is currently ignored. To set the log filter, use `LOG_FILTER` or the `--log-filter` flag. * **Parquet output format for `show` subcommands**: You can now save query results from the `show` subcommand directly to a Parquet file. * **SQL: `tag_values()` table function**: Query distinct tag values using the new `tag_values()` SQL table function. * **InfluxQL: `SHOW TAG VALUES` improvements**: In Enterprise deployments with auto-DVC enabled, `SHOW TAG VALUES` queries now use the Distinct Value Cache (DVC) automatically for improved performance. The `WHERE` clause is also now supported in `SHOW TAG VALUES` queries backed by the DVC, including compound predicates using `AND` and `OR`. * **InfluxQL: `SHOW RETENTION POLICIES` returns duration**: The `duration` column in `SHOW RETENTION POLICIES` results now returns the configured retention period in InfluxDB v1-compatible format (for example, `168h0m0s`) instead of returning an empty value. * **Ceph S3 backend support**: Use `--aws-s3-custom-backend ceph` with `influxdb3 serve` to connect to Ceph S3-compatible object storage. This enables ETag quote stripping required for conditional PUT operations with Ceph. * **`_internal` database default retention**: The `_internal` system database now defaults to a 7-day retention period (previously infinite). Only admin tokens can modify retention on the `_internal` database. * **Snapshot checkpointing for faster startup**: Use the new [`--checkpoint-interval`](/influxdb3/core/reference/config-options/#checkpoint-interval) serve option to periodically consolidate snapshots into monthly checkpoints. On startup, the server loads one to two checkpoints per calendar month instead of thousands of individual snapshots, reducing startup time for long-running servers. #### Bug fixes * **Sparse write handling for LVC, DVC, and Processing Engine**: Fixed incorrect behavior when processing sparse writes (writes that include only some fields from a table with multiple field families). * **`influxdb3-launcher`: SSL certificate path on RHEL systems**: Fixed an issue where the `SSL_CERT_FILE` environment variable was not correctly set on affected RHEL-based systems when using the `influxdb3-launcher` script. * Additional bug fixes and performance improvements. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **Data-only deletion for databases and tables**: Delete only the stored data from a database or table while preserving catalog entries, schema, and associated resources (tokens, triggers, caches, and processing engine configurations). #### Bug fixes * **Compaction stability**: Several fixes to compaction scheduling and processing to improve stability and correctness in multi-node clusters. * **TableIndexCache initialization**: Fixed a concurrency bug that could cause incorrect behavior during `TableIndexCache` initialization. * **Snapshot checkpointing**: Fixed an issue where snapshot checkpoint cleanup was not running as a background task. ## v3.8.0 ### Core #### Features * **Linux Service Management**: Run InfluxDB 3 as a managed system service on Linux ([#27026](https://github.com/influxdata/influxdb/pull/27026)): * Use `influxdb3-launcher` script to initialize the service * Deploy with systemd on modern Linux distributions * Deploy with SysV init on legacy systems * Customize service behavior with configuration files #### Bug fixes * **CLI**: View only active databases and tables when running `SHOW RETENTION` * **Database operations**: Receive an error when attempting to delete tables from an already-deleted database * **Retention Policy**: Receive an error when attempting to modify retention settings on deleted databases #### Security * **Processing Engine**: Run processing engine plugins with Python 3.13.11, which includes security and bug fixes ([#27014](https://github.com/influxdata/influxdb/pull/27014)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Bug fixes * **Table Limits**: Delete tables without affecting your table limit quota * **Retention Policy**: Receive an error when attempting to modify retention settings on deleted tables ## v3.7.0 ### Core #### Features * **HTTP API Enhancements**: * All HTTP responses now include a `cluster-uuid` header containing the catalog UUID, enabling clients to identify specific cluster instances programmatically * HTTP API now supports multi-member gzip payloads enabling batch operations * **CLI Commands**: * The new `influxdb3 show retention` command displays effective retention periods for each table, showing whether retention is set at the database-level or table-level with human-readable formatting (for example, “7d”, “24h”) #### Bug fixes * **Authorization**: Fixed multi-database permission handling to properly authorize queries across multiple databases. * **General Improvements**: Several key bug fixes and performance improvements. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: * **General Improvements**: Several key bug fixes and performance improvements. ## v3.6.0 ### Core #### Features * **Quick-Start Developer Experience**: * `influxdb3` now supports running without arguments for instant database startup, automatically generating IDs and storage flags values based on your system’s setup. * **Processing Engine**: * Plugins now support multiple files instead of single-file limitations. * When creating a trigger, you can upload a plugin directly from your local machine using the `--upload` flag. * Existing plugin files can now be updated at runtime without recreating triggers. * New `system.plugin_files` table and `show plugins` CLI command now provide visibility into all loaded plugin files. * Custom plugin repositories are now supported via `--plugin-repo` CLI flag. * Python package installation can now be disabled with `--package-manager disabled` for locked-down environments. * Plugin file path validation now prevents directory traversal attacks by blocking relative and absolute path patterns. #### Bug fixes * **Write API**: Fixed abbreviated precision values (`ns`, `ms`, `us`, `s`) to work correctly with the `/api/v3/write_lp` endpoint. Previously, only full precision names (`nanosecond`, `microsecond`, `millisecond`, `second`) worked. * **Token management**: Token display now works correctly for hard-deleted databases ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Operational improvements * **Storage engine**: improvements to the Docker-based license service development environment * **Catalog consistency**: Node management fixes for catalog edge cases * Other enhancements and performance improvements ## v3.5.0 ### Core #### Features * **Custom Plugin Repository**: * Use the `--plugin-repo` option with `influxdb3 serve` to specify custom plugin repositories. This enables loading plugins from personal repos or disabling remote repo access. #### Bug fixes * **Database reliability**: * Table index updates now complete atomically before creating new indices, preventing race conditions that could corrupt database state ([#26838](https://github.com/influxdata/influxdb/pull/26838)) * Delete operations are now idempotent, preventing errors during object store cleanup ([#26839](https://github.com/influxdata/influxdb/pull/26839)) * **Write path**: * Write operations to soft-deleted databases are now rejected, preventing data loss ([#26722](https://github.com/influxdata/influxdb/pull/26722)) * **Runtime stability**: * Fixed a compatibility issue that could cause deadlocks for concurrent operations ([#26804](https://github.com/influxdata/influxdb/pull/26804)) * Other bug fixes and performance improvements #### Security & Misc * Sensitive environment variable values are now hidden in CLI output and log messages ([#26837](https://github.com/influxdata/influxdb/pull/26837)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **Cache optimization**: * Last Value Cache (LVC) and Distinct Value Cache (DVC) now populate on creation and only on query nodes, reducing resource usage on ingest nodes. #### Bug fixes * **Object store reliability**: * Object store operations now use retryable mechanisms with better error handling #### Operational improvements * **Compaction optimizations**: * Compaction producer now waits 10 seconds before starting cycles, reducing resource contention during startup * Enhanced scheduling algorithms distribute compaction work more efficiently across available resources * **System tables**: * System tables now provide consistent data across different node modes (ingest, query, compact), enabling better monitoring in multi-node deployments ## v3.4.2 ### Core #### Bug fixes * **Database reliability**: * TableIndexCache initialization and ObjectStore improvements * Persister doesn’t need a TableIndexCache #### HTTP API changes * **v2 write API**: Standardized `/api/v2/write` error response format to match other InfluxDB editions. Error responses now use the consistent format: `{"code": "", "message": ""}` ([#26787](https://github.com/influxdata/influxdb/pull/26787)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **Storage engine**: Pass in root CA and disable TLS verify for object store * **Support**: Add support for manually stopping a node #### Bug fixes * **Bug fix**: Generation detail path calculation panic * **Database reliability**: Pass TableIndexCache through to PersistedFiles #### Operational improvements * **Compaction optimizations**: * Compaction cleaner now waits for 1 hour by default (previously 10 minutes) * Compaction producer now waits for 10 seconds before starting compaction cycle * **Catalog synchronization**: Background catalog update is synchronized every 1 second (previously 10 seconds) * **Logging improvements**: Added clear logging to indicate what sequence is persisted on producer side and what is consumed by the consumer side ## v3.4.1 ### Core #### Bug Fixes * Upgrading from 3.3.0 to 3.4.x no longer causes possible catalog migration issues ([#26756](https://github.com/influxdata/influxdb/pull/26756)) ## v3.4.0 ### Core #### Features * **Token Provisioning**: * Generate admin tokens offline and use them when starting the database if tokens do not already exist. This is meant for automated deployments and containerized environments. ([#26734](https://github.com/influxdata/influxdb/pull/26734)) * **Azure Endpoint**: * Use the `--azure-endpoint` option with `influxdb3 serve` to specify the Azure Blob Storage endpoint for object store connections. ([#26687](https://github.com/influxdata/influxdb/pull/26687)) * **No\_Sync via CLI**: * Use the `--no-sync` option with `influxdb3 write` to skip waiting for WAL persistence on write and immediately return a response to the write request. ([#26703](https://github.com/influxdata/influxdb/pull/26703)) #### Bug Fixes * Validate tag and field names when creating tables ([#26641](https://github.com/influxdata/influxdb/pull/26641)) * Using GROUP BY twice on the same column no longer causes incorrect data ([#26732](https://github.com/influxdata/influxdb/pull/26732)) #### Operational and security improvements * Introduce a new `v2` catalog path structure: * `catalog/v2/logs/` directory for log files (instead of `catalogs/`) * `catalog/v2/snapshot` file for checkpoint/snapshot files (instead of `_catalog_checkpoint`) * Reduce verbosity of the TableIndexCache log. ([#26709](https://github.com/influxdata/influxdb/pull/26709)) * WAL replay concurrency limit defaults to number of CPU cores, preventing possible OOMs. ([#26715](https://github.com/influxdata/influxdb/pull/26715)) * Remove unsafe signal\_handler code. ([#26685](https://github.com/influxdata/influxdb/pull/26685)) * Upgrade Python version to 3.13.7-20250818. ([#26686](https://github.com/influxdata/influxdb/pull/26686), [#26700](https://github.com/influxdata/influxdb/pull/26700)) * Tags with `/` in the name no longer break the primary key. ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **Token Provisioning**: * Generate *resource* and *admin* tokens offline and use them when starting the database. * Select a home or trial license without using an interactive terminal. Use `--license-type` [home | trial | commercial] option to the `influxdb3 serve` command to automate the selection of the license type. #### Bug Fixes * Don’t initialize the Processing Engine when the specified `--mode` does not require it. * Don’t panic when `INFLUXDB3_PLUGIN_DIR` is set in containers without the Processing Engine enabled. ## v3.3.0 ### Core #### Features * **Database management**: * Add `influxdb_schema` system table for database schema management ([#26640](https://github.com/influxdata/influxdb/pull/26640)) * Add `system.processing_engine_trigger_arguments` table for trigger configuration management ([#26604](https://github.com/influxdata/influxdb/pull/26604)) * Add write path logging to capture database name and client IP address for failed writes. The IP address is fetched from `x-forwarded-for` header if available, `x-real-ip` if available, or remote address as reported by TlsStream/AddrStream ([#26616](https://github.com/influxdata/influxdb/pull/26616)) * **Storage engine**: Introduce `TableIndexCache` for efficient automatic cleanup of expired gen1 Parquet files based on retention policies and hard deletes. Includes new background loop for applying data retention policies with configurable intervals and comprehensive purge operations for tables and retention period expired data ([#26636](https://github.com/influxdata/influxdb/pull/26636)) * **Authentication and security**: Add admin token recovery server that allows regenerating lost admin tokens without existing authentication. Includes new `--admin-token-recovery-http-bind` option for running recovery server on separate port, with automatic shutdown after successful token regeneration ([#26594](https://github.com/influxdata/influxdb/pull/26594)) * **Build process**: Allow passing git hash via environment variable in build process ([#26618](https://github.com/influxdata/influxdb/pull/26618)) #### Bug Fixes * **Database reliability**: * Fix URL-encoded table name handling failures ([#26586](https://github.com/influxdata/influxdb/pull/26586)) * Allow hard deletion of existing soft-deleted schema ([#26574](https://github.com/influxdata/influxdb/pull/26574)) * **Authentication**: Fix AWS S3 API error handling when tokens are expired ([#1013](https://github.com/influxdata/influxdb/pull/1013)) * **Query processing**: Set nanosecond precision as default for V1 query API CSV output ([#26577](https://github.com/influxdata/influxdb/pull/26577)) * **CLI reliability**: * Mark `--object-store` CLI argument as explicitly required ([#26575](https://github.com/influxdata/influxdb/pull/26575)) * Add help text for the new update subcommand ([#26569](https://github.com/influxdata/influxdb/pull/26569)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **License management**: * Improve licensing suggestions for Core users * Update license information handling * **Database management**: * Enhance `TableIndexCache` with advanced features beyond Core’s basic cleanup: persistent snapshots, object store integration, merge operations for distributed environments, and recovery capabilities for multi-node clusters * Add `TableIndexSnapshot`, `TableIndex`, and `TableIndices` types for distributed table index management * **Support**: Include contact information in trial error messages * **Telemetry**: Send onboarding telemetry before licensing setup #### Bug Fixes * **Compaction stability**: * Fix compactor re-compaction issues on max generation data overwrite * Fix compactor to treat “all” mode as “ingest” mode * **Database reliability**: * Add missing system tables to compact mode * **Storage integrity**: Update Parquet file paths to use 20 digits of 0-padding * **General fixes**: * Only load processing engine in correct server modes * Remove load generator alias clash ## v3.2.1 ### Core #### Features * **Enhanced database lifecycle management**: * Allow updating the hard deletion date for already-deleted databases and tables, providing flexibility in managing data retention and compliance requirements * Include `hard_deletion_date` column in `_internal` system tables (`databases` and `tables`) for better visibility into data lifecycle and audit trails #### Bug Fixes * **CLI improvements**: * Added help text for the new `update` subcommand for database and table update features ([#26569](https://github.com/influxdata/influxdb/pull/26569)) * `--object-store` and storage configuration parameters are required for the `serve` command ([#26575](https://github.com/influxdata/influxdb/pull/26575)) * **Query processing**: Fixed V1-compatible `/query` HTTP API endpoint to correctly default to nanosecond precision (`ns`) for CSV output, ensuring backward compatibility with InfluxDB 1.x clients and preventing data precision loss ([#26577](https://github.com/influxdata/influxdb/pull/26577)) * **Database reliability**: Fixed issue preventing hard deletion of soft-deleted databases and tables, enabling complete data removal for compliance and storage management needs ([#26574](https://github.com/influxdata/influxdb/pull/26574)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **License management improvements**: New `influxdb3 show license` command displays detailed license information including type, expiration date, and resource limits, making it easier to monitor license status and compliance #### Bug Fixes * **API stability**: Fixed HTTP API trigger specification to use the correct `"request:REQUEST_PATH"` syntax, ensuring proper request-based trigger configuration for processing engine workflows ## v3.2.0 **Core**: revision 1ca3168bee **Enterprise**: revision 1ca3168bee ### Core #### Features * **Hard delete for databases and tables**: Permanently delete databases and tables, enabling complete removal of data structures for compliance and storage management ([#26553](https://github.com/influxdata/influxdb/pull/26553)) * **AWS credentials auto-reload**: Support dynamic reloading of ephemeral AWS credentials from files, improving security and reliability when using AWS services ([#26537](https://github.com/influxdata/influxdb/pull/26537)) * **Database retention period support**: Add retention period support for databases via CLI commands (`create database` and `update database` commands) and HTTP APIs ([#26520](https://github.com/influxdata/influxdb/pull/26520)): * New CLI command: `update database --retention-period` * **Configurable lookback duration**: Users can specify lookback duration for PersistedFiles buffer, providing better control over query performance ([#26528](https://github.com/influxdata/influxdb/pull/26528)) * **WAL replay concurrency control**: Add concurrency limits for WAL (Write-Ahead Log) replay to improve startup performance and resource management ([#26483](https://github.com/influxdata/influxdb/pull/26483)) * **Enhanced write path**: Separate write path executor with unbounded memory for improved write performance ([#26455](https://github.com/influxdata/influxdb/pull/26455)) #### Bug Fixes * **WAL corruption handling**: Handle corrupt WAL files during replay without panic, improving data recovery and system resilience ([#26556](https://github.com/influxdata/influxdb/pull/26556)) * **Database naming validation**: Disallow underscores in database names when created via API to ensure consistency ([#26507](https://github.com/influxdata/influxdb/pull/26507)) * **Object store cleanup**: Automatic intermediate directory cleanup for file object store, preventing storage bloat ([#26480](https://github.com/influxdata/influxdb/pull/26480)) #### Additional Updates * Track generation 1 duration in catalog for better performance monitoring ([#26508](https://github.com/influxdata/influxdb/pull/26508)) * Add retention period support to the catalog ([#26479](https://github.com/influxdata/influxdb/pull/26479)) * Update help text for improved user experience ([#26509](https://github.com/influxdata/influxdb/pull/26509)) ### Enterprise All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: #### Features * **License management improvements**: * New `influxdb3 show license` command to display current license information * **Table-level retention period support**: Add retention period support for individual tables in addition to database-level retention, providing granular data lifecycle management * New CLI commands: `create table --retention-period` and `update table --retention-period` * Set or clear table-specific retention periods independent of database settings * **Compaction improvements**: * Address compactor restart issues for better reliability * Track compacted generation durations in catalog for monitoring * Disable Parquet cache for ingest mode to optimize memory usage #### Bug Fixes * **Query optimization**: Correctly partition query chunks into generations for improved performance * **Data integrity**: Don’t delete generation 1 files as part of compaction process * **License handling**: Trim whitespace from license file contents after reading to prevent validation issues ## v3.1.0 **Core**: revision `482dd8aac580c04f37e8713a8fffae89ae8bc264` **Enterprise**: revision `2cb23cf32b67f9f0d0803e31b356813a1a151b00` ### Core #### Token and Security Updates * Named admin tokens can now be created, with configurable expirations * `health`, `ping`, and `metrics` endpoints can now be opted out of authorization * `Basic $TOKEN` is now supported for all APIs * Additional info available when creating a new token * Additional info available when starting InfuxDB using `--without-auth` #### Additional Updates * New catalog metrics available for count operations * New object store metrics available for transfer latencies and transfer sizes * New query duration metrics available for Last Value caches * `/ping` API now contains versioning headers * Other performance improvements #### Fixes * New tags are now backfilled with NULL instead of empty strings * Bitcode deserialization error fixed * Series key metadata not persisting to Parquet is now fixed * Other general fixes and corrections ### Enterprise #### Token and Security Updates * Resource tokens now use resource names in `show tokens` * Tokens can now be granted `CREATE` permission for creating databases #### Additional Updates * Last value caches reload on restart * Distinct value caches reload on restart * Other performance improvements * Replaces remaining “INFLUXDB\_IOX” Dockerfile environment variables with the following: * `ENV INFLUXDB3_OBJECT_STORE=file` * `ENV INFLUXDB3_DB_DIR=/var/lib/influxdb3` #### Fixes * Improvements and fixes for license validations * False positive fixed for catalog error on shutdown * UX improvements for error and onboarding messages * Other general fixes and corrections ## v3.0.3 **Core**: revision 384c457ef5f0d5ca4981b22855e411d8cac2688e **Enterprise**: revision 34f4d28295132b9efafebf654e9f6decd1a13caf ### Core #### Fixes * Prevent operator token, `_admin`, from being deleted. ### Enterprise #### Fixes * Fix object store info digest that is output during onboarding. * Fix issues with false positive catalog error on shutdown. * Fix licensing validation issues. * Other fixes and performance improvements. ## v3.0.2 **Core**: revision d80d6cd60049c7b266794a48c97b1b6438ac5da9 **Enterprise**: revision e9d7e03c2290d0c3e44d26e3eeb60aaf12099f29 ### Core #### Security updates * Generate testing TLS certificates on the fly. * Set the TLS CA via the INFLUXDB3\_TLS\_CA environment variable. * Enforce a minimum TLS version for enhanced security. * Allow CORS requests from browsers. #### General updates * Support the `--format json` option in the token creation output. * Remove the Last Values Cache size limitation to improve performance and flexibility. * Incorporate additional performance improvements. #### Fixes * Fix a counting bug in the distinct cache. * Fix how the distinct cache handles rows with null values. * Fix handling of `group by` tag columns that use escape quotes. * Sort the IOx table schema consistently in the `SHOW TABLES` command. ### Enterprise #### Updates * Introduce a command and system table to list cluster nodes. * Support multiple custom permission argument matches. * Improve overall performance. #### Fixes * Initialize the object store only once. * Prevent the Home license server from crashing on restart. * Enforce the `--num-cores` thread allocation limit. ## v3.0.1 **Core**: revision d7c071e0c4959beebc7a1a433daf8916abd51214 **Enterprise**: revision 96e4aad870b44709e149160d523b4319ea91b54c ### Core #### Updates * TLS CA can now be set with an environment variable: `INFLUXDB3_TLS_CA` * Other general performance improvements #### Fixes * The `--tags` argument is now optional for creating a table, and additionally now requires at least one tag *if* specified ### Enterprise #### Updates * Catalog limits for databases, tables, and columns are now configurable using `influxdb3 serve` options: * `--num-database-limit` * `--num-table-limit` * `--num-total-columns-per-table-limit` * Improvements to licensing prompts for clarity * Other general performance improvements #### Fixes * **Home** license thread count log errors ## v3.0.0 ### Core #### Breaking Changes * **Parquet cache configuration**: Replaced `--parquet-mem-cache-size-mb` option with `--parquet-mem-cache-size`. The new option accepts values in megabytes (as an integer) or as a percentage of total available memory (for example, `20%`). The default value changed from `1000` MB to `20%` of total available memory. The environment variable `INFLUXDB3_PARQUET_MEM_CACHE_SIZE_MB` was replaced with `INFLUXDB3_PARQUET_MEM_CACHE_SIZE`. ([#26023](https://github.com/influxdata/influxdb/pull/26023)) * **Memory settings updates**: * Force snapshot memory threshold now defaults to `50%` of available memory * DataFusion execution memory pool now defaults to `20%` of available memory #### General Updates * Performance and reliability improvements. ### Enterprise #### Token Support * Authorization is now turned on by default. * Token support for database level permissions are now available. * Token support for system level queries are now available. #### General Updates * You can now use Commercial, Trial, and At-Home licenses. ## v3.0.0-0.beta.3 **Core**: revision f881c5844bec93a85242f26357a1ef3ebf419dd3 **Enterprise**: revision 6bef9e700a59c0973b0cefdc6baf11583933e262 ### Core #### General Improvements * InfluxDB 3 now supports graceful shutdowns when sending the interrupt signal to the service. #### Bug fixes * Empty batches in JSON format results are now handled properly * The Processing Engine now properly extracts data from DictionaryArrays ### Enterprise ##### Multi-node improvements * Query nodes now automatically detect new ingest nodes #### Bug fixes * Several fixes for compaction planning and processing * The Processing Engine now properly extracts data from DictionaryArrays ## v3.0.0-0.beta.2 **Core**: revision 033e1176d8c322b763b4aefb24686121b1b24f7c **Enterprise**: revision e530fcd498c593cffec2b56d4f5194afc717d898 This update brings several backend performance improvements to both Core and Enterprise in preparation for additional new features over the next several weeks. ## v3.0.0-0.beta.1 ### Core #### Features ##### Query and storage enhancements * New ability to stream response data for CSV and JSON queries, similar to how JSONL streaming works * Parquet files are now cached on the query path, improving performance * Query buffer is incrementally cleared when snapshotting, lowering memory spikes ##### Processing engine improvements * New Trigger Types: * *Scheduled*: Run Python plugins on custom, time-defined basis * *Request*: Call Python plugins via HTTP requests * New in-memory cache for storing data temporarily; cached data can be stored for a single trigger or across all triggers * Integration with virtual environments and install packages: * Specify Python virtual environment via CLI or `VIRTUAL_ENV` variable * Install packages or a `requirements.txt` * Python plugins are now implemented through triggers only. Simply create a trigger that references your Python plugin code file directly * Snapshots are now persisted in parallel, improving performance by running jobs simultaneously, rather than sequentially * Write to logs from within the Processing Engine ##### Database and CLI improvements * You can now specify the precision on your timestamps for writes using the `--precision` flag. Includes nano/micro/milli/seconds (ns/us/ms/s) * Added a new `show` system subcommand to display system tables with different options via SQL (default limit: 100) * Clearer table creation error messages ##### Bug fixes * If a database was created and the service was killed before any data was written, the database would not be retained * A last cache with specific “value” columns could not be queried * Running CTRL-C no longer stopped an InfluxDB process, due to a Python trigger * A previous build had broken JSON queries for RecordBatches * There was an issue with the distinct cache that caused panics #### Parameter changes For Core and Enterprise, there are parameter changes for simplicity: | Old Parameter |New Parameter| |-------------------------------|-------------| |`--writer-id`
`--host-id`| `--node-id` | ### Enterprise features #### Cluster management * Nodes are now associated with *clusters*, simplifying compaction, read replication, and processing * Node specs are now available for simpler management of cache creations #### Mode types * Set `ingest`, `query`, `compact`, and `process` individually per node ### Enterprise parameter changes For Enterprise, additional parameters for the `serve` command have been consolidated for simplicity: | Old Parameter | New Parameter | |------------------------------------------------------|---------------------------------------| |`--read-from-node-ids`
`--compact-from-node-ids`| `--cluster-id` | | `--run-compactions`
`--mode=compactor` |`--mode=compact`
`--mode=compact`| In addition to the above changes, `--cluster-id` is now a required parameter for all new instances. #### Related * [Get started with InfluxDB 3 Core](/influxdb3/core/get-started/) | Old | New | | --- | --- | | Old | New | | --disable-parquet-mem-cache , --disable-data-file-cache | --disable-file-cache | | --wal-max-write-buffer-size | --wal-max-buffered-writes | | --wal-snapshot-size | --wal-files-per-snapshot | | INFLUXDB3_DB_DIR | INFLUXDB3_DATA_DIR | | INFLUXDB3_NODE_IDENTIFIER_PREFIX | INFLUXDB3_NODE_ID | | INFLUXDB3_NODE_IDENTIFIER_FROM_ENV | INFLUXDB3_NODE_ID_FROM_ENV | | INFLUXDB3_NUM_WAL_FILES_TO_KEEP | INFLUXDB3_SNAPSHOTTED_WAL_FILES_TO_KEEP | | INFLUXDB3_START_WITHOUT_AUTH | INFLUXDB3_WITHOUT_AUTH | | INFLUXDB3_TCP_LISTINER_FILE_PATH (misspelling) | INFLUXDB3_TCP_LISTENER_FILE_PATH | | INFLUXDB3_TELEMETRY_DISABLE_UPLOAD | INFLUXDB3_DISABLE_TELEMETRY_UPLOAD | | Old name | New name | | --- | --- | | Old name | New name | | --pt-max-columns | --max-total-columns | | --pt-gen0-max-bytes-per-file | --gen0-max-file-size | | --pt-wal-replica-queue-size | --wal-replica-queue-length | | --pt-wal-max-buffer-size | --wal-buffer-size | | Old Parameter | New Parameter | | --- | --- | | Old Parameter | New Parameter | | --writer-id --host-id | --node-id | | Old Parameter | New Parameter | | --- | --- | | Old Parameter | New Parameter | | --read-from-node-ids --compact-from-node-ids | --cluster-id | | --run-compactions --mode=compactor | --mode=compact --mode=compact | --- # Visualize data Source: https://docs.influxdata.com/influxdb3/core/visualize-data/ Use visualization tools like Grafana, Superset, and others to visualize time series data queried from InfluxDB 3 Core. ### [Chronograf](/influxdb3/core/visualize-data/chronograf/) Chronograf is a data visualization and dashboarding tool designed to visualize data in InfluxDB 1.x. Learn how to use Chronograf with InfluxDB 3 Core. ### [Grafana](/influxdb3/core/visualize-data/grafana/) Install and run [Grafana](https://grafana.com/) to query and visualize data from InfluxDB 3 Core. ### [Power BI](/influxdb3/core/visualize-data/powerbi/) Use Microsoft Power BI Desktop with the InfluxDB 3 custom connector to query and visualize data from InfluxDB 3 Core. #### Related * [Query data in InfluxDB 3 Core](/influxdb3/core/query-data/) --- # Use Chronograf to visualize data Source: https://docs.influxdata.com/influxdb3/core/visualize-data/chronograf/ * InfluxQL only [Chronograf](/chronograf/v1/) is a data visualization and dashboarding tool designed to visualize data in InfluxDB 1.x using the **InfluxQL** query language. This page walks through how to use Chronograf with **InfluxDB 3 Core**. ## Prerequisites * [Download and install Chronograf](/chronograf/v1/introduction/installation/#download-and-install) * A running InfluxDB 3 Core instance with: * A [database](/influxdb3/core/admin/databases/) to query * A [token](/influxdb3/core/admin/tokens/)with read permissions ## Enable InfluxDB 3 support To connect Chronograf to InfluxDB 3 Core, start Chronograf with InfluxDB 3 support enabled using one of the following methods: #### CLI flag #### ```sh chronograf --influxdb-v3-support-enabled ``` ```sh export INFLUXDB_V3_SUPPORT_ENABLED=true chronograf ``` ## Create an InfluxDB connection 1. Open Chronograf and click **Configuration** (wrench icon) in the navigation menu. 2. Click **Add Connection**. ![Chronograf connections landing page](/img/chronograf/1-6-connection-landing-page.png) 3. In the **Server Type** dropdown, select **InfluxDB 3 Core**. Chronograf Server Type dropdown 4. Enter your InfluxDB 3 Core connection credentials: * **Connection URL:** URL of your InfluxDB 3 Core instance ``` http://localhost:8181 ``` * **Connection Name:** A name that uniquely identifies this connection configuration * **Database Token:** InfluxDB [token](/influxdb3/core/admin/tokens/) with read permissions on the database you want to query * **Telegraf Database Name:** InfluxDB [database](/influxdb3/core/admin/databases/)Chronograf uses to populate parts of the application, including the Host List page (default is `telegraf`) Chronograf InfluxDB 3 Core connection configuration 5. Click **Add Connection**. 6. Select the dashboards you would like to create, and then click **Next**. 7. To configure a Kapacitor connection, provide the necessary credentials, and then click **Continue**. Otherwise, click **Skip**. 8. Click **Finish**. ### Configure connection via CLI You can also configure the connection when starting Chronograf: Replace the following: * `DATABASE_TOKEN`: [token](/influxdb3/core/admin/tokens/)with read permissions ```sh chronograf --influxdb-v3-support-enabled \ --influxdb-type=influx-v3-core \ --influxdb-url=http://localhost:8181 \ --influxdb-token=DATABASE_TOKEN ``` For a complete list of configuration options, see [InfluxDB 3 connection options](/chronograf/v1/administration/config-options/#influxdb-3-connection-options). ## Query data in the Data Explorer 1. In Chronograf, click **Explore** in the left navigation bar. 2. Build and submit InfluxQL queries. > [!Note] > #### Schema information in the Data Explorer > > InfluxDB 3 Core supports InfluxQL metaqueries, so schema information > is available in the Data Explorer to help build queries. > You can also use [fully qualified measurements](/influxdb3/core/reference/influxql/select/#fully-qualified-measurement)in the `FROM` clause. For example: > > ``` > -- Fully qualified measurement > SELECT * FROM "db-name"."rp-name"."measurement-name" > > -- Fully qualified measurement shorthand (use the default retention policy) > SELECT * FROM "db-name".."measurement-name" > ``` > > For more information about available InfluxQL functionality, see[InfluxQL feature support](/influxdb3/core/reference/influxql/feature-support/). ## Important notes * [No administrative functionality](#no-administrative-functionality) * [Annotations and variables](#annotations-and-variables) ### No administrative functionality Chronograf cannot be used for administrative tasks in InfluxDB 3 Core. For example, you **cannot** do the following: * Define databases * Modify retention policies * Add users * Kill queries When connected to an InfluxDB 3 Core database, functionality in the **InfluxDB Admin** section of Chronograf is disabled. To complete administrative tasks, use the[`influxdb3` CLI](/influxdb3/core/reference/cli/influxdb3/). ### Annotations and variables Annotations and dashboard variables work with InfluxDB 3 Core when a `chronograf` database exists and is accessible with the same database token. When setting up variables with dynamic tag values, the backend query limits the scope of the record search with a time condition. By default, this is `time > now() - 7d`. Tags from records older than this limit are ignored. To change this setting, use the `--influxdb-v3-time-condition` flag or `INFLUXDB_V3_TIME_CONDITION` environment variable. #### Related * [Chronograf documentation](/chronograf/v1/) * [Query data with InfluxQL](/influxdb3/core/query-data/influxql/) --- # Use Grafana to visualize data Source: https://docs.influxdata.com/influxdb3/core/visualize-data/grafana/ Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/)to query and visualize data from InfluxDB 3 Core. > [!Note] > #### Identify your InfluxDB version > > If you are unsure which InfluxDB product you are using, use our interactive version detector to help identify it: > > [Detect my InfluxDB version](#) > *(Interactive feature in HTML: Opens version detector modal)* > > > [Grafana] enables you to query, visualize, alert on, and explore your metrics, > logs, and traces wherever they are stored. > [Grafana] provides you with tools to turn your time-series database (TSDB) > data into insightful graphs and visualizations. > > > > – [Grafana documentation](https://grafana.com/docs/grafana/latest/introduction/) > > * [Install Grafana or log in to Grafana Cloud](#install-grafana-or-log-in-to-grafana-cloud) * [InfluxDB data source](#influxdb-data-source) * [Before you begin](#before-you-begin) * [Create an InfluxDB data source](#create-an-influxdb-data-source) * [Query and visualize data](#query-and-visualize-data) ## Install Grafana or log in to Grafana Cloud 1. [Sign up for Grafana Cloud](https://grafana.com/products/cloud/) or follow the[Grafana installation instructions](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)to install Grafana for your operating system. 2. If running Grafana locally, enable the `newInfluxDSConfigPageDesign` feature flag to use the latest InfluxDB data source plugin. [](#option-1-configuration-file-recommended) Option 1: Configuration file (recommended) Add the following to your `grafana.ini` configuration file: ``` [feature_toggles] enable = newInfluxDSConfigPageDesign ``` Configuration file locations: * **Linux**: `/etc/grafana/grafana.ini` * **macOS (Homebrew)**: `/opt/homebrew/etc/grafana/grafana.ini` * **Windows**: `\conf\grafana.ini` [](#option-2-command-line) Option 2: Command line Enable the feature flag when starting Grafana: #### Linux #### ``` grafana-server --config /etc/grafana/grafana.ini \ cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign ``` ``` /opt/homebrew/opt/grafana/bin/grafana server \ --config /opt/homebrew/etc/grafana/grafana.ini \ --homepath /opt/homebrew/opt/grafana/share/grafana \ --packaging=brew \ cfg:default.paths.logs=/opt/homebrew/var/log/grafana \ cfg:default.paths.data=/opt/homebrew/var/lib/grafana \ cfg:default.paths.plugins=/opt/homebrew/var/lib/grafana/plugins \ cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign ``` ``` grafana-server.exe --config \conf\grafana.ini ` cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign ``` For more information, see [Configure feature toggles](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/) in the Grafana documentation. 3. Visit your **Grafana Cloud user interface** (UI) or, if running Grafana locally,[start Grafana](https://grafana.com/docs/grafana/latest/installation/) and visit[http://localhost:3000](http://localhost:3000) in your browser. > [!Note] > #### Using Grafana Cloud with a local InfluxDB instance > > If you need to keep your database local, consider running Grafana locally instead of using Grafana Cloud, > as this avoids the need to expose your database to the internet. > > To use InfluxDB running on your private network with Grafana Cloud, you must configure a[private data source for Grafana Cloud](https://grafana.com/docs/grafana-cloud/data-sources/private-data-sources/). ## InfluxDB data source The InfluxDB data source plugin is included in the Grafana core distribution. Use the plugin to query and visualize data from InfluxDB 3 Core with both SQL and InfluxQL. > [!Note] > #### Grafana 12.2+ > > The instructions below are for **Grafana 12.2+** with the `newInfluxDSConfigPageDesign`feature flag enabled. This introduces the newest version of the InfluxDB core plugin. > The updated plugin includes **SQL support** for InfluxDB 3-based products such > as InfluxDB 3 Core, and the interface dynamically adapts based on your > product and query language selection in [URL and authentication](#configure-url-and-authentication). ## Before you begin **Prerequisites:** * Grafana 12.2 or later * Administrator role in Grafana * Your [admin token](/influxdb3/core/admin/tokens/database)with read access to the database ### Quick reference: InfluxDB 3 Core configuration | Configuration |Value| |------------------------------------------------------------------|-----| | **Product selection** | | |**InfluxDB Enterprise 3.x** *(currently, no **Core** menu option)*| | | | **URL** | Server URL –for example, `https://localhost:8181`| | **Query languages** | SQL (requires HTTP/2), InfluxQL | | **Authentication** | Admin token (if authentication is enabled) | | **Database/Bucket** | Database name | ## Create an InfluxDB data source 1. In your Grafana interface, click **Connections** in the left sidebar. 2. Click **Data sources**. 3. Click **Add new data source**. 4. Search for and select **InfluxDB**. The InfluxDB data source configuration page displays. 5. In the **Settings** tab, enter a **Name** for your data source. ### Configure URL and authentication In the **URL and authentication** section, configure the following: * **URL**: Your InfluxDB 3 Core server URL –for example, `https://localhost:8181` * **Product**: From the dropdown, select**InfluxDB Enterprise 3.x** *(currently, no **Core** menu option)***InfluxDB Enterprise 3.x** * **Query Language**: Select **SQL** or **InfluxQL** * *(Optional)* **Advanced HTTP Settings**, **Auth**, and **TLS/SSL Settings** as needed for your environment ### Configure database settings The fields in this section change based on your query language selection in [URL and authentication](#configure-url-and-authentication). #### SQL #### #### SQL configuration When you select **SQL** as the query language, configure the following fields: * **Database**: Your [database](/influxdb3/core/admin/databases/) name. * **Token**: Your [admin token](/influxdb3/core/admin/tokens/database)with read access to the database SQL configuration for {{% product-name %}} #### Use SQL without TLS/SSL If using SQL to query InfluxDB 3 Core without TLS/SSL, enable the**Insecure Connection** option in your InfluxDB datasource configuration: 1. Under **Database settings**, enable **Advanced Database Settings**. 2. Enable **Insecure Connection**. Query InfluxDB using SQL without TLS/SSL > [!Important] > #### Grafana queries through a proxy require HTTP/2 > > For SQL queries, Grafana uses the Flight SQL protocol (gRPC) to query InfluxDB 3 Core, which requires **HTTP/2**. > If you query InfluxDB 3 Core through a proxy (such as HAProxy, nginx, or a load balancer), > verify that your proxy is configured to support HTTP/2. > Without HTTP/2 support, SQL queries through Grafana will fail to connect. > > InfluxQL queries use HTTP/1.1 and are not affected by this requirement. Click **Save & test**. Grafana attempts to connect to InfluxDB 3 Core and returns the result of the test. #### InfluxQL configuration When you select **InfluxQL** as the query language, configure the following fields: * **Database**: Your [database](/influxdb3/core/admin/databases/) name. * **User**: A username (can be any non-empty value). * **Password**: Your [database token](/influxdb3/core/admin/tokens/#database-tokens) with read access to the database. * **HTTP Method**: Select **POST** (recommended) or **GET** InfluxQL configuration for {{% product-name %}} Click **Save & test**. Grafana attempts to connect to InfluxDB 3 Core and returns the result of the test. ## Query and visualize data With your InfluxDB connection configured, use Grafana to query and visualize time series data. ### Query InfluxDB with Grafana After you [configure and save an InfluxDB datasource](#create-an-influxdb-data-source), use Grafana to build, run, and inspect queries against InfluxDB 3 Core . #### SQL #### > [!Note] > When working with the InfluxDB 3 Core SQL implementation > a **bucket** is equivalent to a **database**, > a **measurement** is equivalent to a **table**, and **time**, **fields**, and**tags** are structured as **columns**. > > > To learn more, see [Query Data](/influxdb3/core/query-data/sql/). > > 1. Click **Explore**. 2. In the dropdown, select the saved InfluxDB data source to query. 3. Use the SQL query form to build your query: * **Table**: Select the table (measurement) to query. * **Column**: Select one or more fields and tags to return as columns in query results. With SQL, select the `time` column to include timestamps with the data. Grafana relies on the `time` column to correctly graph time series data. * ***Optional:*** Toggle **filter** to generate **WHERE** clause statements. * **WHERE**: Configure condition expressions to include in the `WHERE` clause. * ***Optional:*** Toggle **group** to generate **GROUP BY** clause statements. * **GROUP BY**: Select columns to group by. If you include an aggregation function in the **SELECT** list, you must group by one or more of the queried columns. SQL returns the aggregation for each group. * Recommended: Toggle **order** to generate **ORDER BY** clause statements. * **ORDER BY**: Select columns to sort by. You can sort by time and multiple fields or tags. To sort in descending order, select **DESC**. 4. Recommended: Change format to **Time series**. * Use the **Format** dropdown to change the format of the query results. For example, to visualize the query results as a time series, select **Time series**. 5. Click **Run query** to execute the query. 1. Click **Explore**. 2. In the dropdown, select the **InfluxDB** data source that you want to query. 3. Use the InfluxQL query form to build your query: * **FROM**: Select the measurement that you want to query. * **WHERE**: To filter the query results, enter a conditional expression. * **SELECT**: Select fields to query and an aggregate function to apply to each. The aggregate function is applied to each time interval defined in the`GROUP BY` clause. * **GROUP BY**: By default, Grafana groups data by time to downsample results and improve query performance. You can also add other tags to group by. 4. Click **Run query** to execute the query. With your InfluxDB connection configured, use Grafana to query and visualize time series data. ### Build visualizations with Grafana For a comprehensive walk-through of creating visualizations with Grafana, see the [Grafana documentation](https://grafana.com/docs/grafana/latest/). ### Query inspection in Grafana To learn more about query management and inspection in Grafana, see the[Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/). [query](/influxdb3/core/tags/query/)[visualization](/influxdb3/core/tags/visualization/) | Configuration | Value | | --- | --- | | Configuration | Value | | Product selection | | | InfluxDB Enterprise 3.x (currently, no Core menu option) | | --- # Use Power BI to visualize data Source: https://docs.influxdata.com/influxdb3/core/visualize-data/powerbi/ * SQL Use [Microsoft Power BI Desktop](https://powerbi.microsoft.com/) with the This guide includes Windows (64‑bit) installation steps for the Arrow Flight SQL ODBC driver and the InfluxDB 3 Power BI connector. > > > Microsoft Power BI is a collection of software services, apps, and connectors > that work together to turn your unrelated sources of data into coherent, > visually immersive, and interactive insights. > > > > – [Microsoft Power BI documentation](https://learn.microsoft.com/en-us/power-bi/fundamentals/power-bi-overview) > > > [!Important] > These instructions are for Power BI Desktop only; it uses a custom connector. 1. [Prerequisites](#prerequisites) 2. [Install the Arrow Flight SQL ODBC driver](#install-the-arrow-flight-sql-odbc-driver) 3. [Install the Power BI connector](#install-the-power-bi-connector) 4. [Enable the connector in Power BI](#enable-the-connector-in-power-bi) 5. [Connect Power BI to InfluxDB](#connect-power-bi-to-influxdb) 6. [Query and visualize data](#query-and-visualize-data) ## Prerequisites * **Windows operating system**: The custom connector requires Windows (macOS users can use virtualization software like [Parallels](https://www.parallels.com/)) * **Power BI Desktop**: [Download and install Power BI Desktop](https://powerbi.microsoft.com/desktop/)(A free trial is available) * **InfluxDB 3 Core**: A running instance with data to query * **Database token**: Your [admin token](/influxdb3/core/admin/tokens/database) ## Install the Arrow Flight SQL ODBC driver The InfluxDB 3 custom connector for Power BI requires the Arrow Flight SQL ODBC driver. Install the driver before installing the Power BI connector. [Download the Arrow Flight SQL ODBC driver](https://docs.influxdata.com/downloads/apache-arrow-flight-sql-odbc-1.0.0-win64.msi) 1. Run the downloaded `.msi` installer. 2. Follow the installation wizard using default settings. 3. Complete the installation. #### Verify driver installation 1. Open the Windows application [ODBC Data Source Administrator (64-bit)](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/open-the-odbc-data-source-administrator). 2. Open the [ODBC Data Source Administrator (64-bit) Windows component](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/open-the-odbc-data-source-administrator) 3. Navigate to the **Drivers** tab 4. Verify **Arrow Flight SQL ODBC Driver** appears in the list. ## Install the Power BI connector After installing the ODBC driver, download and install the InfluxDB 3 custom connector for Power BI Desktop. [Download the InfluxDB 3 Power BI connector](https://docs.influxdata.com/downloads/InfluxDB.pqx) ### Move the connector to the custom connectors directory 1. Create the custom connectors folder if it doesn’t exist: ``` mkdir "$env:USERPROFILE\Documents\Power BI Desktop\Custom Connectors" ``` 2. Move the connector file to the custom connectors folder: ``` Move-Item "C:\Users\YOUR_USER\Downloads\InfluxDB.pqx" ` "$env:USERPROFILE\Documents\Power BI Desktop\Custom Connectors\" ``` Replace the following: * `YOUR_USER`: Your Windows username ## Enable the connector in Power BI To use custom connectors, you must adjust Power BI Desktop’s security settings: 1. Open Power BI Desktop 2. Select **File** \> **Options and settings** \> **Options** 3. Navigate to **Security** under **GLOBAL** 4. Under **Data Extensions**, select **(Not Recommended) Allow any extension to load without validation or warning** 5. Click **OK** 6. **Restart Power BI Desktop** for the changes to take effect > [!Warning] > #### Security considerations > > Enabling uncertified extensions allows any custom connector to load. > Only enable this setting if you trust the connectors you’re installing. ## Connect Power BI to InfluxDB After installing the connector and restarting Power BI Desktop: 1. Open **Power BI Desktop** 2. Click **Get Data** \> **More** 3. Search for **InfluxDB 3** and select it 4. Click **Connect** 5. In the **InfluxDB 3** connection dialog, configure the following: * **Server**: Your InfluxDB 3 Core URL without the port, (for example, `http://localhost`) * **Database**: Your database name * **Port**: Your server port (for example,`8181` (default) ) * **Native Query** (optional): Enter a SQL query to limit the data loaded 1. Select **DirectQuery** as the **Data Connectivity mode** 2. Click **OK** 3. When prompted for credentials: * Select **Basic** authentication * **Username**: Leave blank or enter any value * **Password**: Enter your [admin token](/influxdb3/core/admin/tokens/database) 1. Click **Connect** 2. Preview your data and click **Load** > [!Important] > #### Limit query size for optimal performance > > InfluxDB 3 Core can handle high throughput and dimensional data. > To ensure Power BI can successfully process data, limit query size by: > > * Using a `LIMIT` clause > * Specifying time ranges with `WHERE time >= ...` > * Filtering by specific columns or tags ## Query and visualize data ### Use Native Queries When connecting to InfluxDB 3, you can use the **Native Query** option to execute custom SQL queries: 1. In the connection dialog, enable **Native Query** 2. Enter your query in the provided field: ``` SELECT time, temp, room FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time DESC LIMIT 1000 ``` 3. Select **DirectQuery** as the connectivity mode 4. Click **OK** to load the data ### Create visualizations After loading data, Power BI displays your dataset in the **Fields** pane. #### View data in a table 1. In the **Visualizations** pane, select the **Table** visualization 2. In the **Fields** pane, select the columns to display: * **time**: Timestamp column * **room**: Tag column * **temp**: Field column 3. By default, Power BI summarizes numeric fields. To display raw values: * Select the field in the **Fields** or **Visualizations** pane * Go to the **Modeling** tab * Change **Default Summarization** to **Don’t Summarize** #### Create time series visualizations 1. In the **Visualizations** pane, select a visualization type (for example, **Line chart**) 2. Drag fields to the appropriate areas: * **X-axis**: `time` field * **Y-axis**: Measurement fields (for example, `temp`) * **Legend**: Tag fields (for example, `room`) 3. Use the **Filters** pane to apply additional filters 4. Configure visualization properties in the **Format** pane 5. Save your report ### Time series best practices * Always include time range filters in your queries to limit data volume * Use the `time` column for time-based visualizations * Apply Power BI’s date hierarchy features with the `time` column * Select only the columns you need to improve query performance * Use the `LIMIT` clause to restrict the number of rows returned ## Troubleshooting ### Driver not found If Power BI or other applications can’t find the Arrow Flight SQL ODBC driver: 1. Open the [ODBC Data Source Administrator (64-bit) Windows component](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/open-the-odbc-data-source-administrator) 2. Navigate to the **Drivers** tab 3. Verify **Arrow Flight SQL ODBC Driver** appears in the list 4. If not listed, reinstall the driver ### Connector not found If Power BI Desktop doesn’t show the InfluxDB 3 connector: * Verify the `.pqx` file is in the correct location:`Documents\Power BI Desktop\Custom Connectors\` * Ensure you enabled custom connectors in Power BI security settings * Restart Power BI Desktop after copying the connector file ### Connection errors If you encounter connection errors: * Verify your InfluxDB 3 Core instance is running and accessible * Check that the host URL and port are correct: * Local instances typically use `http://localhost:8181` * * Ensure `UseEncryption` is configured correctly for your connection type * Verify network connectivity and firewall rules allow connections on the specified port * Ensure your token has query permissions for the specified database ### Authentication errors If authentication fails: * Verify your database token is valid and not expired * Ensure the token is specified correctly (in the **Password** field for Power BI) * * Check that the token was copied correctly without extra spaces or characters * Leave the **Username** field blank or enter any value ### Query errors If queries fail or return errors: * Verify SQL syntax is correct for InfluxDB SQL * Check that referenced tables (measurements) exist in the database * Ensure column names match your schema * Review the [SQL reference](/influxdb3/core/reference/sql/) for supported features * For large result sets, consider adding `LIMIT` clauses ### Query performance For better query performance: * Always use `WHERE` clauses to filter data before loading * Include time range filters (for example, `WHERE time >= now() - INTERVAL '7 days'`) to limit the data scanned * Select only the columns you need * Use the `LIMIT` clause to restrict result size * Consider using **DirectQuery** mode instead of **Import** for large datasets * Monitor query execution for optimization opportunities #### Related * [Power BI documentation](https://learn.microsoft.com/en-us/power-bi/desktop/) * [Query data with SQL](/influxdb3/core/query-data/sql/) [visualization](/influxdb3/core/tags/visualization/)[powerbi](/influxdb3/core/tags/powerbi/)[sql](/influxdb3/core/tags/sql/) --- # Write data to InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/write-data/ Use tools like the `influxdb3`CLI, Telegraf, and InfluxDB client libraries to write time series data to InfluxDB 3 Core.[line protocol](#line-protocol)is the text-based format used to write data to InfluxDB. > [!Tip] > Tools are available to convert other formats (for example—[CSV](/influxdb3/core/write-data/use-telegraf/csv/)) to line protocol. * [Choose the write endpoint for your workload](#choose-the-write-endpoint-for-your-workload) * [Timestamp precision across write APIs](#timestamp-precision-across-write-apis) * [Line protocol](#line-protocol) * [Line protocol elements](#line-protocol-elements) * [Write data to InfluxDB](#write-data-to-influxdb) * [Use InfluxDB client libraries to write data](#use-influxdb-client-libraries-to-write-data) * [Use the InfluxDB HTTP API to write data](#use-the-influxdb-http-api-to-write-data) * [Use Telegraf to write data](#use-telegraf-to-write-data) * [Use the influxdb3 CLI to write data](#use-the-influxdb3-cli-to-write-data) * [Best practices for writing data](#best-practices-for-writing-data) * [Troubleshoot issues writing data](#troubleshoot-issues-writing-data) > [!Tip] > #### Choose the write endpoint for your workload > > When creating new write workloads, use the[InfluxDB HTTP API `/api/v3/write_lp` endpoint](/influxdb3/core/write-data/http-api/v3-write-lp/)and [client libraries](/influxdb3/core/write-data/client-libraries/). > > When bringing existing *v1* write workloads, use the InfluxDB 3 Core > HTTP API [`/write` endpoint](/influxdb3/core/api/write-data/#operation/PostV1Write). > > When bringing existing *v2* write workloads, use the InfluxDB 3 Core > HTTP API [`/api/v2/write` endpoint](/influxdb3/core/api/write-data/). > > **For Telegraf**, use the [`outputs.influxdb_v3`](/telegraf/v1/output-plugins/influxdb_v3/) output plugin. > For existing v1 or v2 write workloads, use the v1.x [`outputs.influxdb`](/telegraf/v1/output-plugins/influxdb/) or v2.x [`outputs.influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/) output plugins. > See how to [use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/). ## Timestamp precision across write APIs InfluxDB 3 Core provides multiple write endpoints for compatibility with different InfluxDB versions. The following table compares timestamp precision support across v1, v2, and v3 write APIs: | Precision |v1 (`/write`)|v2 (`/api/v2/write`)|v3 (`/api/v3/write_lp`)| |------------------|-------------|--------------------|-----------------------| |**Auto detection**| ❌ No | ❌ No | ✅ `auto` (default) | | **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` | | **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` | | **Microseconds** |✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` | | **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` | | **Minutes** | ✅ `m` | ❌ No | ❌ No | | **Hours** | ✅ `h` | ❌ No | ❌ No | | **Default** | Nanosecond | Nanosecond | **Auto** (guessed) | * All write endpoints accept timestamps in line protocol format. * InfluxDB 3 Core multiplies timestamps by the appropriate precision value to convert them to nanoseconds for internal storage. * All timestamps are stored internally as nanoseconds regardless of the precision specified when writing. ## Line protocol All data written to InfluxDB is written using[line protocol](/influxdb3/core/reference/line-protocol/), a text-based format that lets you provide the necessary information to write a data point to InfluxDB. ### Line protocol elements In InfluxDB, a point contains a table name, one or more fields, a timestamp, and optional tags that provide metadata about the observation. Each line of line protocol contains the following elements: \* Required * \* **table**: A string that identifies the table to store the data in. * **tag set**: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. *Spaces, commas, and equal characters must be escaped.* * \* **field set**: Comma-delimited list of key value pairs, each representing a field. Field keys are unquoted strings. *Spaces and commas must be escaped.*Field values can be [strings](/influxdb3/core/reference/line-protocol/#string)(quoted),[floats](/influxdb3/core/reference/line-protocol/#float),[integers](/influxdb3/core/reference/line-protocol/#integer),[unsigned integers](/influxdb3/core/reference/line-protocol/#uinteger), or [booleans](/influxdb3/core/reference/line-protocol/#boolean). * **timestamp**: [Unix timestamp](/influxdb3/core/reference/line-protocol/#unix-timestamp)associated with the data. InfluxDB supports up to nanosecond precision.*If the precision of the timestamp is not in nanoseconds, you must specify the precision when writing the data to InfluxDB.* #### Line protocol element parsing * **table**: Everything before the *first unescaped comma before the first whitespace*. * **tag set**: Key-value pairs between the *first unescaped comma* and the *first unescaped whitespace*. * **field set**: Key-value pairs between the *first and second unescaped whitespaces*. * **timestamp**: Integer value after the *second unescaped whitespace*. * Lines are separated by the newline character (`\n`). Line protocol is whitespace sensitive. myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 *For schema design recommendations, see[InfluxDB schema design](/influxdb3/core/write-data/best-practices/schema-design/).* ## Write data to InfluxDB ### [Use InfluxDB client libraries to write data](/influxdb3/core/write-data/client-libraries/) Use InfluxDB API clients to write points as line protocol data to InfluxDB 3 Core. ### [Use the InfluxDB HTTP API to write data](/influxdb3/core/write-data/http-api/) Use the `/api/v3/write_lp`, `/api/v2/write`, or `/write` HTTP API endpoints to write data to InfluxDB 3 Core. ### [Use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/) Use Telegraf to collect and write data to InfluxDB 3 Core. ### [Use the influxdb3 CLI to write data](/influxdb3/core/write-data/influxdb3-cli/) Use the [`influxdb3` CLI](/influxdb3/core/reference/cli/influxdb3/) to write line protocol data to InfluxDB 3 Core. ### [Best practices for writing data](/influxdb3/core/write-data/best-practices/) Learn about the recommendations and best practices for writing data to InfluxDB 3 Core. ### [Troubleshoot issues writing data](/influxdb3/core/write-data/troubleshoot/) Troubleshoot issues writing data. Find response codes for failed writes. Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. [write](/influxdb3/core/tags/write/)[line protocol](/influxdb3/core/tags/line-protocol/) | Precision | v1 ( /write ) | v2 ( /api/v2/write ) | v3 ( /api/v3/write_lp ) | | --- | --- | --- | --- | | Precision | v1 ( /write ) | v2 ( /api/v2/write ) | v3 ( /api/v3/write_lp ) | | Auto detection | ❌ No | ❌ No | ✅ auto (default) | | Seconds | ✅ s | ✅ s | ✅ second | | Milliseconds | ✅ ms | ✅ ms | ✅ millisecond | | Microseconds | ✅ u or µ | ✅ us | ✅ microsecond | | Nanoseconds | ✅ ns | ✅ ns | ✅ nanosecond | | Minutes | ✅ m | ❌ No | ❌ No | | Hours | ✅ h | ❌ No | ❌ No | | Default | Nanosecond | Nanosecond | Auto (guessed) | --- # Best practices for writing data Source: https://docs.influxdata.com/influxdb3/core/write-data/best-practices/ The following articles walk through recommendations and best practices for writing data to InfluxDB 3 Core. ### [Optimize writes to InfluxDB 3 Core](/influxdb3/core/write-data/best-practices/optimize-writes/) Tips and examples to optimize performance and system overhead when writing data to InfluxDB 3 Core. ### [InfluxDB schema design recommendations](/influxdb3/core/write-data/best-practices/schema-design/) Design your schema for simpler and more performant queries. --- # Optimize writes to InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/write-data/best-practices/optimize-writes/ Use these tips to optimize performance and system overhead when writing data to InfluxDB 3 Core. * [Batch writes](#batch-writes) * [On first write, sort tags by query priority](#on-first-write-sort-tags-by-query-priority) * [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible) * [Use gzip compression](#use-gzip-compression) * [Enable gzip compression in Telegraf](#enable-gzip-compression-in-telegraf) * [Enable gzip compression in InfluxDB client libraries](#enable-gzip-compression-in-influxdb-client-libraries) * [Use gzip compression with the InfluxDB API](#use-gzip-compression-with-the-influxdb-api) * [Synchronize hosts with NTP](#synchronize-hosts-with-ntp) * [Write multiple data points in one request](#write-multiple-data-points-in-one-request) * [Pre-process data before writing](#pre-process-data-before-writing) * [Prerequisites](#prerequisites) * [Filter data from a batch](#filter-data-from-a-batch) * [Coerce data types to avoid rejected point errors](#coerce-data-types-to-avoid-rejected-point-errors) * [Merge lines to optimize memory and bandwidth](#merge-lines-to-optimize-memory-and-bandwidth) * [Avoid sending duplicate data](#avoid-sending-duplicate-data) * [Run custom preprocessing code](#run-custom-preprocessing-code) > [!Note] > The following tools write to InfluxDB and employ *most* write optimizations by > default: > > * [Telegraf](/influxdb3/core/write-data/use-telegraf/) > * InfluxDB client libraries ## Batch writes Write data in batches to minimize network overhead when writing data to InfluxDB. > [!Note] > The optimal batch size is 10,000 lines of line protocol or 10 MBs, whichever > threshold is met first. ## On first write, sort tags by query priority The first write to a table in InfluxDB 3 Core determines the physical column order in storage, and that order has a direct impact on query performance. Columns that appear earlier are typically faster to filter and access during query execution. Sort your tags by query priority when performing the initial write to a table. Place the most commonly queried tags first—those you frequently use in `WHERE`clauses or joins—followed by less frequently queried ones. For example, if most of your queries filter by `region` and then by `host`, structure your first write so that `region` comes before `host`. > [!Important] > Column order is determined on the first write and cannot be changed afterward. > Tags added after the first write are added last in the column sort order. > Plan your schema with your query workload in mind to ensure the best long-term > performance. ## Use the coarsest time precision possible InfluxDB 3 Core supports up to nanosecond timestamp precision. However, if your data isn’t collected in nanoseconds, there is no need to write at that precision. For better performance, use the coarsest timestamp precision you can for your use case. > [!Tip] > By default, in CLI and HTTP API write requests, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision. To specify the precision of timestamps in your write request, pass the `precision` option. For more information, see the following: * [`/api/v3/write_lp` endpoint parameters](/influxdb3/core/write-data/http-api/v3-write-lp/) * [`/api/v2/write` v2 API endpoint parameters](/influxdb3/core/write-data/http-api/compatibility-apis/#v2-api-write-parameters) * [`/write` v1 API endpoint parameters](/influxdb3/core/write-data/http-api/compatibility-apis/#v1-api-write-parameters) ## Use gzip compression Use gzip compression to speed up writes to InfluxDB 3 Core. Benchmarks have shown up to a 5x speed improvement when data is compressed. #### Telegraf #### ### Enable gzip compression in Telegraf The [`influxdb_v3` output plugin](/telegraf/v1/output-plugins/influxdb_v3/)compresses write request bodies with gzip by default. If you use the `influxdb_v2` output plugin, set the `content_encoding` option to `gzip` in your `telegraf.conf`: ```toml [[outputs.influxdb_v2]] urls = ["http://localhost:8181"] # ... content_encoding = "gzip" ``` ### Enable gzip compression in InfluxDB client libraries Each [InfluxDB client library](/influxdb3/core/reference/client-libraries/) provides options for compressing write requests or enforces compression by default. The method for enabling compression is different for each library. For specific instructions, see the[InfluxDB client libraries documentation](/influxdb3/core/reference/client-libraries/). ### Use gzip compression with the InfluxDB API When using the InfluxDB API `/api/v2/write` endpoint to write data, compress the data with `gzip` and set the `Content-Encoding` header to `gzip`–for example: ```bash echo "mem,host=host1 used_percent=23.43234543 1641024000 mem,host=host2 used_percent=26.81522361 1641027600 mem,host=host1 used_percent=22.52984738 1641031200 mem,host=host2 used_percent=27.18294630 1641034800" | gzip > system.gzip \ curl --request POST "http://localhost:8181/api/v2/write?org=ignored&bucket=DATABASE_NAME" \ --header "Authorization: Token AUTH_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Content-Encoding: gzip" \ --data-binary @system.gzip ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* ## Synchronize hosts with NTP Use the Network Time Protocol (NTP) to synchronize time between hosts. If a timestamp isn’t included in line protocol, InfluxDB uses its host’s local time (in UTC) to assign timestamps to each point. If a host’s clocks isn’t synchronized with NTP, timestamps may be inaccurate. ## Write multiple data points in one request To write multiple lines in one request, each line of line protocol must be delimited by a new line (`\n`). ## Pre-process data before writing Pre-processing data in your write workload can help you avoid[write failures](/influxdb3/core/write-data/troubleshoot/#troubleshoot-failures)due to schema conflicts or resource use. For example, if you have many devices that write to the same table, and some devices use different data types for the same field, then you might want to generate an alert or convert field data to fit your schema before you send the data to InfluxDB. With [Telegraf](/telegraf/v1/), you can process data from other services and files and then write it to InfluxDB. In addition to processing data with Telegraf’s included plugins, you can use the[Execd processor plugin](/telegraf/v1/plugins/#processor-execd) to integrate your own code and external applications. The following examples show how to [configure the Telegraf agent](/telegraf/v1/configuration)and [plugins](/telegraf/v1/plugins/) to optimize writes. The examples use the [File input plugin](/telegraf/v1/plugins/#input-file) to read data from a file and use the [InfluxDB v3 output plugin](/telegraf/v1/plugins/#output-influxdb_v3)to write data to a database, but you can use any input and output plugin. ### Prerequisites [Install Telegraf](/telegraf/v1/install/) if you haven’t already. ### Filter data from a batch Use Telegraf and metric filtering to filter data before writing it to InfluxDB. Configure [metric filters](/telegraf/v1/configuration/#filters) to retain or remove data elements (before processor and aggregator plugins run). 1. Enter the following command to create a Telegraf configuration that parses system usage data, removes the specified fields and tags, and then writes the data to InfluxDB: ``` cat <> ./telegraf.conf [[inputs.cpu]] # Remove the specified fields from points. fieldpass = ["usage_system", "usage_idle"] # Remove the specified tags from points. tagexclude = ["host"] [[outputs.influxdb_v3]] urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" EOF ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* 2. To test the input and processor, enter the following command: ``` telegraf --test --config telegraf.conf ``` The output is similar to the following. For each row of input data, the filters pass the metric name, tags, specified fields, and timestamp. ``` > cpu,cpu=cpu0 usage_idle=100,usage_system=0 1702067201000000000 ... > cpu,cpu=cpu-total usage_idle=99.80198019802448,usage_system=0.1980198019802045 1702067201000000000 ``` ### Coerce data types to avoid rejected point errors Use Telegraf and the [Converter processor plugin](/telegraf/v1/plugins/#processor-converter)to convert field data types to fit your schema. For example, if you write the sample data in[Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data)to a database and then try to write the following batch to the same table: ```text home,room=Kitchen temp=23.1,hum=36.6,co=22.1 1641063600 home,room=Living\ Room temp=22i,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ``` InfluxDB expects `co` to contain an integer value and rejects points with `co`floating-point decimal (`22.1`) values. To avoid the error, configure Telegraf to convert fields to the data types in your schema columns. The following example converts the `temp`, `hum`, and `co` fields to fit the[sample data](/influxdb3/core/reference/sample-data/#home-sensor-data) schema: 1. In your terminal, enter the following command to create the sample data file: ``` cat < ./home.lp home,room=Kitchen temp=23.1,hum=36.6,co=22.1 1641063600 home,room=Living\ Room temp=22i,hum=36.4,co=17i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 EOF ``` 2. Enter the following command to create a Telegraf configuration that parses the sample data, converts the field values to the specified data types, and then writes the data to InfluxDB: ``` cat < ./telegraf.conf [[inputs.file]] ## For each interval, parse data from files in the list. files = ["home.lp"] influx_timestamp_precision = "1s" precision = "1s" tagexclude = ["host"] [[processors.converter]] [processors.converter.fields] ## A data type and a list of fields to convert to the data type. float = ["temp", "hum"] integer = ["co"] [[outputs.influxdb_v3]] ## InfluxDB credentials and the database to write to. urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" EOF ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* 3. To test the input and processor, enter the following command: ``` telegraf --test --config telegraf.conf ``` Telegraf outputs the following to stdout, and then exits: ``` > home,room=Kitchen co=22i,hum=36.6,temp=23.1 1641063600000000000 > home,room=Living\ Room co=17i,hum=36.4,temp=22 1641067200000000000 > home,room=Kitchen co=26i,hum=36.5,temp=22.7 1641067200000000000 ``` ### Merge lines to optimize memory and bandwidth Use Telegraf and the [Merge aggregator plugin](/telegraf/v1/plugins/#aggregator-merge)to merge points that share the same measurement, tag set, and timestamp. The following example creates sample data for two series (the combination of table, tag set, and timestamp), and then merges points in each series: 1. In your terminal, enter the following command to create the sample data file and calculate the number of seconds between the earliest timestamp and *now*. The command assigns the calculated value to a `grace_duration` variable that you’ll use in the next step. ``` cat < ./home.lp home,room=Kitchen temp=23.1 1641063600 home,room=Kitchen hum=36.6 1641063600 home,room=Kitchen co=22i 1641063600 home,room=Living\ Room temp=22.7 1641063600 home,room=Living\ Room hum=36.4 1641063600 home,room=Living\ Room co=17i 1641063600 EOF grace_duration="$(($(date +%s)-1641063000))s" ``` 2. Enter the following command to configure Telegraf to parse the file, merge the points, and write the data to InfluxDB–specifically, the configuration sets the following properties: * `influx_timestamp_precision`: for parsers, specifies the timestamp precision in the input data * Optional: `aggregators.merge.grace` extends the duration for merging points. To ensure the sample data is included, the configuration uses the calculated variable from the preceding step. ``` cat < ./telegraf.conf # Parse metrics from a file [[inputs.file]] ## A list of files to parse during each interval. files = ["home.lp"] ## The precision of timestamps in your data. influx_timestamp_precision = "1s" tagexclude = ["host"] # Merge separate metrics that share a series key [[aggregators.merge]] grace = "$grace_duration" ## If true, drops the original metric. drop_original = true # Writes metrics as line protocol to InfluxDB [[outputs.influxdb_v3]] ## InfluxDB credentials and the database to write data to. urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" EOF ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* 3. To test the input and aggregator, enter the following command: ``` telegraf --test --config telegraf.conf ``` Telegraf outputs the following to stdout, and then exits: ``` > home,room=Kitchen co=22i,hum=36.6,temp=23.1 1641063600000000000 > home,room=Living\ Room co=17i,hum=36.4,temp=22.7 1641063600000000000 ``` ### Avoid sending duplicate data Use Telegraf and the [Dedup processor plugin](/telegraf/v1/plugins/#processor-dedup)to filter data whose field values are exact repetitions of previous values. Deduplicating your data can reduce your write payload size and resource usage. The following example shows how to use Telegraf to remove points that repeat field values, and then write the data to InfluxDB: 1. In your terminal, enter the following command to create the sample data file and calculate the number of seconds between the earliest timestamp and *now*. The command assigns the calculated value to a `dedup_duration` variable that you’ll use in the next step. ``` cat < ./home.lp home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Living\ Room temp=22.5,hum=36.4,co=17i 1641063600 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641063605 home,room=Living\ Room temp=22.5,hum=36.4,co=17i 1641063605 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063610 home,room=Living\ Room temp=23.0,hum=36.4,co=17i 1641063610 EOF dedup_duration="$(($(date +%s)-1641063000))s" ``` 2. Enter the following command to configure Telegraf to parse the file, drop duplicate points, and write the data to InfluxDB–specifically, the sample configuration sets the following: * `influx_timestamp_precision`: for parsers, specifies the timestamp precision in the input data * `processors.dedup`: configures the Dedup processor plugin * Optional: `processors.dedup.dedup_interval`. Points in the range`dedup_interval` *to now* are considered for removal. To ensure the sample data is included, the configuration uses the calculated variable from the preceding step. ``` cat < ./telegraf.conf # Parse metrics from a file [[inputs.file]] ## A list of files to parse during each interval. files = ["home.lp"] ## The precision of timestamps in your data. influx_timestamp_precision = "1s" tagexclude = ["host"] # Filter metrics that repeat previous field values [[processors.dedup]] ## Drops duplicates within the specified duration dedup_interval = "$dedup_duration" # Writes metrics as line protocol to InfluxDB [[outputs.influxdb_v3]] ## InfluxDB credentials and the database to write data to. urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" EOF ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* 3. To test the input and processor, enter the following command: ``` telegraf --test --config telegraf.conf ``` Telegraf outputs the following to stdout, and then exits: ``` > home,room=Kitchen co=22i,hum=36.6,temp=23.1 1641063600000000000 > home,room=Living\ Room co=17i,hum=36.4,temp=22.5 1641063600000000000 > home,room=Kitchen co=26i,hum=36.5,temp=22.7 1641063605000000000 > home,room=Kitchen co=22i,hum=36.6,temp=23.1 1641063610000000000 > home,room=Living\ Room co=17i,hum=36.4,temp=23 1641063610000000000 ``` ### Run custom preprocessing code Use Telegraf and the [Execd processor plugin](/telegraf/v1/plugins/#processor-execd)to execute code external to Telegraf and then write the processed data. The Execd plugin expects line protocol data in stdin, passes the data to the configured executable, and then outputs line protocol to stdout. The following example shows how to use Telegraf to execute Go code for processing metrics and then write the output to InfluxDB. The Go `multiplier.go` sample code does the following: 1. Imports `influx` parser and serializer plugins from Telegraf. 2. Parses each line of data into a Telegraf metric. 3. If the metric contains a `count` field, multiplies the field value by `2`; otherwise, prints a message to stderr and exits. 4. In your editor, enter the following sample code and save the file as `multiplier.go`: ``` package main import ( "fmt" "os" "github.com/influxdata/telegraf/plugins/parsers/influx" influxSerializer "github.com/influxdata/telegraf/plugins/serializers/influx" ) func main() { parser := influx.NewStreamParser(os.Stdin) serializer := influxSerializer.Serializer{} if err := serializer.Init(); err != nil { fmt.Fprintf(os.Stderr, "serializer init failed: %v\n", err) os.Exit(1) } for { metric, err := parser.Next() if err != nil { if err == influx.EOF { return // stream ended } if parseErr, isParseError := err.(*influx.ParseError); isParseError { fmt.Fprintf(os.Stderr, "parse ERR %v\n", parseErr) os.Exit(1) } fmt.Fprintf(os.Stderr, "ERR %v\n", err) os.Exit(1) } c, found := metric.GetField("count") if !found { fmt.Fprintf(os.Stderr, "metric has no count field\n") os.Exit(1) } switch t := c.(type) { case float64: t *= 2 metric.AddField("count", t) case int64: t *= 2 metric.AddField("count", t) default: fmt.Fprintf(os.Stderr, "count is not an unknown type, it's a %T\n", c) os.Exit(1) } b, err := serializer.Serialize(metric) if err != nil { fmt.Fprintf(os.Stderr, "ERR %v\n", err) os.Exit(1) } fmt.Fprint(os.Stdout, string(b)) } } ``` 5. Initialize the module and install dependencies: ``` go mod init processlp go mod tidy ``` 6. In your terminal, enter the following command to create the sample data file: ``` cat < ./home.lp home,room=Kitchen temp=23.1,count=1 1641063600 home,room=Living\ Room temp=22.7,count=1 1641063600 home,room=Kitchen temp=23.1 1641063601 home,room=Living\ Room temp=22.7 1641063601 EOF ``` 7. Enter the following command to configure Telegraf to parse the file, execute the Go binary, and write the data–specifically, the sample configuration sets the following: * `influx_timestamp_precision`: for parsers, specifies the timestamp precision in the input data * `processors.execd`: configures the Execd plugin * `processors.execd.command`: sets the executable and arguments for Execd to run ``` cat < ./telegraf.conf # Parse metrics from a file [[inputs.file]] ## A list of files to parse during each interval. files = ["home.lp"] ## The precision of timestamps in your data. influx_timestamp_precision = "1s" tagexclude = ["host"] # Filter metrics that repeat previous field values [[processors.execd]] ## A list that contains the executable command and arguments to run as a daemon. command = ["go", "run", "multiplier.go"] # Writes metrics as line protocol to InfluxDB [[outputs.influxdb_v3]] ## InfluxDB credentials and the database to write data to. urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" EOF ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) *Store this in a secret store or environment variable to avoid exposing the raw token string.* 8. To test the input and processor, enter the following command: ``` telegraf --test --config telegraf.conf ``` Telegraf outputs the following to stdout, and then exits: ``` > home,room=Kitchen count=2,temp=23.1 1641063600000000000 > home,room=Living\ Room count=2,temp=22.7 1641063600000000000 ``` #### Related * [How to Ingest Data in InfluxDB (Video)](/resources/videos/ingest-data/) * [Use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/) --- # InfluxDB schema design recommendations Source: https://docs.influxdata.com/influxdb3/core/write-data/best-practices/schema-design/ Use the following guidelines to design your [schema](/influxdb3/core/reference/glossary/#schema)for simpler and more performant queries. * [InfluxDB data structure](#influxdb-data-structure) * [Primary keys](#primary-keys) * [Tags versus fields](#tags-versus-fields) * [Schema restrictions](#schema-restrictions) * [Do not use duplicate names for tags and fields](#do-not-use-duplicate-names-for-tags-and-fields) * [Maximum number of columns per table](#maximum-number-of-columns-per-table) * [Design for performance](#design-for-performance) * [Sort tags by query priority](#sort-tags-by-query-priority) * [Avoid wide schemas](#avoid-wide-schemas) * [Avoid sparse schemas](#avoid-sparse-schemas) * [Table schemas should be homogenous](#table-schemas-should-be-homogenous) * [Use the best data type for your data](#use-the-best-data-type-for-your-data) * [Design for query simplicity](#design-for-query-simplicity) * [Keep table names, tags, and fields simple](#keep-table-names-tags-and-fields-simple) * [Avoid keywords and special characters](#avoid-keywords-and-special-characters) ## InfluxDB data structure The InfluxDB 3 Core data model organizes time series data into databases and tables. A database can contain multiple tables. Tables contain multiple tags and fields. * **Database**: A named location where time series data is stored. In InfluxDB 3 Core, *database* is synonymous with *bucket* in InfluxDB Cloud Serverless and InfluxDB TSM implementations. A database can contain multiple *tables*. * **Table**: A logical grouping for time series data. In InfluxDB 3 Core, *table* is synonymous with *measurement* in InfluxDB Cloud Serverless and InfluxDB TSM implementations. All *points* in a given table should have the same *tags*. A table contains multiple *tags* and *fields*. * **Tags**: Key-value pairs that store metadata string values for each point–for example, a value that identifies or differentiates the data source or context–for example, host, location, station, etc. Tag values may be null. * **Fields**: Key-value pairs that store data for each point–for example, temperature, pressure, stock price, etc. Field values may be null, but at least one field value is not null on any given row. * **Timestamp**: Timestamp associated with the data. When stored on disk and queried, all data is ordered by time. In InfluxDB, a timestamp is a nanosecond-scale[Unix timestamp](/influxdb3/core/reference/glossary/#unix-timestamp)in UTC. A timestamp is never null. > [!Note] > #### What happened to buckets and measurements? > > If coming from earlier versions of InfluxDB, InfluxDB Cloud (TSM), or > InfluxDB Cloud Serverless, you’re likely familiar with the concepts *bucket*and *measurement*: > > * ***Bucket*** in InfluxDB v2 or InfluxDB Cloud Serverless is synonymous with***database*** in InfluxDB 3 Core. > * ***Measurement*** in InfluxDB v1, v2, or InfluxDB Cloud Serverless is synonymous > with ***table*** in InfluxDB 3 Core. ### Primary keys In time series data, the primary key for a row of data is typically a combination of timestamp and other attributes that uniquely identify each data point. In InfluxDB 3 Core, the primary key for a row is the combination of the point’s timestamp and *tag set*—the collection of[tag keys](/influxdb3/core/reference/glossary/#tag-key) and[tag values](/influxdb3/core/reference/glossary/#tag-value) on the point. A row’s primary key tag set does not include tags with null values. ### Tags versus fields When designing your schema for InfluxDB, a common question is, “what should be a tag and what should be a field?” The following guidelines should help answer that question as you design your schema. * Use tags to store metadata, or identifying information, about the source or context of the data. * Use fields to store measured values. * Tag values can only be strings. * Field values can be any of the following data types: * Integer * Unsigned integer * Float * String * Boolean > [!Note] > The InfluxDB 3 storage engine supports infinite tag value and series cardinality. > Unlike previous versions of InfluxDB, **tag value** cardinality doesn’t affect > the overall performance of your database. ## Schema restrictions ### Do not use duplicate names for tags and fields Use unique names for tags and fields within the same table. InfluxDB 3 Core stores tags and fields as unique columns in a table. If you attempt to write a table that contains tags or fields with the same name, the write fails due to a column conflict. ### Maximum number of columns per table A table has a [maximum number of columns](/influxdb3/core/admin/databases/#column-limit). Each row must include a time column. As a result, a table can have the following: * a time column * field and tag columns up to the configured maximum If you attempt to write to a table and exceed the column limit, then the write request fails and InfluxDB returns an error. InfluxData identified the[column limit](/influxdb3/core/admin/databases/#column-limit)as the safe limit for maintaining system performance and stability. Exceeding this threshold can result in[wide schemas](#avoid-wide-schemas), which can negatively impact performance and resource use, [depending on your queries](#avoid-non-specific-queries), the shape of your schema, and data types in the schema. ## Design for performance How you structure your schema within a table can affect resource use and the performance of queries against that table. The following guidelines help to optimize query performance: * [Sort tags by query priority](#sort-tags-by-query-priority) * [Avoid wide schemas](#avoid-wide-schemas) * [Avoid sparse schemas](#avoid-sparse-schemas) * [Table schemas should be homogenous](#table-schemas-should-be-homogenous) * [Use the best data type for your data](#use-the-best-data-type-for-your-data) ### Sort tags by query priority The first write to a table in InfluxDB 3 Core determines the physical column order in storage, and that order has a direct impact on query performance. Columns that appear earlier are typically faster to filter and access during query execution. Sort your tags by query priority when performing the initial write to a table. Place the most commonly queried tags first—those you frequently use in `WHERE`clauses or joins—followed by less frequently queried ones. For example, if most of your queries filter by `region` and then by `host`, structure your first write so that `region` comes before `host`. > [!Important] > Column order is determined on the first write and cannot be changed afterward. > Tags added after the first write are added last in the column sort order. > Plan your schema with your query workload in mind to ensure the best long-term > performance. ### Avoid wide schemas A wide schema refers to a schema with a large number of columns (tags and fields). Wide schemas can lead to the following issues: * Increased resource usage for persisting data during ingestion. * Reduced sorting performance due to complex primary keys with [too many tags](#avoid-too-many-tags). * Reduced query performance when selecting too many columns To prevent wide schema issues, limit the number of tags and fields stored in a table. If you need to store more than the [maximum number of columns](/influxdb3/core/admin/databases/#column-limit), consider segmenting your fields into separate tables. #### Avoid too many tags In InfluxDB 3 Core, the primary key for a row is the combination of the point’s timestamp and *tag set* - the collection of[tag keys](/influxdb3/core/reference/glossary/#tag-key)and [tag values](/influxdb3/core/reference/glossary/#tag-value) on the point. A point that contains more tags has a more complex primary key, which could impact sorting performance if you sort using all parts of the key. ### Avoid sparse schemas A sparse schema is one where, for many rows, columns contain null values. These generally stem from the following: * [non-homogenous table schemas](#table-schemas-should-be-homogenous) * [writing individual fields with different timestamps](#writing-individual-fields-with-different-timestamps) Sparse schemas require the InfluxDB query engine to evaluate many null columns, adding unnecessary overhead to storing and querying data. *For an example of a sparse schema,[view the non-homogenous schema example below](#view-example-of-a-sparse-non-homogenous-schema).* #### Writing individual fields with different timestamps Reporting fields at different times with different timestamps creates distinct rows that contain null values–for example: You report `fieldA` with `tagset`, and then report `field B` with the same`tagset`, but with a different timestamp. The result is two rows: one row has a *null* value for **field A** and the other has a *null* value for **field B**. In contrast, if you report fields at different times while using the same tagset and timestamp, the existing row is updated. This requires slightly more resources at ingestion time, but then gets resolved at persistence time or compaction time and avoids a sparse schema. ### Table schemas should be homogenous Data stored in a table should be “homogenous,” meaning each row should have the same tag and field keys. All rows stored in a table share the same columns, but if a point doesn’t include a value for a column, the column value is *null*. A table full of *null* values has a [“sparse” schema](#avoid-sparse-schemas). [](#view-example-of-a-sparse-non-homogenous-schema) View example of a sparse, non-homogenous schema Non-homogenous schemas are often caused by writing points to a table with inconsistent tag or field sets. In the following example, data is collected from two different sources and each source returns data with different tag and field sets. ##### Source 1 tags and fields: * tags: * source * code * crypto * fields: * price ##### Source 2 tags and fields: * tags: * src * currency * crypto * fields: * cost * volume These sets of data written to the same table result in a table full of null values (also known as a *sparse schema*): | time |source|src|code|currency|crypto | price | cost | volume | |--------------------|------|---|----|--------|-------|-----------|----------|-----------| |2025-01-01T12:00:00Z| src1 | |USD | |bitcoin|16588.45865| | | |2025-01-01T12:00:00Z| | 2 | | EUR |bitcoin| |16159.5806|16749450200| |2025-01-01T13:00:00Z| src1 | |USD | |bitcoin|16559.49871| | | |2025-01-01T13:00:00Z| | 2 | | EUR |bitcoin| |16131.3694|16829683245| |2025-01-01T14:00:00Z| src1 | |USD | |bitcoin|16577.46667| | | |2025-01-01T14:00:00Z| | 2 | | EUR |bitcoin| |16148.8727|17151722208| |2025-01-01T15:00:00Z| src1 | |USD | |bitcoin|16591.36998| | | |2025-01-01T15:00:00Z| | 2 | | EUR |bitcoin| |16162.4167|17311854919| ### Use the best data type for your data When writing data to a field, use the most appropriate[data type](/influxdb3/core/reference/glossary/#data-type) for your data–write integers as integers, decimals as floats, and booleans as booleans. A query against a field that stores integers outperforms a query against string data; querying over many long string values can negatively affect performance. ## Design for query simplicity Naming conventions for tables, tag keys, and field keys can simplify or complicate the process of writing queries for your data. The following guidelines help to ensure writing queries for your data is as simple as possible. * [Keep table names, tags, and fields simple](#keep-table-names-tags-and-fields-simple) * [Avoid keywords and special characters](#avoid-keywords-and-special-characters) ### Keep table names, tags, and fields simple Use one tag or one field for each data attribute. If your source data contains multiple data attributes in a single parameter, split each attribute into its own tag or field. Table names, tag keys, and field keys should be simple and accurately describe what each contains. Keep names free of data. The most common cause of a complex naming convention is when you try to “embed” data attributes into a table name, tag key, or field key. When each key and value represents one attribute (not multiple concatenated attributes) of your data, you’ll reduce the need for regular expressions in your queries. Without regular expressions, your queries will be easier to write and more performant. #### Not recommended For example, consider the following [line protocol](/influxdb3/core/reference/syntax/line-protocol/)that embeds multiple attributes (location, model, and ID) into a `sensor` tag value: ```text home,sensor=loc-kitchen.model-A612.id-1726ZA temp=72.1 home,sensor=loc-bath.model-A612.id-2635YB temp=71.8 ``` [](#view-written-data) View written data **table**: home | time | sensor |temp| |--------------------|--------------------------------|----| |2025-01-01T00:00:00Z|loc-kitchen.model-A612.id-1726ZA|72.1| |2025-01-01T00:00:00Z| loc-bath.model-A612.id-2635YB |71.8| To query data from the sensor with ID `1726ZA`, you have to use either SQL pattern matching or regular expressions to evaluate the `sensor` tag: #### SQL #### ```sql SELECT * FROM home WHERE sensor LIKE '%id-1726ZA%' ``` ```sql SELECT * FROM home WHERE sensor =~ /id-1726ZA/ ``` SQL pattern matching and regular expressions both complicate the query and are less performant than simple equality expressions. #### Recommended The better approach would be to write each sensor attribute as a separate tag: ```text home,location=kitchen,sensor_model=A612,sensor_id=1726ZA temp=72.1 home,location=bath,sensor_model=A612,sensor_id=2635YB temp=71.8 ``` [](#view-written-data) View written data **table**: home | time |location|sensor\_model|sensor\_id|temp| |--------------------|--------|-------------|----------|----| |2023-01-01T00:00:00Z|kitchen | A612 | 1726ZA |72.1| |2023-01-01T00:00:00Z| bath | A612 | 2635YB |71.8| To query data from the sensor with ID `1726ZA` using this schema, you can use a simple equality expression: ```sql SELECT * FROM home WHERE sensor_id = '1726ZA' ``` This query is easier to write and is more performant than using pattern matching or regular expressions. ### Avoid keywords and special characters To simplify query writing, avoid using reserved keywords or special characters in table names, tag keys, and field keys. * [SQL keywords](/influxdb3/core/reference/sql/#keywords) * [InfluxQL keywords](/influxdb3/core/reference/influxql/#keywords) When using SQL or InfluxQL to query tables, tags, and fields with special characters or keywords, you have to wrap these identifiers in **double quotes**. ```sql SELECT "example-field", "tag@1-23" FROM "example-table" WHERE "tag@1-23" = 'ABC' ``` #### Related * [Manage databases](/influxdb3/core/admin/databases/) * [influxdb3 CLI](/influxdb3/core/reference/cli/influxdb3/) | time | source | src | code | currency | crypto | price | cost | volume | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | time | source | src | code | currency | crypto | price | cost | volume | | 2025-01-01T12:00:00Z | src1 | | USD | | bitcoin | 16588.45865 | | | | 2025-01-01T12:00:00Z | | 2 | | EUR | bitcoin | | 16159.5806 | 16749450200 | | 2025-01-01T13:00:00Z | src1 | | USD | | bitcoin | 16559.49871 | | | | 2025-01-01T13:00:00Z | | 2 | | EUR | bitcoin | | 16131.3694 | 16829683245 | | 2025-01-01T14:00:00Z | src1 | | USD | | bitcoin | 16577.46667 | | | | 2025-01-01T14:00:00Z | | 2 | | EUR | bitcoin | | 16148.8727 | 17151722208 | | 2025-01-01T15:00:00Z | src1 | | USD | | bitcoin | 16591.36998 | | | | 2025-01-01T15:00:00Z | | 2 | | EUR | bitcoin | | 16162.4167 | 17311854919 | | time | sensor | temp | | --- | --- | --- | | time | sensor | temp | | 2025-01-01T00:00:00Z | loc-kitchen.model-A612.id-1726ZA | 72.1 | | 2025-01-01T00:00:00Z | loc-bath.model-A612.id-2635YB | 71.8 | | time | location | sensor_model | sensor_id | temp | | --- | --- | --- | --- | --- | | time | location | sensor_model | sensor_id | temp | | 2023-01-01T00:00:00Z | kitchen | A612 | 1726ZA | 72.1 | | 2023-01-01T00:00:00Z | bath | A612 | 2635YB | 71.8 | --- # Use InfluxDB client libraries to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/client-libraries/ Use InfluxDB 3 client libraries that integrate with your code to construct data as time series points, and then write them as line protocol to an InfluxDB 3 Core database. * [Set up your project](#set-up-your-project) * [Initialize a project directory](#initialize-a-project-directory) * [Install the client library](#install-the-client-library) * [Construct line protocol](#construct-line-protocol) * [Example home schema](#example-home-schema) ## Set up your project Set up your InfluxDB 3 Core project and credentials to write data using the InfluxDB 3 client library for your programming language of choice. 1. [Install InfluxDB 3 Core](/influxdb3/core/install/) 2. [Set up InfluxDB 3 Core](/influxdb3/core/get-started/setup/) 3. Create a project directory and store your InfluxDB 3 Core credentials as environment variables or in a project configuration file, such as a `.env` (“dotenv”) file. After setting up InfluxDB 3 Core and your project, you should have the following: * InfluxDB 3 Core credentials: * [Database](/influxdb3/core/admin/databases/) * [Authorization token](/influxdb3/core/admin/tokens/) * InfluxDB 3 Core URL * A directory for your project. * Credentials stored as environment variables or in a project configuration file–for example, a `.env` (“dotenv”) file. ### Initialize a project directory Create a project directory and initialize it for your programming language. #### Go #### 1. Install [Go 1.13 or later](https://golang.org/doc/install). 2. Create a directory for your Go module and change to the directory–for example: ``` mkdir iot-starter-go && cd $_ ``` 3. Initialize a Go module–for example: ``` go mod init iot-starter ``` 1. Install [Node.js](https://nodejs.org/en/download/). 2. Create a directory for your JavaScript project and change to the directory–for example: ``` mkdir -p iot-starter-js && cd $_ ``` 3. Initialize a project–for example, using `npm`: ``` npm init ``` 1. Install [Python](https://www.python.org/downloads/) 2. Inside of your project directory, create a directory for your Python module and change to the module directory–for example: ``` mkdir -p iot-starter-py && cd $_ ``` 3. **Optional, but recommended**: Use[`venv`](https://docs.python.org/3/library/venv.html) or[`conda`](https://docs.continuum.io/anaconda/install/) to activate a virtual environment for installing and executing code–for example, enter the following command using `venv` to create and activate a virtual environment for the project: ``` python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate ``` ### Install the client library Install the InfluxDB 3 client library for your programming language of choice. #### C# #### Add the [InfluxDB 3 C# client library](https://github.com/InfluxCommunity/influxdb3-csharp) to your project using the[`dotnet` CLI](https://docs.microsoft.com/dotnet/core/tools/dotnet) or by adding the package to your project file–for example: ```bash dotnet add package InfluxDB3.Client ``` Add the[InfluxDB 3 Go client library](https://github.com/InfluxCommunity/influxdb3-go)to your project using the[`go get` command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)–for example: ```bash go mod init path/to/project/dir && cd $_ go get github.com/InfluxCommunity/influxdb3-go/v2/influxdb3 ``` Add the [InfluxDB 3 Java client library](https://github.com/InfluxCommunity/influxdb3-java) to your project dependencies using the [Maven](https://maven.apache.org/)[Gradle](https://gradle.org/) build tools. For example, to add the library to a Maven project, add the following dependency to your `pom.xml` file: ```xml com.influxdb influxdb3-java 1.1.0 ``` To add the library to a Gradle project, add the following dependency to your `build.gradle` file: ```groovy dependencies { implementation 'com.influxdb:influxdb3-java:1.1.0' } ``` For a Node.js project, use `@influxdata/influxdb3-client`, which provides main (CommonJS), module (ESM), and browser (UMD) exports. Add the [InfluxDB 3 JavaScript client library](https://github.com/InfluxCommunity/influxdb3-js) using your preferred package manager–for example, using [`npm`](https://www.npmjs.com/): ```bash npm install --save @influxdata/influxdb3-client ``` Install the [InfluxDB 3 Python client library](https://github.com/InfluxCommunity/influxdb3-python) using[`pip`](https://pypi.org/project/pip/). To use Pandas features, such as `to_pandas()`, provided by the Python client library, you must also install the[`pandas` package](https://pandas.pydata.org/). ```bash pip install influxdb3-python pandas ``` ## Construct line protocol With a [basic understanding of line protocol](/influxdb3/core/write-data/#line-protocol), you can construct line protocol data and write it to InfluxDB 3 Core. Use client library write methods to provide data as raw line protocol or as `Point` objects that the client library converts to line protocol. If your program creates the data you write to InfluxDB, the `Point`interface to take advantage of type safety in your program. Client libraries provide one or more `Point` constructor methods. Some libraries support language-native data structures, such as Go’s `struct`, for creating points. Examples in this guide show how to construct `Point` objects that follow the [example `home` schema](#example-home-schema), and then write the points as line protocol data to an InfluxDB 3 Core database. ### Example home schema Consider a use case where you collect data from sensors in your home. Each sensor collects temperature, humidity, and carbon monoxide readings. To collect this data, use the following schema: * **table**: `home` * **tags** * `room`: Living Room or Kitchen * **fields** * `temp`: temperature in °C (float) * `hum`: percent humidity (float) * `co`: carbon monoxide in parts per million (integer) * **timestamp**: Unix timestamp in *second* precision #### Go #### 1. Create a file for your module–for example: `main.go`. 2. In `main.go`, enter the following sample code: ``` package main import ( "context" "os" "fmt" "time" "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" "github.com/influxdata/line-protocol/v2/lineprotocol" ) func Write() error { url := os.Getenv("INFLUX_HOST") token := os.Getenv("INFLUX_TOKEN") database := os.Getenv("INFLUX_DATABASE") // To instantiate a client, call New() with InfluxDB credentials. client, err := influxdb3.New(influxdb3.ClientConfig{ Host: url, Token: token, Database: database, }) /** Use a deferred function to ensure the client is closed when the * function returns. **/ defer func (client *influxdb3.Client) { err = client.Close() if err != nil { panic(err) } }(client) /** Use the NewPoint method to construct a point. * NewPoint(measurement, tags map, fields map, time) **/ point := influxdb3.NewPoint("home", map[string]string{ "room": "Living Room", }, map[string]any{ "temp": 24.5, "hum": 40.5, "co": 15i}, time.Now(), ) /** Use the NewPointWithMeasurement method to construct a point with * method chaining. **/ point2 := influxdb3.NewPointWithMeasurement("home"). SetTag("room", "Living Room"). SetField("temp", 23.5). SetField("hum", 38.0). SetField("co", 16i). SetTimestamp(time.Now()) fmt.Println("Writing points") points := []*influxdb3.Point{point, point2} /** Write points to InfluxDB. * You can specify WriteOptions, such as Gzip threshold, * default tags, and timestamp precision. Default precision is lineprotocol.Nanosecond **/ err = client.WritePoints(context.Background(), points, influxdb3.WithPrecision(lineprotocol.Second)) return nil } func main() { Write() } ``` 3. To run the module and write the data to your InfluxDB 3 Core database, enter the following command in your terminal: ``` go run main.go ``` 1. Create a file for your module–for example: `write-points.js`. 2. In `write-points.js`, enter the following sample code: ``` // write-points.js import { InfluxDBClient, Point } from '@influxdata/influxdb3-client'; /** * Set InfluxDB credentials. */ const host = process.env.INFLUX_HOST ?? ''; const database = process.env.INFLUX_DATABASE; const token = process.env.INFLUX_TOKEN; /** * Write line protocol to InfluxDB using the JavaScript client library. */ export async function writePoints() { /** * Instantiate an InfluxDBClient. * Provide the host URL and the database token. */ const client = new InfluxDBClient({ host, token }); /** Use the fluent interface with chained methods to construct Points. */ const point = Point.measurement('home') .setTag('room', 'Living Room') .setFloatField('temp', 22.2) .setFloatField('hum', 35.5) .setIntegerField('co', 7) .setTimestamp(new Date().getTime() / 1000); const point2 = Point.measurement('home') .setTag('room', 'Kitchen') .setFloatField('temp', 21.0) .setFloatField('hum', 35.9) .setIntegerField('co', 0) .setTimestamp(new Date().getTime() / 1000); /** Write points to InfluxDB. * The write method accepts an array of points, the target database, and * an optional configuration object. * You can specify WriteOptions, such as Gzip threshold, default tags, * and timestamp precision. Default precision is lineprotocol.Nanosecond **/ try { await client.write([point, point2], database, '', { precision: 's' }); console.log('Data has been written successfully!'); } catch (error) { console.error(`Error writing data to InfluxDB: ${error.body}`); } client.close(); } writePoints(); ``` 3. To run the module and write the data to your {{\< product-name \>}} database, enter the following command in your terminal: ``` node writePoints.js ``` 1. Create a file for your module–for example: `write-points.py`. 2. In `write-points.py`, enter the following sample code to write data in batching mode: ``` import os from influxdb_client_3 import ( InfluxDBClient3, InfluxDBError, Point, WritePrecision, WriteOptions, write_client_options) host = os.getenv('INFLUX_HOST') token = os.getenv('INFLUX_TOKEN') database = os.getenv('INFLUX_DATABASE') # Create an array of points with tags and fields. points = [Point("home") .tag("room", "Kitchen") .field("temp", 25.3) .field('hum', 20.2) .field('co', 9)] # With batching mode, define callbacks to execute after a successful or # failed write request. # Callback methods receive the configuration and data sent in the request. def success(self, data: str): print(f"Successfully wrote batch: data: {data}") def error(self, data: str, exception: InfluxDBError): print(f"Failed writing batch: config: {self}, data: {data} due: {exception}") def retry(self, data: str, exception: InfluxDBError): print(f"Failed retry writing batch: config: {self}, data: {data} retry: {exception}") # Configure options for batch writing. write_options = WriteOptions(batch_size=500, flush_interval=10_000, jitter_interval=2_000, retry_interval=5_000, max_retries=5, max_retry_delay=30_000, exponential_base=2) # Create an options dict that sets callbacks and WriteOptions. wco = write_client_options(success_callback=success, error_callback=error, retry_callback=retry, write_options=write_options) # Instantiate a synchronous instance of the client with your # InfluxDB credentials and write options, such as Gzip threshold, default tags, # and timestamp precision. Default precision is nanosecond ('ns'). with InfluxDBClient3(host=host, token=token, database=database, write_client_options=wco) as client: client.write(points, write_precision='s') ``` 3. To run the module and write the data to your InfluxDB 3 Core database, enter the following command in your terminal: ``` python write-points.py ``` The sample code does the following: 1. Instantiates a client configured with the InfluxDB URL and API token. 2. Constructs `home`table `Point` objects. 3. Sends data as line protocol format to InfluxDB and waits for the response. 4. If the write succeeds, logs the success message to stdout; otherwise, logs the failure message and error details. 5. Closes the client to release resources. #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) * [InfluxDB 3 API client libraries](/influxdb3/core/reference/client-libraries/v3/) * [/api/v3/write\_lp endpoint](/influxdb3/core/api/write-data/#operation/PostWriteLP) --- # Use the InfluxDB HTTP API to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/http-api/ Use the InfluxDB HTTP API to write data to InfluxDB 3 Core. Different APIs are available depending on your integration method. > [!Tip] > #### Choose the write endpoint for your workload > > When creating new write workloads, use the[InfluxDB HTTP API `/api/v3/write_lp` endpoint](/influxdb3/core/write-data/http-api/v3-write-lp/)and [client libraries](/influxdb3/core/write-data/client-libraries/). > > When bringing existing *v1* write workloads, use the InfluxDB 3 Core > HTTP API [`/write` endpoint](/influxdb3/core/api/write-data/#operation/PostV1Write). > > When bringing existing *v2* write workloads, use the InfluxDB 3 Core > HTTP API [`/api/v2/write` endpoint](/influxdb3/core/api/write-data/). > > **For Telegraf**, use the [`outputs.influxdb_v3`](/telegraf/v1/output-plugins/influxdb_v3/) output plugin. > For existing v1 or v2 write workloads, use the v1.x [`outputs.influxdb`](/telegraf/v1/output-plugins/influxdb/) or v2.x [`outputs.influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/) output plugins. > See how to [use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/). ### [Use the v3 write\_lp API to write data](/influxdb3/core/write-data/http-api/v3-write-lp/) Use the `/api/v3/write_lp` HTTP API endpoint to write data to InfluxDB 3 Core. ### [Use compatibility APIs and client libraries to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) Use HTTP API endpoints compatible with InfluxDB v2 and v1 clients to write points as line protocol data to InfluxDB 3 Core. #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) * [/api/v3/write\_lp endpoint](/influxdb3/core/api/write-data/#operation/PostWriteLP) --- # Use compatibility APIs and client libraries to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/http-api/compatibility-apis/ Use compatibility APIs when you need to migrate existing InfluxDB v1 or v2 write workloads to InfluxDB 3.x. The `/api/v2/write` (v2-compatible) and `/write` (v1-compatible) HTTP API endpoints work with InfluxDB [client libraries](/influxdb3/core/reference/client-libraries/), [Telegraf](/telegraf/v1/), and third-party integrations to write points as line protocol data to InfluxDB 3 Core. > [!Tip] > #### Choose the write endpoint for your workload > > When creating new write workloads, use the[InfluxDB HTTP API `/api/v3/write_lp` endpoint](/influxdb3/core/write-data/http-api/v3-write-lp/)and [client libraries](/influxdb3/core/write-data/client-libraries/). > > When bringing existing v1 write workloads, use the[v1-compatible `/write` endpoint](#influxdb-v1-compatibility). > > When bringing existing v2 write workloads, use the[v2-compatible `/api/v2/write` endpoint](#influxdb-v2-compatibility). > > **For Telegraf**, use the InfluxDB v1.x [`outputs.influxdb`](/telegraf/v1/output-plugins/influxdb/) or v2.x [`outputs.influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/) output plugins. > For new write workloads, use the [`outputs.influxdb_v3`](/telegraf/v1/output-plugins/influxdb_v3/) output plugin, which writes to the native [`/api/v3/write_lp` endpoint](/influxdb3/core/write-data/http-api/v3-write-lp/). > > > See how to [use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/). > > > [!Note] > #### Compatibility APIs differ from native APIs > > Keep in mind that the compatibility APIs differ from the v1 and v2 APIs in previous versions in the following ways: > > * Tags in a table (measurement) are *immutable* > * A tag and a field can’t have the same name within a table. ## InfluxDB v2 compatibility The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM). ``` POST /api/v2/write?bucket=mydb&precision=ns ``` ### Authenticate v2 API requests InfluxDB 3 Core requires each API request to be authenticated with a [token](/influxdb3/core/admin/tokens/) . Use the `Authorization: Bearer` or `Authorization: Token` scheme to authenticate v2 API write requests: #### Syntax ```http Authorization: Bearer DATABASE_TOKEN ``` ```http Authorization: Token DATABASE_TOKEN ``` #### Examples Use `Bearer` to authenticate a v2 write request: ```sh curl -i "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Use `Token` to authenticate a v2 write request: ```sh curl -i "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ --header "Authorization: Token DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` ### v2 API write parameters For InfluxDB 3 Core v2 API `/api/v2/write` requests, set parameters as listed in the following table: | Parameter | Allowed in |Ignored| Value | |------------------|------------|-------|-----------------------------------------------------| | `bucket` \* |Query string|Honored| Database name | | `precision` |Query string|Honored| [Timestamp precision](#timestamp-precision-v2) | |`Content-Encoding`| Header |Honored|`gzip` (compressed data) or `identity` (uncompressed)| | `Authorization` | Header |Honored| `Bearer DATABASE_TOKEN` or `Token DATABASE_TOKEN` | \* = Required #### Timestamp precision > [!Note] > By default, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision. > To avoid any ambiguity, you can specify the precision of timestamps in your data. Use one of the following `precision` values in v2 API `/api/v2/write` requests: * `ns`: nanoseconds * `us`: microseconds * `ms`: milliseconds * `s`: seconds * `m`: minutes * `h`: hours ## InfluxDB v1 compatibility The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB v1.x. ``` POST /write?db=mydb&precision=ns ``` ### Authenticate v1 API requests InfluxDB 3 Core requires each API request to be authenticated with a [token](/influxdb3/core/admin/tokens/) . With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. * [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) * [Authenticate with a token scheme](#authenticate-with-a-token-scheme) #### Authenticate with a username and password scheme With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate database writes by passing a [token](/influxdb3/core/admin/tokens/) as the `password` credential. When authenticating requests to the v1 API `/write` endpoint, InfluxDB 3 Core checks that the `password` (`p`) value is an authorized [token](/influxdb3/core/admin/tokens/) . InfluxDB 3 Core ignores the `username` (`u`) parameter in the request. Use one of the following authentication schemes with clients that support Basic authentication or query parameters: * [Basic authentication](#basic-authentication-v1) * [Query string authentication](#query-string-authentication-v1) ##### Basic authentication Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` requests. When authenticating requests, InfluxDB 3 Core checks that the `password` part of the decoded credential is an authorized [token](/influxdb3/core/admin/tokens/) . InfluxDB 3 Core ignores the `username` part of the decoded credential. ###### Syntax ```http Authorization: Basic ``` Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. ###### Example The following example shows how to use cURL with the `Basic` authentication scheme: ```sh curl -i "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ --user "any:DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` ##### Query string authentication In the URL, pass the `p` query parameter to authenticate `/write` requests. When authenticating requests, InfluxDB 3 Core checks that the `p` (*password*) value is an authorized [token](/influxdb3/core/admin/tokens/) and ignores the `u` (*username*) parameter. ###### Syntax ```sh http://localhost:8181/write/?u=any&p=DATABASE_TOKEN ``` ###### Example The following example shows how to use cURL with query string authentication: ```sh curl -i "http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` #### Authenticate with a token scheme Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a [token](/influxdb3/core/admin/tokens/) for authenticating v1 API `/write` requests. `Bearer` and `Token` are equivalent in InfluxDB 3 Core. The `Token` scheme is used in the InfluxDB 2.x API.`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). Support for one or the other may vary across InfluxDB API clients. ##### Syntax ```http Authorization: Bearer DATABASE_TOKEN ``` ```http Authorization: Token DATABASE_TOKEN ``` ##### Examples Use `Bearer` to authenticate a v1 write request: ```sh curl -i "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Use `Token` to authenticate a v1 write request: ```sh curl -i "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ --header "Authorization: Token DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` ### v1 API write parameters For InfluxDB 3 Core v1 API `/write` requests, set parameters as listed in the following table: | Parameter | Allowed in | Ignored | Value | |-------------|------------|------------------------|------------------------------------------------------------------------------------------------------------| |`consistency`|Query string| Ignored | N/A | | `db` \* |Query string| Honored | Database name | | `precision` |Query string| Honored | [Timestamp precision](#timestamp-precision-v1) | | `rp` |Query string|Honored, but discouraged| Retention policy | | `u` |Query string| Ignored | For [query string authentication](#query-string-authentication-v1), any arbitrary string | | `p` |Query string| Honored |For [query string authentication](#query-string-authentication-v1), a [token](/influxdb3/core/admin/tokens/)| `Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)`Authorization` | Header | Honored | `Bearer DATABASE_TOKEN`, `Token DATABASE_TOKEN`, or `Basic ` \* = Required #### Timestamp precision > [!Note] > By default, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision. > To avoid any ambiguity, you can specify the precision of timestamps in your data. Use one of the following `precision` values in v1 API `/write` requests: * `ns`: nanoseconds * `us`: microseconds * `ms`: milliseconds * `s`: seconds * `m`: minutes * `h`: hours ## Client library examples Use language-specific client libraries with your custom code to write data to InfluxDB 3 Core. ### v1 client libraries v1 client libraries send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. #### Node.js #### Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascript) JavaScript client library: ```js const Influx = require('influx') // Instantiate a client for writing to InfluxDB 3 Core v1 API const client = new Influx.InfluxDB({ host: 'localhost:8181', port: 443, protocol: 'https', database: 'DATABASE_NAME', username: 'ignored', password: 'DATABASE_TOKEN' }) ``` Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library: ```python from influxdb import InfluxDBClient # Instantiate a client for writing to InfluxDB 3 Core v1 API client = InfluxDBClient( host='localhost:8181', ssl=True, database='DATABASE_NAME', username='', password='DATABASE_TOKEN', headers={'Content-Type': 'text/plain; charset=utf-8'} ) ``` ### v2 client libraries v2 client libraries send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) syntax to the v2 API `/api/v2/write` endpoint. For more information about using v2 client libraries, see [v2 client libraries](/influxdb3/core/reference/client-libraries/v2/). ## Telegraf configuration If you have existing v1 workloads that use Telegraf, you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](/telegraf/v1/output-plugins/influxdb/) to write data. The following table shows `outputs.influxdb` plugin parameters and values for writing to the InfluxDB 3 Core v1 API: | Parameter | Ignored | Value | |------------------|------------------------|--------------------------------------------------------| | `database` | Honored | Database name | |`retention_policy`|Honored, but discouraged|[Duration](/influxdb3/core/reference/glossary/#duration)| | `username` | Ignored | String or empty | | `password` | Honored | [token](/influxdb3/core/admin/tokens/) | `content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb3/core/admin/databases/create/)) To configure the v1.x output plugin for writing to InfluxDB 3 Core, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: ```toml [[outputs.influxdb]] urls = ["http://localhost:8181"] database = "DATABASE_NAME" skip_database_creation = true retention_policy = "" username = "ignored" password = "DATABASE_TOKEN" content_encoding = "gzip" ``` Replace the following configuration values: * `DATABASE_NAME`: the name of the [database](/influxdb3/core/admin/databases/) to write to * `DATABASE_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) * [InfluxDB v2 API client libraries](/influxdb3/core/reference/client-libraries/v2/) * [/api/v2/write (v2-compatible) endpoint](/influxdb3/core/api/write-data/#operation/PostV2Write) * [/write (v1-compatible) endpoint](/influxdb3/core/api/write-data/#operation/PostV1Write) | Parameter | Allowed in | Ignored | Value | | --- | --- | --- | --- | | Parameter | Allowed in | Ignored | Value | | bucket * | Query string | Honored | Database name | | precision | Query string | Honored | Timestamp precision | | Content-Encoding | Header | Honored | gzip (compressed data) or identity (uncompressed) | | Authorization | Header | Honored | Bearer DATABASE_TOKEN or Token DATABASE_TOKEN | | Parameter | Allowed in | Ignored | Value | | --- | --- | --- | --- | | Parameter | Allowed in | Ignored | Value | | consistency | Query string | Ignored | N/A | | db * | Query string | Honored | Database name | | precision | Query string | Honored | Timestamp precision | | rp | Query string | Honored, but discouraged | Retention policy | | u | Query string | Ignored | For query string authentication , any arbitrary string | | p | Query string | Honored | For query string authentication , a token | | Parameter | Ignored | Value | | --- | --- | --- | | Parameter | Ignored | Value | | database | Honored | Database name | | retention_policy | Honored, but discouraged | Duration | | username | Ignored | String or empty | | password | Honored | token | --- # Use the v3 write_lp API to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/ Use the `/api/v3/write_lp` endpoint to write data to InfluxDB 3 Core. This endpoint accepts the same [line protocol](/influxdb3/core/reference/line-protocol/)syntax as previous versions of InfluxDB, and supports the following: ## Query parameters * `?accept_partial=`: Accept or reject partial writes (default is `true`). * `?no_sync=`: Control when writes are acknowledged: * `no_sync=true`: Acknowledges writes before WAL persistence completes. * `no_sync=false`: Acknowledges writes after WAL persistence completes (default). * `?precision=`: Specify the precision of the timestamp. By default, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision (`auto`). To avoid any ambiguity, you can specify the precision of timestamps in your data. The InfluxDB 3 Core `/api/v3/write_lp` API endpoint supports the following timestamp precisions: * `auto` (automatic detection, default) * `nanosecond` (nanoseconds) * `microsecond` (microseconds) * `millisecond` (milliseconds) * `second` (seconds) ### Auto precision detection When you use `precision=auto` (or omit the parameter), InfluxDB 3 Core automatically detects the timestamp precision based on the magnitude of the timestamp value: * Timestamps \< 5e9 → Second precision (multiplied by 1,000,000,000 to convert to nanoseconds) * Timestamps \< 5e12 → Millisecond precision (multiplied by 1,000,000) * Timestamps \< 5e15 → Microsecond precision (multiplied by 1,000) * Larger timestamps → Nanosecond precision (no conversion needed) ### Precision examples The following examples show how to write data with different timestamp precisions: #### Auto (default) #### ```bash # Auto precision (default) - timestamp magnitude determines precision curl "http://localhost:8181/api/v3/write_lp?db=sensors" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-raw "cpu,host=server1 usage=50.0 1708976567" ``` The timestamp `1708976567` is automatically detected as seconds. ```bash # Explicit nanosecond precision curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=nanosecond" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-raw "cpu,host=server1 usage=50.0 1708976567000000000" ``` ```bash # Millisecond precision curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=millisecond" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-raw "cpu,host=server1 usage=50.0 1708976567000" ``` ```bash # Second precision curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=second" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-raw "cpu,host=server1 usage=50.0 1708976567" ``` ## Configure gzip compression The `/api/v3/write_lp` endpoint supports gzip-encoded request bodies for efficient data transfer. When sending gzip-compressed data to InfluxDB, include the `Content-Encoding: gzip` header in your InfluxDB API request. ### Multi-member gzip support InfluxDB 3 Core supports multi-member gzip payloads (concatenated gzip files per [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952)). This allows you to: * Concatenate multiple gzip files and send them in a single request * Maintain compatibility with InfluxDB v1 and v2 write endpoints * Simplify batch operations using standard compression tools #### Example: Write concatenated gzip files ```bash # Create multiple gzip files echo "cpu,host=server1 usage=50.0 1708976567" | gzip > batch1.gz echo "cpu,host=server2 usage=60.0 1708976568" | gzip > batch2.gz # Concatenate and send in a single request cat batch1.gz batch2.gz | curl "http://localhost:8181/api/v3/write_lp?db=sensors" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-Encoding: gzip" \ --data-binary @- ``` ## Request body * Line protocol ``` POST /api/v3/write_lp?db=mydb&precision=nanosecond&accept_partial=true&no_sync=false ``` *The following example uses [cURL](https://curl.se/) to send a write request using the [Home sensor sample data](/influxdb3/core/reference/sample-data/#home-sensor-data), but you can use any HTTP client.* ```bash curl -v "http://localhost:8181/api/v3/write_lp?db=sensors&precision=second" \ --data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1735549200 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1735549200 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1735552800 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1735552800 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1735556400 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1735556400 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1735560000 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1735560000 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1735563600 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1735563600 home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1735567200 home,room=Kitchen temp=22.8,hum=36.3,co=1i 1735567200 home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1735570800 home,room=Kitchen temp=22.7,hum=36.2,co=3i 1735570800 home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1735574400 home,room=Kitchen temp=22.4,hum=36.0,co=7i 1735574400 home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1735578000 home,room=Kitchen temp=22.7,hum=36.0,co=9i 1735578000 home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1735581600 home,room=Kitchen temp=23.3,hum=36.9,co=18i 1735581600 home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1735585200 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1735585200 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1735588800 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1735588800" ``` * [Partial writes](#partial-writes) * [Accept partial writes](#accept-partial-writes) * [Do not accept partial writes](#do-not-accept-partial-writes) * [Write responses](#write-responses) * [Use no\_sync for immediate write responses](#use-no_sync-for-immediate-write-responses) > [!Note] > #### InfluxDB client libraries > > InfluxData provides supported InfluxDB 3 client libraries that you can > integrate with your code to construct data as time series points, and then > write them as line protocol to an InfluxDB 3 Core database. > For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/core/write-data/client-libraries/). ## Partial writes The `/api/v3/write_lp` endpoint lets you accept or reject partial writes using the `accept_partial` parameter. This parameter changes the behavior of the API when the write request contains invalid line protocol or schema conflicts. For example, the following line protocol contains two points, each using a different datatype for the `temp` field, which causes a schema conflict: ``` home,room=Sunroom temp=96 1735545600 home,room=Sunroom temp="hi" 1735549200 ``` ### Accept partial writes With `accept_partial=true` (default), InfluxDB: * Accepts and writes line `1` * Rejects line `2` * Returns a `400 Bad Request` status code and the following response body: ``` < HTTP/1.1 400 Bad Request ... { "error": "partial write of line protocol occurred", "data": [ { "original_line": "home,room=Sunroom temp=hi 1735549200", "line_number": 2, "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" } ] } ``` ### Do not accept partial writes With `accept_partial=false`, InfluxDB: * Rejects *all* points in the batch * Returns a `400 Bad Request` status code and the following response body: ``` < HTTP/1.1 400 Bad Request ... { "error": "parsing failed for write_lp endpoint", "data": { "original_line": "home,room=Sunroom temp=hi 1735549200", "line_number": 2, "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" } } ``` *For more information about the ingest path and data flow, see[Data durability](/influxdb3/core/reference/internals/durability/).* ## Write responses By default, InfluxDB 3 Core 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. > [!Tip] > 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. * With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence. The following example immediately returns a response without waiting for WAL persistence: ```bash curl "http://localhost:8181/api/v3/write_lp?db=sensors&no_sync=true" \ --data-raw "home,room=Sunroom temp=96" ``` ## Response headers All HTTP responses from InfluxDB 3 Core include the following standard headers: ### cluster-uuid The `cluster-uuid` response header contains the catalog UUID of your InfluxDB 3 Core instance. This header is included in all HTTP API responses, including: * Write requests (`/api/v3/write_lp`, `/api/v2/write`, `/write`) * Query requests * Administrative operations * Authentication failures * CORS preflight requests #### Use cases The `cluster-uuid` header enables you to: * **Identify cluster instances**: Programmatically determine which InfluxDB instance handled a request * **Monitor deployments**: Track requests across multiple InfluxDB instances in load-balanced or multi-cluster environments * **Debug and troubleshooting**: Correlate client requests with specific server instances in distributed systems #### Example response ```bash curl -v "http://localhost:8181/api/v3/write_lp?db=sensors" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --data-raw "cpu,host=server1 usage=50.0" ``` The response headers contain the `cluster-uuid`: ``` < HTTP/1.1 204 No Content < cluster-uuid: 01234567-89ab-cdef-0123-456789abcdef < date: Tue, 19 Nov 2025 20:00:00 GMT ``` #### Related * [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) * [/api/v3/write\_lp endpoint](/influxdb3/core/api/write-data/#operation/PostWriteLP) --- # Use the influxdb3 CLI to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/influxdb3-cli/ Use the [`influxdb3` CLI](/influxdb3/core/reference/cli/influxdb3/)to write line protocol data to InfluxDB 3 Core. * [Construct line protocol](#construct-line-protocol) * [Write the line protocol to InfluxDB](#write-the-line-protocol-to-influxdb) > [!Note] > #### Use the API for batching and higher-volume writes > > The `influxdb3` CLI lets you quickly get started writing data to InfluxDB 3 Core. > For batching and higher-volume write workloads, use the[InfluxDB HTTP API](/influxdb3/core/write-data/http-api),[API client libraries](/influxdb3/core/write-data/client-libraries/)or [Telegraf](/influxdb3/core/write-data/use-telegraf/). ## Construct line protocol With a [basic understanding of line protocol](/influxdb3/core/write-data/#line-protocol), you can construct data in line protocol format and write it to InfluxDB 3 Core. Consider a use case where you collect data from sensors in your home. Each sensor collects temperature, humidity, and carbon monoxide readings. To collect this data, use the following schema: * **table**: `home` * **tags** * `room`: Living Room or Kitchen * **fields** * `temp`: temperature in °C (float) * `hum`: percent humidity (float) * `co`: carbon monoxide in parts per million (integer) * **timestamp**: Unix timestamp in *second* precision The following line protocol represents the schema described above: ```text home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 ``` For this tutorial, you can either pass this line protocol directly to the`influxdb3 write` command as a string, via `stdin`, or you can save it to and read it from a file. ## Write the line protocol to InfluxDB Use the [`influxdb3 write` command](/influxdb3/core/reference/cli/influxdb3/write/)to write the home sensor sample data to InfluxDB 3 Core. Provide the following: * The [database](/influxdb3/core/admin/databases/) name using the`--database` option * Your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/)using the `-t`, `--token` option * [Line protocol](#construct-line-protocol). Provide the line protocol in one of the following ways: * a string * a path to a file that contains the line protocol using the `--file` option * from stdin > [!Note] > By default, InfluxDB 3 Core uses the timestamp magnitude to auto-detect the precision. > To specify the precision of timestamps in your data, use the [`--precision {ns|us|ms|s}` option](/influxdb3/core/reference/cli/influxdb3/write/#options). #### string #### ```sh influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' ``` 1. In your terminal, enter the following command to create the sample data file: ``` echo 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' > ./home.lp ``` 2. Enter the following CLI command to write the data from the sample file: ``` influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --file ./home.lp ``` 1. In your terminal, enter the following command to create the sample data file: ``` echo 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' > ./home.lp ``` 2. Enter the following CLI command to write the data from the sample file: ``` cat ./home.lp | influxdb3 write \ --database DATABASE_NAME \ --token AUTH_TOKEN ``` Replace the following: * `DATABASE_NAME`: the name of the database to write to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) #### Related * [influxdb3 write](/influxdb3/core/reference/cli/influxdb3/write/) * [Write data to InfluxDB 3 Core](/influxdb3/core/get-started/write/) --- # Troubleshoot issues writing data Source: https://docs.influxdata.com/influxdb3/core/write-data/troubleshoot/ Learn how to avoid unexpected results and recover from errors when writing to InfluxDB 3 Core. * [Handle write responses](#handle-write-responses) * [Review HTTP status codes](#review-http-status-codes) * [Troubleshoot failures](#troubleshoot-failures) * [Troubleshoot rejected points](#troubleshoot-rejected-points) * [Troubleshoot write performance issues](#troubleshoot-write-performance-issues) * [Use debug logs for troubleshooting](#use-debug-logs-for-troubleshooting) ## Handle write responses InfluxDB 3 Core does the following when you send a write request: 1. Validates the request. 2. If successful, attempts to ingest data from the request body; otherwise, responds with an [error status](#review-http-status-codes). 3. Ingests or rejects data in the batch and returns one of the following HTTP status codes: * `204 No Content`: All data in the batch is ingested. * `400 Bad Request`: Some or all of the data has been rejected. Data that has not been rejected is ingested and queryable. The response body contains error details about[rejected points](#troubleshoot-rejected-points), up to 100 points. Writes are synchronous–the response status indicates the final status of the write and all ingested data is queryable. To ensure that InfluxDB handles writes in the order you request them, wait for the response before you send the next request. ### Review HTTP status codes InfluxDB 3 Core uses conventional HTTP status codes to indicate the success or failure of a request. The `message` property of the response body may contain additional details about the error. Write requests return the following status codes: | HTTP response code | Message | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `204 "Success"` | | If InfluxDB ingested the data | | `400 "Bad request"` |error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections| If some or all request data isn’t allowed (for example, if it is malformed or falls outside of the bucket’s retention period)–the response body indicates whether a partial write has occurred or if all data has been rejected | | `401 "Unauthorized"` | |If the `Authorization` header is missing or malformed or if the [token](/influxdb3/core/admin/tokens/) doesn’t have permission to write to the database. See [write API examples](/influxdb3/enterprise/write-data/http-api/) using credentials.| | `404 "Not found"` | requested **resource type** (for example, “organization” or “database”), and **resource name** | If a requested resource (for example, organization or database) wasn’t found | |`500 "Internal server error"`| | Default status for an error | | `503` “Service unavailable” | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. | If your data did not write to the database, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). ## Troubleshoot failures If you notice data is missing in your database, do the following: * Check the `message` property in the response body for details about the error. * If the `message` describes a field error, [troubleshoot rejected points](#troubleshoot-rejected-points). * Verify all lines contain valid syntax ([line protocol](/influxdb3/core/reference/syntax/line-protocol/)). * Verify the timestamps in your data match the [precision parameter](/influxdb3/core/reference/glossary/#precision) in your request. * Minimize payload size and network errors by [optimizing writes](/influxdb3/core/write-data/best-practices/optimize-writes/). ## Troubleshoot rejected points InfluxDB rejects points that don’t match the schema of existing data. Check for [field data type](/influxdb3/core/reference/syntax/line-protocol/#data-types-and-format)differences between the rejected data point and points within the same database–for example, did you attempt to write `string` data to an `int` field? ## Troubleshoot write performance issues If you experience slow write performance or timeouts during high-volume ingestion, consider the following: ### Memory configuration InfluxDB 3 Core uses memory for both query processing and internal data operations, including converting data to Parquet format during persistence. For write-heavy workloads, insufficient memory allocation can cause performance issues. **Symptoms of memory-related write issues:** * Slow write performance during data persistence (typically every 10 minutes) * Increased response times during high-volume ingestion * Memory-related errors in server logs **Solutions:** * Increase the [`exec-mem-pool-size`](/influxdb3/core/reference/config-options/#exec-mem-pool-size)configuration to allocate more memory for data operations. For write-heavy workloads, consider setting this to 30-40% of available memory. * Monitor memory usage during peak write periods to identify bottlenecks. * Adjust the [`gen1-duration`](/influxdb3/core/reference/config-options/#gen1-duration)to control how frequently data is persisted to Parquet format. ### Example configuration for write-heavy workloads ```bash influxdb3 serve \ --exec-mem-pool-size PERCENTAGE \ --gen1-duration 15m \ # ... other options ``` Replace `PERCENTAGE` with the percentage of available memory to allocate (for example, `35%` for write-heavy workloads). ### Use debug logs for troubleshooting For deeper investigation of write issues, enable debug logging for specific components. Debug logs provide detailed information about write buffer operations and WAL activity. To enable debug logs for write operations, restart InfluxDB 3 Core with targeted log filters: ```sh influxdb3 serve --log-filter info,influxdb3_write_buffer=debug ``` ```sh influxdb3 serve --log-filter info,influxdb3_wal=debug ``` For more information about log levels and targeted filtering, see[log-filter configuration](/influxdb3/core/reference/config-options/#log-filter). #### Related * [Best practices for writing data](/influxdb3/core/write-data/best-practices/) * [InfluxDB 3 Core internals](/influxdb3/core/reference/internals/durability/) [write](/influxdb3/core/tags/write/)[line protocol](/influxdb3/core/tags/line-protocol/)[errors](/influxdb3/core/tags/errors/) | HTTP response code | Message | Description | | --- | --- | --- | | HTTP response code | Message | Description | | 204 "Success" | | If InfluxDB ingested the data | | 400 "Bad request" | error details about rejected points, up to 100 points: line contains the first rejected line, message describes rejections | If some or all request data isn’t allowed (for example, if it is malformed or falls outside of the bucket’s retention period)–the response body indicates whether a partial write has occurred or if all data has been rejected | | 401 "Unauthorized" | | If the Authorization header is missing or malformed or if the token doesn’t have permission to write to the database. See write API examples using credentials. | | 404 "Not found" | requested resource type (for example, “organization” or “database”), and resource name | If a requested resource (for example, organization or database) wasn’t found | | 500 "Internal server error" | | Default status for an error | | 503 “Service unavailable” | | If the server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. | --- # Use Telegraf to write data Source: https://docs.influxdata.com/influxdb3/core/write-data/use-telegraf/ [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) is a data collection agent for collecting and reporting metrics. Its vast library of input plugins and “plug-and-play” architecture lets you quickly and easily collect metrics from many different sources. For a list of available plugins, see [Telegraf plugins](/telegraf/v1/plugins/). #### Requirements * **Telegraf 1.38 or greater** to use the `influxdb_v3` output plugin. Earlier versions of Telegraf (1.9.2 or greater) can use the[`influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/) or[`influxdb`](/telegraf/v1/output-plugins/influxdb/) (v1) output plugins to write to InfluxDB 3 Core[compatibility APIs](/influxdb3/core/write-data/http-api/compatibility-apis/).*For information about installing Telegraf, see the[Telegraf Installation instructions](/telegraf/v1/install/).* ## Basic Telegraf usage Telegraf is a plugin-based agent with plugins that are enabled and configured in your Telegraf configuration file (`telegraf.conf`). Each Telegraf configuration must **have at least one input plugin and one output plugin**. Telegraf input plugins retrieve metrics from different sources. Telegraf output plugins write those metrics to a destination. Use the [`outputs.influxdb_v3`](/telegraf/v1/plugins/#output-influxdb_v3) plugin to connect to the InfluxDB 3 Core native write API and write metrics collected by Telegraf to InfluxDB 3 Core. ```toml # ... [[outputs.influxdb_v3]] urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" # ... ``` Replace the following: * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/).*Store this in a secret store or environment variable to avoid exposing the raw token string.* * `DATABASE_NAME`: the name of the database to write data to *See how to [Configure Telegraf to write to InfluxDB 3 Core](/influxdb3/core/write-data/use-telegraf/configure/).* ## Use Telegraf with InfluxDB ### [Configure Telegraf to write to InfluxDB 3 Core](/influxdb3/core/write-data/use-telegraf/configure/) Update existing or create new Telegraf configurations to use the `influxdb_v3` output plugin to write to InfluxDB 3 Core. Start Telegraf using the custom configuration. ### [Use Telegraf to dual write to InfluxDB](/influxdb3/core/write-data/use-telegraf/dual-write/) Configure Telegraf to write data to multiple InfluxDB instances or clusters simultaneously. ### [Use Telegraf to write CSV data](/influxdb3/core/write-data/use-telegraf/csv/) Use the Telegraf `file` input plugin to read and parse CSV data into [line protocol](/influxdb3/core/reference/syntax/line-protocol/) and write it to InfluxDB 3 Core. ![InfluxDB University](/svgs/influxdbu-full-white.svg) #### Data Collection with Telegraf Learn how to use Telegraf to make data time series data collection easy in this **free** InfluxDB University course. [Take the course](https://university.influxdata.com/courses/data-collection-with-telegraf-tutorial/) --- # Configure Telegraf to write to InfluxDB 3 Core Source: https://docs.influxdata.com/influxdb3/core/write-data/use-telegraf/configure/ Use the Telegraf [`influxdb_v3` output plugin](/telegraf/v1/output-plugins/influxdb_v3/)to collect and write metrics to InfluxDB 3 Core. This plugin uses the InfluxDB 3 Core native HTTP API[`/api/v3/write_lp` endpoint](/influxdb3/core/write-data/http-api/v3-write-lp/)and requires **Telegraf 1.38 or greater**. Learn how to enable and configure the `influxdb_v3` output plugin to write data to InfluxDB 3 Core. If you use an earlier version of Telegraf or bring an existing Telegraf configuration from InfluxDB v1 or v2, you can use the[`influxdb_v2`](#use-the-influxdb-v2-output-plugin) or[`influxdb`](#use-the-influxdb-v1-output-plugin) (v1) output plugins to write to InfluxDB 3 Core[compatibility APIs](/influxdb3/core/write-data/http-api/compatibility-apis/). > [!Note] > *View the [requirements](/influxdb3/core/write-data/use-telegraf#requirements)for using Telegraf with InfluxDB 3 Core.* * [Configure Telegraf input and output plugins](#configure-telegraf-input-and-output-plugins) * [Add Telegraf plugins](#add-telegraf-plugins) * [Enable and configure the InfluxDB v3 output plugin](#enable-and-configure-the-influxdb-v3-output-plugin) * [urls](#urls) * [token](#token) * [database](#database) * [Additional plugin options](#additional-plugin-options) * [Use the InfluxDB v2 output plugin](#use-the-influxdb-v2-output-plugin) * [Use the InfluxDB v1 output plugin](#use-the-influxdb-v1-output-plugin) * [Other Telegraf configuration options](#other-telegraf-configuration-options) * [Start Telegraf](#start-telegraf) ## Configure Telegraf input and output plugins Configure Telegraf input and output plugins in the Telegraf configuration file (typically named `telegraf.conf`). Input plugins collect metrics. Output plugins define destinations where metrics are sent. This guide assumes you have already [installed InfluxDB 3 Core](/influxdb3/core/install/)and have been through the [getting started guide](/influxdb3/core/get-started/). ### Add Telegraf plugins To add any of the available [Telegraf plugins](/telegraf/v1/plugins/), follow the steps below. 1. Find the plugin you want to enable from the complete list of available[Telegraf plugins](/telegraf/v1/plugins/). 2. Click **View** to the right of the plugin name to open the plugin page on GitHub. For example, view the [MQTT plugin GitHub page](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/mqtt_consumer/README.md). 3. Copy and paste the example configuration into your Telegraf configuration file (typically named `telegraf.conf`). ### Enable and configure the InfluxDB v3 output plugin To send data to InfluxDB 3 Core, enable the[`influxdb_v3` output plugin](/telegraf/v1/output-plugins/influxdb_v3/)in the `telegraf.conf`. ```toml [[outputs.influxdb_v3]] urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/).*Store this in a secret store or environment variable to avoid exposing the raw token string.* The InfluxDB v3 output plugin configuration contains the following options: #### urls An array of URL strings. To write to InfluxDB 3 Core, include your InfluxDB 3 Core URL: ```toml ["http://localhost:8181"] ``` If you specify multiple URLs, Telegraf randomly selects one of them for each write interval and fails over to another if the write doesn’t succeed. #### token Your InfluxDB 3 Core authorization token. > [!Tip] > ##### Store your authorization token as an environment variable > > To prevent a plain text token in your Telegraf configuration file, we > recommend that you store the token as an environment variable and then > reference the environment variable in your configuration file using string > interpolation. For example: > > ``` > [[outputs.influxdb_v3]] > urls = ["http://localhost:8181"] > token = "${INFLUX_TOKEN}" > # ... > ``` #### database The name of the InfluxDB 3 Core database to write data to. #### Additional plugin options The plugin provides additional options for controlling write behavior, including: * **`database_tag`**: the metric tag to use to determine the destination database, overriding `database`. * **`sync`**: set to `false` to acknowledge writes before WAL persistence completes, which reduces write latency but increases the risk of data loss. Default is `true`.*See [Use no\_sync for immediate write responses](/influxdb3/core/write-data/http-api/v3-write-lp/#use-no_sync-for-immediate-write-responses).* * **`content_encoding`**: the plugin compresses write request bodies with gzip by default. For all plugin options, see the[`influxdb_v3` output plugin](/telegraf/v1/output-plugins/influxdb_v3/) reference. ### Use the InfluxDB v2 output plugin If you bring an existing InfluxDB v2 write workload or use a Telegraf version earlier than 1.38, use the[`influxdb_v2` output plugin](/telegraf/v1/output-plugins/influxdb_v2/)to write to InfluxDB 3 Core through the InfluxDB[v2 compatibility API](/influxdb3/core/write-data/http-api/compatibility-apis/#influxdb-v2-compatibility). ```toml [[outputs.influxdb_v2]] urls = ["http://localhost:8181"] token = "AUTH_TOKEN" organization = "" bucket = "DATABASE_NAME" ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) For InfluxDB 3 Core, set the following v2-specific options: * **`organization`**: set to an empty string (`""`). * **`bucket`**: the name of the database to write data to. > [!Note] > An InfluxDB v2 ***bucket*** is synonymous with an InfluxDB 3 Core ***database***. ### Use the InfluxDB v1 output plugin If you bring an existing InfluxDB v1 write workload, use the[`influxdb` output plugin](/telegraf/v1/output-plugins/influxdb/)to write to InfluxDB 3 Core through the InfluxDB[v1 compatibility API](/influxdb3/core/write-data/http-api/compatibility-apis/#influxdb-v1-compatibility). ```toml [[outputs.influxdb]] urls = ["http://localhost:8181"] database = "DATABASE_NAME" skip_database_creation = true username = "ignored" password = "AUTH_TOKEN" ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/) For InfluxDB 3 Core, set the following v1-specific options: * **`skip_database_creation`**: set to `true`. InfluxDB 3 Core doesn’t support creating databases through the v1 API. * **`password`**: your authorization token. The v1 compatibility API authenticates with the token passed as the password credential and ignores `username`. ### Other Telegraf configuration options For more plugin configuration options, see the[`influxdb_v3`](/telegraf/v1/output-plugins/influxdb_v3/),[`influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/), and[`influxdb` (v1)](/telegraf/v1/output-plugins/influxdb/) output plugin references. ## Start Telegraf Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`. ```sh telegraf --config /path/to/custom/telegraf.conf ``` #### Related * [Telegraf plugins](/telegraf/v1/plugins/) * [Telegraf InfluxDB v3 output plugin](/telegraf/v1/output-plugins/influxdb_v3/) [telegraf](/influxdb3/core/tags/telegraf/) --- # Use Telegraf to write CSV data Source: https://docs.influxdata.com/influxdb3/core/write-data/use-telegraf/csv/ Use the Telegraf `file` input plugin to read and parse CSV data into[line protocol](/influxdb3/core/reference/syntax/line-protocol/)and write it to InfluxDB 3 Core.[Telegraf](/telegraf/v1/) is a plugin-based agent that collects metrics from different sources and writes them to specified destinations. * [Configure Telegraf to read CSV files](#configure-telegraf-to-read-csv-files) * [Configure Telegraf to write to InfluxDB](#configure-telegraf-to-write-to-influxdb) * [Other Telegraf configuration options](#other-telegraf-configuration-options) ## Configure Telegraf to read CSV files 1. Add and enable the [`inputs.file` plugin](/telegraf/v1/plugins/#input-file)in your Telegraf configuration file. 2. Use the `files` option to specify the list of CSV files to read. CSV files must be accessible by the Telegraf agent. 3. Set the `data_format` option to `csv`. 4. Define all other `csv_` configuration options specific to the CSV data you want to write to InfluxDB 3 Core.*For detailed information about each of the CSV format configuration options, see [CSV input data format](/telegraf/v1/data_formats/input/csv/).* ```toml [[inputs.file]] files = ["/path/to/example.csv"] data_format = "csv" csv_header_row_count = 0 csv_column_names = [] csv_column_types = [] csv_skip_rows = 0 csv_metadata_rows = 0 csv_metadata_separators = [":", "="] csv_metadata_trim_set = "" csv_skip_columns = 0 csv_delimiter = "," csv_comment = "" csv_trim_space = false csv_tag_columns = [] csv_measurement_column = "" csv_timestamp_column = "" csv_timestamp_format = "" csv_timezone = "" csv_skip_values = [] csv_skip_errors = false csv_reset_mode = "none" ``` ## Configure Telegraf to write to InfluxDB To send data to InfluxDB 3 Core, enable and configure the[`influxdb_v3` output plugin](/influxdb3/core/write-data/use-telegraf/configure/#enable-and-configure-the-influxdb-v3-output-plugin)in your `telegraf.conf`. ```toml [[inputs.file]] files = ["/path/to/example.csv"] data_format = "csv" csv_header_row_count = 0 csv_column_names = [] csv_column_types = [] csv_skip_rows = 0 csv_metadata_rows = 0 csv_metadata_separators = [":", "="] csv_metadata_trim_set = "" csv_skip_columns = 0 csv_delimiter = "," csv_comment = "" csv_trim_space = false csv_tag_columns = [] csv_measurement_column = "" csv_timestamp_column = "" csv_timestamp_format = "" csv_timezone = "" csv_skip_values = [] csv_skip_errors = false csv_reset_mode = "none" [[outputs.influxdb_v3]] urls = ["http://localhost:8181"] token = "AUTH_TOKEN" database = "DATABASE_NAME" ``` Replace the following: * `DATABASE_NAME`: the name of the database to write data to * `AUTH_TOKEN`: your InfluxDB 3 Core [token](/influxdb3/core/admin/tokens/).*Store this in a secret store or environment variable to avoid exposing the raw token string.* ##### Store your authorization token as an environment variable ##### Avoid storing a plain text token in your Telegraf configuration file. Store the token as an environment variable and then reference the environment variable in your configuration file using string interpolation. For example: ``` [[outputs.influxdb_v3]] urls = ["http://localhost:8181"] token = "${INFLUX_TOKEN}" # ... ``` **Restart the Telegraf agent** to apply the configuration change and write the CSV data to InfluxDB 3 Core. #### Other Telegraf configuration options The preceding examples describe Telegraf configurations necessary for writing to InfluxDB 3 Core. The `influxdb_v3` output plugin provides several other configuration options. For more information, see the[`influxdb_v3` plugin options](/telegraf/v1/output-plugins/influxdb_v3/). #### Related * [CSV input data format](/telegraf/v1/data_formats/input/csv/) * [Use Telegraf to write data](/influxdb3/core/write-data/use-telegraf/) --- # Use Telegraf to dual write to InfluxDB Source: https://docs.influxdata.com/influxdb3/core/write-data/use-telegraf/dual-write/ Use Telegraf to write your data simultaneously to multiple InfluxDB instances or clusters. This method, known as “dual writing,” is useful for backing up data to a separate instance or for migrating from other versions of InfluxDB to InfluxDB 3 Core. The following example configures Telegraf for dual writing to InfluxDB 3 Core and an InfluxDB v2 OSS instance. Specifically, it uses the following: * The [InfluxDB v3 output plugin](/telegraf/v1/output-plugins/influxdb_v3/)pointing to InfluxDB 3 Core and the[InfluxDB v2 output plugin](/telegraf/v1/output-plugins/influxdb_v2/)pointing to an InfluxDB v2 OSS instance. * Two different tokens: one for InfluxDB v2 OSS and one for InfluxDB 3 Core. Configure both tokens as environment variables and use string interpolation in your Telegraf configuration file to reference each environment variable. ## Sample configuration ```toml # Include any other input, processor, or aggregator plugins that you want to # include in your configuration. # Send data to InfluxDB 3 Core [[outputs.influxdb_v3]] ## The InfluxDB 3 Core URL urls = ["http://localhost:8181"] ## InfluxDB 3 Core authorization token token = "${INFLUX_TOKEN}" ## Destination database to write into database = "DATABASE_NAME" # Send data to InfluxDB v2 OSS [[outputs.influxdb_v2]] ## The InfluxDB v2 OSS URL urls = ["http://localhost:8086"] ## OSS token for authentication token = "${INFLUX_TOKEN_OSS}" ## Organization is the name of the organization you want to write to. organization = "ORG_NAME_OSS" ## Destination bucket to write to bucket = "BUCKET_NAME_OSS" ``` Telegraf lets you dual write data to any version of InfluxDB using the[`influxdb` (v1)](/telegraf/v1/output-plugins/influxdb/),[`influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/), and[`influxdb_v3`](/telegraf/v1/output-plugins/influxdb_v3/) output plugins. A single Telegraf agent sends identical data sets to all target outputs. You cannot filter data based on the output. > [!Note] > InfluxDB v1 does *not* support the unsigned integer data type. > You can only write unsigned integer field values to InfluxDB v2- and 3-based > products.