# InfluxDB OSS v2 — full Markdown corpus > Generated 2026-10-31T04:19:00.007Z from https://docs.influxdata.com/influxdb/v2/ > 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/ --- # Get started with InfluxDB v2 Source: https://docs.influxdata.com/influxdb/v2/ --- # Administer InfluxDB Source: https://docs.influxdata.com/influxdb/v2/admin/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB API, user interface (UI), and CLIs to perform administrative tasks in InfluxDB. ### [Identify InfluxDB OSS v2 version](/influxdb/v2/admin/identify-version/) Learn how to identify your InfluxDB OSS v2 version using command-line tools, the UI, and HTTP endpoints. ### [Manage organizations](/influxdb/v2/admin/organizations/) Manage organizations in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage API tokens](/influxdb/v2/admin/tokens/) Manage API tokens in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage buckets](/influxdb/v2/admin/buckets/) Manage buckets in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage users](/influxdb/v2/admin/users/) Manage users in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage security and authorization](/influxdb/v2/admin/security/) Security, access control, and sensitive secret handling are incredibly important when handling any sort of sensitive data. This section provides information about managing the security of your InfluxDB instance. ### [Manage secrets](/influxdb/v2/admin/secrets/) Manage, use, and store secrets in InfluxDB. ### [Back up and restore data](/influxdb/v2/admin/backup-restore/) InfluxDB provides tools that let you back up and restore data and metadata stored in InfluxDB. ### [Manage InfluxDB internal systems](/influxdb/v2/admin/internals/) Manage the internal systems of InfluxDB such as the Time Series Index (TSI), the time-structured merge tree (TSM) storage engine, and the write-ahead log (WAL). ### [Manage InfluxDB logs](/influxdb/v2/admin/logs/) Learn how to configure, manage, and process your InfluxDB logs. --- # Back up and restore data Source: https://docs.influxdata.com/influxdb/v2/admin/backup-restore/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB provides tools to back up and restore data and metadata stored in InfluxDB. ### [Back up data](/influxdb/v2/admin/backup-restore/backup/) Use the `influx backup` command to back up data and metadata stored in InfluxDB. ### [Restore data](/influxdb/v2/admin/backup-restore/restore/) Use the `influx restore` command to restore backup data and metadata from InfluxDB. [backup](/influxdb/v2/tags/backup/)[restore](/influxdb/v2/tags/restore/) --- # Back up data Source: https://docs.influxdata.com/influxdb/v2/admin/backup-restore/backup/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > #### Token hashing affects backup contents in InfluxDB 2.9.0+ > > A backup taken from a 2.9.0+ instance with the default settings > doesn’t contain a plaintext operator token. To run a full restore of > that backup, supply the operator token via[`influx restore --operator-token`](/influxdb/v2/reference/cli/influx/restore/#restore-a-backup-that-contains-hashed-tokens)(`influx-cli` v2.8.0+). > > [Capture the operator token](/influxdb/v2/admin/tokens/#before-upgrading-to-290)you’ll use for restores **before** the first 2.9.0 startup. Use the [`influx backup` command](/influxdb/v2/reference/cli/influx/backup/) to back up data and metadata stored in InfluxDB. InfluxDB copies all data and metadata to a set of files stored in a specified directory on your local filesystem. > [!Note] > #### InfluxDB 1.x/2.x compatibility > > The InfluxDB 2.10 `influx backup` command is not compatible with versions of InfluxDB prior to 2.0.0.**For information about migrating data between InfluxDB 1.x and 2.10, see:** > > * [Automatically upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/automatic-upgrade/) > * [Manually upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/) > [!Important] > The `influx backup` command **cannot** back up data stored in **InfluxDB Cloud**. The `influx backup` command requires: * The directory path for where to store the backup file set * The **root authorization token** (the token created for the first user in the[InfluxDB setup process](/influxdb/v2/get-started/)). ##### Back up data with the influx CLI ```sh # Syntax influx backup -t # Example influx backup \ path/to/backup_$(date '+%Y-%m-%d_%H-%M') \ -t xXXXX0xXX0xxX0xx_x0XxXxXXXxxXX0XXX0XXxXxX0XxxxXX0Xx0xx== ``` #### Related * [Restore data](/influxdb/v2/admin/backup-restore/restore/) * [influx backup](/influxdb/v2/reference/cli/influx/backup/) --- # Restore data Source: https://docs.influxdata.com/influxdb/v2/admin/backup-restore/restore/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Restores **not supported in InfluxDB Cloud**. > [!Important] > #### Restoring a backup with hashed tokens > > If the backup was taken from an instance with [token > hashing](/influxdb/v2/admin/tokens/#token-hashing) enabled (the > default in **InfluxDB OSS 2.9.0+**), the backup does not contain a > plaintext operator token. To run a full restore of that backup, supply > the operator token to the CLI with the `--operator-token `flag (`influx-cli` v2.8.0+): > > ``` > influx restore --full --operator-token /path/to/backup > ``` Use the `influx restore` command to restore backup data and metadata from InfluxDB OSS. * [Restore data with the influx CLI](#restore-data-with-the-influx-cli) * [Recover from a failed restore](#recover-from-a-failed-restore) InfluxDB moves existing data and metadata to a temporary location. If the restore fails, InfluxDB preserves temporary data for recovery, otherwise this data is deleted.*See [Recover from a failed restore](#recover-from-a-failed-restore).* > [!Note] > #### Cannot restore to existing buckets > > The `influx restore` command cannot restore data to existing buckets. > Use the `--new-bucket` flag to create a new bucket to restore data to. > To restore data and retain bucket names, [delete existing buckets](/influxdb/v2/admin/buckets/delete-bucket/)and then begin the restore process. ## Restore data with the influx CLI Use the `influx restore` command and specify the path to the backup directory. *For more information about restore options and flags, see the[`influx restore` documentation](/influxdb/v2/reference/cli/influx/restore/).* * [Restore all time series data](#restore-all-time-series-data) * [Restore data from a specific bucket](#restore-data-from-a-specific-bucket) * [Restore and replace all InfluxDB data](#restore-and-replace-all-influxdb-data) ### Restore all time series data To restore all time series data from a backup directory, provide the following: * backup directory path ```sh influx restore /backups/2020-01-20_12-00/ ``` ### Restore data from a specific bucket To restore data from a specific backup bucket, provide the following: * backup directory path * bucket name or ID ```sh influx restore \ /backups/2020-01-20_12-00/ \ --bucket example-bucket # OR influx restore \ /backups/2020-01-20_12-00/ \ --bucket-id 000000000000 ``` If a bucket with the same name as the backed up bucket already exists in InfluxDB, use the `--new-bucket` flag to create a new bucket with a different name and restore data into it. ```sh influx restore \ /backups/2020-01-20_12-00/ \ --bucket example-bucket \ --new-bucket new-example-bucket ``` ### Restore and replace all InfluxDB data To restore and replace all time series data *and* InfluxDB key-value data such as tokens, users, dashboards, etc., include the following: * `--full` flag * backup directory path ```sh influx restore \ /backups/2020-01-20_12-00/ \ --full ``` > [!Note] > #### Restore to a new InfluxDB server > > If using a backup to populate a new InfluxDB server: > > 1. Retrieve the [admin token](/influxdb/v2/admin/tokens/#operator-token) from your source InfluxDB instance. > > 2. Set up your new InfluxDB instance, but use the `-t`, `--token` flag to use the**admin token** from your source instance as the admin token on your new instance. > > ``` > influx setup --token My5uP3rSecR37t0keN > ``` > > 3. Restore the backup to the new server. > > ``` > influx restore \ > /backups/2020-01-20_12-00/ \ > --full > ``` > > If you do not provide the admin token from your source InfluxDB instance as the > admin token in your new instance, the restore process and all subsequent attempts > to authenticate with the new server will fail. > > 1. The first restore API call uses the auto-generated token to authenticate with > the new server and overwrites the entire key-value store in the new server, including > the auto-generated token. > 2. The second restore API call attempts to upload time series data, but uses the > auto-generated token to authenticate with new server. > That token is overwritten in first restore API call and the process fails to authenticate. ## Recover from a failed restore If the restoration process fails, InfluxDB preserves existing data in a `tmp`directory in the [target engine path](/influxdb/v2/reference/cli/influx/restore/#flags)(default is `~/.influxdbv2/engine`). To recover from a failed restore: 1. Copy the temporary files back into the `engine` directory. 2. Remove the `.tmp` extensions from each of the copied files. 3. Restart the `influxd` server. #### Related * [Back up data](/influxdb/v2/admin/backup-restore/backup/) [restore](/influxdb/v2/tags/restore/) --- # Manage buckets Source: https://docs.influxdata.com/influxdb/v2/admin/buckets/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A **bucket** is a named location where time series data is stored. All buckets have a **retention period**, a duration of time that each data point persists. InfluxDB drops all points with timestamps older than the bucket’s retention period. A bucket belongs to an organization. The following articles provide information about managing buckets: ### [Create a bucket](/influxdb/v2/admin/buckets/create-bucket/) Create buckets to store time series data in InfluxDB using the InfluxDB UI, `influx` CLI, or InfluxDB API. ### [Update a bucket](/influxdb/v2/admin/buckets/update-bucket/) Update a bucket’s name or retention period in InfluxDB using the InfluxDB UI or the influx CLI. ### [View buckets](/influxdb/v2/admin/buckets/view-buckets/) View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI or the influx CLI. ### [Delete a bucket](/influxdb/v2/admin/buckets/delete-bucket/) Delete a bucket from InfluxDB using the InfluxDB UI or the influx CLI [buckets](/influxdb/v2/tags/buckets/) --- # Create a bucket Source: https://docs.influxdata.com/influxdb/v2/admin/buckets/create-bucket/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB API to create a bucket. > [!Note] > #### Bucket limits > > A single InfluxDB 2.10 OSS instance supports approximately 20 buckets actively being > written to or queried across all organizations depending on the use case. > Any more than that can adversely affect performance. [InfluxDB UI](#influxdb-ui)[influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) There are two places you can create a bucket in the UI. * [Create a bucket from the Load Data menu](#create-a-bucket-from-the-load-data-menu) * [Create a bucket in the Data Explorer](#create-a-bucket-in-the-data-explorer) ### Create a bucket from the Load Data menu 1. In the navigation menu on the left, select **Data (Load Data)** \> **Buckets**. Load Data 2. Click **Create Bucket** in the upper right. 3. Enter a **Name** for the bucket*(see [Bucket naming restrictions](#bucket-naming-restrictions))*. 4. Select when to **Delete Data**: * **Never** to retain data forever. * **Older than** to choose a specific retention period. 5. Click **Create** to create the bucket. ### Create a bucket in the Data Explorer 1. In the navigation menu on the left, select **Explore (Data Explorer)**. Data Explorer 2. In the **From** panel in the Flux Builder, select `+ Create Bucket`. 3. Enter a **Name** for the bucket*(see [Bucket naming restrictions](#bucket-naming-restrictions))*. 4. Select when to **Delete Data**: * **Never** to retain data forever. * **Older than** to choose a specific retention period. 5. Click **Create** to create the bucket. Use the [`influx bucket create` command](/influxdb/v2/reference/cli/influx/bucket/create)to create a new bucket. Include the following flags with the command: * `-n`, `--name`: Bucket name*(see [Bucket naming restrictions](#bucket-naming-restrictions))* * `-o`, `--org` or `--org-id`: Organization name or ID * `-r`, `--retention`: Bucket retention period (duration to keep data) in one of the following units: * nanoseconds (`ns`) * microseconds (`us` or `µs`) * milliseconds (`ms`) * seconds (`s`) * minutes (`m`) * hours (`h`) * days (`d`) * weeks (`w`) > [!Note] > The minimum retention period is **one hour**. ```sh # Syntax influx bucket create \ --name \ --org \ --retention # Example influx bucket create \ --name my-bucket \ --org my-org \ --retention 72h ``` To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint: ``` POST https://localhost:8086/api/v2/buckets ``` Include the following in your request: * **Headers:** * **Authorization:** `Token` scheme with your InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields: \* Required * \* **name:** Bucket name*(see [Bucket naming restrictions](#bucket-naming-restrictions))* * \* **orgID:** InfluxDB organization ID * **description:** Bucket description * **retentionRules:** JSON array containing a single object with the following fields: * **type:** expire * **everySecond**: Number of seconds to retain data *(0 means forever)* * **shardGroupDuration**: Number of seconds to retain shard groups *(0 means forever)* #### Example The URL depends on the version and location of your InfluxDB 2.10instance *(see [InfluxDB URLs](/influxdb/v2/reference/urls/))*. ```sh INFLUX_TOKEN=YOUR_API_TOKEN INFLUX_ORG_ID=YOUR_ORG_ID curl --request POST \ "http://localhost:8086/api/v2/buckets" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header "Content-type: application/json" \ --data '{ "orgID": "'"${INFLUX_ORG_ID}"'", "name": "iot-center", "retentionRules": [ { "type": "expire", "everySeconds": 86400, "shardGroupDurationSeconds": 0 } ] }' ``` *For information about **InfluxDB API options and response codes**, see[InfluxDB API Buckets documentation](/influxdb/v2/api/buckets/).* ## Bucket naming restrictions Bucket names must adhere to the following naming restrictions: * Must contain two or more characters * Cannot start with an underscore (`_`) * Cannot contain a double quote (`"`) #### Related * [Data retention in InfluxDB](/influxdb/v2/reference/internals/data-retention/) --- # Delete a bucket Source: https://docs.influxdata.com/influxdb/v2/admin/buckets/delete-bucket/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to delete a bucket. ## Delete a bucket in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **Buckets**. Load Data 1. Hover over the bucket you would like to delete. 2. Click the icon located far right of the bucket name. 3. Click **Delete** to delete the bucket. ## Delete a bucket using the influx CLI Use the [`influx bucket delete` command](/influxdb/v2/reference/cli/influx/bucket/delete)to delete a bucket a bucket by name or ID. ### Delete a bucket by name **To delete a bucket by name, you need:** * Bucket name * Bucket’s organization name or ID ```sh # Syntax influx bucket delete -n -o # Example influx bucket delete -n my-bucket -o my-org ``` ### Delete a bucket by ID **To delete a bucket by ID, you need:** * Bucket ID *(provided in the output of `influx bucket list`)* ```sh # Syntax influx bucket delete -i # Example influx bucket delete -i 034ad714fdd6f000 ``` --- # Update a bucket Source: https://docs.influxdata.com/influxdb/v2/admin/buckets/update-bucket/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update a bucket. Note that updating an bucket’s name will affect any assets that reference the bucket by name, including the following: * Queries * Dashboards * Tasks * Telegraf configurations * Templates If you change a bucket name, be sure to update the bucket in the above places as well. ## Update a bucket’s name in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **Buckets**. Load Data 2. Click **Settings** under the bucket you want to rename. 3. Click **Rename**. 4. Review the information in the window that appears and click **I understand, let’s rename my bucket**. 5. Update the bucket’s name and click **Change Bucket Name**. > [!Note] > > [!Note] > For information about permitted bucket names, see[bucket naming restrictions](/influxdb/cloud/admin/buckets/create-bucket/#bucket-naming-restrictions). ## Update a bucket’s retention period in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **Buckets**. Load Data 2. Click **Settings** next to the bucket you want to update. 3. In the window that appears, edit the bucket’s retention period. 4. Click **Save Changes**. ## Update a bucket using the influx CLI Use the [`influx bucket update` command](/influxdb/v2/reference/cli/influx/bucket/update)to update a bucket. Updating a bucket requires the following: * The bucket ID *(provided in the output of `influx bucket list`)* * The name or ID of the organization the bucket belongs to. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update the name of a bucket For information about permitted bucket names, see[bucket naming restrictions](/influxdb/cloud/admin/buckets/create-bucket/#bucket-naming-restrictions). ```sh # Syntax influx bucket update -i -n # Example influx bucket update -i 034ad714fdd6f000 -n my-new-bucket ``` ##### Update a bucket’s retention period Valid retention period duration units: * nanoseconds (`ns`) * microseconds (`us` or `µs`) * milliseconds (`ms`) * seconds (`s`) * minutes (`m`) * hours (`h`) * days (`d`) * weeks (`w`) > [!Note] > The minimum retention period is **one hour**. ```sh # Syntax influx bucket update -i -r # Example influx bucket update -i 034ad714fdd6f000 -r 1209600000000000ns ``` --- # View buckets Source: https://docs.influxdata.com/influxdb/v2/admin/buckets/view-buckets/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## View buckets in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **Buckets**. Load Data A list of buckets with their retention policies and IDs appears. 2. Click a bucket to open it in the **Data Explorer**. 3. Click the **bucket ID** to copy it to the clipboard. ## View buckets using the influx CLI Use the [`influx bucket list` command](/influxdb/v2/reference/cli/influx/bucket/list)to view a buckets in an organization. ```sh influx bucket list ``` Other filtering options such as filtering by organization, name, or ID are available. See the [`influx bucket list` documentation](/influxdb/v2/reference/cli/influx/bucket/list)for information about other available flags. --- # Identify InfluxDB OSS v2 version Source: https://docs.influxdata.com/influxdb/v2/admin/identify-version/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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 OSS v2 detection Check the version using `influxd`: ```bash influxd version ``` Query the `/health` endpoint and extract the version: ```bash curl -s http://localhost:8086/health | jq -r '.version' ``` The InfluxDB UI displays the version: * On the login page * In the right column of the main landing page * In the user menu dropdown For more details, see [How can I identify my InfluxDB version?](/influxdb/v2/reference/faq/#administration-1) ## 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](/influxdb/v2/get-started/) * [influxd - InfluxDB service](/influxdb/v2/reference/cli/influxd/) --- # Manage InfluxDB internal systems Source: https://docs.influxdata.com/influxdb/v2/admin/internals/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Manage InfluxDB internal systems, including the time series index (TSI), time-structured merge tree (TSM) storage engine, and write-ahead log (WAL). ### [Manage the InfluxDB time series index (TSI)](/influxdb/v2/admin/internals/tsi/) The InfluxDB [time series index (TSI)](/influxdb/v2/reference/internals/storage-engine/#time-series-index-tsi) indexes or caches measurement and tag data to ensure queries are performant. Use the `influxd inspect` command to manage the TSI index. [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # Manage the InfluxDB time series index (TSI) Source: https://docs.influxdata.com/influxdb/v2/admin/internals/tsi/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB [time series index (TSI)](/influxdb/v2/reference/internals/storage-engine/#time-series-index-tsi)indexes or caches measurement and tag data to ensure queries are performant. ### [Rebuild the TSI index](/influxdb/v2/admin/internals/tsi/rebuild-index/) Flush and rebuild the TSI index to purge corrupt index files or remove indexed data that is out of date. ### [Inspect TSI indexes](/influxdb/v2/admin/internals/tsi/inspect/) Use the `influxd inspect` command to inspect the InfluxDB TSI index. [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # Inspect TSI indexes Source: https://docs.influxdata.com/influxdb/v2/admin/internals/tsi/inspect/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influxd inspect` command to inspect the InfluxDB [time series index (TSI)](/influxdb/v2/reference/internals/storage-engine/#time-series-index-tsi). * [Output information about TSI index files](#output-information-about-tsi-index-files) * [Output raw series data stored in the index](#output-raw-series-data-stored-in-the-index) * [Output measurement data stored in the index](#output-measurement-data-stored-in-the-index) * [Export TSI index data as SQL](#export-tsi-index-data-as-sql) * [Report the cardinality of TSI files](#report-the-cardinality-of-tsi-files) ## Output information about TSI index files Use the [`influxd inspect dump-tsi` command](/influxdb/v2/reference/cli/influxd/inspect/dump-tsi/)to output low-level details about TSI index (`tsi1`) files. Provide the following: * (Required) `--series-file` flag with the path to bucket’s[`_series` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * (Required) Path to the shard’s[`index` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout) ```sh influxd inspect dump-tsi \ --series-file ~/.influxdbv2/engine/data/056d83f962a08461/_series \ ~/.influxdbv2/engine/data/056d83f962a08461/autogen/1023/index ``` [](#view-example-output) View example output ``` [LOG FILE] L0-00000006.tsl Series: 0 Measurements: 0 Tag Keys: 0 Tag Values: 0 [INDEX FILE] L3-00000008.tsi Measurements: 3 Series data size: 0 (0.0b) Bytes per series: 0.0b Tag Keys: 15 Tag Values: 1025 Series: 1700 Series data size: 0 (0.0b) Bytes per series: 0.0b [LOG FILE] L0-00000010.tsl Series: 0 Measurements: 0 Tag Keys: 0 Tag Values: 0 [INDEX FILE] L2-00000011.tsi Measurements: 1 Series data size: 0 (0.0b) Bytes per series: 0.0b Tag Keys: 5 Tag Values: 9 Series: 10 Series data size: 0 (0.0b) Bytes per series: 0.0b ``` ### Output raw series data stored in the index To output raw series data stored in index files, include the `--series` flag with the `influxd inspect dump-tsi` command: ```sh influxd inspect dump-tsi \ --series \ --series-file ~/.influxdbv2/engine/data/056d83f962a08461/_series \ ~/.influxdbv2/engine/data/056d83f962a08461/autogen/1023/index ``` [](#view-example-output) View example output ``` earthquake,code=6000iuad,id=us6000iuad,magType=mww,net=us,title=M\ 5.2\ -\ 101\ km\ SE\ of\ Palca\,\ Peru earthquake,code=71377273,id=pr71377273,magType=md,net=pr,title=M\ 1.9\ -\ Puerto\ Rico\ region earthquake,code=73794611,id=nc73794611,magType=md,net=nc,title=M\ 0.6\ -\ 13km\ ESE\ of\ Mammoth\ Lakes\,\ CA earthquake,code=40361800,id=ci40361800,magType=ml,net=ci,title=M\ 1.3\ -\ 12km\ SE\ of\ Olancha\,\ CA earthquake,code=6000itfk,id=us6000itfk,magType=mb,net=us,title=M\ 4.4\ -\ Mindanao\,\ Philippines earthquake,code=2022ucrr,id=ok2022ucrr,magType=ml,net=ok,title=M\ 1.4\ -\ 4\ km\ SSE\ of\ Dover\,\ Oklahoma earthquake,code=73792706,id=nc73792706,magType=md,net=nc,title=M\ 0.6\ -\ 7km\ W\ of\ Cobb\,\ CA earthquake,code=6000isjn,id=us6000isjn,magType=mww,net=us,title=M\ 5.5\ -\ 69\ km\ E\ of\ Hualien\ City\,\ Taiwan earthquake,code=022d8mp4dd,id=ak022d8mp4dd,magType=ml,net=ak,title=M\ 1.3\ -\ Southern\ Alaska earthquake,code=022dbrb8vb,id=ak022dbrb8vb,magType=ml,net=ak,title=M\ 1.6\ -\ 37\ km\ NE\ of\ Paxson\,\ Alaska earthquake,code=6000iu2e,id=us6000iu2e,magType=mb,net=us,title=M\ 4.1\ -\ 81\ km\ WSW\ of\ San\ Antonio\ de\ los\ Cobres\,\ Argentina ``` ### Output measurement data stored in the index To output measurement information stored in index files, include the `--measurement`flag with the `influxd inspect dump-tsi` command: ```sh influxd inspect dump-tsi \ --measurements \ --series-file ~/.influxdbv2/engine/data/056d83f962a08461/_series \ ~/.influxdbv2/engine/data/056d83f962a08461/autogen/1023/index ``` [](#view-example-output) View example output ``` Measurement earthquake explosion quarry blast Measurement earthquake explosion ice quake quarry blast Measurement earthquake explosion ``` ## Export TSI index data as SQL Use the [`influxd inspect export-index` command](/influxdb/v2/reference/cli/influxd/inspect/export-index/)to export an index in SQL format for easier inspection and debugging. Provide the following: * `--series-path` flag with the path to the bucket’s[`_series` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * `--index-path` flag with the path to the shard’s[`index` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). ```sh influxd inspect export-index \ --series-path ~/.influxdbv2/engine/data/056d83f962a08461/_series \ --index-path ~/.influxdbv2/engine/data/056d83f962a08461/autogen/1023/index ``` [](#view-example-output) View example output ```sql CREATE TABLE IF NOT EXISTS measurement_series ( name TEXT NOT NULL, series_id INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS tag_value_series ( name TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, series_id INTEGER NOT NULL ); BEGIN TRANSACTION; INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26920); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26928); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26936); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26944); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26952); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26960); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26968); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26976); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26984); INSERT INTO measurement_series (name, series_id) VALUES ('earthquake', 26992); COMMIT; ``` ## Report the cardinality of TSI files Use the [`influxd inspect report-tsi` command](/influxdb/v2/reference/cli/influxd/inspect/report-tsi/)to output information about the cardinality of data in a bucket’s index. Provide the following: * `--bucket-id` with the ID of the bucket. ```sh influxd inspect report-tsi --bucket-id 056d83f962a08461 ``` [](#view-example-output) View example output ``` Summary Database Path: /Users/scottanderson/.influxdbv2/engine/data/056d83f962a08461 Cardinality (exact): 101698 Measurement Cardinality (exact) "earthquake" 99876 "quarry blast" 1160 "explosion" 589 "ice quake" 58 "other event" 10 "chemical explosion" 2 "rock burst" 1 "sonic boom" 1 "volcanic eruption" 1 =============== Shard ID: 452 Path: /Users/scottanderson/.influxdbv2/engine/data/056d83f962a08461/autogen/452 Cardinality (exact): 1644 Measurement Cardinality (exact) "earthquake" 1607 "quarry blast" 29 "explosion" 7 # "sonic boom" 1 =============== Shard ID: 453 Path: /Users/scottanderson/.influxdbv2/engine/data/056d83f962a08461/autogen/453 Cardinality (exact): 2329 Measurement Cardinality (exact) "earthquake" 2298 "quarry blast" 24 # "explosion" 7 ``` #### Related * [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/) * [InfluxDB file system layout](/influxdb/v2/reference/internals/file-system-layout/) * [influxd inspect dump-tsi](/influxdb/v2/reference/cli/influxd/inspect/dump-tsi/) * [influxd inspect export-index](/influxdb/v2/reference/cli/influxd/inspect/export-index/) * [influxd inspect report-tsi](/influxdb/v2/reference/cli/influxd/inspect/report-tsi/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # Rebuild the TSI index Source: https://docs.influxdata.com/influxdb/v2/admin/internals/tsi/rebuild-index/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). In some cases, it may be necessary to flush and rebuild the TSI index. For example, purging corrupt index files or removing outdated indexed data. To rebuild your InfluxDB TSI index: 1. **Stop the InfluxDB (`influxd`) process**. Rebuilding the TSI index while the `influxd` is running could prevent some data from being queryable. 2. Navigate to the `data` directory in your[InfluxDB engine path](/influxdb/v2/reference/internals/file-system-layout/).*The engine path depends on your operating system or[custom engine path setting](/influxdb/v2/reference/config-options/#engine-path).* [macOS & Linux](#macos--linux)[Windows (PowerShell)](#windows-powershell) ``` cd ~/.influxdbv2/engine/data/ ``` ``` cd -Path 'C:\%USERPROFILE%\.influxdbv2\engine\data\' ``` 3. **Delete all `_series` directories in your InfluxDB `data` directory.**By default, `_series` directories are are stored at `/data//_series`, but check for and remove `_series` directories throughout the`data` directory. [macOS & Linux](#macos--linux-2)[Windows (PowerShell)](#windows-powershell-2) ``` find . -type d -name _series -exec -delete ``` ``` get-childitem -Include _series -Recurse -force | Remove-Item -Force -Recurse ``` 4. **Delete all `index` directories.** By default, `index` directories are stored at`/data//autogen//index`, but check for and remove`index` directories throughout the `data` directory. [macOS & Linux](#macos--linux-3)[Windows (PowerShell)](#windows-powershell-3) ``` find . -type d -name index -exec -delete ``` ``` get-childitem -Include index -Recurse -force | Remove-Item -Force -Recurse ``` 5. Use the [`influxd inspect build-tsi` command](/influxdb/v2/reference/cli/influxd/inspect/build-tsi/)to rebuild the TSI index. ``` influxd inspect build-tsi ``` #### Related * [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/) * [InfluxDB file system layout](/influxdb/v2/reference/internals/file-system-layout/) * [influxd inspect build-tsi](/influxdb/v2/reference/cli/influxd/inspect/build-tsi/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # Manage InfluxDB logs Source: https://docs.influxdata.com/influxdb/v2/admin/logs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Learn how to configure, manage, and process your InfluxDB logs: * [Configure your InfluxDB log location](#configure-your-influxdb-log-location) * [Configure your log level](#configure-your-log-level) * [Enable the Flux query log](#enable-the-flux-query-log) * [Use external tools to manage and process logs](#use-external-tools-to-manage-and-process-logs) * [Log formats](#log-formats) ## Configure your InfluxDB log location By default, InfluxDB outputs all logs to **stdout**. To view InfluxDB logs, view the output of the [`influxd`](/influxdb/v2/reference/cli/influxd/) process. * [Write logs to a file](#write-logs-to-a-file) * [Logs when running InfluxDB as a service](#logs-when-running-influxdb-as-a-service) ### Write logs to a file To write InfluxDB logs to a file, redirect **stdout** to a file when starting the InfluxDB service ([`influxd`](/influxdb/v2/reference/cli/influxd/)). ```sh influxd 1> /path/to/influxdb.log ``` > [!Note] > When logging to a file, InfluxDB uses the [logfmt](#logfmt) format. ### Logs when running InfluxDB as a service If you use a service manager to run InfluxDB, the service manager determines the location of logs. [systemd](#systemd)[sysvinit](#sysvinit) Most Linux systems direct logs to the `systemd` journal. To access these logs, use the following command: ```sh sudo journalctl -u influxdb.service ``` For more information, see the [journald.conf documentation](https://www.freedesktop.org/software/systemd/man/journald.conf.html). When InfluxDB is run as a service, **stdout** is discarded by default (sent to `/dev/null`). To write logs to a file: 1. Open the InfluxDB startup script (`/etc/default/influxdb`) in a text editor. 2. Set the `STDOUT` environment variable to the path where you want to store the InfluxDB logs. For example: ``` STDOUT=/var/log/influxdb/influxd.log ``` 3. Save the changes to the startup script. 4. Restart the InfluxDB service to apply the changes. ``` service influxdb restart ``` ## Configure your log level Use the [`log-level` InfluxDB configuration option](/influxdb/v2/reference/config-options/#log-level)to specify the log levels the InfluxDB service outputs. InfluxDB supports the following log levels: * **debug**: Output logs with debug, info, and error log levels. * **info**: *(Default)* Output logs with info and error log levels. * **error**: Output logs with the error log level only. [influxd flag](#influxd-flag)[Environment variable](#environment-variable)[InfluxDB configuration file](#influxdb-configuration-file) ```sh influxd --log-level=info ``` ```sh export INFLUXD_LOG_LEVEL=info ``` [YAML](#yaml)[TOML](#toml)[JSON](#json) ```yml log-level: info ``` ```toml log-level = "info" ``` ```json { "log-level": "info" } ``` *For information about configuring InfluxDB, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/).* ## Enable the Flux query log Use the [`flux-log-enabled` configuration option](/influxdb/v2/reference/config-options/#flux-log-enabled)to enable Flux query logging. InfluxDB outputs Flux query logs to **stdout**with all other InfluxDB logs. [influxd flag](#influxd-flag-2)[Environment variable](#environment-variable-2)[InfluxDB configuration file](#influxdb-configuration-file-2) ```sh influxd --flux-log-enabled ``` ```sh export INFLUXD_FLUX_LOG_ENABLED=true ``` [YAML](#yaml-2)[TOML](#toml-2)[JSON](#json-2) ```yml flux-log-enabled: true ``` ```toml flux-log-enabled = true ``` ```json { "flux-log-enabled": true } ``` *For information about configuring InfluxDB, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/).* ## Use external tools to manage and process logs Use the following popular tools to manage and process InfluxDB logs: ### logrotate [logrotate](https://github.com/logrotate/logrotate) simplifies the administration of log files and provides automatic rotation compression, removal and mailing of log files. Logrotate can be set to handle a log file hourly, daily, weekly, monthly or when the log file gets to a certain size. ### hutils [hutils](https://blog.heroku.com/hutils-explore-your-structured-data-logs) is a collection of command line utilities for working with logs with [logfmt](#logfmt)encoding, including: * **lcut**: Extracts values from a logfmt trace based on a specified field name. * **lfmt**: Reformats and highlights key sections of logfmt lines. * **ltap**: Accesses messages from log providers in a consistent way to allow easy parsing by other utilities that operate on logfmt traces. * **lviz**: Visualizes logfmt output by building a tree out of a dataset combining common sets of key-value pairs into shared parent nodes. ### lnav (Log File Navigator) [lnav (Log File Navigator)](http://lnav.org/) is an advanced log file viewer useful for watching and analyzing log files from a terminal. The lnav viewer provides a single log view, automatic log format detection, filtering, timeline view, pretty-print view, and querying logs using SQL. ## Log formats InfluxDB outputs logs in one of two formats depending on the location of where logs are output. * [Console/TTY](#consoletty) * [logfmt](#logfmt) ### Console/TTY **When logging to a terminal or other TTY devices**, InfluxDB uses a console-friendly format. ##### Example console/TTY format ```sh 2022-09-29T21:58:29.936355Z info Welcome to InfluxDB {"log_id": "0dEoz3C0000", "version": "dev", "commit": "663d43d210", "build_date": "2022-09-29T21:58:29Z", "log_level": "info"} 2022-09-29T21:58:29.977671Z info Resources opened {"log_id": "0dEoz3C0000", "service": "bolt", "path": "/Users/exampleuser/.influxdbv2/influxd.bolt"} 2022-09-29T21:58:29.977891Z info Resources opened {"log_id": "0dEoz3C0000", "service": "sqlite", "path": "/Users/exampleuser/.influxdbv2/influxd.sqlite"} 2022-09-29T21:58:30.059709Z info Checking InfluxDB metadata for prior version. {"log_id": "0dEoz3C0000", "bolt_path": "/Users/exampleuser/.influxdbv2/influxd.bolt"} ``` ### logfmt **When logging to a file**, InfluxDB uses **logfmt**, a machine-readable structured log format that provides simpler integrations with external tools like[Splunk](https://www.splunk.com/), [Papertrail](https://www.papertrail.com/),[Elasticsearch](https://www.elastic.co/), and other third party tools. ##### Example logfmt format ```sh ts=2022-09-29T16:54:16.021427Z lvl=info msg="Welcome to InfluxDB" log_id=0dEYZvqG000 version=dev commit=663d43d210 build_date=2022-09-29T16:54:15Z log_level=info ts=2022-09-29T16:54:16.062239Z lvl=info msg="Resources opened" log_id=0dEYZvqG000 service=bolt path=/Users/exampleuser/.influxdbv2/influxd.bolt ts=2022-09-29T16:54:16.062457Z lvl=info msg="Resources opened" log_id=0dEYZvqG000 service=sqlite path=/Users/exampleuser/.influxdbv2/influxd.sqlite ts=2022-09-29T16:54:16.144430Z lvl=info msg="Checking InfluxDB metadata for prior version." log_id=0dEYZvqG000 bolt_path=/Users/exampleuser/.influxdbv2/influxd.bolt ``` --- # Manage organizations Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). An **organization** is a workspace for a group of users. All dashboards, tasks, buckets, members, etc., belong to an organization. The following articles provide information about managing organizations: ### [Create an organization](/influxdb/v2/admin/organizations/create-org/) Create an organization in InfluxDB using the InfluxDB UI or the influx CLI. ### [View organizations](/influxdb/v2/admin/organizations/view-orgs/) Review a list of organizations in InfluxDB using the InfluxDB UI or the influx CLI. ### [Update an organization](/influxdb/v2/admin/organizations/update-org/) Update an organization’s name and assets in InfluxDB using the InfluxDB UI or the influx CLI. ### [Delete an organization](/influxdb/v2/admin/organizations/delete-org/) Delete an existing organization from InfluxDB using the influx CLI. ### [Switch organizations](/influxdb/v2/admin/organizations/switch-org/) Switch from one organization to another in the InfluxDB UI ### [Manage organization members](/influxdb/v2/admin/organizations/members/) Manage members of an organization in InfluxDB using the InfluxDB UI or CLI. [organizations](/influxdb/v2/tags/organizations/) --- # Create an organization Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/create-org/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to create an organization. > [!Note] > #### Organization and bucket limits > > A single InfluxDB 2.10 OSS instance supports approximately 20 buckets actively being > written to or queried across all organizations depending on the use case. > Any more than that can adversely affect performance. > Because each organization is created with a bucket, we do not recommend more than > 20 organizations in a single InfluxDB OSS instance. ## Create an organization in the InfluxDB UI 1. In the navigation menu on the left, click the **Account dropdown**. u u username org-name 2. Select **Create Organization**. 3. In the window that appears, enter an **Organization Name** and **Bucket Name** and click **Create**. ## Create an organization using the influx CLI Use the [`influx org create` command](/influxdb/v2/reference/cli/influx/org/create)to create a new organization. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * A name for the organization with the `--name, -n` flag. * *Optional:* A description of the organization with the `--description, -d` flag. ```sh influx org create \ --name ORG_NAME \ --description "ORG_DESCRIPTION" ``` Replace the following: * `ORG_NAME`: The name of the organization to create * `ORG_DESCRIPTION`: A description of the organization --- # Delete an organization Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/delete-org/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) to delete an organization. ## Delete an organization using the influx CLI Use the [`influx org delete` command](/influxdb/v2/reference/cli/influx/org/delete)to delete an organization. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The [ID of the organization](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)to delete ```sh influx org delete -i ORG_ID ``` Replace `ORG_ID` with the ID of the organization to delete. --- # Manage organization members Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/members/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A **member** is a user that belongs to an organization. The following articles provide information about managing users: ### [Add a member](/influxdb/v2/admin/organizations/members/add-member/) Use the `influx` command line interface (CLI) to add a member to an organization and optionally make that member an owner across all organizations. ### [View members](/influxdb/v2/admin/organizations/members/view-members/) Review a list of members for an organization. ### [Remove a member](/influxdb/v2/admin/organizations/members/remove-member/) Remove a member from an organization. [members](/influxdb/v2/tags/members/) --- # Add a member Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/members/add-member/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) to add a member to an organization and optionally make that member an owner across all organizations. ## Add a member to an organization using the influx CLI 1. Get a list of users and their IDs by running the following: ``` influx user list ``` 2. To add a user as a member of an organization, use the `influx org members add command`. Provide the following: * Organization name * User ID * *(Optional)* `--owner` flag to add the user as an owner*(requires an [operator token](/influxdb/v2/admin/tokens/#operator-token))* [Add member](#add-member)[Add owner](#add-owner) ``` influx org members add \ -n \ -m ``` ``` influx org members add \ -n \ -m \ --owner ``` For more information, see the [`influx org members add` command](/influxdb/v2/reference/cli/influx/org/members/add). --- # Remove a member Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/members/remove-member/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to remove a member from an organization. > [!Note] > Removing a member from an organization removes all permissions associated with the organization, > but it does not delete the user from the system entirely. > For information about deleting a user from InfluxDB, see [Delete a user](/influxdb/v2/admin/users/delete-user/). ## Remove a member from an organization in the InfluxDB UI 1. In the navigation menu on the left, click your **Account avatar** and select **Members**. u u username org-name 2. Click the icon next to the member you want to delete. 3. Click **Delete** to confirm and remove the user from the organization. ## Remove a member from an organization using the influx CLI Use the [`influx org members remove` command](/influxdb/v2/reference/cli/influx/org/members/remove)to remove a member from an organization. Removing a member requires the following: * The organization name or ID *(provided in the output of [`influx org list`](/influxdb/v2/reference/cli/influx/org/list/))* * The member ID *(provided in the output of [`influx org members list`](/influxdb/v2/reference/cli/influx/org/members/list/))* ```sh # Syntax influx org members remove -o -i # Example influx org members remove -o 00xXx0x00xXX0000 -i x0xXXXx00x0x000X ``` --- # View members Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/members/view-members/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to view members of an organization. ## View members of organization in the InfluxDB UI In the navigation menu on the left, click your **Account avatar** and select **Members**. u u username org-name ## View members of organization using the influx CLI Use the [`influx org members list` command](/influxdb/v2/reference/cli/influx/org/members/list)to list members of an organization. Listing an organization’s members requires the following: * The name or ID of the organization ```sh # Syntax influx org members list -n # Example influx org members list -n my-org ``` --- # Switch organizations Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/switch-org/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) to switch from one organization to another. The organization you’re currently viewing determines what dashboards, tasks, buckets, members, and other assets you can access. ## Switch organizations in the InfluxDB UI 1. In the navigation menu on the left, click the **Account dropdown**. u u username org-name 2. Select **Switch Organizations**. 3. Click the organization you want to switch to. --- # Update an organization Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/update-org/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update an organization. Note that updating an organization’s name will affect any assets that reference the organization by name, including the following: * Queries * Dashboards * Tasks * Telegraf configurations * Templates If you change an organization name, be sure to update the organization in the above places as well. ## Update an organization in the InfluxDB UI 1. In the navigation menu on the left, click the user icon \> **About**. u u username org-name 2. Click **Rename**. A verification window appears. 3. Review the information, and then click **I understand, let’s rename my organization**. 4. Enter a new name for your organization, and then click **Change organization name**. ## Update an organization using the influx CLI Use the [`influx org update` command](/influxdb/v2/reference/cli/influx/org/update)to update an organization. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The [ID of the organization](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)to update using the `--org-id, -i` flag. * *Optional:* The updated name for the organization with the `--name, -n` flag. * *Optional:* The updated description for the organization with the`--description, -d` flag. ##### Update the name of an organization ```sh influx org update \ --org-id ORG_ID \ --name NEW_ORG_NAME \ --description NEW_ORG_DESCRIPTION \ ``` Replace the following: * `ORG_ID`: The ID of the organization to update. * `NEW_ORG_NAME`: The new name for the organization. * `NEW_ORG_DESCRIPTION`: The new description for the organization. --- # View organizations Source: https://docs.influxdata.com/influxdb/v2/admin/organizations/view-orgs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to view organizations. ## View organizations in the InfluxDB UI 1. In the navigation menu on the left, click the **Account dropdown**. u u username org-name 2. Select **Switch Organizations**. The list of organizations appears. ## View organizations using the influx CLI Use the [`influx org list` command](/influxdb/v2/reference/cli/influx/org/list)to view organizations. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. ```sh influx org list ``` Filtering options such as filtering by name or ID are available. See the [`influx org list` documentation](/influxdb/v2/reference/cli/influx/org/list)for information about other available flags. ## View your organization ID Use the InfluxDB UI or `influx` CLI to view your organization ID. ### Organization ID in the UI After logging in to the InfluxDB UI, your organization ID appears in the URL. ```sh http://localhost:8086/orgs/03a2bbf46249a000/... ``` ### Organization ID in the CLI Use [`influx org list`](#view-organizations-using-the-influx-cli) to view your organization ID. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. ```sh influx org list ``` The command returns output similar to: ``` ID Name 03a2bbf46249a000 org-1 03ace3a859669000 org-2 ``` --- # Manage secrets Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Secrets are key-value pairs that contain sensitive information you want to control access to, such as API keys, passwords, or certificates. There are two options for storing secrets with InfluxDB: * By default, secrets are Base64-encoded and stored in the InfluxDB embedded key value store,[BoltDB](https://github.com/boltdb/bolt). * You can also set up a Vault server to store secrets. For details, see [Store secrets in Vault](/influxdb/v2/admin/secrets/use-vault). ### [Add secrets](/influxdb/v2/admin/secrets/add/) Add secrets using the `influx` CLI or the InfluxDB API. ### [View secret keys](/influxdb/v2/admin/secrets/view/) View secret keys using the `influx` CLI or the InfluxDB API. ### [Update secrets](/influxdb/v2/admin/secrets/update/) Update secrets using the `influx` CLI or the InfluxDB API. ### [Delete secrets](/influxdb/v2/admin/secrets/delete/) Delete secrets using the `influx` CLI or the InfluxDB API. ### [Use secrets](/influxdb/v2/admin/secrets/use/) Use secrets in a query with Flux. ### [Store secrets in Vault](/influxdb/v2/admin/secrets/use-vault/) Use Vault as an InfluxDB secret store and manage secrets through the in InfluxDB API. [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Add secrets Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/add/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Add secrets using the `influx` command line interface (CLI) or the InfluxDB API. * [Add a secret using the influx CLI](#add-a-secret-using-the-influx-cli) * [Add a secret using the InfluxDB API](#add-a-secret-using-the-influxdb-api) ## Add a secret using the influx CLI Use the [`influx secret update` command](/influxdb/v2/reference/cli/influx/secret/update/)to add a new secret to your organization. Provide the secret key with the `-k` or `--key` flag. You may also provide the secret value with the `-v` or `--value` flag. If you do not provide the secret value with the `-v` or `--value` flag, enter the value when prompted. Providing a secret value with the `-v` or `--value` flag may expose the secret in your command history. ```sh # Syntax influx secret update -k # Example influx secret update -k foo ``` ## Add a secret using the InfluxDB API Use the `PATCH` request method and the `/orgs/{orgID}/secrets` API endpoint to add a new secret to your organization. **Include the following:** * Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/v2/admin/tokens/view-tokens/) in the `Authorization` header * The secret key-value pair in the request body ```sh curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ --header 'Authorization: Token YOURAUTHTOKEN' \ --header 'Content-type: application/json' \ --data '{ "": "" }' ``` [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Delete secrets Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Delete secrets using the `influx` command line interface (CLI) or the InfluxDB API. * [Delete a secret using the influx CLI](#delete-a-secret-using-the-influx-cli) * [Delete secrets using the InfluxDB API](#delete-secrets-using-the-influxdb-api) ## Delete a secret using the influx CLI Use the [`influx secret delete` command](/influxdb/v2/reference/cli/influx/secret/delete/)to delete a secret key-value pair from your organization. Provide the secret key to delete with the `-k` or `--key` flag. ```sh # Syntax influx secret delete -k # Example influx secret delete -k foo ``` ## Delete secrets using the InfluxDB API Use the `POST` request method and the `orgs/{orgID}/secrets/delete` API endpoint to delete one or more secrets. **Include the following:** * Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/v2/admin/tokens/view-tokens/) in the `Authorization` header * An array of secret keys to delete in the request body ```bash curl --request GET http://localhost:8086/api/v2/orgs//secrets/delete \ --header 'Authorization: Token YOURAUTHTOKEN' \ --data '{ "secrets": [ "" ] }' ``` [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Update secrets Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update secrets using the `influx` command line interface (CLI) or the InfluxDB API. * [Update a secret using the influx CLI](#update-a-secret-using-the-influx-cli) * [Update a secret using the InfluxDB API](#update-a-secret-using-the-influxdb-api) ## Update a secret using the influx CLI Use the [`influx secret update` command](/influxdb/v2/reference/cli/influx/secret/update/)to update a secret in your organization. Provide the secret key to update with the `-k` or `--key` flag. You may also provide the secret value with the `-v` or `--value` flag. If you do not provide the secret value with the `-v` or `--value` flag, enter the value when prompted. Providing a secret value with the `-v` or `--value` flag may expose the secret in your command history. ```sh # Syntax influx secret update -k # Example influx secret update -k foo ``` ## Update a secret using the InfluxDB API Use the `PATCH` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint to update a secret in your organization. **Include the following:** * Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/v2/admin/tokens/view-tokens/) in the `Authorization` header * The updated secret key-value pair in the request body ```sh curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ --header 'Authorization: Token YOURAUTHTOKEN' \ --header 'Content-type: application/json' \ --data '{ "": "" }' ``` [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Store secrets in Vault Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/use-vault/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Vault](https://www.vaultproject.io/) secures, stores, and controls access to tokens, passwords, certificates, and other sensitive secrets. Store sensitive secrets in Vault using InfluxDB’s built-in Vault integration. To store secrets in Vault, complete the following steps: 1. [Start a Vault server](#start-a-vault-server). 2. [Provide Vault server address and token](#provide-vault-server-address-and-token). 3. [Start InfluxDB](#start-influxdb). 4. [Manage secrets through the InfluxDB API](#manage-secrets-through-the-influxdb-api). ## Start a Vault server Start a Vault server and ensure InfluxDB has network access to the server. The following links provide information about running Vault in both development and production: * [Install Vault](https://learn.hashicorp.com/vault/getting-started/install) * [Start a Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server) * [Deploy Vault](https://learn.hashicorp.com/vault/getting-started/deploy) > [!Note] > InfluxDB supports the [Vault KV Secrets Engine Version 2 API](https://www.vaultproject.io/api/secret/kv/kv-v2.html) only. > When you create a secrets engine, enable the `kv-v2` version by running: > > ``` > vault secrets enable kv-v2 > ``` For this example, install Vault on your local machine and start a Vault dev server. ```bash vault server -dev ``` ## Provide Vault server address and token Use `influxd` Vault-related tags or [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables)to provide connection credentials and other important Vault-related information to InfluxDB. ### Required credentials #### Vault address Provide the API address of your Vault server *(available in the Vault server output)*using the [`--vault-addr` flag](/influxdb/v2/reference/config-options/#vault-addr) when starting `influxd` or with the `VAULT_ADDR` environment variable. #### Vault token Provide your [Vault token](https://learn.hashicorp.com/vault/getting-started/authentication)(required to access your Vault server) using the [`--vault-token` flag](/influxdb/v2/reference/config-options/#vault-token)when starting `influxd` or with the `VAULT_TOKEN` environment variable. *Your Vault server configuration may require other Vault settings.* ## Start InfluxDB Start the [`influxd` service](/influxdb/v2/reference/cli/influxd/) with the `--secret-store`option set to `vault` and any other necessary flags–for example, enter the following command: ```bash influxd --secret-store vault \ --vault-addr=http://127.0.0.1:8200 \ --vault-token=$VAULT_TOKEN ``` `influxd` includes the following Vault configuration options. If set, these flags override any [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables): * `--vault-addr` * `--vault-cacert` * `--vault-capath` * `--vault-client-cert` * `--vault-client-key` * `--vault-max-retries` * `--vault-client-timeout` * `--vault-skip-verify` * `--vault-tls-server-name` * `--vault-token` For more information, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/). ## Manage secrets through the InfluxDB API Use the InfluxDB `/org/{orgID}/secrets` API endpoint to add tokens to Vault. For details, see [Secrets](/influxdb/v2/admin/secrets/). [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Use secrets Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/use/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## Use secrets in a query Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function to populate sensitive data in queries with secrets from your secret store. ```js import "influxdata/influxdb/secrets" import "sql" username = secrets.get(key: "POSTGRES_USERNAME") password = secrets.get(key: "POSTGRES_PASSWORD") sql.from( driverName: "postgres", dataSourceName: "postgresql://${username}:${password}@localhost", query:"SELECT * FROM example-table", ) ``` [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # View secret keys Source: https://docs.influxdata.com/influxdb/v2/admin/secrets/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View secret keys using the `influx` command line interface (CLI) or the InfluxDB API. * [View secret keys using the influx CLI](#view-secret-keys-using-the-influx-cli) * [View secret keys using the InfluxDB API](#view-secret-keys-using-the-influxdb-api) ## View secret keys using the influx CLI Use the [`influx secret list` command](/influxdb/v2/reference/cli/influx/secret/list/)to list your organization’s secret keys. ```sh influx secret list ``` ## View secret keys using the InfluxDB API Use the `GET` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint to view your organization’s secrets keys. **Include the following:** * Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/v2/admin/tokens/view-tokens/) in the `Authorization` header ```sh curl --request GET http://localhost:8086/api/v2/orgs//secrets \ --header 'Authorization: Token YOURAUTHTOKEN' ``` [secrets](/influxdb/v2/tags/secrets/)[security](/influxdb/v2/tags/security/) --- # Manage security and authorization Source: https://docs.influxdata.com/influxdb/v2/admin/security/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Security, access control, and sensitive secret handling are incredibly important when handling any sort of sensitive data. This section provides information about managing the security of your InfluxDB instance. > [!Note] > #### InfluxDB 2.x/1.x compatibility > > If you [upgraded from 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/), > use the [`influx v1 auth`](/influxdb/v2/reference/cli/influx/v1/auth/) commands > to manage authorizations for the [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ### [Enable TLS encryption](/influxdb/v2/admin/security/enable-tls/) Enable Transport Layer Security (TLS) and use the HTTPS protocol to secure communication between clients and InfluxDB. ### [Enable security features](/influxdb/v2/admin/security/enable-hardening/) Enable a collection of additional security and hardening features in InfluxDB OSS to better secure your InfluxDB instance. ### [Disable development features](/influxdb/v2/admin/security/disable-devel/) Disable development features that may not be desirable in production. [security](/influxdb/v2/tags/security/)[authentication](/influxdb/v2/tags/authentication/) --- # Disable development features Source: https://docs.influxdata.com/influxdb/v2/admin/security/disable-devel/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). By default, InfluxDB 2.10 enables useful functionality that exposes some level of information about your instance. Two of these are endpoints for observability of the health and activity of your instance. The third is the bundled UI. Depending on your site requirements, you may want to disable one or more of these when running InfluxDB in production. To disable, use the following configuration options: * [Disable /debug/pprof](/influxdb/v2/reference/config-options/#pprof-disabled). This endpoint provides runtime profiling data. * [Disable /metrics](/influxdb/v2/reference/config-options/#metrics-disabled). This endpoint exposes [internal InfluxDB metrics](/influxdb/v2/reference/internals/metrics/). * [Disable UI](/influxdb/v2/reference/config-options/#ui-disabled). The user interface for InfluxDB. [security](/influxdb/v2/tags/security/)[development](/influxdb/v2/tags/development/) --- # Enable security features Source: https://docs.influxdata.com/influxdb/v2/admin/security/enable-hardening/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB 2.10 provides optional security features that ensure your InfluxDB instance is secure in whatever environment it’s used in. To enable all [additional security features](#security-features), use the[`hardening-enabled` configuration option](/influxdb/v2/reference/config-options/#hardening-enabled)when starting InfluxDB. ## Security features * [Private IP Validation](#private-ip-validation) * [Restricted health check details](#restricted-health-check-details) ### Private IP Validation Some Flux functions ([`to()`](/flux/v0/stdlib/influxdata/influxdb/to/),[`from()`](/flux/v0/stdlib/influxdata/influxdb/from/), [`http.post()`](/flux/v0/stdlib/http/post/), etc.),[template fetching](/influxdb/v2/tools/influxdb-templates/) and[notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/)can require InfluxDB to make HTTP requests over the network. With private IP validation enabled, InfluxDB first verifies that the IP address of the URL is not a private IP address. IP addresses are considered private if they fall into one of the following categories: * IPv4 loopback (`127.0.0.0/8`) * RFC1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) * RFC3927 (`169.254.0.0/16`) * IPv6 loopback (`::1/128`) * IPv6 link-local (`fe80::/10`) * IPv6 unique local (`fc00::/7`) > [!Note] > #### Private IP considerations > > If your environment requires that these authenticated HTTP requests be made to private IP addresses, > omit the use of `--hardening-enabled` and > consider instead setting up egress firewalling to limit which hosts InfluxDB is allowed to connect. ### Restricted health check details *Available in InfluxDB OSS v2.10 and later.* The `/health` and `/ready` endpoints report check messages that can include file system paths, permission errors, and other configuration details. With hardening enabled, InfluxDB returns these details only to callers with operator permissions. Other callers receive check names and statuses only. The HTTP status code doesn’t change, so liveness and readiness probes without credentials keep working. To control this behavior separately from other hardening features, use the [`health-auth-mode` configuration option](/influxdb/v2/reference/config-options/#health-auth-mode). For example, if your monitoring reads check messages from `/health`, keep full responses with hardening enabled: ```sh influxd --hardening-enabled --health-auth-mode=disabled ``` [security](/influxdb/v2/tags/security/)[hardening](/influxdb/v2/tags/hardening/) --- # Enable TLS encryption Source: https://docs.influxdata.com/influxdb/v2/admin/security/enable-tls/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Enabling TLS encrypts the communication between clients and the InfluxDB server. When configured with a signed certificate, TLS also allows clients to verify the authenticity of the InfluxDB server. Follow steps to set up TLS over HTTPS, connect to your server, and troubleshoot problems: * [Obtain requirements](#obtain-requirements) * [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls) * [Connect Telegraf to a secured InfluxDB instance](#connect-telegraf-to-a-secured-influxdb-instance) * [Troubleshoot TLS](#troubleshoot-tls) InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network. ## Obtain requirements To enable HTTPS with InfluxDB, you need a Transport Layer Security (TLS) certificate, also known as a Secured Sockets Layer (SSL) certificate. InfluxDB supports three types of TLS certificates: ### Single domain certificates signed by a Certificate Authority (CA) Single domain certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. These certificates are signed and issued by a trusted, third-party [Certificate Authority (CA)](https://en.wikipedia.org/wiki/Certificate_authority). With this certificate option, every InfluxDB instance requires a unique single domain certificate. ### Wildcard certificates signed by a Certificate Authority Wildcard certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. Wildcard certificates can be used across multiple InfluxDB instances on different servers. ### Self-signed certificates Self-signed certificates are *not* signed by a trusted, third-party CA. Unlike CA-signed certificates, self-signed certificates only provide cryptographic security to HTTPS requests. They do not allow clients to verify the identity of the InfluxDB server. With this certificate option, every InfluxDB instance requires a unique self-signed certificate. You can generate a self-signed certificate on your own machine. ## Configure InfluxDB to use TLS 1. [Download or generate certificate files](#download-or-generate-certificate-files) 2. [Set certificate file permissions](#set-certificate-file-permissions) 3. [Run `influxd` with TLS flags](#run-influxd-with-tls-flags) 4. [Verify TLS connection](#verify-tls-connection) ### Download or generate certificate files Choose one of the following: * [Download and install CA certificate files](#download-and-install-ca-certificate-files) * [Generate self-signed certificates](#generate-self-signed-certificates) #### Download and install CA certificate files If using a [certificate signed by a CA](#single-domain-certificates-signed-by-a-certificate-authority-ca), follow their instructions to download and install the certificate files. Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions). > [!Note] > #### Where are my certificates? > > The location of your certificate files depends on your system, domain, and certificate authority. > > For example, if [Let’s Encrypt](https://letsencrypt.org/) is your CA and you use [certbot](https://certbot.eff.org/) to install certificates, the default location is`/etc/letsencrypt/live/$domain`. For more information about Let’s Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates) #### Generate self-signed certificates To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system. The following example: 1. Configures [Subject Alternative Name](https://docs.openssl.org/master/man5/x509v3_config/#subject-alternative-name) (`subjectAltName`, SAN) for your TLS certificate. 2. Generates certificates located in `/etc/ssl` for Unix-like and Windows systems. *For example purposes only, the code creates an unencrypted private key.* #### Encrypt private keys Use encrypted keys to enhance security. If you must use an unencrypted key, ensure it’s stored securely and has appropriate file permissions. ``` # Create a temporary configuration file that defines properties for # the Subject Alternative Name (SAN) extension cat > san.cnf < [!Note] > You may opt to set up multiple users, groups, and permissions. > Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate. In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files. The following example shows how to transfer the ownership to the user and group `influxdb` and set read permissions on the self-signed certificate and key files generated in [the preceding step](#download-or-generate-certificate-files): ```bash sudo chown influxdb: /etc/ssl/influxdb-selfsigned.crt /etc/ssl/influxdb-selfsigned.key sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt sudo chmod 600 /etc/ssl/influxdb-selfsigned.key ``` ### Verify certificate and key files To ensure that the certificate and key files are correct and match each other, enter the following commands in your terminal: ```bash openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5 openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5 ``` ### Run `influxd` with TLS flags To start InfluxDB with TLS command line flags, enter the following command with paths to your key and certificate files: ```bash influxd \ --tls-cert="/etc/ssl/influxdb-selfsigned.crt" \ --tls-key="/etc/ssl/influxdb-selfsigned.key" > /var/log/influxdb.log 2>&1 & ``` If successful, InfluxDB runs in the background and logs to `influxdb.log`. ### Verify TLS connection To test your certificates, access InfluxDB using the `https://` protocol–for example, using cURL: ```bash curl --verbose https://localhost:8086/api/v2/ping ``` If using a self-signed certificate, skip certificate verification–for example, in a cURL command, pass the `-k, --insecure` flag: ```bash curl --verbose --insecure https://localhost:8086/api/v2/ping ``` If successful, the `curl --verbose` output shows a TLS handshake–for example: ```bash * [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake ``` You can further configure TLS settings using[`tls-min-version`](/influxdb/v2/reference/config-options/#tls-min-version)and[`tls-strict-ciphers`](/influxdb/v2/reference/config-options/#tls-strict-ciphers). ## Connect Telegraf to a secured InfluxDB instance To connect [Telegraf](/telegraf/v1/) to an InfluxDB 2.10 instance with TLS enabled, update the following `influxdb_v2` output settings in your Telegraf configuration file: * Update URLs to use HTTPS instead of HTTP. * If using a self-signed certificate, uncomment and set `insecure_skip_verify` to `true`. ### Example Telegraf configuration ``` ############################################################################### # OUTPUT PLUGINS ############################################################################### # Configuration for sending metrics to InfluxDB [[outputs.influxdb_v2]] ## The URLs of the InfluxDB cluster nodes. ## ## Multiple URLs can be specified for a single cluster, only ONE of the ## urls will be written to each interval. urls = ["https://127.0.0.1:8086"] [...] ## Optional TLS Config for use on HTTP connections. [...] ## Use TLS but skip chain & host verification insecure_skip_verify = true ``` Restart Telegraf using the updated configuration file. ## Troubleshoot TLS Identify and resolve issues after activating TLS. * [Check InfluxDB logs](#check-influxdb-logs) * [Verify certificate and key files](#verify-certificate-and-key-files) * [Test with OpenSSL](#test-with-openssl) * [Check file permissions](#check-file-permissions) * [Verify TLS configuration](#verify-tls-configuration) * [Update OpenSSL and InfluxDB](#update-openssl-and-influxdb) ### Check InfluxDB logs Review the InfluxDB logs for any error messages or warnings about the issue. #### Example TLS error ```text msg="http: TLS handshake error from [::1]:50476: remote error: tls: illegal parameter" log_id=0rqN8H_0000 service=http ``` ### Verify certificate and key Files To ensure that the certificate and key files are correct and match each other, enter the following command in your terminal: ```bash openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5 openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5 ``` ### Test with OpenSSL Use OpenSSL to test the server’s certificate and key–for example, enter the following command in your terminal: ```bash openssl s_client -connect localhost:8086 -CAfile /etc/ssl/influxdb-selfsigned.crt ``` ### Check file permissions Ensure that the InfluxDB process has read access to the certificate and key files–for example, enter the following command to set file permissions: ```bash sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt sudo chmod 600 /etc/ssl/influxdb-selfsigned.key ``` ### Verify TLS configuration Ensure that the TLS configuration in InfluxDB is correct. Check the paths to the certificate and key files in the InfluxDB configuration or command line flags. #### Example error: cannot validate certificate for \ ```log Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055617Z lvl=error msg="Unable to gather" log_id=0rr6jG30000 service=scraper scraper-name="new target" error="Get \"https://10.1.2.3:8086/metrics\": tls: failed to verify certificate: x509: cannot validate certificate for 10.1.2.3 because it doesn't contain any IP SANs" Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055397Z lvl=info msg="http: TLS handshake error from 10.1.2.3:46380: remote error: tls: bad certificate" log_id=0rr6jG30000 service=http ``` If you access your InfluxDB server via IP address, then include the address in your subjectAltName configuration. ### Update OpenSSL and InfluxDB Ensure that you are using the latest versions of OpenSSL and InfluxDB, as updates may include fixes for TLS-related issues. [security](/influxdb/v2/tags/security/)[authentication](/influxdb/v2/tags/authentication/)[tls](/influxdb/v2/tags/tls/)[https](/influxdb/v2/tags/https/)[ssl](/influxdb/v2/tags/ssl/) --- # Manage API tokens Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB **API tokens** ensure secure interaction between InfluxDB and external tools such as clients or applications. An API token belongs to a specific user and identifies InfluxDB permissions within the user’s organization. Learn how to create, view, update, or delete an API token. ## API token types * [Operator API token](#operator-token) * [All Access API token](#all-access-token) * [Read/Write token](#readwrite-token) ### Operator token Grants full read and write access to **all organizations and all organization resources in InfluxDB OSS 2.x**. Some operations–for example, [retrieving the server configuration](/influxdb/v2/reference/config-options/)–require *operator* permissions. #### Initial operator token When you first initialize InfluxDB, the [setup](/influxdb/v2/get-started/setup/) process creates an initial user, org, bucket, and an Operator token with full read/write access to all organizations. When running setup, you can either: * Supply the token value yourself ([`influx setup --token` flag](/influxdb/v2/reference/cli/influx/setup/) or the [setup API](/influxdb/v2/api/v2/#tag/Setup) `token` field), or * Let InfluxDB auto-generate it. InfluxDB stores the generated token in the active influx CLI config so the CLI can use it later. #### Creating operator tokens after setup To [create an operator token manually](/influxdb/v2/admin/tokens/create-token/) with the InfluxDB UI, `api/v2` API, or `influx` CLI after the setup process is completed, you must use an existing [Operator token](/influxdb/v2/admin/tokens/#operator-token). To create a new Operator token without using an existing one, see how to use the [`influxd recovery auth`](/influxdb/v2/reference/cli/influxd/recovery/auth/) CLI. > [!Tip] > Because Operator tokens have full read and write access to all organizations in the database, > we recommend [creating an All Access token](/influxdb/v2/admin/tokens/create-token/)for each organization and using those to manage InfluxDB. > This helps to prevent accidental interactions across organizations. ### All Access token Grants full read and write access to all resources in an organization. ### Read/Write token Grants read access, write access, or both to specific buckets in an organization. ## Token hashing InfluxDB can store API tokens as hashes on disk. Hashed storage protects tokens at rest: a copy of the underlying database file doesn’t expose usable tokens. |InfluxDB version| Token hashing default | |----------------|----------------------------------| |2.9.0 and later | **Enabled** by default | | 2.8.0–2.8.x |Available, **disabled** by default| |2.7 and earlier | Not supported | ### How token hashing works When `influxd` starts with token hashing enabled: 1. Existing unhashed tokens are migrated to hashed form. 2. After migration, the original token strings cannot be retrieved. 3. New tokens created while hashing is enabled are stored as hashes. Hashed tokens continue to authenticate exactly like unhashed tokens — clients and integrations that already store their token in plaintext continue to work. If you disable token hashing later, tokens that have already been hashed on disk remain hashed. New tokens created while hashing is disabled are stored unhashed. ### Before upgrading to 2.9.0 > [!Important] > #### Capture plaintext tokens before you upgrade > > Once `influxd` 2.9.0 starts with the default settings, all existing > tokens are hashed and the original strings cannot be recovered. > Capture any tokens you still need in plaintext **before** the first > 2.9.0 startup — including the operator token, which is required when[restoring a backup](/influxdb/v2/admin/backup-restore/restore/) with`influx restore --full`. ### Backup and restore A backup taken from an instance with token hashing enabled does not contain a plaintext operator token. To restore that backup with`influx restore --full`, supply the operator token via the`--operator-token ` flag (`influx-cli` v2.8.0+). Without that flag, the CLI cannot authenticate post-restore requests. ### Disable token hashing To opt out of the default — for example, to preserve compatibility with a possible downgrade to InfluxDB 2.7 or earlier — start `influxd` with the[`use-hashed-tokens`](/influxdb/v2/reference/config-options/#use-hashed-tokens)option set to `false`: ```sh influxd --use-hashed-tokens=false ``` Or set the environment variable or configuration file equivalent: ```sh export INFLUXD_USE_HASHED_TOKENS=false ``` ```yml use-hashed-tokens: false ``` ### Downgrade considerations Downgrading to InfluxDB 2.7 or earlier after token hashing has run on a database **erases all stored tokens** as part of the schema downgrade. If you may need to downgrade, start `influxd` 2.9.0 with`--use-hashed-tokens=false` so that token hashing never runs on the database. If token hashing is *never* enabled, downgrading from 2.9.0 to 2.8.x or 2.7.x is supported. Downgrading directly to a version earlier than 2.7 is not recommended. ### Replace a lost token Because hashing prevents recovery of the original token string, replace lost tokens by [creating a new token](/influxdb/v2/admin/tokens/create-token/). To replace a lost *operator* token without an existing one, use[`influxd recovery auth`](/influxdb/v2/reference/cli/influxd/recovery/auth/). ## [Create a token](/influxdb/v2/admin/tokens/create-token/) Create an API token in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. ## [View tokens](/influxdb/v2/admin/tokens/view-tokens/) View API tokens in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. ## [Update a token](/influxdb/v2/admin/tokens/update-tokens/) Update API tokens’ descriptions in InfluxDB using the InfluxDB UI. ## [Delete a token](/influxdb/v2/admin/tokens/delete-token/) Delete an API token from InfluxDB using the InfluxDB UI or the `influx` CLI. ## [Use tokens](/influxdb/v2/admin/tokens/use-tokens/) Use an API token in the InfluxDB UI, the `influx` CLI, or the InfluxDB API. [tokens](/influxdb/v2/tags/tokens/)[authentication](/influxdb/v2/tags/authentication/)[security](/influxdb/v2/tags/security/) | InfluxDB version | Token hashing default | | --- | --- | | InfluxDB version | Token hashing default | | 2.9.0 and later | Enabled by default | | 2.8.0–2.8.x | Available, disabled by default | | 2.7 and earlier | Not supported | --- # Create a token Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/create-token/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create API tokens using the InfluxDB user interface (UI), the `influx`command line interface (CLI), or the InfluxDB API. > [!Note] > To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. > > * Tokens are visible to the user who created the token. > * InfluxDB only allows access to the API token value immediately after the token is created. > * You can’t change access (**read/write**) permissions for an API token after it’s created. > * Tokens stop working when the user who created the token is deleted. > > **We recommend the following for managing your tokens:** > > * Create a generic user to create and manage tokens for writing data. > * Store your tokens in a secure password vault for future access. * [Manage tokens in the InfluxDB UI](#manage-tokens-in-the-influxdb-ui) * [Create a token in the InfluxDB UI](#create-a-token-in-the-influxdb-ui) * [Create a token using the influx CLI](#create-a-token-using-the-influx-cli) * [Create a token using the InfluxDB API](#create-a-token-using-the-influxdb-api) ## Manage tokens in the InfluxDB UI To manage InfluxDB API Tokens in the InfluxDB UI, navigate to the **API Tokens** management page. In the navigation menu on the left, select **Data (Load Data)** \> **API Tokens**. Load Data ## Create a token in the InfluxDB UI 1. From the [API Tokens management page](#manage-tokens-in-the-influxdb-ui), click **Generate** and select a token type (**Read/Write Token** or **All Access API Token**). 2. In the window that appears, enter a description for your token in the **Description** field. 3. If generating a **read/write token**: * Search for and select buckets to read from in the **Read** pane. * Search for and select buckets to write to in the **Write** pane. 4. Click **Save**. ## Create a token using the influx CLI Use the [`influx auth create` command](/influxdb/v2/reference/cli/influx/auth/create) to create a token. Include flags with the command to grant specific permissions to the token. See the [available flags](/influxdb/v2/reference/cli/influx/auth/create#flags). Only tokens with the `write: authorizations` permission can create tokens. ```sh # Syntax influx auth create -o [permission-flags] ``` ### Examples #### Create an All Access token Create an All Access token to grant permissions to all resources in an organization. ```sh influx auth create \ --org my-org \ --all-access ``` #### Create an operator token Create an operator token to grant permissions to all resources in all organizations. ```sh influx auth create \ --org my-org \ --operator ``` > [!Note] > To [view or create an operator token](/influxdb/v2/admin/tokens/create-token/) with the InfluxDB UI, `api/v2` API, or `influx` CLI after the setup process is completed, you must use an existing operator token. > > To create a new operator token without using an existing one, see how to use the [`influxd recovery auth`](/influxdb/v2/reference/cli/influxd/recovery/auth/) CLI. #### Create a token with specified permissions ##### Create a token with specified read permissions ```sh influx auth create \ --org my-org \ --read-bucket 03a2bbf46309a000 \ --read-bucket 3a87c03ace269000 \ --read-dashboards \ --read-tasks \ --read-telegrafs \ --read-user ``` ##### Create a token scoped to a user and with specified read and write permissions ```sh influx auth create \ --org ORG_NAME \ --user USERNAME \ --read-authorizations \ --write-authorizations \ --read-buckets \ --write-buckets \ --read-dashboards \ --write-dashboards \ --read-tasks \ --write-tasks \ --read-telegrafs \ --write-telegrafs \ --read-users \ --write-users ``` See the [`influx auth create` documentation](/influxdb/v2/reference/cli/influx/auth/create) for information about other available flags. ## Create a token using the InfluxDB API Use the `/api/v2/authorizations` InfluxDB API endpoint to create a token. ``` POST http://localhost:8086/api/v2/authorizations ``` Include the following in your request: | Requirement | Include by | |----------------------------------------------------------------------------------------------------|--------------------------------------------------| |API token with the [`write: authorizations`](/influxdb/v2/api/authorizations-api-tokens/) permission|Use the `Authorization` header and the `Bearer` or| | `Token` scheme. | | | Organization | Pass as `orgID` in the request body. | | Permissions list |Pass as a `permissions` array in the request body.| ``` INFLUX_ORG_ID=YOUR_ORG_ID INFLUX_TOKEN=YOUR_API_TOKEN curl -v --request POST \ http://localhost:8086/api/v2/authorizations \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' \ --data '{ "status": "active", "description": "iot-center-device", "orgID": "'"${INFLUX_ORG_ID}"'", "permissions": [ { "action": "read", "resource": { "orgID": "'"${INFLUX_ORG_ID}"'", "type": "authorizations" } }, { "action": "read", "resource": { "orgID": "'"${INFLUX_ORG_ID}"'", "type": "buckets" } }, { "action": "write", "resource": { "orgID": "'"${INFLUX_ORG_ID}"'", "type": "buckets", "name": "iot-center" } } ] }' ``` ### Create a token scoped to a user To scope a token to a user other than the token creator, pass the `userID` property in the request body. ``` ###################################################### # The example below uses common command-line tools # `curl`, `jq` with the InfluxDB API to do the following: # 1. Create a user. # 2. Find the new or existing user by name. # 3. If the user exists: # a. Build an authorization object with the user ID. # b. Create the new authorization. # c. Return the new token. ###################################################### INFLUX_ORG_ID=YOUR_ORG_ID INFLUX_TOKEN=YOUR_API_TOKEN function create_token_with_user() { curl --request POST \ "http://localhost:8086/api/v2/users/" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' \ --data "{\"name\": \"$1\"}" curl --request GET \ "http://localhost:8086/api/v2/users?name=$1" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' | \ jq --arg USER $1 '.users[0] // error("User missing") | { "orgID": "'"${INFLUX_ORG_ID}"'", "userID": .id, "description": $USER, "permissions": [ {"action": "read", "resource": {"type": "buckets"}} ] }' | \ curl --request POST \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' \ --data @- | \ jq '.token' } create_token_with_user 'iot_user_1' ``` See the[`POST /api/v2/authorizations` documentation](/influxdb/v2/api/authorizations-api-tokens/)for more information about options. | Requirement | Include by | | --- | --- | | Requirement | Include by | | API token with the write: authorizations permission | Use the Authorization header and the Bearer or | | Token scheme. | | | Organization | Pass as orgID in the request body. | | Permissions list | Pass as a permissions array in the request body. | --- # Delete a token Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/delete-token/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Delete API tokens from the InfluxDB user interface (UI) or the `influx` command line interface (CLI). Once deleted, all users and external integrations using the API token will no longer have access to your InfluxDB instance. * [Delete tokens in the InfluxDB UI](#delete-tokens-in-the-influxdb-ui) * [Delete a token using the influx CLI](#delete-a-token-using-the-influx-cli) * [Delete a token using the InfluxDB API](#delete-a-token-using-the-influxdb-api) ## Delete tokens in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **API Tokens**. Load Data 1. Hover over the token you want to delete. 2. Click the icon located far right of the token description. 3. Click **Delete** to delete the token. ## Delete a token using the influx CLI Use the [`influx auth delete` command](/influxdb/v2/reference/cli/influx/auth/delete)to delete a token. *This command requires an auth ID, which is available in the output of `influx auth find`.* ```sh # Syntax influx auth delete -i # Example influx auth delete -i 03a2bee5a9c9a000 ``` ## Delete a token using the InfluxDB API Use the `/api/v2/authorizations` InfluxDB API endpoint to delete a token. ``` DELETE http://localhost:8086/api/v2/authorizations/AUTH_ID ``` Include the following in your request: | Requirement | Include by | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------| |API token with the [`write: authorizations`](/influxdb/v2/api/authorizations-api-tokens/) permission|Use the `Authorization: Token YOUR_API_TOKEN` header.| | Authorization ID | URL path parameter. | ```sh # Delete the first authorization listed for the user. curl --request GET \ "http://localhost:8086/api/v2/authorizations?user=user2" \ --header "Authorization: Token ${INFLUX_OP_TOKEN}" \ --header 'Content-type: application/json' \ | jq .authorizations[0].id \ | xargs -I authid curl --request DELETE \ http://localhost:8086/api/v2/authorizations/authid \ --header "Authorization: Token ${INFLUX_OP_TOKEN}" \ --header 'Content-type: application/json' ``` | Requirement | Include by | | --- | --- | | Requirement | Include by | | API token with the write: authorizations permission | Use the Authorization: Token YOUR_API_TOKEN header. | | Authorization ID | URL path parameter. | --- # Update a token Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/update-tokens/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update an API token’s description and status. using the InfluxDB user interface (UI). * [Update a token in the InfluxDB UI](#update-a-token-in-the-influxdb-ui) * [Enable or disable a token in the InfluxDB UI](#enable-or-disable-a-token-in-the-influxdb-ui) * [Enable a token using the influx CLI](#enable-a-token-using-the-influx-cli) * [Disable a token using the influx CLI](#disable-a-token-using-the-influx-cli) * [Update a token using the InfluxDB API](#update-a-token-using-the-influxdb-api) ## Update a token in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **API Tokens**. Load Data 1. Click the pencil icon next to the token’s name in the **Description** column. 2. Update the token description, then click anywhere else to save. ## Enable or disable a token in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **API Tokens**. Load Data 1. Click the **Status** toggle. ## Enable a token using the influx CLI Use the [`influx auth active` command](/influxdb/v2/reference/cli/influx/auth/active)to activate a token. *This command requires an authorization ID, which is available in the output of `influx auth find`.* ```sh # Syntax influx auth active -i # Example influx auth active -i 0804f74142bbf000 ``` To get the current status of a token, use the JSON output of the [`influx auth list` command](/influxdb/v2/reference/cli/influx/auth/list). ```sh influx auth find --json ``` ### Disable a token using the influx CLI Use the [`influx auth inactive` command](/influxdb/v2/reference/cli/influx/auth/active)to deactivate a token. *This command requires an authorization ID, which is available in the output of `influx auth find`.* ```sh # Syntax influx auth inactive -i # Example influx auth inactive -i 0804f74142bbf000 ``` To get the current status of a token, use the JSON output of the [`influx auth list` command](/influxdb/v2/reference/cli/influx/auth/list). ```sh influx auth find --json ``` ## Update a token using the InfluxDB API Use the `/api/v2/authorizations` InfluxDB API endpoint to update the description and status of a token. ``` PATCH http://localhost:8086/api/v2/authorizations/AUTH_ID ``` Include the following in your request: | Requirement | Include by | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------| |API token with the [`write: authorizations`](/influxdb/v2/api/authorizations-api-tokens/) permission|Use the `Authorization: Token YOUR_API_TOKEN` header.| | Authorization ID | URL path parameter. | | Description and/or Status |Pass as `description`, `status` in the request body. | ### Disable a token ```sh # Update the description and status of the first authorization listed for the user. curl --request GET \ "http://localhost:8086/api/v2/authorizations?user=user2" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' \ | jq .authorizations[0].id \ | xargs -I authid curl --request PATCH \ http://localhost:8086/api/v2/authorizations/authid \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' \ --data '{ "description": "deactivated_auth", "status": "inactive" }' | jq . ``` | Requirement | Include by | | --- | --- | | Requirement | Include by | | API token with the write: authorizations permission | Use the Authorization: Token YOUR_API_TOKEN header. | | Authorization ID | URL path parameter. | | Description and/or Status | Pass as description , status in the request body. | --- # Use tokens Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/use-tokens/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use tokens to authenticate requests to InfluxDB, including requests to write, query, and manage data and resources. Authenticate requests using the [`influx` CLI](/influxdb/v2/reference/cli/influx/), API requests made with client libraries, and tools like `curl`. ### Add a token to a CLI request ```sh influx write -t -b BUCKET -o org-name ``` ``` export INFLUX_TOKEN=my-token influx write -t $INFLUX_TOKEN -b my-bucket -o my-org "measurement field=1" ``` > [!Note] > See [here](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#configure-your-token-as-an-environment-variable)to configure environment variables on Windows. > (Click on the **Windows** tab.) ### Use CLI configurations Automatically manage and use tokens from the CLI using [`influx config`](/influxdb/v2/reference/cli/influx/config/). ### Use a token in an API request Use tokens in [API requests](/influxdb/v2/api-guide/api_intro/#authentication). ### Use a token in Postman Make authenticated requests with tokens [using Postman](/influxdb/v2/tools/postman/). --- # View tokens Source: https://docs.influxdata.com/influxdb/v2/admin/tokens/view-tokens/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View API tokens and permissions using the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB API. > [!Note] > Tokens are visible to the user who created the token. Users who own a token with operator permissions also have access to all tokens. Tokens stop working when the user who created the token is deleted. > > In the InfluxDB UI, full tokens are only visible immediately after the token is created. > > **We recommend creating a generic user to create and manage tokens for writing data.** ## View tokens in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** \> **API Tokens**. Load Data 1. Click a token name in the list to view the token status and a summary of access permissions. ## View tokens using the influx CLI Use the [`influx auth list` command](/influxdb/v2/reference/cli/influx/auth/list)to view tokens. ```sh influx auth list ``` Filtering options such as filtering by authorization ID, username, or user ID are available. See the [`influx auth list` documentation](/influxdb/v2/reference/cli/influx/auth/list)for information about other available flags. ## View tokens using the InfluxDB API Use the `/api/v2/authorizations` InfluxDB API endpoint to view tokens and permissions. ``` GET /api/v2/authorizations ``` Include the following in your request: | Requirement | Include by | |---------------------------------------------------------------------------------------------------|-----------------------------------------------------| |API token with the [`read: authorizations`](/influxdb/v2/api/authorizations-api-tokens/) permission|Use the `Authorization: Token YOUR_API_TOKEN` header.| ```sh INFLUX_TOKEN=YOUR_API_TOKEN curl --request GET \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' ``` ### View a single token To view a specific authorization and token, include the authorization ID in the URL path. ``` GET /api/v2/authorizations/{authID} ``` ### Filter the token list InfluxDB returns authorizations from the same organization as the token used in the request. To filter tokens by user, include `userID` as a query parameter in your request. ``` # The example below uses the common `curl` and `jq` command-line tools # with the InfluxDB API to do the following: # 1. Find a user by username and extract the user ID. # 2. Find the user's authorizations by user ID. # 3. Filter for `active` authorizations that have `write` permission. INFLUX_TOKEN=YOUR_API_TOKEN function list_write_auths() { curl "http://localhost:8086/api/v2/users/?name=$1" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' | \ jq --arg USER $1 '.users[] | select(.name == $USER) | .id' | \ xargs -I '%' \ curl "http://localhost:8086/api/v2/authorizations/?userID=%" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Content-type: application/json' | \ jq '.authorizations[] | select(.permissions[] | select(.action=="write")) | select(.status=="active")' } list_write_auths 'iot_user_1' ``` [***Operator tokens***](/influxdb/v2/admin/tokens/#operator-token) have access to all organizations’ authorizations. To filter authorizations by organization when using an operator token, include an `org` or `orgID` query parameter in your request. See the [`/authorizations` endpoint documentation](/influxdb/v2/api/authorizations-api-tokens/) for more information about available parameters. | Requirement | Include by | | --- | --- | | Requirement | Include by | | API token with the read: authorizations permission | Use the Authorization: Token YOUR_API_TOKEN header. | --- # Manage users Source: https://docs.influxdata.com/influxdb/v2/admin/users/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Users are those with access to InfluxDB. To grant a user permission to access data, add them as a[member of an organization](/influxdb/v2/admin/organizations/members/)and provide them with an [API token](/influxdb/v2/admin/tokens/). The following articles walk through managing users. > [!Note] > #### InfluxDB 2.x/1.x compatibility > > If you [upgraded from 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/), > use the [`influx v1 auth`](/influxdb/v2/reference/cli/influx/v1/auth/) commands > to manage authorizations for the InfluxDB [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ### [Create a user](/influxdb/v2/admin/users/create-user/) Create a user in InfluxDB using the InfluxDB UI or the influx CLI. ### [View users](/influxdb/v2/admin/users/view-users/) Review a list of users in InfluxDB using the InfluxDB UI or the influx CLI. ### [Delete a user](/influxdb/v2/admin/users/delete-user/) Delete a user from InfluxDB using the InfluxDB UI or the influx CLI. ### [Update a user](/influxdb/v2/admin/users/update-user/) Update a user in InfluxDB using the InfluxDB UI or the influx CLI. ### [Change your password](/influxdb/v2/admin/users/change-password/) Change your password in InfluxDB using the influx CLI. ### [Recover user credentials](/influxdb/v2/admin/users/recover-credentials/) Recover InfluxDB user credentials using the influx CLI. [users](/influxdb/v2/tags/users/)[authentication](/influxdb/v2/tags/authentication/) --- # Change your password Source: https://docs.influxdata.com/influxdb/v2/admin/users/change-password/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use `influx` command line interface (CLI) to update your password. > [!Note] > User passwords cannot be updated in the InfluxDB UI. ## Change your password using the influx CLI Use the [`influx user password` command](/influxdb/v2/reference/cli/influx/user/password)to update a password for a user. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The username (with the `--name, -n` flag) or the user ID (with the `--id, -i` flag). View usernames and IDs in the output of `influx user list`. * *Optional*: the `--password, -p` flag and the new password. If you don’t provide a password flag, enter the new password when prompted. ##### Update a password ```sh influx user password \ --name USERNAME \ --password PASSWORD ``` Replace the following: * `USERNAME`: The username to change the password for * `PASSWORD`: The new password --- # Create a user Source: https://docs.influxdata.com/influxdb/v2/admin/users/create-user/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) to create a user. > [!Note] > Additional users cannot be created in the InfluxDB UI. To create a new user, you must have an [operator token](/influxdb/v2/reference/glossary/#token). For more information, see how to [create an operator token](/influxdb/v2/admin/tokens/create-token/#create-an-operator-token). Use the [`influx user create` command](/influxdb/v2/reference/cli/influx/user/create)and provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The [organization name or ID](/influxdb/v2/admin/organizations/view-orgs/) to add the new user to. * A username for the new user with the `--name, -n` flag. * *Optional*: the `--password, -p` flag and a password for the user. If you don’t provide a password, the new user will be prompted to provide one. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ```sh influx user create \ --org ORG_NAME \ --name USER_NAME \ --password USER_PASSWORD ``` Replace the following: * `ORG_NAME`: The name of the organization to add the new user to * `USER_NAME`: The username of the new user * `USER_PASSWORD`: The password for the new user --- # Delete a user Source: https://docs.influxdata.com/influxdb/v2/admin/users/delete-user/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to delete a user. Deleting a user removes them completely from InfluxDB. To remove a user from an organization without deleting the user entirely, see[Remove a member from an organization](/influxdb/v2/admin/organizations/members/remove-member/). ## Delete a user from the InfluxDB UI > [!Note] > Users cannot be deleted from the InfluxDB UI. ## Delete a user using the influx CLI Use the [`influx user delete` command](/influxdb/v2/reference/cli/influx/user/delete)to delete a user. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The user ID *(provided in the output of `influx user list`)* ```sh influx user delete --id USER_ID ``` Replace `USER_ID` with the ID of the user to delete. --- # Recover user credentials Source: https://docs.influxdata.com/influxdb/v2/admin/users/recover-credentials/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influxd` command line interface (CLI) to recover user credentials and regain access to your InfluxDB instance: * [Update a password](#update-a-password) * [List existing users in the InfluxDB instance](#list-existing-users-in-the-influxdb-instance) * [Create a user for recovery purposes](#create-a-user-for-recovery-purposes) ## Update a password To update a password, run the following: ```sh influxd recovery user update \ --username example-username \ --password ExAmPL3-paS5W0rD ``` > [!Note] > **Note:** If you’re not sure of the username, [list existing users in the InfluxDB instance](#list-existing-users-in-the-influxdb-instance) or [create a user for recovery purposes](#create-a-user-for-recovery-purposes). ## List existing users in the InfluxDB instance To list existing users in the system, run the following: ```sh influxd recovery user list ``` > [!Note] > If you used a [custom `bolt-path`](/influxdb/v2/reference/config-options/#bolt-path) when starting InfluxDB, provide your custom bolt path to the `influx recovery user list` command with the `--bolt-path` flag. ## Create a user for recovery purposes To create a new user for recovery purposes, run the following: ```sh influxd recovery user create \ --username example-username \ --password ExAmPL3-paS5W0rD ``` #### Related * [influxd recovery](/influxdb/v2/reference/cli/influxd/recovery/) --- # Update a user Source: https://docs.influxdata.com/influxdb/v2/admin/users/update-user/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to update a user. ## Update a user in the InfluxDB UI > [!Note] > User information cannot be updated in the InfluxDB UI. ## Update a user using the influx CLI Use the [`influx user update` command](/influxdb/v2/reference/cli/influx/user/update)to update a user. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. * The user ID *(provided in the output of `influx user list`)* using the `--id, -i` flag. * The new username for the user using the `--name, -n` flag. ##### Update the name of a user ```sh influx user update \ --id USER_ID \ --name NEW_USERNAME ``` Replace the following: * `USER_ID`: The ID of the user to update * `NEW_USERNAME`: The new username for the user --- # View users Source: https://docs.influxdata.com/influxdb/v2/admin/users/view-users/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) to view users. ## View users using the influx CLI Use the [`influx user list` command](/influxdb/v2/reference/cli/influx/user/list)to view users. Provide the following: * An [operator token](/influxdb/v2/admin/tokens/#operator-token) using your[`influx` CLI connection configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials),`INFLUX_TOKEN` environment variable, or the `--token, -t` flag. ```sh influx user list ``` Filtering options such as filtering by username or ID are available. See the [`influx user list` documentation](/influxdb/v2/reference/cli/influx/user/list)for information about other available flags. --- # Develop with the InfluxDB API Source: https://docs.influxdata.com/influxdb/v2/api-guide/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. ## Developer guides * [API Quick Start](/influxdb/v2/api-guide/api_intro/) ## InfluxDB client libraries InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. For tutorials and information about client libraries, see [InfluxDB client libraries](/influxdb/v2/api-guide/client-libraries/). ## InfluxDB v2 API documentation [InfluxDB OSS 2.10 API documentation](/influxdb/v2/api/) ### View InfluxDB API documentation locally InfluxDB API documentation is built into the `influxd` service and represents the API specific to the current version of InfluxDB. To view the API documentation locally, [start InfluxDB](/influxdb/v2/get-started/#start-influxdb)and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localhost:8086/docs)). ## InfluxDB v1 compatibility API documentation The InfluxDB v2 API includes [InfluxDB v1 compatibility endpoints and authentication](/influxdb/v2/api-guide/influxdb-1x/)that work with InfluxDB 1.x client libraries and third-party integrations like[Grafana](https://grafana.com) and others. [View full v1 compatibility API documentation](/influxdb/v2/api/v2/#tag/Compatibility-endpoints) [api](/influxdb/v2/tags/api/) --- # API Quick Start Source: https://docs.influxdata.com/influxdb/v2/api-guide/api_intro/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB offers a rich API and [client libraries](/influxdb/v2/api-guide/client-libraries) ready to integrate with your application. Use popular tools like Curl and [Postman](/influxdb/v2/api-guide/postman) for rapidly testing API requests. This section guides you through the most commonly used API methods. For detailed documentation on the entire API, see the [InfluxDB v2 API Reference](/influxdb/v2/api/). > [!Tip] > #### Use InfluxDB 1.x API clients with 2.10 > > If you need to use InfluxDB 2.10 with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility guide](/influxdb/v2/reference/api/influxdb-1x/). ## Bootstrap your application With most API requests, you’ll need to provide a minimum of your InfluxDB URL and [Authorization Token (API Token)](/influxdb/v2/admin/tokens/). [Install InfluxDB OSS v2.x](/influxdb/v2/install/) or upgrade to an [InfluxDB Cloud account](/influxdb/cloud/sign-up). ### Authentication InfluxDB uses [API tokens](/influxdb/v2/admin/tokens/) to authorize API requests. InfluxDB filters API requests and response data based on the permissions associated with the token. 1. Before exploring the API, use the `influx` CLI or the InfluxDB UI to[create an initial API token](/influxdb/v2/admin/tokens/create-token/) for your application. 2. Include your API token in an `Authorization: Token API_TOKEN` HTTP header with each request–for example: [curl](#curl)[Node.js](#nodejs) ```bash # Use a token to authorize a GET request to the InfluxDB API. # List buckets in your organization that the token can read. curl -X GET "http://localhost:8086/api/v2/buckets" \ --header 'Accept: application/json' \ --header 'Authorization: Token API_TOKEN' ``` ```js /** * Use a token to authorize a GET request to the InfluxDB API. * List buckets in your organization that the token can read. */ const https = require('https'); function listBuckets() { const options = { host: 'localhost:8086', path: "/api/v2/buckets", headers: { 'Authorization': 'Token API_TOKEN', 'Content-type': 'application/json' }, }; const request = https.get(options, (response) => { let rawData = ''; response.on('data', () => { response.on('data', (chunk) => { rawData += chunk; }); }) response.on('end', () => { console.log(rawData); }) }); request.end(); } ``` > [!Note] > Postman is another popular tool for exploring APIs. > See how to [send authenticated requests with Postman](/influxdb/v2/tools/postman/#send-authenticated-api-requests-with-postman). ## Buckets API Before writing data you’ll need to create a bucket in your InfluxDB instance. To use the API to create a bucket, send a request to the following endpoint: ``` POST /api/v2/buckets ``` ```bash curl --request POST \ "http://localhost:8086/api/v2/buckets" \ --header "Authorization: Token API_TOKEN" \ --json '{ "orgID": "'"ORG_ID"'", "name": "BUCKET_NAME", "retentionRules": [ { "type": "expire", "everySeconds": RETENTION_PERIOD_SECONDS, "shardGroupDurationSeconds": 0 } ] }' ``` Replace the following placeholders with your values: * `API_TOKEN` - your [token](/influxdb/v2/admin/tokens/). * `ORG_ID` - the ID of the [organization](/influxdb/v2/admin/organizations/) that owns the bucket. * `BUCKET_NAME` - the name of the [bucket](/influxdb/v2/admin/buckets/) to create. * Optional: `RETENTION_PERIOD_SECONDS` - the [retention period](/influxdb/v2/reference/glossary/#retention-period) (in number of seconds) to retain data in the bucket. Default is `0` (infinite retention). * For example, `31536000` (1 year) or `604800` (7 days). For more information, see [Create a bucket](/influxdb/v2/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api). ## Write API [Write data to InfluxDB](/influxdb/v2/write-data/developer-tools/api/) using an HTTP request to the InfluxDB API `/api/v2/write` endpoint. ## Query API [Query from InfluxDB](/influxdb/v2/query-data/execute-queries/influx-api/) using an HTTP request to the `/api/v2/query` endpoint. --- # Use InfluxDB client libraries Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. The following **InfluxDB v2** client libraries are available: * [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](/influxdb/v2/api-guide/client-libraries/go/) * [Java](https://github.com/influxdata/influxdb-client-java) * [JavaScript for browsers](/influxdb/v2/api-guide/client-libraries/browserjs/) * [Kotlin](https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin) * [Node.js](/influxdb/v2/api-guide/client-libraries/nodejs/) * [PHP](https://github.com/influxdata/influxdb-client-php) * [Python](/influxdb/v2/api-guide/client-libraries/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](/influxdb/v2/tags/client-libraries/) --- # Arduino client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/arduino/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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) --- # JavaScript client library for web browsers Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/browserjs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to interact with the InfluxDB v2 API in browsers and front-end clients. 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/). ### 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 InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2/reference/urls/). ## Use with module bundlers If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`. For more information and examples, see [Node.js](/influxdb/v2/api-guide/client-libraries/nodejs/). ## 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](#esm)[UMD](#umd) ``` ``` ``` ``` After you’ve imported the client library, you’re ready to [write data](/influxdb/v2/api-guide/client-libraries/nodejs/write/?t=nodejs) to InfluxDB. ## Get started with the example app This library includes an example browser app that queries from and writes to your InfluxDB instance. 1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo. 2. Navigate to the `examples` directory: ``` cd examples ``` 3. Update `./env_browser.js` with your InfluxDB [url](/influxdb/v2/reference/urls/), [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), and [token](/influxdb/v2/admin/tokens/) 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. #### Related * [/influxdb/v2/api-guide/client-libraries/nodejs/write/](/influxdb/v2/api-guide/client-libraries/nodejs/write/) * [/influxdb/v2/api-guide/client-libraries/nodejs/query/](/influxdb/v2/api-guide/client-libraries/nodejs/query/) [client libraries](/influxdb/v2/tags/client-libraries/)[JavaScript](/influxdb/v2/tags/javascript/) --- # C# client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/csharp/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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/influxdb/v2/api-guide/client-libraries/dart/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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) --- # Go client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/go/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications. This guide presumes some familiarity with Go and InfluxDB. If just getting started, see [Get started with InfluxDB](/influxdb/v2/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 InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2/reference/urls/). ## 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 [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), and [token](/influxdb/v2/admin/tokens/). ``` bucket := "example-bucket" org := "example-org" token := "example-token" // Store the URL of your InfluxDB instance url := "http://localhost:8086" ``` 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) ``` 5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`. ``` queryAPI := client.QueryAPI(org) ``` ## Write data to InfluxDB with Go Use the Go library to write data to InfluxDB. 1. Create a [point](/influxdb/v2/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 func main() { bucket := "example-bucket" org := "example-org" token := "example-token" // Store the URL of your InfluxDB instance url := "http://localhost:8086" // 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() } ``` ## Query data from InfluxDB with Go Use the Go library to query data stored in InfluxDB. 1. Create a Flux query and pass the `bucket` parameter with your bucket name. ``` from(bucket:"") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat") ``` The query client sends the Flux query to InfluxDB and returns the results as a FluxRecord object with a table structure. **The query client includes the following methods:** * `Query`: Sends the Flux query to InfluxDB. * `Next`: Iterates over the query response. * `TableChanged`: Identifies when the group key changes. * `Record`: Returns the last parsed FluxRecord and gives access to value and row properties. * `Value`: Returns the actual field value. ``` result, err := queryAPI.Query(context.Background(), `from(bucket:"") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`) if err == nil { for result.Next() { if result.TableChanged() { fmt.Printf("table: %s\n", result.TableMetadata().String()) } fmt.Printf("value: %v\n", result.Record().Value()) } if result.Err() != nil { fmt.Printf("query parsing error: %s\n", result.Err().Error()) } } else { panic(err) } ``` **The FluxRecord object includes the following methods for accessing your data:** * `Table()`: Returns the index of the table the record belongs to. * `Start()`: Returns the inclusive lower time bound of all records in the current table. * `Stop()`: Returns the exclusive upper time bound of all records in the current table. * `Time()`: Returns the time of the record. * `Value() `: Returns the actual field value. * `Field()`: Returns the field name. * `Measurement()`: Returns the measurement name of the record. * `Values()`: Returns a map of column values. * `ValueByKey()`: Returns a value from the record for given column key. ### Complete example query script ``` func main() { // Create client client := influxdb2.NewClient(url, token) // Get query client queryAPI := client.QueryAPI(org) // Get QueryTableResult result, err := queryAPI.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`) if err == nil { // Iterate over query response for result.Next() { // Notice when group key has changed if result.TableChanged() { fmt.Printf("table: %s\n", result.TableMetadata().String()) } // Access data fmt.Printf("value: %v\n", result.Record().Value()) } // Check for an error if result.Err() != nil { fmt.Printf("query parsing error: %s\n", result.Err().Error()) } } else { panic(err) } // Ensures background processes finishes client.Close() } ``` For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go). [client libraries](/influxdb/v2/tags/client-libraries/)[Go](/influxdb/v2/tags/go/) --- # Java client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/java/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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) --- # Kotlin client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/kotlin/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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) --- # Node.js JavaScript client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/nodejs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into your Node.js application. In this guide, you’ll start a Node.js project from scratch and code some simple API operations. ### [Install the InfluxDB JavaScript client library](/influxdb/v2/api-guide/client-libraries/nodejs/install/) Install the Node.js JavaScript client library to interact with the InfluxDB v2 API. ### [Write data with the InfluxDB JavaScript client library](/influxdb/v2/api-guide/client-libraries/nodejs/write/) Use the JavaScript client library to write data with the InfluxDB API in Node.js. ### [Query data with the InfluxDB JavaScript client library](/influxdb/v2/api-guide/client-libraries/nodejs/query/) Use the JavaScript client library to query data with the InfluxDB API in Node.js. For more examples and information, see the [JavaScript client on GitHub](https://github.com/influxdata/influxdb-client-js). [client libraries](/influxdb/v2/tags/client-libraries/)[JavaScript](/influxdb/v2/tags/javascript/) --- # Install the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/nodejs/install/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## 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 InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2/reference/urls/). 3. Create a directory for your new Node.js project, and then change to the directory–for example, enter the following command into your terminal: ``` 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 The JavaScript client library contains two packages: `@influxdata/influxdb-client` and `@influxdata/influxdb-client-apis`. Add both as dependencies of your project. 1. Open a new terminal window and install `@influxdata/influxdb-client` for querying and writing data: ``` npm install --save @influxdata/influxdb-client ``` 2. Install `@influxdata/influxdb-client-apis` for access to the InfluxDB management APIs: ``` npm install --save @influxdata/influxdb-client-apis ``` ## Next steps Once you’ve installed the JavaScript client library, you’re ready to [write data](/influxdb/v2/api-guide/client-libraries/nodejs/write/) to InfluxDB or [get started](#get-started-with-examples) with other examples from the client library. ## Get started with examples > [!Note] > The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.mjs) module for accessing your InfluxDB properties from environment variables or from `env.mjs`. > The examples use these properties to interact with the InfluxDB API. 1. Set environment variables or update `env.mjs` with your InfluxDB [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), [token](/influxdb/v2/admin/tokens/), and [URL](/influxdb/v2/reference/urls/). ``` export INFLUX_URL=http://localhost:8086 export INFLUX_TOKEN=YOUR_API_TOKEN export INFLUX_ORG=YOUR_ORG export INFLUX_BUCKET=YOUR_BUCKET ``` Replace the following: * *`YOUR_API_TOKEN`*: InfluxDB API token * *`YOUR_ORG`*: InfluxDB organization ID * *`YOUR_BUCKET`*: InfluxDB bucket name 2. Run one of the [`influxdb-client-js` example scripts](https://github.com/influxdata/influxdb-client-js/tree/master/examples/). ``` query.ts ``` For more examples and information, see the [JavaScript client on GitHub](https://github.com/influxdata/influxdb-client-js). [client libraries](/influxdb/v2/tags/client-libraries/)[JavaScript](/influxdb/v2/tags/javascript/) --- # Query data with the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/nodejs/query/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) in a Node.js environment to query InfluxDB. The following example sends a Flux query to an InfluxDB bucket and outputs rows from an observable table. ## Before you begin * [Install the client library and other dependencies](/influxdb/v2/api-guide/client-libraries/nodejs/install/). ## Query InfluxDB 1. Change to your new project directory and create a file for your query module. ``` cd influx-node-app && touch query.js ``` 2. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. Use the `getQueryApi()` method of the client. Provide your InfluxDB organization ID to create a configured **query client**. ``` import { InfluxDB, Point } from '@influxdata/influxdb-client' const queryApi = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}).getQueryApi(YOUR_ORG) ``` Replace the following: * *`YOUR_URL`*: InfluxDB URL * *`YOUR_API_TOKEN`*: InfluxDB API token * *`YOUR_ORG`*: InfluxDB organization ID 3. Create a Flux query for your InfluxDB bucket. Store the query as a string variable. To prevent SQL injection attacks, avoid concatenating unsafe user input with queries. ``` const fluxQuery = 'from(bucket: "YOUR_BUCKET") |> range(start: 0) |> filter(fn: (r) => r._measurement == "temperature")' ``` Replace *`YOUR_BUCKET`* with the name of your InfluxDB bucket. 4. Use the `queryRows()` method of the query client to query InfluxDB.`queryRows()` takes a Flux query and an [RxJS **Observer**](http://reactivex.io/rxjs/manual/overview.html#observer) object. The client returns [table](/influxdb/v2/reference/syntax/annotated-csv/#tables) metadata and rows as an [RxJS **Observable**](http://reactivex.io/rxjs/manual/overview.html#observable).`queryRows()` subscribes your observer to the observable. Finally, the observer logs the rows from the response to the terminal. ``` const observer = { next(row, tableMeta) { const o = tableMeta.toObject(row) console.log( `${o._time} ${o._measurement} in '${o.location}' (${o.sensor_id}): ${o._field}=${o._value}` ) } } queryApi.queryRows(fluxQuery, observer) ``` ### Complete example ``` 'use strict' /** @module query * Queries a data point in InfluxDB using the Javascript client library with Node.js. **/ import { InfluxDB, Point } from '@influxdata/influxdb-client' /** Environment variables **/ const url = process.env.INFLUX_URL || '' const token = process.env.INFLUX_TOKEN const org = process.env.INFLUX_ORG || '' /** * Instantiate the InfluxDB client * with a configuration object. * * Get a query client configured for your org. **/ const queryApi = new InfluxDB({url, token}).getQueryApi(org) /** To avoid SQL injection, use a string literal for the query. */ const fluxQuery = 'from(bucket:"air_sensor") |> range(start: 0) |> filter(fn: (r) => r._measurement == "temperature")' const myQuery = async () => { for await (const {values, tableMeta} of queryApi.iterateRows(fluxQuery)) { const o = tableMeta.toObject(values) console.log( `${o._time} ${o._measurement} in '${o.location}' (${o.sensor_id}): ${o._field}=${o._value}` ) } } /** Execute a query and receive line table metadata and rows. */ myQuery() ``` To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. ```sh export INFLUX_URL=http://localhost:8086 && \ export INFLUX_TOKEN=YOUR_API_TOKEN && \ export INFLUX_ORG=YOUR_ORG && \ node query.js ``` For more examples and information, see the [JavaScript client on GitHub](https://github.com/influxdata/influxdb-client-js). [client libraries](/influxdb/v2/tags/client-libraries/)[JavaScript](/influxdb/v2/tags/javascript/) --- # Write data with the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/nodejs/write/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [InfluxDB 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](/influxdb/v2/api-guide/client-libraries/nodejs/install/). ### Write data with the client library 1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. ``` import {InfluxDB, Point} from '@influxdata/influxdb-client' const influxDB = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}) ``` Replace the following: * *`YOUR_URL`*: InfluxDB URL * *`YOUR_API_TOKEN`*: InfluxDB API token 2. Use the `getWriteApi()` method of the client to create a **write client**. Provide your InfluxDB organization ID and bucket name. ``` const writeApi = influxDB.getWriteApi(YOUR_ORG, YOUR_BUCKET) ``` Replace the following: * *`YOUR_ORG`*: InfluxDB organization ID * *`YOUR_BUCKET`*: InfluxDB bucket name 3. To apply one or more [tags](/influxdb/v2/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](/influxdb/v2/reference/glossary/#point). 1. Call the constructor and provide a [measurement](/influxdb/v2/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) ``` 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 [Curl](#curl)[Node.js](#nodejs) ```sh curl --request POST \ "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=ns" \ --header "Authorization: Token YOUR_API_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary ' airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000 ' ``` ```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' /** Environment variables **/ const url = process.env.INFLUX_URL const token = process.env.INFLUX_TOKEN const org = process.env.INFLUX_ORG const bucket = process.env.INFLUX_BUCKET /** * Instantiate the InfluxDB client * with a configuration object. **/ const influxDB = new InfluxDB({ url, token }) /** * Create a write client from the getWriteApi method. * Provide your `org` and `bucket`. **/ const writeApi = influxDB.getWriteApi(org, bucket) /** * 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') }) ``` To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. ```sh export INFLUX_URL=http://localhost:8086 && \ export INFLUX_TOKEN=YOUR_API_TOKEN && \ export INFLUX_ORG=YOUR_ORG && \ export INFLUX_BUCKET=YOUR_BUCKET && \ node write.js ``` ### Response codes *For information about **InfluxDB API response codes**, see[InfluxDB API Write documentation](/influxdb/cloud/api/write-data/).* #### Related * [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/) [client libraries](/influxdb/v2/tags/client-libraries/)[JavaScript](/influxdb/v2/tags/javascript/) --- # PHP client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/php/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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/influxdb/v2/api-guide/client-libraries/python/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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](/influxdb/v2/get-started/). ## Before you begin 1. Install the InfluxDB Python library: ``` pip install influxdb-client ``` 2. Ensure that InfluxDB is running. If running InfluxDB locally, visit http://localhost:8086. (If using InfluxDB Cloud, visit the URL of your InfluxDB Cloud UI. For example: https://us-west-2-1.aws.cloud2.influxdata.com.) ## Write data to InfluxDB with Python We are going to write some data in [line protocol](/influxdb/v2/reference/syntax/line-protocol/) using the Python library. 1. In your Python program, import the InfluxDB client library and use it to write data to InfluxDB. ``` import influxdb_client from influxdb_client.client.write_api import SYNCHRONOUS ``` 2. Define a few variables with the name of your [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), and [token](/influxdb/v2/admin/tokens/). ``` bucket = "" org = "" token = "" # Store the URL of your InfluxDB instance url="http://localhost:8086" ``` 3. Instantiate the client. The `InfluxDBClient` object takes three named parameters: `url`, `org`, and `token`. Pass in the named parameters. ``` client = influxdb_client.InfluxDBClient( url=url, token=token, org=org ) ``` The `InfluxDBClient` object has a `write_api` method used for configuration. 4. Instantiate a **write client** using the `client` object and the `write_api` method. Use the `write_api` method to configure the writer object. ``` write_api = client.write_api(write_options=SYNCHRONOUS) ``` 5. Create a [point](/influxdb/v2/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=bucket, org=org, record=p) ``` ### Complete example write script ```python import influxdb_client from influxdb_client.client.write_api import SYNCHRONOUS bucket = "" org = "" token = "" # Store the URL of your InfluxDB instance url="http://localhost:8086" 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=bucket, org=org, record=p) ``` ## Query data from InfluxDB with Python 1. Instantiate the **query client**. ``` query_api = client.query_api() ``` 2. Create a Flux query, and then format it as a Python string. ``` query = 'from(bucket:"my-bucket")\ |> range(start: -10m)\ |> filter(fn:(r) => r._measurement == "my_measurement")\ |> filter(fn:(r) => r.location == "Prague")\ |> filter(fn:(r) => r._field == "temperature")' ``` The query client sends the Flux query to InfluxDB and returns a Flux object with a table structure. 3. Pass the `query()` method two named parameters:`org` and `query`. ``` result = query_api.query(org=org, query=query) ``` 4. Iterate through the tables and records in the Flux object. * Use the `get_value()` method to return values. * Use the `get_field()` method to return fields. ``` results = [] for table in result: for record in table.records: results.append((record.get_field(), record.get_value())) print(results) [(temperature, 25.3)] ``` **The Flux object provides the following methods for accessing your data:** * `get_measurement()`: Returns the measurement name of the record. * `get_field()`: Returns the field name. * `get_value()`: Returns the actual field value. * `values`: Returns a map of column values. * `values.get("")`: Returns a value from the record for given column. * `get_time()`: Returns the time of the record. * `get_start()`: Returns the inclusive lower time bound of all records in the current table. * `get_stop()`: Returns the exclusive upper time bound of all records in the current table. ### Complete example query script ```python import influxdb_client from influxdb_client.client.write_api import SYNCHRONOUS bucket = "" org = "" token = "" # Store the URL of your InfluxDB instance url="http://localhost:8086" client = influxdb_client.InfluxDBClient( url=url, token=token, org=org ) # Query script query_api = client.query_api() query = 'from(bucket:"my-bucket")\ |> range(start: -10m)\ |> filter(fn:(r) => r._measurement == "my_measurement")\ |> filter(fn:(r) => r.location == "Prague")\ |> filter(fn:(r) => r._field == "temperature")' result = query_api.query(org=org, query=query) results = [] for table in result: for record in table.records: results.append((record.get_field(), record.get_value())) print(results) [(temperature, 25.3)] ``` For more information, see the [Python client README on GitHub](https://github.com/influxdata/influxdb-client-python). [client libraries](/influxdb/v2/tags/client-libraries/)[python](/influxdb/v2/tags/python/) --- # R package client library Source: https://docs.influxdata.com/influxdb/v2/api-guide/client-libraries/r/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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/influxdb/v2/api-guide/client-libraries/ruby/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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/influxdb/v2/api-guide/client-libraries/scala/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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/influxdb/v2/api-guide/client-libraries/swift/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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 1.x compatibility API Source: https://docs.influxdata.com/influxdb/v2/api-guide/influxdb-1x/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. [View full v1 compatibility API documentation](/influxdb/v2/api/v1-compatibility/) ## Authentication InfluxDB 1.x compatibility endpoints require all query and write requests to be authenticated with an[API token](/influxdb/v2/admin/tokens/) or v1-compatible credentials. > [!Important] > #### Authenticate with an API token or 1.x-compatible credentials > > You can’t use an InfluxDB 2.x username and password to authenticate with the InfluxDB 1.x compatibility API. * [Authenticate with the Token scheme](#authenticate-with-the-token-scheme) * [Authenticate with a 1.x username and password scheme](#authenticate-with-a-username-and-password-scheme) * [Troubleshoot authentication issues](#troubleshoot-authentication-issues) ### Authenticate with the Token scheme Token authentication requires the following credential: * **token**: InfluxDB [API token](/influxdb/v2/admin/tokens/) Use the `Authorization` header with the `Token` scheme to provide your token to InfluxDB. The `Token` scheme is the word `Token`, a space, and your token (all case-sensitive). #### Syntax ```http Authorization: Token INFLUX_API_TOKEN ``` #### Example [curl](#curl-5)[Node.js](#nodejs-5) ```sh ####################################### # Use a token in the Authorization header # to query the InfluxDB 1.x compatibility API. # # Replace INFLUX_API_TOKEN with your InfluxDB API token. ####################################### curl --get "http://localhost:8086" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header 'Content-type: application/json' \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ```js /** * Use the Token authentication scheme * to query the InfluxDB 1.x compatibility API. * * Replace INFLUX_API_TOKEN with your InfluxDB API token. */ const https = require('https'); const querystring = require('querystring'); function queryWithToken() { const queryparams = { db: 'mydb', q: 'SELECT * FROM cpu_usage', }; const options = { host: 'localhost:8086', path: "/query?" + querystring.stringify(queryparams), headers: { 'Authorization': 'Token INFLUX_API_TOKEN', 'Content-type': 'application/json' }, }; const request = https.get(options, (response) => { let rawData = ''; response.on('data', () => { response.on('data', (chunk) => { rawData += chunk; }); }) response.on('end', () => { console.log(rawData); }) }); request.end(); } ``` ### Authenticate with a username and password scheme Use the following authentication schemes with clients that support the InfluxDB 1.x convention of `username` and `password` (that don’t support the `Authorization: Token` scheme): * [Basic authentication](#basic-authentication) * [Query string authentication](#query-string-authentication) #### Manage credentials Username and password schemes require the following credentials: * **username**: 1.x username (this is separate from the UI login username) * **password**: 1.x password or InfluxDB API token. > [!Note] > #### Password or Token > > If you have [set a password](/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) for the v1-compatible username, provide the v1-compatible password. > If you haven’t set a password for the v1-compatible username, provide the InfluxDB [authentication token](/influxdb/v2/admin/tokens/) as the password. For more information, see how to create and manage[v1-compatible authorizations](/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations)when manually upgrading from InfluxDB v1 to v2. #### Basic authentication Use the `Authorization` header with the `Basic` scheme to provide username and password credentials to InfluxDB. > [!Note] > Most HTTP clients provide a **Basic authentication** option that > accepts the `:` syntax > and encodes the credentials before sending the request. ##### Syntax ```http Authorization: Basic INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN ``` ##### Example [curl](#curl)[Node.js](#nodejs) ```sh ####################################### # Use Basic authentication with an # InfluxDB 1.x compatible username and password # to query the InfluxDB 1.x compatibility API. # # Replace INFLUX_USERNAME with your 1.x-compatible username. # Replace INFLUX_PASSWORD_OR_TOKEN with your InfluxDB API token # or 1.x-compatible password. ####################################### # Use the default retention policy. ####################################### # Use the --user option with `--user :` syntax # or the `--user ` interactive syntax to ensure your credentials are # encoded in the header. ####################################### curl --get "http://localhost:8086/query" \ --user "INFLUX_USERNAME":"INFLUX_PASSWORD_OR_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ```js /** * Use Basic authentication with an * InfluxDB 1.x compatible username and password * to query the InfluxDB 1.x compatibility API. * Replace INFLUX_USERNAME with your 1.x-compatible username. * Replace INFLUX_PASSWORD_OR_TOKEN with your InfluxDB API token * or 1.x-compatible password. * Use the default retention policy. */ const https = require('https'); const querystring = require('querystring'); function queryWithUsername() { const queryparams = { db: 'mydb', q: 'SELECT * FROM cpu_usage', }; const options = { host: 'localhost:8086', path: '/query?' + querystring.stringify(queryparams), auth: 'INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN', headers: { 'Content-type': 'application/json' }, }; const request = https.get(options, (response) => { let rawData = ''; response.on('data', () => { response.on('data', (chunk) => { rawData += chunk; }); }) response.on('end', () => { console.log(rawData); }) }); request.end(); } ``` #### Query string authentication Use InfluxDB 1.x API parameters to provide credentials through the query string. > [!Note] > ##### Consider when using query string parameters > > * URL-encode query parameters that may contain whitespace or other special characters. > * Be aware of the [risks](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) when exposing sensitive data through URLs. ##### Syntax ``` /query/?u=INFLUX_USERNAME&p=INFLUX_PASSWORD_OR_TOKEN /write/?u=INFLUX_USERNAME&p=INFLUX_PASSWORD_OR_TOKEN ``` ##### Example [curl](#curl-3)[Node.js](#nodejs-3) ```sh ####################################### # Use querystring authentication with an # InfluxDB 1.x compatible username and password # to query the InfluxDB 1.x compatibility API. # # Replace INFLUX_USERNAME with your 1.x-compatible username. # Replace INFLUX_PASSWORD_OR_TOKEN with your InfluxDB API token # or 1.x-compatible password. # # Use the default retention policy. ####################################### curl --get "http://localhost:8086/query" \ --data-urlencode "u=INFLUX_USERNAME" \ --data-urlencode "p=INFLUX_PASSWORD_OR_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ```js /** * Use querystring authentication with an * InfluxDB 1.x compatible username and password * to query the InfluxDB 1.x compatibility API. * * Replace INFLUX_USERNAME with your 1.x-compatible username. * Replace INFLUX_PASSWORD_OR_TOKEN with your InfluxDB API token * or 1.x-compatible password. * * Use the default retention policy. */ const https = require('https'); const querystring = require('querystring'); function queryWithToken() { const queryparams = { db: 'mydb', q: 'SELECT * FROM cpu_usage', u: 'INFLUX_USERNAME', p: 'INFLUX_PASSWORD_OR_TOKEN' }; const options = { host: 'localhost:8086', path: "/query?" + querystring.stringify(queryparams) }; const request = https.get(options, (response) => { let rawData = ''; response.on('data', () => { response.on('data', (chunk) => { rawData += chunk; }); }) response.on('end', () => { console.log(rawData); }) }); request.end(); } ``` Replace the following: * `INFLUX_USERNAME`: [InfluxDB 1.x username](#manage-credentials) * `INFLUX_PASSWORD_OR_TOKEN`: [InfluxDB 1.x password or InfluxDB API token](#manage-credentials) ### Troubleshoot authentication issues #### Unauthorized when using the initial username and password You can’t use the InfluxDB 2.x username and password to authenticate with the InfluxDB 1.x compatibility API. For example, given the following Docker Compose configuration: ```yaml # Docker compose example influx2: image: influxdb:2.4.0 volumes: - ./dev/influxdb2:/var/lib/influxdb2 ports: - "8086:8086" environment: DOCKER_INFLUXDB_INIT_USERNAME: dev DOCKER_INFLUXDB_INIT_PASSWORD: 12345678 DOCKER_INFLUXDB_INIT_ORG: com.some DOCKER_INFLUXDB_INIT_BUCKET: m2_dev DOCKER_INFLUXDB_INIT_MODE: setup ``` The following query using the v1 `/query` endpoint and v2 initial username and password returns an `unauthorized` error: ```bash # Using the initial username and password curl --get "http://localhost:8086/query" \ --data-urlencode "u=dev" \ --data-urlencode "p=12345678" \ --data-urlencode "db=m2_dev" \ --data-urlencode "q=SELECT * FROM default" ``` Instead, [authenticate with a token](#authenticate-with-the-token-scheme) or a [1.x username and password scheme](#authenticate-with-a-username-and-password-scheme). ## InfluxQL support The compatibility API supports InfluxQL, with the following caveats: * The `INTO` clause (for example, `SELECT ... INTO ...`) is not supported. * With the exception of [`DELETE`](/influxdb/v1/query_language/manage-database/#delete-series-with-delete) and[`DROP MEASUREMENT`](/influxdb/v1/query_language/manage-database/#delete-measurements-with-drop-measurement) queries, which are still allowed, InfluxQL database management commands are not supported. ## Compatibility endpoints ### [/query](/influxdb/v2/api-guide/influxdb-1x/query/) The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS 2.x using **InfluxQL**. ``` GET http://localhost:8086/query ``` [Read more ](/influxdb/v2/api-guide/influxdb-1x/query/) ### [/write](/influxdb/v2/api-guide/influxdb-1x/write/) The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS 2.x using patterns from the InfluxDB 1.x `/write` API endpoint. ``` POST http://localhost:8086/write ``` [Read more ](/influxdb/v2/api-guide/influxdb-1x/write/) ### [Database and retention policy mapping](/influxdb/v2/api-guide/influxdb-1x/dbrp/) The database and retention policy (DBRP) mapping service maps InfluxDB 1.x database and retention policy combinations to InfluxDB Cloud and InfluxDB OSS 2.x buckets. #### Related * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) [influxql](/influxdb/v2/tags/influxql/)[query](/influxdb/v2/tags/query/)[write](/influxdb/v2/tags/write/) --- # Database and retention policy mapping Source: https://docs.influxdata.com/influxdb/v2/api-guide/influxdb-1x/dbrp/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB 1.x data model includes [databases](/influxdb/v1/concepts/glossary/#database)and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp). InfluxDB 2.10 replaces databases and retention policies with[buckets](/influxdb/v2/reference/glossary/#bucket). To support InfluxDB 1.x query and write patterns in InfluxDB 2.10, databases and retention policies are mapped to buckets using the**database and retention policy (DBRP) mapping service**. The DBRP mapping service uses the **database** and **retention policy** specified in[1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) requests to route operations to a bucket. ### Default retention policies A database can have multiple retention policies with one set as default. If no retention policy is specified in a query or write request, InfluxDB uses the default retention policy for the specified database. Use the `influx` CLI or the InfluxDB API to set a retention policy as the default retention policy for a database. ### When creating a bucket When you [create a bucket](/influxdb/v2/admin/buckets/create-bucket/), InfluxDB 2.10 automatically creates a “virtual” DBRP mapping. Virtual DBRP mappings are those that are created on your behalf. * **If your bucket name includes a forward slash (`/`)**, the virtual DBRP mapping uses everything before the forward slash as the database name and everything after the forward slash as the retention policy name. If the database does not already have a default retention policy, the parsed retention policy is set as the default. * **If your bucket name does not include a forward slash (`/`)**, the virtual DBRP mapping uses the bucket name as the database and `autogen` as the retention policy. The `autogen` retention policy is set as the default retention policy. ### When writing data When writing data using the[`/write` compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/write/), the DBRP mapping service uses the database and retention policy specified in the request to write the data to the appropriate bucket. ### When querying data When querying data from InfluxDB 2.10using the [`/query` compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/query/), the DBRP mapping service uses the database and retention policy specified in the request to query data from the appropriate bucket. If no retention policy is specified, the database’s default retention policy is used. > [!Note] > #### A DBRP combination can only be mapped to a single bucket > > Each unique DBRP combination can only be mapped to a single bucket. > If you map a DBRP combination that is already mapped to another bucket, > it will overwrite the existing DBRP mapping. #### Related * [/influxdb/v2/api/dbrps/ InfluxDB v2 API /dbrps endpoint](/influxdb/v2/api/dbrps/%20InfluxDB%20v2%20API%20/dbrps%20endpoint) * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) --- # /query 1.x compatibility API Source: https://docs.influxdata.com/influxdb/v2/api-guide/influxdb-1x/query/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `/query` 1.x compatibility endpoint queries InfluxDB 2.10 using **InfluxQL**. Send an InfluxQL query in an HTTP `GET` or `POST` request to query data from the `/query` endpoint. The `/query` compatibility endpoint uses the **database** and **retention policy**specified in the query request to map the request to an InfluxDB bucket. For more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp). ## Authentication Use one of the following authentication methods: * the 2.x `Authorization: Token` scheme in the header * the v1-compatible `u` and `p` query string parameters * the v1-compatible `Basic` authentication scheme in the header For more information, see [Authentication for the 1.x compatibility API](/influxdb/v2/api-guide/influxdb-1x/). ## Query string parameters ### u (Optional) The 1.x **username** to authenticate the request. If you provide an API token as the password, `u` is required, but can be any value.*See [query string authentication](/influxdb/v2/reference/api/influxdb-1x/#query-string-authentication).* ### p (Optional) The 1.x **password** or the 2.x API token to authenticate the request.*See [query string authentication](/influxdb/v2/reference/api/influxdb-1x/#query-string-authentication).* ### db (Required) The **database** to query data from. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket).*See [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).* ### rp The **retention policy** to query data from. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket).*See [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).* ### q (Required) The **InfluxQL** query to execute. To execute multiple queries, delimit queries with a semicolon (`;`). ### epoch Return results with [Unix timestamps](/influxdb/v2/reference/glossary/#unix-timestamp)(also known as epoch timestamps) in the specified precision instead of[RFC3339 timestamps](/influxdb/v2/reference/glossary/#rfc3339-timestamp) with nanosecond precision. The following precisions are available: * `ns` - nanoseconds * `u` or `µ` - microseconds * `ms` - milliseconds * `s` - seconds * `m` - minutes * `h` - hours ## Query examples * [Query using basic authentication](#query-using-basic-authentication) * [Query a non-default retention policy](#query-a-non-default-retention-policy) * [Execute multiple queries](#execute-multiple-queries) * [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps) * [Execute InfluxQL queries from a file](#execute-influxql-queries-from-a-file) ##### Query using basic authentication The following example: * sends a `GET` request to the `/query` endpoint * uses the `Authorization` header with the `Basic` scheme (compatible with InfluxDB 1.x) to provide username and password credentials * uses the default retention policy for the database ```sh ############################################################################## # Use Basic authentication with an # InfluxDB v1-compatible username and password # to query the InfluxDB 1.x compatibility API. # # INFLUX_USERNAME: your v1-compatible username. # INFLUX_PASSWORD_OR_TOKEN: your API token or v1-compatible password. ############################################################################## curl --get "http://localhost:8086/query" \ --user "INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN" \ --data-urlencode "db=BUCKET_NAME" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ##### Query using an HTTP POST request ```bash curl \ --request POST \ "http://localhost:8086/query?db=DATABASE_NAME&rp=RETENTION_POLICY" \ --user "INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN" \ --header "Content-type: application/vnd.influxql" \ --data "SELECT * FROM cpu_usage WHERE time > now() - 1h" ``` ##### Query a non-default retention policy The following example: * sends a `GET` request to the `/query` endpoint * uses the `Authorization` header with the `Token` scheme (compatible with InfluxDB 2.x) to provide the API token * queries a custom retention policy mapped for the database ```sh curl --get http://localhost:8086/query \ --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "rp=RETENTION_POLICY_NAME" \ --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" ``` ##### Execute multiple queries ```sh curl --get http://localhost:8086/query \ --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM mem WHERE host=host1;SELECT mean(used_percent) FROM mem WHERE host=host1 GROUP BY time(10m)" ``` ##### Return query results with millisecond Unix timestamps ```sh curl --get http://localhost:8086/query \ --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "rp=RETENTION_POLICY_NAME" \ --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" \ --data-urlencode "epoch=ms" ``` ##### Execute InfluxQL queries from a file ```sh curl --get http://localhost:8086/query \ --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q@path/to/influxql.txt" ``` ##### Return a gzip-compressed response ```sh curl --get http://localhost:8086/query \ --header 'Accept-Encoding: gzip' \ --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" ``` Replace the following: * `API_TOKEN`: your InfluxDB [API token](/influxdb/v2/admin/tokens/) * `DATABASE_NAME`: the name of the database to query. In InfluxDB 2.x, databases and retention policies map to [buckets](/influxdb/v2/admin/buckets/). * `RETENTION_POLICY_NAME`: the name of the retention policy to query. In InfluxDB 2.x, databases and retention policies map to [buckets](/influxdb/v2/admin/buckets/). *For more information about the database and retention policy mapping, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp).* #### Related * [Query with the InfluxDB API](/influxdb/v2/query-data/execute-queries/influx-api/) * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) [influxql](/influxdb/v2/tags/influxql/)[query](/influxdb/v2/tags/query/) --- # /write 1.x compatibility API Source: https://docs.influxdata.com/influxdb/v2/api-guide/influxdb-1x/write/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS 2.10using patterns from the InfluxDB 1.x `/write` API endpoint. Use the `POST` request method to write [line protocol](/influxdb/v2/reference/syntax/line-protocol/)to the `/write` endpoint. ``` POST http://localhost:8086/write ``` ## Authentication Use one of the following authentication methods: * **token authentication** * **basic authentication with username and password** * **query string authentication with username and password** *For more information, see [Authentication](/influxdb/v2/reference/api/influxdb-1x/#authentication).* ## Request body Include your line protocol in the request body.**Binary encode** the line protocol to prevent unintended formatting. The examples [below](#write-examples) use the curl `--data-binary` flag to binary encode the line protocol. ## Query string parameters ### u (Optional) The 1.x **username** to authenticate the request.*See [query string authentication](/influxdb/v2/reference/api/influxdb-1x/#query-string-authentication).* ### p (Optional) The 1.x **password** to authenticate the request.*See [query string authentication](/influxdb/v2/reference/api/influxdb-1x/#query-string-authentication).* ### db (Required) The **database** to write data to. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket).*See [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).* ### rp The **retention policy** to write data to. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket).*See [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).* ### precision The precision of [Unix timestamps](/influxdb/v2/reference/glossary/#unix-timestamp) in the line protocol. Default is nanosconds (`ns`). The following precisions are available: * `ns` - nanoseconds * `u` or `µ` - microseconds * `ms` - milliseconds * `s` - seconds * `m` - minutes * `h` - hours ## Write examples * [Write data using basic authentication](#write-data-using-basic-authentication) * [Write data to a non-default retention policy](#write-data-to-a-non-default-retention-policy) * [Write multiple lines of line protocol](#write-multiple-lines-of-line-protocol) * [Write data with millisecond Unix timestamps](#write-data-with-millisecond-unix-timestamps) * [Use curl to write data from a file](#use-curl-to-write-data-from-a-file) ##### Write data using basic authentication ```sh curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ --user "USERNAME:PASSWORD_OR_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` ##### Write data using token authentication ```sh curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` ##### Write data to a non-default retention policy ```sh curl --request POST "http://localhost:8086/write?db=DATABASE_NAME&rp=RETENTION_POLICY" \ --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` ##### Write multiple lines of line protocol ```sh curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000 measurement,host=host2 field1=14i,field2=12.7 1577836800000000000 measurement,host=host3 field1=5i,field2=6.8 1577836800000000000" ``` ##### Write data with millisecond Unix timestamps ```sh curl --request POST "http://localhost:8086/write?db=DATABASE_NAME&precision=ms" \ --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000" ``` ##### Use curl to write data from a file ```sh curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ --header "Authorization: Token API_TOKEN" \ --data-binary @path/to/line-protocol.txt ``` Replace the following: * `DATABASE_NAME` and `RETENTION_POLICY`: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to * `USERNAME`: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) * `PASSWORD_OR_TOKEN`: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) * `API_TOKEN`: your [InfluxDB API token](/influxdb/v2/admin/tokens/) #### Related * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) [write](/influxdb/v2/tags/write/) --- # InfluxDB API client library tutorials Source: https://docs.influxdata.com/influxdb/v2/api-guide/tutorials/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Follow step-by-step tutorials to build an Internet-of-Things (IoT) application with InfluxData client libraries and your favorite framework or language. 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. In these tutorials, you’ll use the InfluxDB API and client libraries to build a modern application, and learn the following: * InfluxDB core concepts. * How the application interacts with devices and InfluxDB. * How to authenticate apps and devices to the API. * How to install a client library. * How to write and query data in InfluxDB. * How to use the InfluxData UI libraries to format data and create visualizations. ### [Python](/influxdb/v2/api-guide/tutorials/python/) Build an application that writes, queries, and manages devices with the InfluxDB client library for Python. ### [JavaScript](/influxdb/v2/api-guide/tutorials/nodejs/) Build a JavaScript application that writes, queries, and manages devices with the InfluxDB client library. [api](/influxdb/v2/tags/api/) --- # JavaScript client library starter Source: https://docs.influxdata.com/influxdb/v2/api-guide/tutorials/nodejs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Follow this step-by-step tutorial to build an Internet-of-Things (IoT) application with InfluxData client libraries and your favorite framework or language. In this tutorial, you’ll use the InfluxDB API and client libraries to build a modern application as you learn the following: * InfluxDB core concepts. * How the application interacts with devices and InfluxDB. * How to authenticate apps and devices to the API. * How to install a client library. * How to write and query data in InfluxDB. ## Contents * [Contents](#contents) * [Set up InfluxDB](#set-up-influxdb) * [Introducing IoT Starter](#introducing-iot-starter) * [Install Yarn](#install-yarn) * [Create the application](#create-the-application) * [Install InfluxDB client library](#install-influxdb-client-library) * [Configure the client library](#configure-the-client-library) * [Build the API](#build-the-api) * [Create the API to list devices](#create-the-api-to-list-devices) * [Handle requests for device information](#handle-requests-for-device-information) * [Retrieve and list devices](#retrieve-and-list-devices) * [Create the API to register devices](#create-the-api-to-register-devices) * [Create an authorization for the device](#create-an-authorization-for-the-device) * [Write the device authorization to a bucket](#write-the-device-authorization-to-a-bucket) * [Install and run the UI](#install-and-run-the-ui) ## Set up InfluxDB If you haven’t already, [create an InfluxDB Cloud account](https://www.influxdata.com/products/influxdb-cloud/) or [install InfluxDB OSS](https://www.influxdata.com/products/influxdb/). The IoT Starter example app assumes the following prerequisites: * An InfluxDB [org ID](/influxdb/v2/admin/organizations/view-orgs/) * An [API token](/influxdb/v2/admin/tokens/create-token/) (for example, an **All Access token**) that has read and write permissions for the buckets * A [bucket](/influxdb/v2/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center` for storing time series data from devices * A [bucket](/influxdb/v2/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center_devices` for storing device metadata and API token IDs > [!Note] > #### Use restricted tokens for production apps > > For a production application, create and use a > > read-write > > token with minimal permissions and only use it with a single client or application. ## Introducing IoT Starter The application architecture has four layers: * **InfluxDB API**: InfluxDB v2 API. * **IoT device**: Virtual or physical devices write IoT data to the InfluxDB API. * **UI**: Sends requests to the server and renders views in the browser. * **API**: Receives requests from the UI, sends requests to InfluxDB, and processes responses from InfluxDB. > [!Note] > For the complete code referenced in this tutorial, see the [influxdata/iot-api-js repository](https://github.com/influxdata/iot-api-js). ## Install Yarn If you haven’t already installed `yarn`, follow the [Yarn package manager installation instructions](https://yarnpkg.com/getting-started/install#nodejs-1610-1) for your version of Node.js. * To check the installed `yarn` version, enter the following code into your terminal: ``` yarn --version ``` ## Create the application Create a directory that will contain your `iot-api` projects. The following example code creates an `iot-api` directory in your home directory and changes to the new directory: ```bash mkdir ~/iot-api-apps cd ~/iot-api-apps ``` Follow these steps to create a JavaScript application with [Next.js](https://nextjs.org/): 1. In your `~/iot-api-apps` directory, open a terminal and enter the following commands to create the `iot-api-js` app from the NextJS [learn-starter template](https://github.com/vercel/next-learn/tree/master/basics/learn-starter): ``` yarn create-next-app iot-api-js --example "https://github.com/vercel/next-learn/tree/master/basics/learn-starter" ``` 2. After the installation completes, enter the following commands in your terminal to go into your `./iot-api-js` directory and start the development server: ``` cd iot-api-js yarn dev -p 3001 ``` To view the application, visit [http://localhost:3001](http://localhost:3001) in your browser. ## Install InfluxDB client library The InfluxDB client library provides the following InfluxDB API interactions: * Query data with the Flux language. * Write data to InfluxDB. * Batch data in the background. * Retry requests automatically on failure. 1. Enter the following command into your terminal to install the client library: ``` yarn add @influxdata/influxdb-client ``` 2. Enter the following command into your terminal to install `@influxdata/influxdb-client-apis`, the *management APIs* that create, modify, and delete authorizations, buckets, tasks, and other InfluxDB resources: ``` yarn add @influxdata/influxdb-client-apis ``` For more information about the client library, see the [influxdata/influxdb-client-js repo](https://github.com/influxdata/influxdb-client-js). ## Configure the client library InfluxDB client libraries require configuration properties from your InfluxDB environment. Typically, you’ll provide the following properties as environment variables for your application: * `INFLUX_URL` * `INFLUX_TOKEN` * `INFLUX_ORG` * `INFLUX_BUCKET` * `INFLUX_BUCKET_AUTH` Next.js uses the `env` module to provide environment variables to your application. The `./.env.development` file is versioned and contains non-secret default settings for your *development* environment. ```bash # .env.development INFLUX_URL=http://localhost:8086 INFLUX_BUCKET=iot_center INFLUX_BUCKET_AUTH=iot_center_devices ``` To configure secrets and settings that aren’t added to version control, create a `./.env.local` file and set the variables–for example, set your InfluxDB token and organization: ```sh # .env.local # INFLUX_TOKEN # InfluxDB API token used by the application server to send requests to InfluxDB. # For convenience in development, use an **All Access** token. INFLUX_TOKEN=29Xx1KH9VkASPR2DSfRfFd82OwGD... # INFLUX_ORG # InfluxDB organization ID you want to use in development. INFLUX_ORG=48c88459ee424a04 ``` Enter the following commands into your terminal to restart and load the `.env` files: 1. `CONTROL+C` to stop the application. 2. `yarn dev` to start the application. Next.js sets variables that you can access in the `process.env` object–for example: ```ts console.log(process.env.INFLUX_ORG) ``` ## Build the API Your application API provides server-side HTTP endpoints that process requests from the UI. Each API endpoint is responsible for the following: 1. Listen for HTTP requests (from the UI). 2. Translate requests into InfluxDB API requests. 3. Process InfluxDB API responses and handle errors. 4. Respond with status and data (for the UI). ## Create the API to list devices Add the `/api/devices` API endpoint that retrieves, processes, and lists devices.`/api/devices` uses the `/api/v2/query` InfluxDB API endpoint to query `INFLUX_BUCKET_AUTH` for a registered device. ### Handle requests for device information 1. Create a `./pages/api/devices/[[...deviceParams]].js` file to handle requests for `/api/devices` and `/api/devices//measurements/`. 2. In the file, export a Next.js request `handler` function.[See the example](https://github.com/influxdata/iot-api-js/blob/18d34bcd59b93ad545c5cd9311164c77f6d1995a/pages/api/devices/%5B%5B...deviceParams%5D%5D.js). > [!Note] > In Next.js, the filename pattern `[[...param]].js` creates a *catch-all* API route. > To learn more, see [Next.js dynamic API routes](https://nextjs.org/docs/api-routes/dynamic-api-routes). ### Retrieve and list devices Retrieve registered devices in `INFLUX_BUCKET_AUTH` and process the query results. 1. Create a Flux query that gets the last row of each [series](/influxdb/v2/reference/glossary#series) that contains a `deviceauth` measurement. The example query below returns rows that contain the `key` field (authorization ID) and excludes rows that contain a `token` field (to avoid exposing tokens to the UI). ``` // Flux query finds devices from(bucket:`${INFLUX_BUCKET_AUTH}`) |> range(start: 0) |> filter(fn: (r) => r._measurement == "deviceauth" and r._field != "token") |> last() ``` 2. Use the `QueryApi` client to send the Flux query to the `POST /api/v2/query` InfluxDB API endpoint. Create a `./pages/api/devices/_devices.js` file that contains the following: [Node.js](#nodejs) ```ts import { InfluxDB } from '@influxdata/influxdb-client' import { flux } from '@influxdata/influxdb-client' const INFLUX_ORG = process.env.INFLUX_ORG const INFLUX_BUCKET_AUTH = process.env.INFLUX_BUCKET_AUTH const influxdb = new InfluxDB({url: process.env.INFLUX_URL, token: process.env.INFLUX_TOKEN}) /** * Gets devices or a particular device when deviceId is specified. Tokens * are not returned unless deviceId is specified. It can also return devices * with empty/unknown key, such devices can be ignored (InfluxDB authorization is not associated). * @param deviceId optional deviceId * @returns promise with an Record. */ export async function getDevices(deviceId) { const queryApi = influxdb.getQueryApi(INFLUX_ORG) const deviceFilter = deviceId !== undefined ? flux` and r.deviceId == "${deviceId}"` : flux` and r._field != "token"` const fluxQuery = flux`from(bucket:${INFLUX_BUCKET_AUTH}) |> range(start: 0) |> filter(fn: (r) => r._measurement == "deviceauth"${deviceFilter}) |> last()` const devices = {} return await new Promise((resolve, reject) => { queryApi.queryRows(fluxQuery, { next(row, tableMeta) { const o = tableMeta.toObject(row) const deviceId = o.deviceId if (!deviceId) { return } const device = devices[deviceId] || (devices[deviceId] = {deviceId}) device[o._field] = o._value if (!device.updatedAt || device.updatedAt < o._time) { device.updatedAt = o._time } }, error: reject, complete() { resolve(devices) }, }) }) } ``` [](#) [iot-api-js/pages/api/devices/\_devices.js getDevices(deviceId)](https://github.com/influxdata/iot-api-js/blob/18d34bcd59b93ad545c5cd9311164c77f6d1995a/pages/api/devices/_devices.js) The `_devices` module exports a `getDevices(deviceId)` function that queries for registered devices, processes the data, and returns a Promise with the result. If you invoke the function as `getDevices()` (without a *`deviceId`*), it retrieves all `deviceauth` points and returns a Promise with `{ DEVICE_ID: ROW_DATA }`. To send the query and process results, the `getDevices(deviceId)` function uses the `QueryAPI queryRows(query, consumer)` method.`queryRows` executes the `query` and provides the Annotated CSV result as an Observable to the `consumer`.`queryRows` has the following TypeScript signature: ```ts queryRows( query: string | ParameterizedQuery, consumer: FluxResultObserver ): void ``` [@influxdata/influxdb-client-js QueryAPI](https://github.com/influxdata/influxdb-client-js/blob/3db2942432b993048d152e0d0e8ec8499eedfa60/packages/core/src/QueryApi.ts) The `consumer` that you provide must implement the [`FluxResultObserver` interface](https://github.com/influxdata/influxdb-client-js/blob/3db2942432b993048d152e0d0e8ec8499eedfa60/packages/core/src/results/FluxResultObserver.ts) and provide the following callback functions: * `next(row, tableMeta)`: processes the next row and table metadata–for example, to prepare the response. * `error(error)`: receives and handles errors–for example, by rejecting the Promise. * `complete()`: signals when all rows have been consumed–for example, by resolving the Promise. To learn more about Observers, see the [RxJS Guide](https://rxjs.dev/guide/observer). ## Create the API to register devices In this application, a *registered device* is a point that contains your device ID, authorization ID, and API token. The API token and authorization permissions allow the device to query and write to `INFLUX_BUCKET`. In this section, you add the API endpoint that handles requests from the UI, creates an authorization in InfluxDB, and writes the registered device to the `INFLUX_BUCKET_AUTH` bucket. To learn more about API tokens and authorizations, see [Manage API tokens](/influxdb/v2/admin/tokens/) The application API uses the following `/api/v2` InfluxDB API endpoints: * `POST /api/v2/query`: to query `INFLUX_BUCKET_AUTH` for a registered device. * `GET /api/v2/buckets`: to get the bucket ID for `INFLUX_BUCKET`. * `POST /api/v2/authorizations`: to create an authorization for the device. * `POST /api/v2/write`: to write the device authorization to `INFLUX_BUCKET_AUTH`. 1. Add a `./pages/api/devices/create.js` file to handle requests for `/api/devices/create`. 2. In the file, export a Next.js request `handler` function that does the following: 1. Accept a device ID in the request body. 2. Query `INFLUX_BUCKET_AUTH` and respond with an error if an authorization exists for the device. 3. [Create an authorization for the device](#create-an-authorization-for-the-device). 4. [Write the device ID and authorization to `INFLUX_BUCKET_AUTH`](#write-the-device-authorization-to-a-bucket). 5. Respond with `HTTP 200` when the write request completes. [See the example](https://github.com/influxdata/iot-api-js/blob/25b38c94a1f04ea71f2ef4b9fcba5350d691cb9d/pages/api/devices/create.js). ### Create an authorization for the device In this section, you create an authorization with *read*-*write* permission to `INFLUX_BUCKET` and receive an API token for the device. The example below uses the following steps to create the authorization: 1. Instantiate the `AuthorizationsAPI` client and `BucketsAPI` client with the configuration. 2. Retrieve the bucket ID. 3. Use the client library to send a `POST` request to the `/api/v2/authorizations` InfluxDB API endpoint. In `./api/devices/create.js`, add the following `createAuthorization(deviceId)` function: [Node.js](#nodejs-2) ``` import { InfluxDB } from '@influxdata/influxdb-client' import { getDevices } from './_devices' import { AuthorizationsAPI, BucketsAPI } from '@influxdata/influxdb-client-apis' import { Point } from '@influxdata/influxdb-client' const INFLUX_ORG = process.env.INFLUX_ORG const INFLUX_BUCKET_AUTH = process.env.INFLUX_BUCKET_AUTH const INFLUX_BUCKET = process.env.INFLUX_BUCKET const influxdb = new InfluxDB({url: process.env.INFLUX_URL, token: process.env.INFLUX_TOKEN}) /** * Creates an authorization for a supplied deviceId * @param {string} deviceId client identifier * @returns {import('@influxdata/influxdb-client-apis').Authorization} promise with authorization or an error */ async function createAuthorization(deviceId) { const authorizationsAPI = new AuthorizationsAPI(influxdb) const bucketsAPI = new BucketsAPI(influxdb) const DESC_PREFIX = 'IoTCenterDevice: ' const buckets = await bucketsAPI.getBuckets({name: INFLUX_BUCKET, orgID: INFLUX_ORG}) const bucketId = buckets.buckets[0]?.id return await authorizationsAPI.postAuthorizations( { body: { orgID: INFLUX_ORG, description: DESC_PREFIX + deviceId, permissions: [ { action: 'read', resource: {type: 'buckets', id: bucketId, orgID: INFLUX_ORG}, }, { action: 'write', resource: {type: 'buckets', id: bucketId, orgID: INFLUX_ORG}, }, ], }, } ) } ``` [](#) [iot-api-js/pages/api/devices/create.js](https://github.com/influxdata/iot-api-js/blob/42a37d683b5e4df601422f85d2c22f5e9d592e68/pages/api/devices/create.js) To create an authorization that has *read*-*write* permission to `INFLUX_BUCKET`, you need the bucket ID. To retrieve the bucket ID,`createAuthorization(deviceId)` calls the `BucketsAPI getBuckets` function that sends a `GET` request to the `/api/v2/buckets` InfluxDB API endpoint.`createAuthorization(deviceId)` then passes a new authorization in the request body with the following: * Bucket ID. * Organization ID. * Description: `IoTCenterDevice: DEVICE_ID`. * List of permissions to the bucket. To learn more about API tokens and authorizations, see [Manage API tokens](/influxdb/v2/admin/tokens/). Next, [write the device authorization to a bucket](#write-the-device-authorization-to-a-bucket). ### Write the device authorization to a bucket With a device authorization in InfluxDB, write a point for the device and authorization details to `INFLUX_BUCKET_AUTH`. Storing the device authorization in a bucket allows you to do the following: * Report device authorization history. * Manage devices with and without tokens. * Assign the same token to multiple devices. * Refresh tokens. To write a point to InfluxDB, use the InfluxDB client library to send a `POST` request to the `/api/v2/write` InfluxDB API endpoint. In `./pages/api/devices/create.js`, add the following `createDevice(deviceId)` function: [Node.js](#nodejs-3) ```ts /** Creates an authorization for a deviceId and writes it to a bucket */ async function createDevice(deviceId) { let device = (await getDevices(deviceId)) || {} let authorizationValid = !!Object.values(device)[0]?.key if(authorizationValid) { console.log(JSON.stringify(device)) return Promise.reject('This device ID is already registered and has an authorization.') } else { console.log(`createDeviceAuthorization: deviceId=${deviceId}`) const authorization = await createAuthorization(deviceId) const writeApi = influxdb.getWriteApi(INFLUX_ORG, INFLUX_BUCKET_AUTH, 'ms', { batchSize: 2, }) const point = new Point('deviceauth') .tag('deviceId', deviceId) .stringField('key', authorization.id) .stringField('token', authorization.token) writeApi.writePoint(point) await writeApi.close() return } } ``` [iot-api-js/pages/api/devices/create.js](https://github.com/influxdata/iot-api-js/blob/25b38c94a1f04ea71f2ef4b9fcba5350d691cb9d/pages/api/devices/create.js) `createDevice(device_id)` takes a *`device_id`* and writes data to `INFLUX_BUCKET_AUTH` in the following steps: 1. Initialize `InfluxDBClient()` with `url`, `token`, and `org` values from the configuration. 2. Initialize a `WriteAPI` client for writing data to an InfluxDB bucket. 3. Create a `Point`. 4. Use `writeApi.writePoint(point)` to write the `Point` to the bucket. The function writes a point with the following elements: | Element | Name | Value | |-----------|----------|-------------------------| |measurement| | `deviceauth` | | tag |`deviceId`| device ID | | field | `key` | authorization ID | | field | `token` |authorization (API) token| ## Install and run the UI `influxdata/iot-api-ui` is a standalone [Next.js React](https://nextjs.org/docs/basic-features/pages) UI that uses your application API to write and query data in InfluxDB.`iot-api-ui` uses Next.js *[rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites)* to route all requests in the `/api/` path to your API. To install and run the UI, do the following: 1. In your `~/iot-api-apps` directory, clone the [`influxdata/iot-api-ui` repo](https://github.com/influxdata/iot-api-ui) and go into the `iot-api-ui` directory–for example: ``` cd ~/iot-api-apps git clone git@github.com:influxdata/iot-api-ui.git cd ./iot-app-ui ``` 2. The `./.env.development` file contains default configuration settings that you can edit or override (with a `./.env.local` file). 3. To start the UI, enter the following command into your terminal: ``` yarn dev ``` To view the list and register devices, visit [http://localhost:3000/devices](http://localhost:3000/devices) in your browser. To learn more about the UI components, see [`influxdata/iot-api-ui`](https://github.com/influxdata/iot-api-ui). [api](/influxdb/v2/tags/api/)[javascript](/influxdb/v2/tags/javascript/)[nodejs](/influxdb/v2/tags/nodejs/) | Element | Name | Value | | --- | --- | --- | | Element | Name | Value | | measurement | | deviceauth | | tag | deviceId | device ID | | field | key | authorization ID | | field | token | authorization (API) token | --- # Python client library starter Source: https://docs.influxdata.com/influxdb/v2/api-guide/tutorials/python/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Follow this step-by-step tutorial to build an Internet-of-Things (IoT) application with InfluxData client libraries and your favorite framework or language. In this tutorial, you’ll use the InfluxDB API and client libraries to build a modern application as you learn the following: * InfluxDB core concepts. * How the application interacts with devices and InfluxDB. * How to authenticate apps and devices to the API. * How to install a client library. * How to write and query data in InfluxDB. * How to use the InfluxData UI libraries to format data and create visualizations. ## Contents * [Contents](#contents) * [Set up InfluxDB](#set-up-influxdb) * [Introducing IoT Starter](#introducing-iot-starter) * [Create the application](#create-the-application) * [Install InfluxDB client library](#install-influxdb-client-library) * [Configure the client library](#configure-the-client-library) * [Build the API](#build-the-api) * [Create the API to register devices](#create-the-api-to-register-devices) * [Create an authorization for the device](#create-an-authorization-for-the-device) * [Write the device authorization to a bucket](#write-the-device-authorization-to-a-bucket) * [Create the API to list devices](#create-the-api-to-list-devices) * [Create IoT virtual device](#create-iot-virtual-device) * [Write telemetry data](#write-telemetry-data) * [Query telemetry data](#query-telemetry-data) * [Define API responses](#define-api-responses) * [Install and run the UI](#install-and-run-the-ui) ## Set up InfluxDB If you haven’t already, [create an InfluxDB Cloud account](https://www.influxdata.com/products/influxdb-cloud/) or [install InfluxDB OSS](https://www.influxdata.com/products/influxdb/). The IoT Starter example app assumes the following prerequisites: * An InfluxDB [org ID](/influxdb/v2/admin/organizations/view-orgs/) * An [API token](/influxdb/v2/admin/tokens/create-token/) (for example, an **All Access token**) that has read and write permissions for the buckets * A [bucket](/influxdb/v2/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center` for storing time series data from devices * A [bucket](/influxdb/v2/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center_devices` for storing device metadata and API token IDs ## Introducing IoT Starter The application architecture has four layers: * **InfluxDB API**: InfluxDB v2 API. * **IoT device**: Virtual or physical devices write IoT data to the InfluxDB API. * **UI**: Sends requests to the server and renders views in the browser. * **API**: Receives requests from the UI, sends requests to InfluxDB, and processes responses from InfluxDB. > [!Note] > For the complete code referenced in this tutorial, see the [influxdata/iot-api-python repository](https://github.com/influxdata/iot-api-python). ## Create the application Create a directory that will contain your `iot-api` projects. The following example code creates an `iot-api` directory in your home directory and changes to the new directory: ```bash mkdir ~/iot-api-apps cd ~/iot-api-apps ``` Use [Flask](https://flask.palletsprojects.com/), a lightweight Python web framework, to create your application. 1. In your `~/iot-api-apps` directory, open a terminal and enter the following commands to create and navigate into a new project directory: ``` mkdir iot-api-python && cd $_ ``` 2. Enter the following commands in your terminal to create and activate a Python virtual environment for the project: ``` # Create a new virtual environment named "virtualenv" # Python 3.8+ python -m venv virtualenv # Activate the virtualenv (OS X & Linux) source virtualenv/bin/activate ``` 3. After activation completes, enter the following commands in your terminal to install Flask with the `pip` package installer (included with Python): ``` pip install Flask ``` 4. In your project, create a `app.py` file that: 1. Imports the Flask package. 2. Instantiates a Flask application. 3. Provides a route to execute the application. ``` from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" ``` [influxdata/iot-api-python app.py](https://github.com/influxdata/iot-api-python/blob/main/app.py) Start your application. The following example code starts the application on `http://localhost:3001` with debugging and hot-reloading enabled: ``` export FLASK_ENV=development flask run -h localhost -p 3001 ``` In your browser, visit [http://localhost:3001](http://localhost:3001) to view the “Hello World!” response. ## Install InfluxDB client library The InfluxDB client library provides the following InfluxDB API interactions: * Query data with the Flux language. * Write data to InfluxDB. * Batch data in the background. * Retry requests automatically on failure. Enter the following command into your terminal to install the client library: ```bash pip install influxdb-client ``` For more information about the client library, see the [influxdata/influxdb-client-python repo](https://github.com/influxdata/influxdb-client-python). ## Configure the client library InfluxDB client libraries require configuration properties from your InfluxDB environment. Typically, you’ll provide the following properties as environment variables for your application: * `INFLUX_URL` * `INFLUX_TOKEN` * `INFLUX_ORG` * `INFLUX_BUCKET` * `INFLUX_BUCKET_AUTH` To set up the client configuration, create a `config.ini` in your project’s top level directory and paste the following to provide the necessary InfluxDB credentials: ```ini [APP] INFLUX_URL = INFLUX_TOKEN = INFLUX_ORG = INFLUX_BUCKET = iot_center INFLUX_BUCKET_AUTH = iot_center_devices ``` [/iot-api-python/config.ini](https://github.com/influxdata/iot-api-python/blob/main/config.ini) Replace the following: * **``**: your InfluxDB instance URL. * **``**: your InfluxDB [API token](#authorization) with permission to query (*read*) buckets and create (*write*) authorizations for devices. * **``**: your InfluxDB organization ID. ## Build the API Your application API provides server-side HTTP endpoints that process requests from the UI. Each API endpoint is responsible for the following: 1. Listen for HTTP requests (from the UI). 2. Translate requests into InfluxDB API requests. 3. Process InfluxDB API responses and handle errors. 4. Respond with status and data (for the UI). ## Create the API to register devices In this application, a *registered device* is a point that contains your device ID, authorization ID, and API token. The API token and authorization permissions allow the device to query and write to `INFLUX_BUCKET`. In this section, you add the API endpoint that handles requests from the UI, creates an authorization in InfluxDB, and writes the registered device to the `INFLUX_BUCKET_AUTH` bucket. To learn more about API tokens and authorizations, see [Manage API tokens](/influxdb/v2/admin/tokens/) The application API uses the following `/api/v2` InfluxDB API endpoints: * `POST /api/v2/query`: to query `INFLUX_BUCKET_AUTH` for a registered device. * `GET /api/v2/buckets`: to get the bucket ID for `INFLUX_BUCKET`. * `POST /api/v2/authorizations`: to create an authorization for the device. * `POST /api/v2/write`: to write the device authorization to `INFLUX_BUCKET_AUTH`. ### Create an authorization for the device In this section, you create an authorization with *read*-*write* permission to `INFLUX_BUCKET` and receive an API token for the device. The example below uses the following steps to create the authorization: 1. Instantiate the `AuthorizationsAPI` client and `BucketsAPI` client with the configuration. 2. Retrieve the bucket ID. 3. Use the client library to send a `POST` request to the `/api/v2/authorizations` InfluxDB API endpoint. Create a `./api/devices.py` file that contains the following: ```python # Import the dependencies. import configparser from datetime import datetime from uuid import uuid4 # Import client library classes. from influxdb_client import Authorization, InfluxDBClient, Permission, PermissionResource, Point, WriteOptions from influxdb_client.client.authorizations_api import AuthorizationsApi from influxdb_client.client.bucket_api import BucketsApi from influxdb_client.client.query_api import QueryApi from influxdb_client.client.write_api import SYNCHRONOUS from api.sensor import Sensor # Get the configuration key-value pairs. config = configparser.ConfigParser() config.read('config.ini') def create_authorization(device_id) -> Authorization: influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'), token=os.environ.get('INFLUX_TOKEN'), org=os.environ.get('INFLUX_ORG')) authorization_api = AuthorizationsApi(influxdb_client) # get bucket_id from bucket buckets_api = BucketsApi(influxdb_client) buckets = buckets_api.find_bucket_by_name(config.get('APP', 'INFLUX_BUCKET')) # function returns only 1 bucket bucket_id = buckets.id org_id = buckets.org_id desc_prefix = f'IoTCenterDevice: {device_id}' org_resource = PermissionResource(org_id=org_id, id=bucket_id, type="buckets") read = Permission(action="read", resource=org_resource) write = Permission(action="write", resource=org_resource) permissions = [read, write] authorization = Authorization(org_id=org_id, permissions=permissions, description=desc_prefix) request = authorization_api.create_authorization(authorization=authorization) return request ``` [](#) [iot-api-python/api/devices.py](https://github.com/influxdata/iot-api-python/blob/d389a0e072c7a03dfea99e5663bdc32be94966bb/api/devices.py#L145) To create an authorization that has *read*-*write* permission to `INFLUX_BUCKET`, you need the bucket ID. To retrieve the bucket ID, `create_authorization(deviceId)` calls the`BucketsAPI find_bucket_by_name` function that sends a `GET` request to the `/api/v2/buckets` InfluxDB API endpoint.`create_authorization(deviceId)` then passes a new authorization in the request body with the following: * Bucket ID. * Organization ID. * Description: `IoTCenterDevice: DEVICE_ID`. * List of permissions to the bucket. To learn more about API tokens and authorizations, see [Manage API tokens](/influxdb/v2/admin/tokens/). Next, [write the device authorization to a bucket](#write-the-device-authorization-to-a-bucket). ### Write the device authorization to a bucket With a device authorization in InfluxDB, write a point for the device and authorization details to `INFLUX_BUCKET_AUTH`. Storing the device authorization in a bucket allows you to do the following: * Report device authorization history. * Manage devices with and without tokens. * Assign the same token to multiple devices. * Refresh tokens. To write a point to InfluxDB, use the InfluxDB client library to send a `POST` request to the `/api/v2/write` InfluxDB API endpoint. In `./api/devices.py`, add the following `create_device(device_id)` function: ```python def create_device(device_id=None): influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'), token=config.get('APP', 'INFLUX_TOKEN'), org=config.get('APP', 'INFLUX_ORG')) if device_id is None: device_id = str(uuid4()) write_api = influxdb_client.write_api(write_options=SYNCHRONOUS) point = Point('deviceauth') \ .tag("deviceId", device_id) \ .field('key', f'fake_auth_id_{device_id}') \ .field('token', f'fake_auth_token_{device_id}') client_response = write_api.write(bucket=config.get('APP', 'INFLUX_BUCKET_AUTH'), record=point) # write() returns None on success if client_response is None: return device_id # Return None on failure return None ``` [iot-api-python/api/devices.py](https://github.com/influxdata/iot-api-python/blob/f354941c80b6bac643ca29efe408fde1deebdc96/api/devices.py#L47) `create_device(device_id)` takes a *`device_id`* and writes data to `INFLUX_BUCKET_AUTH` in the following steps: 1. Initialize `InfluxDBClient()` with `url`, `token`, and `org` values from the configuration. 2. Initialize a `WriteAPI` client for writing data to an InfluxDB bucket. 3. Create a `Point`. 4. Use `write_api.write()` to write the `Point` to the bucket. 5. Check for failures–if the write was successful, `write_api` returns `None`. 6. Return *`device_id`* if successful; `None` otherwise. The function writes a point with the following elements: | Element | Name | Value | |-----------|----------|-------------------------| |measurement| | `deviceauth` | | tag |`deviceId`| device ID | | field | `key` | authorization ID | | field | `token` |authorization (API) token| Next, [create the API to list devices](#create-the-api-to-list-devices). ## Create the API to list devices Add the `/api/devices` API endpoint that retrieves, processes, and lists registered devices. 1. Create a Flux query that gets the last row of each [series](/influxdb/v2/reference/glossary#series) that contains a `deviceauth` measurement. The example query below returns rows that contain the `key` field (authorization ID) and excludes rows that contain a `token` field (to avoid exposing tokens to the UI). ``` // Flux query finds devices from(bucket:`${INFLUX_BUCKET_AUTH}`) |> range(start: 0) |> filter(fn: (r) => r._measurement == "deviceauth" and r._field != "token") |> last() ``` 2. Use the `QueryApi` client to send the Flux query to the `POST /api/v2/query` InfluxDB API endpoint. In `./api/devices.py`, add the following: ``` def get_device(device_id=None) -> {}: influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'), token=os.environ.get('INFLUX_TOKEN'), org=os.environ.get('INFLUX_ORG')) # Queries must be formatted with single and double quotes correctly query_api = QueryApi(influxdb_client) device_filter = '' if device_id: device_id = str(device_id) device_filter = f'r.deviceId == "{device_id}" and r._field != "token"' else: device_filter = f'r._field != "token"' flux_query = f'from(bucket: "{config.get("APP", "INFLUX_BUCKET_AUTH")}") ' \ f'|> range(start: 0) ' \ f'|> filter(fn: (r) => r._measurement == "deviceauth" and {device_filter}) ' \ f'|> last()' response = query_api.query(flux_query) result = [] for table in response: for record in table.records: try: 'updatedAt' in record except KeyError: record['updatedAt'] = record.get_time() record[record.get_field()] = record.get_value() result.append(record.values) return result ``` [iot-api-python/api/devices.py get\_device()](https://github.com/influxdata/iot-api-python/blob/9bf44a659424a27eb937d545dc0455754354aef5/api/devices.py#L30) The `get_device(device_id)` function does the following: 1. Instantiates a `QueryApi` client and sends the Flux query to InfluxDB. 2. Iterates over the `FluxTable` in the response and returns a list of tuples. ## Create IoT virtual device Create a `./api/sensor.py` file that generates simulated weather telemetry data. Follow the [example code](https://github.com/influxdata/iot-api-python/blob/f354941c80b6bac643ca29efe408fde1deebdc96/api/sensor.py) to create the IoT virtual device. Next, generate data for virtual devices and [write the data to InfluxDB](#write-telemetry-data). ## Write telemetry data In this section, you write telemetry data to an InfluxDB bucket. To write data, use the InfluxDB client library to send a `POST` request to the `/api/v2/write` InfluxDB API endpoint. The example below uses the following steps to generate data and then write it to InfluxDB: 1. Initialize a `WriteAPI` instance. 2. Create a `Point` with the `environment` measurement and data fields for temperature, humidity, pressure, latitude, and longitude. 3. Use the `WriteAPI write` method to send the point to InfluxDB. In `./api/devices.py`, add the following `write_measurements(device_id)` function: ```python def write_measurements(device_id): influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'), token=config.get('APP', 'INFLUX_TOKEN'), org=config.get('APP', 'INFLUX_ORG')) write_api = influxdb_client.write_api(write_options=SYNCHRONOUS) virtual_device = Sensor() coord = virtual_device.geo() point = Point("environment") \ .tag("device", device_id) \ .tag("TemperatureSensor", "virtual_bme280") \ .tag("HumiditySensor", "virtual_bme280") \ .tag("PressureSensor", "virtual_bme280") \ .field("Temperature", virtual_device.generate_measurement()) \ .field("Humidity", virtual_device.generate_measurement()) \ .field("Pressure", virtual_device.generate_measurement()) \ .field("Lat", coord['latitude']) \ .field("Lon", coord['latitude']) \ .time(datetime.utcnow()) print(f"Writing: {point.to_line_protocol()}") client_response = write_api.write(bucket=config.get('APP', 'INFLUX_BUCKET'), record=point) # write() returns None on success if client_response is None: # TODO Maybe also return the data that was written return device_id # Return None on failure return None ``` [iot-api-python/api/devices.py write\_measurement()](https://github.com/influxdata/iot-api-python/blob/f354941c80b6bac643ca29efe408fde1deebdc96/api/devices.py) ## Query telemetry data In this section, you retrieve telemetry data from an InfluxDB bucket. To retrieve data, use the InfluxDB client library to send a `POST` request to the `/api/v2/query` InfluxDB API endpoint. The example below uses the following steps to retrieve and process telemetry data: 1. Query `environment` measurements in `INFLUX_BUCKET`. 2. Filter results by `device_id`. 3. Return CSV data that the [`influxdata/giraffe` UI library](https://github.com/influxdata/giraffe) can process. In `./api/devices.py`, add the following `get_measurements(device_id)` function: ```python def get_measurements(query): influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'), token=os.environ.get('INFLUX_TOKEN'), org=os.environ.get('INFLUX_ORG')) query_api = QueryApi(influxdb_client) result = query_api.query_csv(query, dialect=Dialect( header=True, delimiter=",", comment_prefix="#", annotations=['group', 'datatype', 'default'], date_time_format="RFC3339")) response = '' for row in result: response += (',').join(row) + ('\n') return response ``` [iot-api-python/api/devices.py get\_measurements()](https://github.com/influxdata/iot-api-python/blob/9bf44a659424a27eb937d545dc0455754354aef5/api/devices.py#L122) ## Define API responses In `app.py`, add API endpoints that match incoming requests and respond with the results of your modules. In the following `/api/devices/` route example, `app.py` retrieves *`device_id`* from `GET` and `POST` requests, passes it to the `get_device(device_id)` method and returns the result as JSON data with CORS `allow-` headers. ```python @app.route('/api/devices/', methods=['GET', 'POST']) def api_get_device(device_id): if request.method == "OPTIONS": # CORS preflight return _build_cors_preflight_response() return _corsify_actual_response(jsonify(devices.get_device(device_id))) ``` [iot-api-python/app.py](https://github.com/influxdata/iot-api-python/blob/9bf44a659424a27eb937d545dc0455754354aef5/app.py) Enter the following commands into your terminal to restart the application: 1. `CONTROL+C` to stop the application. 2. `flask run -h localhost -p 3001` to start the application. To retrieve devices data from your API, visit [http://localhost:3001/api/devices](http://localhost:3001/api/devices) in your browser. ## Install and run the UI `influxdata/iot-api-ui` is a standalone [Next.js React](https://nextjs.org/docs/basic-features/pages) UI that uses your application API to write and query data in InfluxDB.`iot-api-ui` uses Next.js *[rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites)* to route all requests in the `/api/` path to your API. To install and run the UI, do the following: 1. In your `~/iot-api-apps` directory, clone the [`influxdata/iot-api-ui` repo](https://github.com/influxdata/iot-api-ui) and go into the `iot-api-ui` directory–for example: ``` cd ~/iot-api-apps git clone git@github.com:influxdata/iot-api-ui.git cd ./iot-app-ui ``` 2. The `./.env.development` file contains default configuration settings that you can edit or override (with a `./.env.local` file). 3. To start the UI, enter the following command into your terminal: ``` yarn dev ``` To view the list and register devices, visit [http://localhost:3000/devices](http://localhost:3000/devices) in your browser. To learn more about the UI components, see [`influxdata/iot-api-ui`](https://github.com/influxdata/iot-api-ui). [api](/influxdb/v2/tags/api/)[python](/influxdb/v2/tags/python/) | Element | Name | Value | | --- | --- | --- | | Element | Name | Value | | measurement | | deviceauth | | tag | deviceId | device ID | | field | key | authorization ID | | field | token | authorization (API) token | --- # InfluxDB HTTP API Source: https://docs.influxdata.com/influxdb/v2/api/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Use the InfluxDB HTTP API to write data, query data, and manage databases, tables, and tokens. ### [Quick start](/influxdb/v2/api/quick-start/) Authenticate, write, and query with the InfluxDB OSS v2 API: ### [Authentication](/influxdb/v2/api/authentication/) Use one of the following schemes to authenticate to the InfluxDB OSS v2 API: ### [Common parameters](/influxdb/v2/api/common-parameters/) Most InfluxDB OSS v2 API endpoints require parameters in the request–for example, to specify the bucket or organization. ### [Compatibility endpoints](/influxdb/v2/api/compatibility-endpoints/) InfluxDB v1-compatible API endpoints for backward compatibility with InfluxDB 1.x clients, tools, and integrations such as Grafana and Telegraf. ### [Headers](/influxdb/v2/api/headers/) InfluxDB OSS v2 API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB OSS v2 API endpoints. Some endpoints may use other headers… ### [Pagination](/influxdb/v2/api/pagination/) List endpoints in the InfluxDB OSS v2 API support pagination via query parameters. Use these parameters to page through large result sets. ### [Response codes](/influxdb/v2/api/response-codes/) InfluxDB OSS v2 API endpoints return standard HTTP status codes. The following table summarizes the most common response codes. ### [Supported operations](/influxdb/v2/api/supported-operations/) The InfluxDB OSS v2 API supports create, read, update, and delete operations on resources. Most endpoints follow standard HTTP method conventions: ### [Authorizations (API tokens)](/influxdb/v2/api/authorizations-api-tokens/) Create and manage API token authorizations that grant read and write permissions to InfluxDB OSS v2 organization resources. ### [Backup](/influxdb/v2/api/backup/) Back up InfluxDB OSS v2 data, including time series data and metadata, for use in restore operations. ### [Buckets](/influxdb/v2/api/buckets/) Create and manage named storage locations (buckets) in InfluxDB OSS v2, each with a configurable retention period. ### [Cells](/influxdb/v2/api/cells/) Manage cells within InfluxDB OSS v2 dashboards. ### [Checks](/influxdb/v2/api/checks/) Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB OSS v2. ### [Config](/influxdb/v2/api/config/) Retrieve configuration information for an InfluxDB OSS v2 instance. ### [Dashboards](/influxdb/v2/api/dashboards/) Create and manage dashboards in InfluxDB OSS v2. ### [Data I/O endpoints](/influxdb/v2/api/data-i-o-endpoints/) API reference for Data I/O endpoints ### [DBRPs](/influxdb/v2/api/dbrps/) Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB OSS v2 buckets. ### [Debug](/influxdb/v2/api/debug/) Generate Go runtime profiling and trace reports for troubleshooting and performance analysis of an InfluxDB OSS v2 instance. ### [Delete](/influxdb/v2/api/delete/) Delete time series data from an InfluxDB OSS v2 bucket by specifying a time range and optional tag predicate. ### [Health](/influxdb/v2/api/health/) Check the health and readiness of an InfluxDB OSS v2 instance. ### [Labels](/influxdb/v2/api/labels/) Create and manage labels for organizing InfluxDB OSS v2 resources such as dashboards, tasks, and buckets. ### [Legacy Authorizations](/influxdb/v2/api/legacy-authorizations/) API reference for Legacy Authorizations ### [Legacy Query](/influxdb/v2/api/legacy-query/) API reference for Legacy Query ### [Legacy Write](/influxdb/v2/api/legacy-write/) API reference for Legacy Write ### [Metrics](/influxdb/v2/api/metrics/) Retrieve internal metrics for an InfluxDB OSS v2 instance in Prometheus exposition format. ### [NotificationEndpoints](/influxdb/v2/api/notificationendpoints/) Create and manage notification endpoints that receive alert notifications from InfluxDB OSS v2 monitoring checks. ### [NotificationRules](/influxdb/v2/api/notificationrules/) Create and manage notification rules that define when and how InfluxDB OSS v2 sends notifications to configured endpoints. ### [Organizations](/influxdb/v2/api/organizations/) Create and manage InfluxDB OSS v2 organizations, which are workspaces that group users, buckets, and resources. ### [Ping](/influxdb/v2/api/ping/) Check the availability of an InfluxDB OSS v2 instance. ### [Query](/influxdb/v2/api/query/) Retrieve data, analyze queries, and get query suggestions. ### [Ready](/influxdb/v2/api/ready/) Check whether an InfluxDB OSS v2 instance is ready to accept requests. ### [RemoteConnections](/influxdb/v2/api/remoteconnections/) Create and manage remote InfluxDB connections for replicating data from an InfluxDB OSS v2 instance to a remote InfluxDB instance. ### [Replications](/influxdb/v2/api/replications/) Create and manage replication streams that copy data from an InfluxDB OSS v2 bucket to a remote InfluxDB instance. ### [Resources](/influxdb/v2/api/resources/) Retrieve a list of top-level resource types available in the InfluxDB OSS v2 API. ### [Restore](/influxdb/v2/api/restore/) Restore InfluxDB OSS v2 data from a backup, including time series data and metadata. ### [Routes](/influxdb/v2/api/routes/) Retrieve top-level routes for the InfluxDB OSS v2 API. ### [Rules](/influxdb/v2/api/rules/) Manage notification rules in InfluxDB OSS v2. ### [Scraper Targets](/influxdb/v2/api/scraper-targets/) Create and manage Prometheus scraper targets that collect metrics and write them to InfluxDB OSS v2 buckets. ### [Secrets](/influxdb/v2/api/secrets/) Create and manage secrets (key-value pairs) for use in InfluxDB OSS v2 Flux scripts and tasks. ### [Security and access endpoints](/influxdb/v2/api/security-and-access-endpoints/) Endpoints for managing authentication and access control in InfluxDB OSS v2. ### [Setup](/influxdb/v2/api/setup/) Configure a new InfluxDB OSS v2 instance, including creating the initial user, organization, bucket, and API token. ### [Signin](/influxdb/v2/api/signin/) Create a user session by signing in with username and password credentials. ### [Signout](/influxdb/v2/api/signout/) End a user session by signing out. ### [Sources](/influxdb/v2/api/sources/) Manage data sources configured in InfluxDB OSS v2. ### [System information endpoints](/influxdb/v2/api/system-information-endpoints/) Endpoints for retrieving system-level information about the InfluxDB OSS v2 instance. ### [Tasks](/influxdb/v2/api/tasks/) Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB OSS v2. ### [Telegraf Plugins](/influxdb/v2/api/telegraf-plugins/) Retrieve available Telegraf plugin configuration templates for use with InfluxDB OSS v2. ### [Telegrafs](/influxdb/v2/api/telegrafs/) Create and manage Telegraf agent configurations that collect and write data to InfluxDB OSS v2. ### [Templates](/influxdb/v2/api/templates/) Export and apply InfluxDB templates, and manage template stacks for InfluxDB OSS v2. ### [Users](/influxdb/v2/api/users/) Create and manage users that have access to InfluxDB OSS v2 organizations and resources. ### [Variables](/influxdb/v2/api/variables/) Create and manage variables for use in InfluxDB OSS v2 dashboards. ### [Views](/influxdb/v2/api/views/) Manage cell views within InfluxDB OSS v2 dashboards. ### [Write](/influxdb/v2/api/write/) Write time series data to [buckets](/influxdb/v2/reference/glossary/). --- # All endpoints Source: https://docs.influxdata.com/influxdb/v2/api/all-endpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) All InfluxDB API endpoints, sorted by path. ## v2-compatible API [GET`/api/v2`List all top level routes](/influxdb/v2/api/routes/#operation/GetRoutes)[GET`/api/v2`List all top level routes](/influxdb/v2/api/system-information-endpoints/#operation/GetRoutes)[GET`/api/v2/authorizations`List authorizations](/influxdb/v2/api/authorizations-api-tokens/#operation/GetAuthorizations)[GET`/api/v2/authorizations`List authorizations](/influxdb/v2/api/security-and-access-endpoints/#operation/GetAuthorizations)[POST`/api/v2/authorizations`Create an authorization](/influxdb/v2/api/authorizations-api-tokens/#operation/PostAuthorizations)[POST`/api/v2/authorizations`Create an authorization](/influxdb/v2/api/security-and-access-endpoints/#operation/PostAuthorizations)[DELETE`/api/v2/authorizations/{authID}`Delete an authorization](/influxdb/v2/api/authorizations-api-tokens/#operation/DeleteAuthorizationsID)[DELETE`/api/v2/authorizations/{authID}`Delete an authorization](/influxdb/v2/api/security-and-access-endpoints/#operation/DeleteAuthorizationsID)[GET`/api/v2/authorizations/{authID}`Retrieve an authorization](/influxdb/v2/api/authorizations-api-tokens/#operation/GetAuthorizationsID)[GET`/api/v2/authorizations/{authID}`Retrieve an authorization](/influxdb/v2/api/security-and-access-endpoints/#operation/GetAuthorizationsID)[PATCH`/api/v2/authorizations/{authID}`Update an API token to be active or inactive](/influxdb/v2/api/authorizations-api-tokens/#operation/PatchAuthorizationsID)[PATCH`/api/v2/authorizations/{authID}`Update an API token to be active or inactive](/influxdb/v2/api/security-and-access-endpoints/#operation/PatchAuthorizationsID)[GET`/api/v2/backup/kv`Download snapshot of metadata stored in the server's embedded KV store. Don't use with InfluxDB versions greater than InfluxDB 2.1.x.Deprecated](/influxdb/v2/api/backup/#operation/GetBackupKV)[GET`/api/v2/backup/metadata`Download snapshot of all metadata in the server](/influxdb/v2/api/backup/#operation/GetBackupMetadata)[GET`/api/v2/backup/shards/{shardID}`Download snapshot of all TSM data in a shard](/influxdb/v2/api/backup/#operation/GetBackupShardId)[GET`/api/v2/buckets`List buckets](/influxdb/v2/api/buckets/#operation/GetBuckets)[POST`/api/v2/buckets`Create a bucket](/influxdb/v2/api/buckets/#operation/PostBuckets)[DELETE`/api/v2/buckets/{bucketID}`Delete a bucket](/influxdb/v2/api/buckets/#operation/DeleteBucketsID)[GET`/api/v2/buckets/{bucketID}`Retrieve a bucket](/influxdb/v2/api/buckets/#operation/GetBucketsID)[PATCH`/api/v2/buckets/{bucketID}`Update a bucket](/influxdb/v2/api/buckets/#operation/PatchBucketsID)[GET`/api/v2/buckets/{bucketID}/labels`List all labels for a bucket](/influxdb/v2/api/buckets/#operation/GetBucketsIDLabels)[POST`/api/v2/buckets/{bucketID}/labels`Add a label to a bucket](/influxdb/v2/api/buckets/#operation/PostBucketsIDLabels)[DELETE`/api/v2/buckets/{bucketID}/labels/{labelID}`Delete a label from a bucket](/influxdb/v2/api/buckets/#operation/DeleteBucketsIDLabelsID)[GET`/api/v2/buckets/{bucketID}/members`List all users with member privileges for a bucket](/influxdb/v2/api/buckets/#operation/GetBucketsIDMembers)[POST`/api/v2/buckets/{bucketID}/members`Add a member to a bucket](/influxdb/v2/api/buckets/#operation/PostBucketsIDMembers)[DELETE`/api/v2/buckets/{bucketID}/members/{userID}`Remove a member from a bucket](/influxdb/v2/api/buckets/#operation/DeleteBucketsIDMembersID)[GET`/api/v2/buckets/{bucketID}/owners`List all owners of a bucket](/influxdb/v2/api/buckets/#operation/GetBucketsIDOwners)[POST`/api/v2/buckets/{bucketID}/owners`Add an owner to a bucket](/influxdb/v2/api/buckets/#operation/PostBucketsIDOwners)[DELETE`/api/v2/buckets/{bucketID}/owners/{userID}`Remove an owner from a bucket](/influxdb/v2/api/buckets/#operation/DeleteBucketsIDOwnersID)[GET`/api/v2/checks`List all checks](/influxdb/v2/api/checks/#operation/GetChecks)[POST`/api/v2/checks`Add new check](/influxdb/v2/api/checks/#operation/CreateCheck)[DELETE`/api/v2/checks/{checkID}`Delete a check](/influxdb/v2/api/checks/#operation/DeleteChecksID)[GET`/api/v2/checks/{checkID}`Retrieve a check](/influxdb/v2/api/checks/#operation/GetChecksID)[PATCH`/api/v2/checks/{checkID}`Update a check](/influxdb/v2/api/checks/#operation/PatchChecksID)[PUT`/api/v2/checks/{checkID}`Update a check](/influxdb/v2/api/checks/#operation/PutChecksID)[GET`/api/v2/checks/{checkID}/labels`List all labels for a check](/influxdb/v2/api/checks/#operation/GetChecksIDLabels)[POST`/api/v2/checks/{checkID}/labels`Add a label to a check](/influxdb/v2/api/checks/#operation/PostChecksIDLabels)[DELETE`/api/v2/checks/{checkID}/labels/{labelID}`Delete label from a check](/influxdb/v2/api/checks/#operation/DeleteChecksIDLabelsID)[GET`/api/v2/checks/{checkID}/query`Retrieve a check query](/influxdb/v2/api/checks/#operation/GetChecksIDQuery)[GET`/api/v2/config`Retrieve runtime configuration](/influxdb/v2/api/config/#operation/GetConfig)[GET`/api/v2/config`Retrieve runtime configuration](/influxdb/v2/api/system-information-endpoints/#operation/GetConfig)[GET`/api/v2/dashboards`List dashboards](/influxdb/v2/api/dashboards/#operation/GetDashboards)[POST`/api/v2/dashboards`Create a dashboard](/influxdb/v2/api/dashboards/#operation/PostDashboards)[DELETE`/api/v2/dashboards/{dashboardID}`Delete a dashboard](/influxdb/v2/api/dashboards/#operation/DeleteDashboardsID)[GET`/api/v2/dashboards/{dashboardID}`Retrieve a dashboard](/influxdb/v2/api/dashboards/#operation/GetDashboardsID)[PATCH`/api/v2/dashboards/{dashboardID}`Update a dashboard](/influxdb/v2/api/dashboards/#operation/PatchDashboardsID)[POST`/api/v2/dashboards/{dashboardID}/cells`Create a dashboard cell](/influxdb/v2/api/cells/#operation/PostDashboardsIDCells)[POST`/api/v2/dashboards/{dashboardID}/cells`Create a dashboard cell](/influxdb/v2/api/dashboards/#operation/PostDashboardsIDCells)[PUT`/api/v2/dashboards/{dashboardID}/cells`Replace cells in a dashboard](/influxdb/v2/api/cells/#operation/PutDashboardsIDCells)[PUT`/api/v2/dashboards/{dashboardID}/cells`Replace cells in a dashboard](/influxdb/v2/api/dashboards/#operation/PutDashboardsIDCells)[DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Delete a dashboard cell](/influxdb/v2/api/cells/#operation/DeleteDashboardsIDCellsID)[DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Delete a dashboard cell](/influxdb/v2/api/dashboards/#operation/DeleteDashboardsIDCellsID)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Update the non-positional information related to a cell](/influxdb/v2/api/cells/#operation/PatchDashboardsIDCellsID)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Update the non-positional information related to a cell](/influxdb/v2/api/dashboards/#operation/PatchDashboardsIDCellsID)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/v2/api/cells/#operation/GetDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/v2/api/dashboards/#operation/GetDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/v2/api/views/#operation/GetDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/v2/api/cells/#operation/PatchDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/v2/api/dashboards/#operation/PatchDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/v2/api/views/#operation/PatchDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/labels`List all labels for a dashboard](/influxdb/v2/api/dashboards/#operation/GetDashboardsIDLabels)[POST`/api/v2/dashboards/{dashboardID}/labels`Add a label to a dashboard](/influxdb/v2/api/dashboards/#operation/PostDashboardsIDLabels)[DELETE`/api/v2/dashboards/{dashboardID}/labels/{labelID}`Delete a label from a dashboard](/influxdb/v2/api/dashboards/#operation/DeleteDashboardsIDLabelsID)[GET`/api/v2/dashboards/{dashboardID}/members`List all dashboard members](/influxdb/v2/api/dashboards/#operation/GetDashboardsIDMembers)[POST`/api/v2/dashboards/{dashboardID}/members`Add a member to a dashboard](/influxdb/v2/api/dashboards/#operation/PostDashboardsIDMembers)[DELETE`/api/v2/dashboards/{dashboardID}/members/{userID}`Remove a member from a dashboard](/influxdb/v2/api/dashboards/#operation/DeleteDashboardsIDMembersID)[GET`/api/v2/dashboards/{dashboardID}/owners`List all dashboard owners](/influxdb/v2/api/dashboards/#operation/GetDashboardsIDOwners)[POST`/api/v2/dashboards/{dashboardID}/owners`Add an owner to a dashboard](/influxdb/v2/api/dashboards/#operation/PostDashboardsIDOwners)[DELETE`/api/v2/dashboards/{dashboardID}/owners/{userID}`Remove an owner from a dashboard](/influxdb/v2/api/dashboards/#operation/DeleteDashboardsIDOwnersID)[GET`/api/v2/dbrps`List database retention policy mappings](/influxdb/v2/api/dbrps/#operation/GetDBRPs)[POST`/api/v2/dbrps`Add a database retention policy mapping](/influxdb/v2/api/dbrps/#operation/PostDBRP)[DELETE`/api/v2/dbrps/{dbrpID}`Delete a database retention policy](/influxdb/v2/api/dbrps/#operation/DeleteDBRPID)[GET`/api/v2/dbrps/{dbrpID}`Retrieve a database retention policy mapping](/influxdb/v2/api/dbrps/#operation/GetDBRPsID)[PATCH`/api/v2/dbrps/{dbrpID}`Update a database retention policy mapping](/influxdb/v2/api/dbrps/#operation/PatchDBRPID)[POST`/api/v2/delete`Delete data](/influxdb/v2/api/data-i-o-endpoints/#operation/PostDelete)[POST`/api/v2/delete`Delete data](/influxdb/v2/api/delete/#operation/PostDelete)[GET`/api/v2/flags`Retrieve feature flags](/influxdb/v2/api/config/#operation/GetFlags)[GET`/api/v2/labels`List all labels](/influxdb/v2/api/labels/#operation/GetLabels)[POST`/api/v2/labels`Create a label](/influxdb/v2/api/labels/#operation/PostLabels)[DELETE`/api/v2/labels/{labelID}`Delete a label](/influxdb/v2/api/labels/#operation/DeleteLabelsID)[GET`/api/v2/labels/{labelID}`Retrieve a label](/influxdb/v2/api/labels/#operation/GetLabelsID)[PATCH`/api/v2/labels/{labelID}`Update a label](/influxdb/v2/api/labels/#operation/PatchLabelsID)[GET`/api/v2/me`Retrieve the currently authenticated user](/influxdb/v2/api/users/#operation/GetMe)[PUT`/api/v2/me/password`Update a password](/influxdb/v2/api/users/#operation/PutMePassword)[GET`/api/v2/notificationEndpoints`List all notification endpoints](/influxdb/v2/api/notificationendpoints/#operation/GetNotificationEndpoints)[POST`/api/v2/notificationEndpoints`Add a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/CreateNotificationEndpoint)[DELETE`/api/v2/notificationEndpoints/{endpointID}`Delete a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/DeleteNotificationEndpointsID)[GET`/api/v2/notificationEndpoints/{endpointID}`Retrieve a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/GetNotificationEndpointsID)[PATCH`/api/v2/notificationEndpoints/{endpointID}`Update a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/PatchNotificationEndpointsID)[PUT`/api/v2/notificationEndpoints/{endpointID}`Update a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/PutNotificationEndpointsID)[GET`/api/v2/notificationEndpoints/{endpointID}/labels`List all labels for a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/GetNotificationEndpointsIDLabels)[POST`/api/v2/notificationEndpoints/{endpointID}/labels`Add a label to a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/PostNotificationEndpointIDLabels)[DELETE`/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}`Delete a label from a notification endpoint](/influxdb/v2/api/notificationendpoints/#operation/DeleteNotificationEndpointsIDLabelsID)[GET`/api/v2/notificationRules`List all notification rules](/influxdb/v2/api/notificationrules/#operation/GetNotificationRules)[POST`/api/v2/notificationRules`Add a notification rule](/influxdb/v2/api/notificationrules/#operation/CreateNotificationRule)[DELETE`/api/v2/notificationRules/{ruleID}`Delete a notification rule](/influxdb/v2/api/notificationrules/#operation/DeleteNotificationRulesID)[GET`/api/v2/notificationRules/{ruleID}`Retrieve a notification rule](/influxdb/v2/api/notificationrules/#operation/GetNotificationRulesID)[PATCH`/api/v2/notificationRules/{ruleID}`Update a notification rule](/influxdb/v2/api/notificationrules/#operation/PatchNotificationRulesID)[PUT`/api/v2/notificationRules/{ruleID}`Update a notification rule](/influxdb/v2/api/notificationrules/#operation/PutNotificationRulesID)[GET`/api/v2/notificationRules/{ruleID}/labels`List all labels for a notification rule](/influxdb/v2/api/notificationrules/#operation/GetNotificationRulesIDLabels)[POST`/api/v2/notificationRules/{ruleID}/labels`Add a label to a notification rule](/influxdb/v2/api/notificationrules/#operation/PostNotificationRuleIDLabels)[DELETE`/api/v2/notificationRules/{ruleID}/labels/{labelID}`Delete label from a notification rule](/influxdb/v2/api/notificationrules/#operation/DeleteNotificationRulesIDLabelsID)[GET`/api/v2/notificationRules/{ruleID}/query`Retrieve a notification rule query](/influxdb/v2/api/rules/#operation/GetNotificationRulesIDQuery)[GET`/api/v2/orgs`List organizations](/influxdb/v2/api/organizations/#operation/GetOrgs)[GET`/api/v2/orgs`List organizations](/influxdb/v2/api/security-and-access-endpoints/#operation/GetOrgs)[POST`/api/v2/orgs`Create an organization](/influxdb/v2/api/organizations/#operation/PostOrgs)[DELETE`/api/v2/orgs/{orgID}`Delete an organization](/influxdb/v2/api/organizations/#operation/DeleteOrgsID)[GET`/api/v2/orgs/{orgID}`Retrieve an organization](/influxdb/v2/api/organizations/#operation/GetOrgsID)[GET`/api/v2/orgs/{orgID}`Retrieve an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/GetOrgsID)[PATCH`/api/v2/orgs/{orgID}`Update an organization](/influxdb/v2/api/organizations/#operation/PatchOrgsID)[GET`/api/v2/orgs/{orgID}/members`List all members of an organization](/influxdb/v2/api/organizations/#operation/GetOrgsIDMembers)[GET`/api/v2/orgs/{orgID}/members`List all members of an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/GetOrgsIDMembers)[POST`/api/v2/orgs/{orgID}/members`Add a member to an organization](/influxdb/v2/api/organizations/#operation/PostOrgsIDMembers)[DELETE`/api/v2/orgs/{orgID}/members/{userID}`Remove a member from an organization](/influxdb/v2/api/organizations/#operation/DeleteOrgsIDMembersID)[DELETE`/api/v2/orgs/{orgID}/members/{userID}`Remove a member from an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/DeleteOrgsIDMembersID)[GET`/api/v2/orgs/{orgID}/owners`List all owners of an organization](/influxdb/v2/api/organizations/#operation/GetOrgsIDOwners)[GET`/api/v2/orgs/{orgID}/owners`List all owners of an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/GetOrgsIDOwners)[POST`/api/v2/orgs/{orgID}/owners`Add an owner to an organization](/influxdb/v2/api/organizations/#operation/PostOrgsIDOwners)[DELETE`/api/v2/orgs/{orgID}/owners/{userID}`Remove an owner from an organization](/influxdb/v2/api/organizations/#operation/DeleteOrgsIDOwnersID)[DELETE`/api/v2/orgs/{orgID}/owners/{userID}`Remove an owner from an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/DeleteOrgsIDOwnersID)[GET`/api/v2/orgs/{orgID}/secrets`List all secret keys for an organization](/influxdb/v2/api/secrets/#operation/GetOrgsIDSecrets)[GET`/api/v2/orgs/{orgID}/secrets`List all secret keys for an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/GetOrgsIDSecrets)[PATCH`/api/v2/orgs/{orgID}/secrets`Update secrets in an organization](/influxdb/v2/api/secrets/#operation/PatchOrgsIDSecrets)[DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}`Delete a secret from an organization](/influxdb/v2/api/secrets/#operation/DeleteOrgsIDSecretsID)[DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}`Delete a secret from an organization](/influxdb/v2/api/security-and-access-endpoints/#operation/DeleteOrgsIDSecretsID)[POST`/api/v2/orgs/{orgID}/secrets/delete`Delete secrets from an organizationDeprecated](/influxdb/v2/api/secrets/#operation/PostOrgsIDSecrets)[POST`/api/v2/orgs/{orgID}/secrets/delete`Delete secrets from an organizationDeprecated](/influxdb/v2/api/security-and-access-endpoints/#operation/PostOrgsIDSecrets)[POST`/api/v2/query`Query data](/influxdb/v2/api/data-i-o-endpoints/#operation/PostQuery)[POST`/api/v2/query`Query data](/influxdb/v2/api/query/#operation/PostQuery)[POST`/api/v2/query/analyze`Analyze a Flux query](/influxdb/v2/api/query/#operation/PostQueryAnalyze)[POST`/api/v2/query/ast`Generate a query Abstract Syntax Tree (AST)](/influxdb/v2/api/query/#operation/PostQueryAst)[GET`/api/v2/query/suggestions`List Flux query suggestions](/influxdb/v2/api/query/#operation/GetQuerySuggestions)[GET`/api/v2/query/suggestions/{name}`Retrieve a query suggestion for a branching suggestion](/influxdb/v2/api/query/#operation/GetQuerySuggestionsName)[GET`/api/v2/remotes`List all remote connections](/influxdb/v2/api/remoteconnections/#operation/GetRemoteConnections)[POST`/api/v2/remotes`Register a new remote connection](/influxdb/v2/api/remoteconnections/#operation/PostRemoteConnection)[DELETE`/api/v2/remotes/{remoteID}`Delete a remote connection](/influxdb/v2/api/remoteconnections/#operation/DeleteRemoteConnectionByID)[GET`/api/v2/remotes/{remoteID}`Retrieve a remote connection](/influxdb/v2/api/remoteconnections/#operation/GetRemoteConnectionByID)[PATCH`/api/v2/remotes/{remoteID}`Update a remote connection](/influxdb/v2/api/remoteconnections/#operation/PatchRemoteConnectionByID)[GET`/api/v2/replications`List all replications](/influxdb/v2/api/replications/#operation/GetReplications)[POST`/api/v2/replications`Register a new replication](/influxdb/v2/api/replications/#operation/PostReplication)[DELETE`/api/v2/replications/{replicationID}`Delete a replication](/influxdb/v2/api/replications/#operation/DeleteReplicationByID)[GET`/api/v2/replications/{replicationID}`Retrieve a replication](/influxdb/v2/api/replications/#operation/GetReplicationByID)[PATCH`/api/v2/replications/{replicationID}`Update a replication](/influxdb/v2/api/replications/#operation/PatchReplicationByID)[POST`/api/v2/replications/{replicationID}/validate`Validate a replication](/influxdb/v2/api/replications/#operation/PostValidateReplicationByID)[GET`/api/v2/resources`List all known resources](/influxdb/v2/api/resources/#operation/GetResources)[GET`/api/v2/resources`List all known resources](/influxdb/v2/api/system-information-endpoints/#operation/GetResources)[POST`/api/v2/restore/bucket/{bucketID}`Overwrite storage metadata for a bucket with shard info from a backup.Deprecated](/influxdb/v2/api/restore/#operation/PostRestoreBucketID)[POST`/api/v2/restore/bucketMetadata`Create a new bucket pre-seeded with shard info from a backup.](/influxdb/v2/api/restore/#operation/PostRestoreBucketMetadata)[POST`/api/v2/restore/kv`Overwrite the embedded KV store on the server with a backed-up snapshot.](/influxdb/v2/api/restore/#operation/PostRestoreKV)[POST`/api/v2/restore/shards/{shardID}`Restore a TSM snapshot into a shard.](/influxdb/v2/api/restore/#operation/PostRestoreShardId)[POST`/api/v2/restore/sql`Overwrite the embedded SQL store on the server with a backed-up snapshot.](/influxdb/v2/api/restore/#operation/PostRestoreSQL)[GET`/api/v2/scrapers`List all scraper targets](/influxdb/v2/api/scraper-targets/#operation/GetScrapers)[POST`/api/v2/scrapers`Create a scraper target](/influxdb/v2/api/scraper-targets/#operation/PostScrapers)[DELETE`/api/v2/scrapers/{scraperTargetID}`Delete a scraper target](/influxdb/v2/api/scraper-targets/#operation/DeleteScrapersID)[GET`/api/v2/scrapers/{scraperTargetID}`Retrieve a scraper target](/influxdb/v2/api/scraper-targets/#operation/GetScrapersID)[PATCH`/api/v2/scrapers/{scraperTargetID}`Update a scraper target](/influxdb/v2/api/scraper-targets/#operation/PatchScrapersID)[GET`/api/v2/scrapers/{scraperTargetID}/labels`List all labels for a scraper target](/influxdb/v2/api/scraper-targets/#operation/GetScrapersIDLabels)[POST`/api/v2/scrapers/{scraperTargetID}/labels`Add a label to a scraper target](/influxdb/v2/api/scraper-targets/#operation/PostScrapersIDLabels)[DELETE`/api/v2/scrapers/{scraperTargetID}/labels/{labelID}`Delete a label from a scraper target](/influxdb/v2/api/scraper-targets/#operation/DeleteScrapersIDLabelsID)[GET`/api/v2/scrapers/{scraperTargetID}/members`List all users with member privileges for a scraper target](/influxdb/v2/api/scraper-targets/#operation/GetScrapersIDMembers)[POST`/api/v2/scrapers/{scraperTargetID}/members`Add a member to a scraper target](/influxdb/v2/api/scraper-targets/#operation/PostScrapersIDMembers)[DELETE`/api/v2/scrapers/{scraperTargetID}/members/{userID}`Remove a member from a scraper target](/influxdb/v2/api/scraper-targets/#operation/DeleteScrapersIDMembersID)[GET`/api/v2/scrapers/{scraperTargetID}/owners`List all owners of a scraper target](/influxdb/v2/api/scraper-targets/#operation/GetScrapersIDOwners)[POST`/api/v2/scrapers/{scraperTargetID}/owners`Add an owner to a scraper target](/influxdb/v2/api/scraper-targets/#operation/PostScrapersIDOwners)[DELETE`/api/v2/scrapers/{scraperTargetID}/owners/{userID}`Remove an owner from a scraper target](/influxdb/v2/api/scraper-targets/#operation/DeleteScrapersIDOwnersID)[GET`/api/v2/setup`Check if database has default user, org, bucket](/influxdb/v2/api/setup/#operation/GetSetup)[POST`/api/v2/setup`Set up initial user, org and bucket](/influxdb/v2/api/setup/#operation/PostSetup)[POST`/api/v2/signin`Create a user session.](/influxdb/v2/api/security-and-access-endpoints/#operation/PostSignin)[POST`/api/v2/signin`Create a user session.](/influxdb/v2/api/signin/#operation/PostSignin)[POST`/api/v2/signout`Expire a user session](/influxdb/v2/api/security-and-access-endpoints/#operation/PostSignout)[POST`/api/v2/signout`Expire a user session](/influxdb/v2/api/signout/#operation/PostSignout)[GET`/api/v2/sources`List all sources](/influxdb/v2/api/sources/#operation/GetSources)[POST`/api/v2/sources`Create a source](/influxdb/v2/api/sources/#operation/PostSources)[DELETE`/api/v2/sources/{sourceID}`Delete a source](/influxdb/v2/api/sources/#operation/DeleteSourcesID)[GET`/api/v2/sources/{sourceID}`Retrieve a source](/influxdb/v2/api/sources/#operation/GetSourcesID)[PATCH`/api/v2/sources/{sourceID}`Update a Source](/influxdb/v2/api/sources/#operation/PatchSourcesID)[GET`/api/v2/sources/{sourceID}/buckets`Get buckets in a source](/influxdb/v2/api/buckets/#operation/GetSourcesIDBuckets)[GET`/api/v2/sources/{sourceID}/buckets`Get buckets in a source](/influxdb/v2/api/sources/#operation/GetSourcesIDBuckets)[GET`/api/v2/sources/{sourceID}/health`Get the health of a source](/influxdb/v2/api/sources/#operation/GetSourcesIDHealth)[GET`/api/v2/stacks`List installed stacks](/influxdb/v2/api/templates/#operation/ListStacks)[POST`/api/v2/stacks`Create a stack](/influxdb/v2/api/templates/#operation/CreateStack)[DELETE`/api/v2/stacks/{stack_id}`Delete a stack and associated resources](/influxdb/v2/api/templates/#operation/DeleteStack)[GET`/api/v2/stacks/{stack_id}`Retrieve a stack](/influxdb/v2/api/templates/#operation/ReadStack)[PATCH`/api/v2/stacks/{stack_id}`Update a stack](/influxdb/v2/api/templates/#operation/UpdateStack)[POST`/api/v2/stacks/{stack_id}/uninstall`Uninstall a stack](/influxdb/v2/api/templates/#operation/UninstallStack)[GET`/api/v2/tasks`List tasks](/influxdb/v2/api/data-i-o-endpoints/#operation/GetTasks)[GET`/api/v2/tasks`List tasks](/influxdb/v2/api/tasks/#operation/GetTasks)[POST`/api/v2/tasks`Create a task](/influxdb/v2/api/data-i-o-endpoints/#operation/PostTasks)[POST`/api/v2/tasks`Create a task](/influxdb/v2/api/tasks/#operation/PostTasks)[DELETE`/api/v2/tasks/{taskID}`Delete a task](/influxdb/v2/api/tasks/#operation/DeleteTasksID)[GET`/api/v2/tasks/{taskID}`Retrieve a task](/influxdb/v2/api/data-i-o-endpoints/#operation/GetTasksID)[GET`/api/v2/tasks/{taskID}`Retrieve a task](/influxdb/v2/api/tasks/#operation/GetTasksID)[PATCH`/api/v2/tasks/{taskID}`Update a task](/influxdb/v2/api/tasks/#operation/PatchTasksID)[GET`/api/v2/tasks/{taskID}/labels`List labels for a task](/influxdb/v2/api/tasks/#operation/GetTasksIDLabels)[POST`/api/v2/tasks/{taskID}/labels`Add a label to a task](/influxdb/v2/api/tasks/#operation/PostTasksIDLabels)[DELETE`/api/v2/tasks/{taskID}/labels/{labelID}`Delete a label from a task](/influxdb/v2/api/tasks/#operation/DeleteTasksIDLabelsID)[GET`/api/v2/tasks/{taskID}/logs`Retrieve all logs for a task](/influxdb/v2/api/tasks/#operation/GetTasksIDLogs)[GET`/api/v2/tasks/{taskID}/members`List all task membersDeprecated](/influxdb/v2/api/tasks/#operation/GetTasksIDMembers)[POST`/api/v2/tasks/{taskID}/members`Add a member to a taskDeprecated](/influxdb/v2/api/tasks/#operation/PostTasksIDMembers)[DELETE`/api/v2/tasks/{taskID}/members/{userID}`Remove a member from a taskDeprecated](/influxdb/v2/api/tasks/#operation/DeleteTasksIDMembersID)[GET`/api/v2/tasks/{taskID}/owners`List all owners of a taskDeprecated](/influxdb/v2/api/tasks/#operation/GetTasksIDOwners)[POST`/api/v2/tasks/{taskID}/owners`Add an owner for a taskDeprecated](/influxdb/v2/api/tasks/#operation/PostTasksIDOwners)[DELETE`/api/v2/tasks/{taskID}/owners/{userID}`Remove an owner from a taskDeprecated](/influxdb/v2/api/tasks/#operation/DeleteTasksIDOwnersID)[GET`/api/v2/tasks/{taskID}/runs`List runs for a task](/influxdb/v2/api/tasks/#operation/GetTasksIDRuns)[POST`/api/v2/tasks/{taskID}/runs`Start a task run, overriding the schedule](/influxdb/v2/api/data-i-o-endpoints/#operation/PostTasksIDRuns)[POST`/api/v2/tasks/{taskID}/runs`Start a task run, overriding the schedule](/influxdb/v2/api/tasks/#operation/PostTasksIDRuns)[DELETE`/api/v2/tasks/{taskID}/runs/{runID}`Cancel a running task](/influxdb/v2/api/tasks/#operation/DeleteTasksIDRunsID)[GET`/api/v2/tasks/{taskID}/runs/{runID}`Retrieve a run for a task.](/influxdb/v2/api/tasks/#operation/GetTasksIDRunsID)[GET`/api/v2/tasks/{taskID}/runs/{runID}/logs`Retrieve all logs for a run](/influxdb/v2/api/tasks/#operation/GetTasksIDRunsIDLogs)[POST`/api/v2/tasks/{taskID}/runs/{runID}/retry`Retry a task run](/influxdb/v2/api/tasks/#operation/PostTasksIDRunsIDRetry)[GET`/api/v2/telegraf/plugins`List all Telegraf plugins](/influxdb/v2/api/telegraf-plugins/#operation/GetTelegrafPlugins)[GET`/api/v2/telegrafs`List all Telegraf configurations](/influxdb/v2/api/telegrafs/#operation/GetTelegrafs)[POST`/api/v2/telegrafs`Create a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/PostTelegrafs)[DELETE`/api/v2/telegrafs/{telegrafID}`Delete a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/DeleteTelegrafsID)[GET`/api/v2/telegrafs/{telegrafID}`Retrieve a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/GetTelegrafsID)[PUT`/api/v2/telegrafs/{telegrafID}`Update a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/PutTelegrafsID)[GET`/api/v2/telegrafs/{telegrafID}/labels`List all labels for a Telegraf config](/influxdb/v2/api/telegrafs/#operation/GetTelegrafsIDLabels)[POST`/api/v2/telegrafs/{telegrafID}/labels`Add a label to a Telegraf config](/influxdb/v2/api/telegrafs/#operation/PostTelegrafsIDLabels)[DELETE`/api/v2/telegrafs/{telegrafID}/labels/{labelID}`Delete a label from a Telegraf config](/influxdb/v2/api/telegrafs/#operation/DeleteTelegrafsIDLabelsID)[GET`/api/v2/telegrafs/{telegrafID}/members`List all users with member privileges for a Telegraf config](/influxdb/v2/api/telegrafs/#operation/GetTelegrafsIDMembers)[POST`/api/v2/telegrafs/{telegrafID}/members`Add a member to a Telegraf config](/influxdb/v2/api/telegrafs/#operation/PostTelegrafsIDMembers)[DELETE`/api/v2/telegrafs/{telegrafID}/members/{userID}`Remove a member from a Telegraf config](/influxdb/v2/api/telegrafs/#operation/DeleteTelegrafsIDMembersID)[GET`/api/v2/telegrafs/{telegrafID}/owners`List all owners of a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/GetTelegrafsIDOwners)[POST`/api/v2/telegrafs/{telegrafID}/owners`Add an owner to a Telegraf configuration](/influxdb/v2/api/telegrafs/#operation/PostTelegrafsIDOwners)[DELETE`/api/v2/telegrafs/{telegrafID}/owners/{userID}`Remove an owner from a Telegraf config](/influxdb/v2/api/telegrafs/#operation/DeleteTelegrafsIDOwnersID)[POST`/api/v2/templates/apply`Apply or dry-run a template](/influxdb/v2/api/templates/#operation/ApplyTemplate)[POST`/api/v2/templates/export`Export a new template](/influxdb/v2/api/templates/#operation/ExportTemplate)[GET`/api/v2/users`List users](/influxdb/v2/api/security-and-access-endpoints/#operation/GetUsers)[GET`/api/v2/users`List users](/influxdb/v2/api/users/#operation/GetUsers)[POST`/api/v2/users`Create a user](/influxdb/v2/api/users/#operation/PostUsers)[DELETE`/api/v2/users/{userID}`Delete a user](/influxdb/v2/api/users/#operation/DeleteUsersID)[GET`/api/v2/users/{userID}`Retrieve a user](/influxdb/v2/api/security-and-access-endpoints/#operation/GetUsersID)[GET`/api/v2/users/{userID}`Retrieve a user](/influxdb/v2/api/users/#operation/GetUsersID)[PATCH`/api/v2/users/{userID}`Update a user](/influxdb/v2/api/users/#operation/PatchUsersID)[POST`/api/v2/users/{userID}/password`Update a password](/influxdb/v2/api/security-and-access-endpoints/#operation/PostUsersIDPassword)[POST`/api/v2/users/{userID}/password`Update a password](/influxdb/v2/api/users/#operation/PostUsersIDPassword)[PUT`/api/v2/users/{userID}/password`Update a password](/influxdb/v2/api/security-and-access-endpoints/#operation/PutUsersIDPassword)[PUT`/api/v2/users/{userID}/password`Update a password](/influxdb/v2/api/users/#operation/PutUsersIDPassword)[GET`/api/v2/variables`List all variables](/influxdb/v2/api/variables/#operation/GetVariables)[POST`/api/v2/variables`Create a variable](/influxdb/v2/api/variables/#operation/PostVariables)[DELETE`/api/v2/variables/{variableID}`Delete a variable](/influxdb/v2/api/variables/#operation/DeleteVariablesID)[GET`/api/v2/variables/{variableID}`Retrieve a variable](/influxdb/v2/api/variables/#operation/GetVariablesID)[PATCH`/api/v2/variables/{variableID}`Update a variable](/influxdb/v2/api/variables/#operation/PatchVariablesID)[PUT`/api/v2/variables/{variableID}`Replace a variable](/influxdb/v2/api/variables/#operation/PutVariablesID)[GET`/api/v2/variables/{variableID}/labels`List all labels for a variable](/influxdb/v2/api/variables/#operation/GetVariablesIDLabels)[POST`/api/v2/variables/{variableID}/labels`Add a label to a variable](/influxdb/v2/api/variables/#operation/PostVariablesIDLabels)[DELETE`/api/v2/variables/{variableID}/labels/{labelID}`Delete a label from a variable](/influxdb/v2/api/variables/#operation/DeleteVariablesIDLabelsID)[POST`/api/v2/write`Write data](/influxdb/v2/api/data-i-o-endpoints/#operation/PostWrite)[POST`/api/v2/write`Write data](/influxdb/v2/api/write/#operation/PostWrite) ## v1-compatible API [GET`/health`Retrieve the health of the instance](/influxdb/v2/api/health/#operation/GetHealth)[GET`/health`Retrieve the health of the instance](/influxdb/v2/api/system-information-endpoints/#operation/GetHealth)[GET`/metrics`Retrieve workload performance metrics](/influxdb/v2/api/metrics/#operation/GetMetrics)[GET`/metrics`Retrieve workload performance metrics](/influxdb/v2/api/system-information-endpoints/#operation/GetMetrics)[GET`/ping`Get the status of the instance](/influxdb/v2/api/ping/#operation/GetPing)[GET`/ping`Get the status of the instance](/influxdb/v2/api/system-information-endpoints/#operation/GetPing)[HEAD`/ping`Get the status of the instance](/influxdb/v2/api/ping/#operation/HeadPing)[GET`/query`Query with the 1.x compatibility API](/influxdb/v2/api/legacy-query/#operation/GetLegacyQuery)[POST`/write`Write time series data into InfluxDB in a V1-compatible format](/influxdb/v2/api/legacy-write/#operation/PostLegacyWrite) ## Management API [GET`/debug/pprof/all`Retrieve all runtime profiles](/influxdb/v2/api/debug/#operation/GetDebugPprofAllProfiles)[GET`/debug/pprof/all`Retrieve all runtime profiles](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofAllProfiles)[GET`/debug/pprof/allocs`Retrieve the memory allocations runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofAllocs)[GET`/debug/pprof/allocs`Retrieve the memory allocations runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofAllocs)[GET`/debug/pprof/block`Retrieve the block runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofBlock)[GET`/debug/pprof/block`Retrieve the block runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofBlock)[GET`/debug/pprof/cmdline`Retrieve the command line invocation](/influxdb/v2/api/debug/#operation/GetDebugPprofCmdline)[GET`/debug/pprof/cmdline`Retrieve the command line invocation](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofCmdline)[GET`/debug/pprof/goroutine`Retrieve the goroutines runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofGoroutine)[GET`/debug/pprof/goroutine`Retrieve the goroutines runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofGoroutine)[GET`/debug/pprof/heap`Retrieve the heap runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofHeap)[GET`/debug/pprof/heap`Retrieve the heap runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofHeap)[GET`/debug/pprof/mutex`Retrieve the mutual exclusion (mutex) runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofMutex)[GET`/debug/pprof/mutex`Retrieve the mutual exclusion (mutex) runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofMutex)[GET`/debug/pprof/profile`Retrieve the CPU runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofProfile)[GET`/debug/pprof/profile`Retrieve the CPU runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofProfile)[GET`/debug/pprof/threadcreate`Retrieve the threadcreate runtime profile](/influxdb/v2/api/debug/#operation/GetDebugPprofThreadCreate)[GET`/debug/pprof/threadcreate`Retrieve the threadcreate runtime profile](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofThreadCreate)[GET`/debug/pprof/trace`Retrieve the runtime execution trace](/influxdb/v2/api/debug/#operation/GetDebugPprofTrace)[GET`/debug/pprof/trace`Retrieve the runtime execution trace](/influxdb/v2/api/system-information-endpoints/#operation/GetDebugPprofTrace)[GET`/legacy/authorizations`List all legacy authorizations](/influxdb/v2/api/legacy-authorizations/#operation/GetLegacyAuthorizations)[POST`/legacy/authorizations`Create a legacy authorization](/influxdb/v2/api/legacy-authorizations/#operation/PostLegacyAuthorizations)[DELETE`/legacy/authorizations/{authID}`Delete a legacy authorization](/influxdb/v2/api/legacy-authorizations/#operation/DeleteLegacyAuthorizationsID)[GET`/legacy/authorizations/{authID}`Retrieve a legacy authorization](/influxdb/v2/api/legacy-authorizations/#operation/GetLegacyAuthorizationsID)[PATCH`/legacy/authorizations/{authID}`Update a legacy authorization to be active or inactive](/influxdb/v2/api/legacy-authorizations/#operation/PatchLegacyAuthorizationsID)[POST`/legacy/authorizations/{authID}/password`Set a legacy authorization password](/influxdb/v2/api/legacy-authorizations/#operation/PostLegacyAuthorizationsIDPassword)[GET`/ready`Get the readiness of an instance at startup](/influxdb/v2/api/ready/#operation/GetReady)[GET`/ready`Get the readiness of an instance at startup](/influxdb/v2/api/system-information-endpoints/#operation/GetReady) --- # Authentication Source: https://docs.influxdata.com/influxdb/v2/api/authentication/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Use one of the following schemes to authenticate to the InfluxDB OSS v2 API: * Token authentication * Basic authentication * Querystring authentication ## Basic Authentication ### Basic authentication scheme Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it: ### Syntax `Authorization: Basic BASE64_ENCODED_CREDENTIALS` To construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and the password with a colon (`USERNAME:PASSWORD`), and then encode the resulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64). Many HTTP clients encode the credentials for you before sending the request. ***Warning**: Base64-encoding can easily be reversed to obtain the original username and password. It is used to keep the data intact and does not provide security. You should always use HTTPS when authenticating or sending a request with sensitive information.* ### Examples In the examples, replace the following: * **`USERNAME`**: InfluxDB username * **`PASSWORD`**: InfluxDB [API token](/influxdb/v2/reference/glossary/#token) * **`INFLUX_URL`**: your InfluxDB URL #### Encode credentials with cURL The following example shows how to use cURL to send an API request that uses Basic authentication. With the `--user` option, cURL encodes the credentials and passes them in the `Authorization: Basic` header. ```sh curl --get "INFLUX_URL/api/v2/signin" --user "USERNAME":"PASSWORD" ``` #### Encode credentials with Flux The Flux [`http.basicAuth()` function](/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded basic authentication header using a specified username and password combination. #### Encode credentials with JavaScript The following example shows how to use the JavaScript `btoa()` function to create a Base64-encoded string: ```js btoa('USERNAME:PASSWORD') ``` The output is the following: ```js 'VVNFUk5BTUU6UEFTU1dPUkQ=' ``` Once you have the Base64-encoded credentials, you can pass them in the`Authorization` header–for example: ```sh curl --get "INFLUX_URL/api/v2/signin" --header "Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ=" ``` To learn more about HTTP authentication, see[Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).\_ ## Token Authentication Use the [Token authentication](#section/Authentication/TokenAuthentication)scheme to authenticate to the InfluxDB API. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. ### Syntax `Authorization: Token INFLUX_API_TOKEN` ### Example #### Use Token authentication with cURL The following example shows how to use cURL to send an API request that uses Token authentication: ```sh curl --request GET "INFLUX_URL/api/v2/buckets" \ --header "Authorization: Token INFLUX_API_TOKEN" ``` Replace the following: * *`INFLUX_URL`*: your InfluxDB URL * *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/v2/reference/glossary/#token) ### Related endpoints * [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides * [Authorize API requests](/influxdb/v2/api-guide/api_intro/#authentication) * [Manage API tokens](/influxdb/v2/security/tokens/) --- # Authorizations (API tokens) Source: https://docs.influxdata.com/influxdb/v2/api/authorizations-api-tokens/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage API token authorizations that grant read and write permissions to InfluxDB OSS v2 organization resources. GET`/api/v2/authorizations` ### List authorizations Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. #### InfluxDB Cloud * InfluxDB Cloud doesn’t expose [API token](/influxdb/v2/reference/glossary/#token)values in `GET /api/v2/authorizations` responses; returns `token: redacted` for all authorizations. #### Required permissions To retrieve an authorization, the request must use an API token that has the following permissions: * `read-authorizations` * `read-user` for the user that the authorization is scoped to #### Related guides * [View tokens](/influxdb/v2/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `token`string An API [token](/influxdb/v2/reference/glossary/#token) value. Specifies an authorization by its `token` property value and returns the authorization. #### InfluxDB OSS * Doesn’t support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. #### Limitations * The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn’t exist, then the response body contains an empty list. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains a list of authorizations. If the response body is missing authorizations that you expect, check that the API token used in the request has `read-user` permission for the users (`userID` property value) in those authorizations. #### InfluxDB OSS * **Warning**: The response body contains authorizations with their[API token](/influxdb/v2/reference/glossary/#token) values in clear text. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. `authorizations`object[] `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/v2/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/v2/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/v2/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx`CLI commands–after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/authorizations` ### Create an authorization Creates an authorization and returns the authorization with the generated API [token](/influxdb/v2/reference/glossary/#token). Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. The API token is the authorization’s `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. * InfluxDB allows access to the API token value immediately after the authorization is created. * You can’t change access (read/write) permissions for an API token after it’s created. * Tokens stop working when the user who created the token is deleted. We recommend the following for managing your tokens: * Create a generic user to create and manage tokens for writing data. * Store your tokens in a secure password vault for future access. #### Required permissions * `write-authorizations` * `write-user` for the user that the authorization is scoped to #### Related guides * [Create a token](/influxdb/v2/security/tokens/create-token/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The authorization to create. Content-Type:`application/json` `description`string A description of the token. `orgID`requiredstring An organization ID. Specifies the organization that owns the authorization. `permissions`requiredobject[] A list of permissions for an authorization. In the list, provide at least one `permission` object. In a `permission`, the `resource.type` property grants access to all resources of the specified type. To grant access to only a specific resource, specify the`resource.id` property. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `id`string A resource ID. Identifies a specific resource. `name`string The name of the resource.*Note: not all resource types have a `name` property*. `org`string An organization name. The organization that owns the resource. `orgID`string An organization ID. Identifies the organization that owns the resource. `type`requiredstring A resource type. Identifies the API resource’s type (or *kind*). Allowed:`authorizations`, `buckets`, `dashboards`, `orgs`, `tasks`, `telegrafs`, `users`, `variables`, `secrets`, `labels`, `views`, `documents`, `notificationRules`, `notificationEndpoints`, `checks`, `dbrp`, `annotations`, `sources`, `scrapers`, `notebooks`, `remotes`, `replications`, `instance`, `flows`, `functions`, `subscriptions` `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `userID`string A user ID. Specifies the user that the authorization is scoped to. When a user authenticates with username and password, InfluxDB generates a *user session* with all the permissions specified by all the user’s authorizations. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "orgID": "ORGID", "permissions": [ { "action": "read", "resource": {} } ], "status": "active", "userID": "USERID" }' ``` #### Responses 201Success. The authorization is created. The response body contains the authorization. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/authorizations/{authID}` ### Retrieve an authorization Retrieves an authorization. Use this endpoint to retrieve information about an API token, including the token’s permissions and the user that the token is scoped to. #### InfluxDB OSS * InfluxDB OSS returns[API token](/influxdb/v2/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides * [View tokens](/influxdb/v2/security/tokens/view-tokens/) #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the authorization. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/authorizations/{authID}` ### Update an API token to be active or inactive Updates an authorization. Use this endpoint to set an API token’s status to be *active* or *inactive*. InfluxDB rejects requests that use inactive API tokens. #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired In the request body, provide the authorization properties to update. Content-Type:`application/json` `description`string A description of the token. `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "status": "active" }' ``` #### Responses 200Success. The response body contains the updated authorization. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/authorizations/{authID}` ### Delete an authorization Deletes an authorization. Use the endpoint to delete an API token. If you want to disable an API token instead of delete it,[update the authorization’s status to `inactive`](#operation/PatchAuthorizationsID). #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The authorization is deleted. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Manage API tokens](/influxdb/v2/security/tokens/) * [View tokens](/influxdb/v2/security/tokens/view-tokens/) --- # Backup Source: https://docs.influxdata.com/influxdb/v2/api/backup/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Back up InfluxDB OSS v2 data, including time series data and metadata, for use in restore operations. GET`/api/v2/backup/kv`Deprecated ### Download snapshot of metadata stored in the server's embedded KV store. Don't use with InfluxDB versions greater than InfluxDB 2.1.x. Retrieves a snapshot of metadata stored in the server’s embedded KV store. InfluxDB versions greater than 2.1.x don’t include metadata stored in embedded SQL; avoid using this endpoint with versions greater than 2.1.x. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/backup/kv" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response contains a snapshot of KV metadata. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/backup/metadata` ### Download snapshot of all metadata in the server #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept-Encoding`string Indicates the content encoding (usually a compression algorithm) that the client can understand. Allowed values:`gzip`, `identity` Default:`identity` Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/backup/metadata" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Snapshot of metadata defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/backup/shards/{shardID}` ### Download snapshot of all TSM data in a shard #### Parameters ##### Path parameters `shardID`requiredinteger \ The shard ID. ##### Query parameters `since`string \ The earliest time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) to include in the snapshot. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept-Encoding`string Indicates the content encoding (usually a compression algorithm) that the client can understand. Allowed values:`gzip`, `identity` Default:`identity` `Gzip-Compression-Level`string The gzip compression level to use when compressing the response. Allowed values:`none`, `default`, `speedy`, `full` Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/backup/shards/{shardID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200TSM snapshot. 404Shard not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Buckets Source: https://docs.influxdata.com/influxdb/v2/api/buckets/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage named storage locations (buckets) in InfluxDB OSS v2, each with a configurable retention period. GET`/api/v2/buckets` ### List buckets Lists [buckets](/influxdb/v2/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the[organization](/influxdb/v2/reference/glossary/#organization)associated with the authorization ([API token](/influxdb/v2/reference/glossary/#token)). To limit which buckets are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all buckets up to the default `limit`. #### InfluxDB OSS * If you use an *[operator token](/influxdb/v2/security/tokens/#operator-token)*to authenticate your request, InfluxDB retrieves resources for *all organizations* in the instance. To retrieve resources for only a specific organization, use the`org` parameter or the `orgID` parameter to specify the organization. #### Required permissions | Action |Permission required| |-----------------------------------------------------------------------------|-------------------| | Retrieve *user buckets* | `read-buckets` | |Retrieve [*system buckets*](/influxdb/v2/reference/internals/system-buckets/)| `read-orgs` | #### Related Guides * [Manage buckets](/influxdb/v2/organizations/buckets/) #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `after`string A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `org`string An organization name. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Lists buckets for the organization associated with the authorization (API token). #### InfluxDB OSS * Lists buckets for the specified organization. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Lists buckets for the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or `orgID` parameter. * Lists buckets for the specified organization. `name`string A bucket name. Only returns buckets with the specified name. `id`string A bucket ID. Only returns the bucket with the specified ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/buckets" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of `buckets`. `buckets`object[] `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/buckets` ### Create a bucket Creates a [bucket](/influxdb/v2/reference/glossary/#bucket)and returns the bucket resource. The default data[retention period](/influxdb/v2/reference/glossary/#retention-period)is 30 days. #### InfluxDB OSS * A single InfluxDB OSS instance supports active writes or queries for approximately 20 buckets across all organizations at a given time. Reading or writing to more than 20 buckets at a time can adversely affect performance. #### Limitations * InfluxDB Cloud Free Plan allows users to create up to two buckets. Exceeding the bucket quota will result in an HTTP `403` status code. For additional information regarding InfluxDB Cloud offerings, see[InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). #### Related Guides * [Create a bucket](/influxdb/v2/organizations/buckets/create-bucket/) * [Create bucket CLI reference](/influxdb/v2/reference/cli/influx/bucket/create) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The bucket to create. Content-Type:`application/json` `description`string A description of the bucket. `name`requiredstring The bucket name. `orgID`requiredstring The organization ID. Specifies the organization that owns the bucket. `retentionRules`object[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string The retention policy for the bucket. For InfluxDB 1.x, specifies the duration of time that each data point in the retention policy persists. If you need compatibility with InfluxDB 1.x, specify a value for the `rp` property; otherwise, see the `retentionRules` property. [Retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp)is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is[retention period](/influxdb/v2/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. Default:`0` `schemaType`string Allowed:`implicit`, `explicit` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/buckets" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "orgID": "ORGID", "retentionRules": [ { "everySeconds": 86400, "shardGroupDurationSeconds": 0, "type": "expire" } ], "rp": "0", "schemaType": "implicit" }' ``` #### Responses 201Success. The bucket is created. `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 403Forbidden. The bucket quota is exceeded. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 422Unprocessable Entity. The request body failed validation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/buckets/{bucketID}` ### Retrieve a bucket Retrieves a bucket. Use this endpoint to retrieve information for a specific bucket. #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/buckets/{bucketID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the bucket information. `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. Bucket not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/buckets/{bucketID}` ### Update a bucket Updates a bucket. Use this endpoint to update properties (`name`, `description`, and `retentionRules`) of a bucket. #### InfluxDB Cloud * Requires the `retentionRules` property in the request body. If you don’t provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. #### InfluxDB OSS * Doesn’t require `retentionRules`. #### Related Guides * [Update a bucket](/influxdb/v2/organizations/buckets/update-bucket/) #### Parameters ##### Path parameters `bucketID`requiredstring The bucket ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The bucket update to apply. Content-Type:`application/json` `description`string A description of the bucket. `name`string The name of the bucket. `retentionRules`object[] Updates to rules to expire or retain data. No rules means no updates. `everySeconds`requiredinteger \ The number of seconds to keep data. Default duration is `2592000` (30 days).`0` represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The [shard group duration](/influxdb/v2/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud * Doesn’t use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the [bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). #### Related guides * InfluxDB [shards and shard groups](/influxdb/v2/reference/internals/shards/) `type`string Allowed:`expire` Default:`expire` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/buckets/{bucketID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "retentionRules": [ { "everySeconds": 86400, "shardGroupDurationSeconds": 0, "type": "expire" } ] }' ``` #### Responses 200An updated bucket `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ 400Bad Request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 403Forbidden. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 404Not found. Bucket not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/buckets/{bucketID}` ### Delete a bucket Deletes a bucket and all associated records. #### InfluxDB Cloud * Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. Returns an HTTP `204` status code if queued; *error* otherwise. 3. Handles the delete asynchronously. #### InfluxDB OSS * Validates the request, handles the delete synchronously, and then responds with success or failure. #### Limitations * Only one bucket can be deleted per request. #### Related Guides * [Delete a bucket](/influxdb/v2/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) #### Parameters ##### Path parameters `bucketID`requiredstring Bucket ID. The ID of the bucket to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/buckets/{bucketID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Success. #### InfluxDB Cloud * The bucket is queued for deletion. #### InfluxDB OSS * The bucket is deleted. 400Bad Request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. Bucket not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/buckets/{bucketID}/labels` ### List all labels for a bucket Lists all labels for a bucket. Labels are objects that contain `labelID`, `name`, `description`, and `color`key-value pairs. They may be used for grouping and filtering InfluxDB resources. Labels are also capable of grouping across different resources–for example, you can apply a label named `air_sensor` to a bucket and a task to quickly organize resources. #### Related guides * Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. * [Manage labels in the InfluxDB UI](/influxdb/v2/visualize-data/labels/) #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to retrieve labels for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/buckets/{bucketID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all labels for the bucket. `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/buckets/{bucketID}/labels` ### Add a label to a bucket Adds a label to a bucket and returns the new label information. Labels are objects that contain `labelID`, `name`, `description`, and `color`key-value pairs. They may be used for grouping and filtering across one or more kinds of **resources**–for example, you can apply a label named`air_sensor` to a bucket and a task to quickly organize resources. #### Limitations * Before adding a label to a bucket, you must create the label if you haven’t already. To create a label with the InfluxDB API, send a `POST`request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). #### Related guides * Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. * [Manage labels in the InfluxDB UI](/influxdb/v2/visualize-data/labels/) #### Parameters ##### Path parameters `bucketID`requiredstring Bucket ID. The ID of the bucket to label. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired An object that contains a *`labelID`* to add to the bucket. Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/buckets/{bucketID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201Success. The response body contains the label information. `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 422Unprocessable entity. Label already exists on the resource. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/buckets/{bucketID}/labels/{labelID}` ### Delete a label from a bucket #### Parameters ##### Path parameters `bucketID`requiredstring The bucket ID. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/buckets/{bucketID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Bucket not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/buckets/{bucketID}/members` ### List all users with member privileges for a bucket Lists all users for a bucket. InfluxDB [users](/influxdb/v2/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/v2/reference/glossary/#member) are users in an organization with access to the specified resource. Use this endpoint to retrieve all users with access to a bucket. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to retrieve users for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/buckets/{bucketID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all users for the bucket. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/buckets/{bucketID}/members` ### Add a member to a bucket Add a user to a bucket and return the new user information. InfluxDB [users](/influxdb/v2/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/v2/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to retrieve users for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A user to add as a member to the bucket. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/buckets/{bucketID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Success. The response body contains the user information. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/buckets/{bucketID}/members/{userID}` ### Remove a member from a bucket Removes a member from a bucket. Use this endpoint to remove a user’s member privileges from a bucket. This removes the user’s `read` and `write` permissions for the bucket. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to remove. `bucketID`requiredstring The ID of the bucket to remove a user from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/buckets/{bucketID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer a member of the bucket. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/buckets/{bucketID}/owners` ### List all owners of a bucket Lists all [owners](/influxdb/v2/reference/glossary/#owner)of a bucket. Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Owner permissions are separate from API token permissions. * Owner permissions are used in the context of the InfluxDB UI. #### Required permissions * `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a list of owners for. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides * [Manage users](/influxdb/v2/users/) #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to retrieve owners for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/buckets/{bucketID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all owners for the bucket. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/buckets/{bucketID}/owners` ### Add an owner to a bucket Adds an owner to a bucket and returns the [owners](/influxdb/v2/reference/glossary/#owner)with role and user detail. Use this endpoint to create a *resource owner* for the bucket. Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Owner permissions are separate from API token permissions. * Owner permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID`*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides * [Manage users](/influxdb/v2/users/) #### Parameters ##### Path parameters `bucketID`requiredstring The ID of the bucket to add an owner for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A user to add as an owner for the bucket. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/buckets/{bucketID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Created. The bucket `owner` role is assigned to the user. The response body contains the resource owner with role and user detail. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/buckets/{bucketID}/owners/{userID}` ### Remove an owner from a bucket Removes an owner from a bucket. Use this endpoint to remove a user’s `owner` role for a bucket. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Owner permissions are separate from API token permissions. * Owner permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides * [Manage users](/influxdb/v2/users/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the owner to remove. `bucketID`requiredstring The ID of the bucket to remove an owner from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/buckets/{bucketID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer an owner of the bucket. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/sources/{sourceID}/buckets` ### Get buckets in a source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Query parameters `org`string The name of the organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/sources/{sourceID}/buckets" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A source `buckets`object[] `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 404Source not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Manage buckets](/influxdb/v2/organizations/buckets/) | Action | Permission required | | --- | --- | | Action | Permission required | | Retrieve user buckets | read-buckets | | Retrieve system buckets | read-orgs | --- # Cells Source: https://docs.influxdata.com/influxdb/v2/api/cells/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Manage cells within InfluxDB OSS v2 dashboards. POST`/api/v2/dashboards/{dashboardID}/cells` ### Create a dashboard cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Cell that will be added Content-Type:`application/json` `h`integer \ `name`string `usingView`string Makes a copy of the provided view. `w`integer \ `x`integer \ `y`integer \ Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "h": 0, "name": "NAME", "usingView": "USINGVIEW", "w": 0, "x": 0, "y": 0 }' ``` #### Responses 201Cell successfully added `h`integer \ `id`string `links`object `self`string `view`string `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/dashboards/{dashboardID}/cells` ### Replace cells in a dashboard Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Replaced dashboard cells 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}` ### Update the non-positional information related to a cell Updates the non positional information related to a cell. Updates to a single cell’s positional data could cause grid conflicts. #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. `cellID`requiredstring The ID of the cell to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `h`integer \ `w`integer \ `x`integer \ `y`integer \ Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "h": 0, "w": 0, "x": 0, "y": 0 }' ``` #### Responses 200Updated dashboard cell `h`integer \ `id`string `links`object `self`string `view`string `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}` ### Delete a dashboard cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to delete. `cellID`requiredstring The ID of the cell to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Cell successfully deleted 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Retrieve the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. `cellID`requiredstring The cell ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A dashboard cells view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Update the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. `cellID`requiredstring The ID of the cell to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "links": { "self": "SELF" }, "name": "NAME", "properties": { "adaptiveZoomHide": false, "axes": {}, "colors": [], "decimalPlaces": {}, "generateXAxisTicks": [], "generateYAxisTicks": [], "hoverDimension": "auto", "legendColorizeRows": false, "legendHide": false, "legendOpacity": 0, "legendOrientationThreshold": 0, "note": "NOTE", "position": "overlaid", "prefix": "PREFIX", "queries": [], "shadeBelow": false, "shape": "chronograf-v2", "showNoteWhenEmpty": false, "staticLegend": {}, "suffix": "SUFFIX", "timeFormat": "TIMEFORMAT", "type": "line-plus-single-stat", "xColumn": "XCOLUMN", "xTickStart": 0, "xTickStep": 0, "xTotalTicks": 0, "yColumn": "YCOLUMN", "yTickStart": 0, "yTickStep": 0, "yTotalTicks": 0 } }' ``` #### Responses 200Updated cell view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Checks Source: https://docs.influxdata.com/influxdb/v2/api/checks/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB OSS v2. GET`/api/v2/checks` ### List all checks #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `orgID`requiredstring Only show checks that belong to a specific organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/checks?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of checks `checks`object[] `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/checks` ### Add new check #### Request bodyrequired Check to create Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/checks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Check created defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/checks/{checkID}` ### Retrieve a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/checks/{checkID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The check requested defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/checks/{checkID}` ### Update a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Check update to apply Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/checks/{checkID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200An updated check 404The check was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/checks/{checkID}` ### Update a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Check update to apply Content-Type:`application/json` `description`string `name`string `status`string Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/checks/{checkID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "status": "active" }' ``` #### Responses 200An updated check 404The check was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/checks/{checkID}` ### Delete a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/checks/{checkID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404The check was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/checks/{checkID}/labels` ### List all labels for a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/checks/{checkID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a check `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/checks/{checkID}/labels` ### Add a label to a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/checks/{checkID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The label was added to the check `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/checks/{checkID}/labels/{labelID}` ### Delete label from a check #### Parameters ##### Path parameters `checkID`requiredstring The check ID. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/checks/{checkID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Check or label not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/checks/{checkID}/query` ### Retrieve a check query #### Parameters ##### Path parameters `checkID`requiredstring The check ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/checks/{checkID}/query" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The check query requested `flux`string 400Invalid request `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 404Check not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Common parameters Source: https://docs.influxdata.com/influxdb/v2/api/common-parameters/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Most InfluxDB OSS v2 API endpoints require parameters in the request–for example, to specify the bucket or organization. The following table shows common query parameters used by many InfluxDB OSS v2 API endpoints. |Query parameter|Value type| Description | |---------------|----------|-------------------------------------------| | `bucket` | string | The bucket name. | | `bucketID` | string | The bucket ID. | | `org` | string | The organization name. | | `orgID` | string | The organization ID. | | `precision` | string |Timestamp precision: `ns`, `us`, `ms`, `s`.| | `db` | string |The database (for v1-compatible endpoints).| | Query parameter | Value type | Description | | --- | --- | --- | | Query parameter | Value type | Description | | bucket | string | The bucket name. | | bucketID | string | The bucket ID. | | org | string | The organization name. | | orgID | string | The organization ID. | | precision | string | Timestamp precision: ns , us , ms , s . | | db | string | The database (for v1-compatible endpoints). | --- # Compatibility endpoints Source: https://docs.influxdata.com/influxdb/v2/api/compatibility-endpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) InfluxDB v1-compatible API endpoints for backward compatibility with InfluxDB 1.x clients, tools, and integrations such as Grafana and Telegraf. --- # Config Source: https://docs.influxdata.com/influxdb/v2/api/config/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve configuration information for an InfluxDB OSS v2 instance. GET`/api/v2/config` ### Retrieve runtime configuration Returns the active runtime configuration of the InfluxDB instance. In InfluxDB v2.2+, use this endpoint to view your active runtime configuration, including flags and environment variables. #### Related guides * [View your runtime server configuration](/influxdb/v2/reference/config-options/#view-your-runtime-server-configuration) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/config" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the active runtime configuration of the InfluxDB instance. `config`object 401Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/flags` ### Retrieve feature flags Retrieves the feature flag key-value pairs configured for the InfluxDB instance.*Feature flags* are configuration options used to develop and test experimental InfluxDB features and are intended for internal use only. This endpoint represents the first step in the following three-step process to configure feature flags: 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve feature flags and their values. 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/v2/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: * Send a request to this endpoint to retrieve the current feature flag values. * Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the current runtime server configuration. #### Related guides * [InfluxDB configuration options](/influxdb/v2/reference/config-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/flags" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains feature flags. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Dashboards Source: https://docs.influxdata.com/influxdb/v2/api/dashboards/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage dashboards in InfluxDB OSS v2. GET`/api/v2/dashboards` ### List dashboards Lists [dashboards](/influxdb/v2/reference/glossary/#dashboard). #### Related guides * [Manage dashboards](/influxdb/v2/visualize-data/dashboards/). #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `descending`boolean `owner`string A user ID. Only returns [dashboards](/influxdb/v2/reference/glossary/#dashboard) where the specified user has the `owner` role. `sortBy`string The column to sort by. Allowed values:`ID`, `CreatedAt`, `UpdatedAt` `id`array A list of dashboard IDs. Returns only the specified [dashboards](/influxdb/v2/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. `orgID`string An organization ID. Only returns [dashboards](/influxdb/v2/reference/glossary/#dashboard) that belong to the specified[organization](/influxdb/v2/reference/glossary/#organization). `org`string An organization name. Only returns [dashboards](/influxdb/v2/reference/glossary/#dashboard) that belong to the specified[organization](/influxdb/v2/reference/glossary/#organization). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains dashboards. `dashboards`object[] `cells`object[] `h`integer \ `id`string `links`object `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ `description`string The user-facing description of the dashboard. `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"cells":"/api/v2/dashboards/1/cells","labels":"/api/v2/dashboards/1/labels","members":"/api/v2/dashboards/1/members","org":"/api/v2/labels/1","owners":"/api/v2/dashboards/1/owners","self":"/api/v2/dashboards/1"}` `cells`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `meta`object `createdAt`string \ `updatedAt`string \ `name`requiredstring The user-facing name of the dashboard. `orgID`requiredstring The ID of the organization that owns the dashboard. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dashboards` ### Create a dashboard #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Dashboard to create Content-Type:`application/json` `description`string The user-facing description of the dashboard. `name`requiredstring The user-facing name of the dashboard. `orgID`requiredstring The ID of the organization that owns the dashboard. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "orgID": "ORGID" }' ``` #### Responses 201Success. The dashboard is created. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}` ### Retrieve a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Query parameters `include`string If `properties`, includes the cell view properties in the response. Allowed values:`properties` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Retrieve a single dashboard 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}` ### Update a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Patching of a dashboard Content-Type:`application/json` `cells`object `h`integer \ `id`string `links`object `self`string `view`string `name`string `properties`object or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `colors`requiredobject[] Colors define color encoding of data into a visualization `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `colors`requiredobject[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `colors`object[] Colors define color encoding of data into a visualization `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ `description`string optional, when provided will replace the description `name`string optional, when provided will replace the name Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cells": { "h": 0, "id": "ID", "links": { "self": "SELF", "view": "VIEW" }, "name": "NAME", "properties": {}, "viewID": "VIEWID", "w": 0, "x": 0, "y": 0 }, "description": "DESCRIPTION", "name": "NAME" }' ``` #### Responses 200Updated dashboard 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}` ### Delete a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dashboards/{dashboardID}/cells` ### Create a dashboard cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Cell that will be added Content-Type:`application/json` `h`integer \ `name`string `usingView`string Makes a copy of the provided view. `w`integer \ `x`integer \ `y`integer \ Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "h": 0, "name": "NAME", "usingView": "USINGVIEW", "w": 0, "x": 0, "y": 0 }' ``` #### Responses 201Cell successfully added `h`integer \ `id`string `links`object `self`string `view`string `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/dashboards/{dashboardID}/cells` ### Replace cells in a dashboard Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Replaced dashboard cells 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}` ### Update the non-positional information related to a cell Updates the non positional information related to a cell. Updates to a single cell’s positional data could cause grid conflicts. #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. `cellID`requiredstring The ID of the cell to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `h`integer \ `w`integer \ `x`integer \ `y`integer \ Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "h": 0, "w": 0, "x": 0, "y": 0 }' ``` #### Responses 200Updated dashboard cell `h`integer \ `id`string `links`object `self`string `view`string `viewID`string The reference to a view from the views API. `w`integer \ `x`integer \ `y`integer \ 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}` ### Delete a dashboard cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to delete. `cellID`requiredstring The ID of the cell to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Cell successfully deleted 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Retrieve the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. `cellID`requiredstring The cell ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A dashboard cells view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Update the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. `cellID`requiredstring The ID of the cell to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "links": { "self": "SELF" }, "name": "NAME", "properties": { "adaptiveZoomHide": false, "axes": {}, "colors": [], "decimalPlaces": {}, "generateXAxisTicks": [], "generateYAxisTicks": [], "hoverDimension": "auto", "legendColorizeRows": false, "legendHide": false, "legendOpacity": 0, "legendOrientationThreshold": 0, "note": "NOTE", "position": "overlaid", "prefix": "PREFIX", "queries": [], "shadeBelow": false, "shape": "chronograf-v2", "showNoteWhenEmpty": false, "staticLegend": {}, "suffix": "SUFFIX", "timeFormat": "TIMEFORMAT", "type": "line-plus-single-stat", "xColumn": "XCOLUMN", "xTickStart": 0, "xTickStep": 0, "xTotalTicks": 0, "yColumn": "YCOLUMN", "yTickStart": 0, "yTickStep": 0, "yTotalTicks": 0 } }' ``` #### Responses 200Updated cell view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}/labels` ### List all labels for a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a dashboard `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dashboards/{dashboardID}/labels` ### Add a label to a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The label added to the dashboard `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}/labels/{labelID}` ### Delete a label from a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}/members` ### List all dashboard members #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of users who have member privileges for a dashboard `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dashboards/{dashboardID}/members` ### Add a member to a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as member Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Added to dashboard members defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}/members/{userID}` ### Remove a member from a dashboard #### Parameters ##### Path parameters `userID`requiredstring The ID of the member to remove. `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Member removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dashboards/{dashboardID}/owners` ### List all dashboard owners #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of users who have owner privileges for a dashboard `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dashboards/{dashboardID}/owners` ### Add an owner to a dashboard #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as owner Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Added to dashboard owners defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dashboards/{dashboardID}/owners/{userID}` ### Remove an owner from a dashboard #### Parameters ##### Path parameters `userID`requiredstring The ID of the owner to remove. `dashboardID`requiredstring The dashboard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Owner removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Data I/O endpoints Source: https://docs.influxdata.com/influxdb/v2/api/data-i-o-endpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) POST`/api/v2/delete` ### Delete data Deletes data from a bucket. Use this endpoint to delete points from a bucket in a specified time range. #### InfluxDB Cloud * Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. If queued, responds with *success* (HTTP `2xx` status code); *error* otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS * Validates the request, handles the delete synchronously, and then responds with success or failure. #### Required permissions * `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Delete data](/influxdb/v2/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). * Learn how InfluxDB handles [deleted tags](/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/)and [deleted fields](/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). #### Parameters ##### Query parameters `org`string An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * Deletes data from the bucket in the specified organization. * If you pass both `orgID` and `org`, they must both be valid. `bucket`string A bucket name or ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * Deletes data from the bucket in the specified organization. * If you pass both `orgID` and `org`, they must both be valid. `bucketID`string A bucket ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Time range parameters and an optional **delete predicate expression**. To select points to delete within the specified time range, pass a**delete predicate expression** in the `predicate` property of the request body. If you don’t pass a `predicate`, InfluxDB deletes all data with timestamps in the specified time range. #### Related guides * [Delete data](/influxdb/v2/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). Content-Type:`application/json` `predicate`string An expression in [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). Example:`"tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"` `start`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. `stop`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/delete" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")", "start": "START", "stop": "STOP" }' ``` #### Responses 204 Success. #### InfluxDB Cloud * Validated and queued the request. * Handles the delete asynchronously - the deletion might not have completed yet. An HTTP `2xx` status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request. Because writes are asynchronous, data might not yet be written when you receive the response. #### InfluxDB OSS * Deleted the data. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/query` ### Query data Retrieves data from buckets. Use this endpoint to send a Flux query request and retrieve data from a bucket. #### Rate limits (with InfluxDB Cloud) `read` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Query with the InfluxDB API](/influxdb/v2/query-data/execute-queries/influx-api/) * [Get started with Flux](/flux/v0.x/get-started/) #### Parameters ##### Query parameters `org`string An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or `orgID` parameter. * Queries the bucket in the specified organization. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or `orgID` parameter. * Queries the bucket in the specified organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept-Encoding`string The content encoding (usually a compression algorithm) that the client can understand. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/json`, `application/vnd.flux` #### Request body Flux query or specification to execute Content-Type:`application/json` `dialect`object Options for tabular data output. Default output is [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). `annotations`string[] Annotation rows to include in the results. An *annotation* is metadata associated with an object (column) in the data model. #### Related guides * See [Annotated CSV annotations](/influxdb/v2/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). `commentPrefix`string The character prefixed to comment strings. Default is a number sign (`#`). Default:`#` `dateTimeFormat`string The format for timestamps in results. Default is [`RFC3339` date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values | Format | Value | |-------------|---------------------------------------| | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | |`RFC3339Nano`|`"2006-01-02T15:04:05.999999999Z07:00"`| Allowed:`RFC3339`, `RFC3339Nano` Default:`RFC3339` `delimiter`string The separator used between cells. Default is a comma (`,`). Default:`,` `header`boolean If true, the results contain a header row. Default:`true` `extern`object Represents a source from a single file `body`object[] List of Flux statements `imports`object[] A list of package imports `as`object A valid Flux identifier `path`object Expressions begin and end with double quote marks `type`string Type of AST node `name`string The name of the file. `package`object Defines a package identifier `name`object A valid Flux identifier `type`string Type of AST node `type`string Type of AST node `now`string \ Specifies the time that should be reported as `now` in the query. Default is the server `now` time. `params`object Key-value pairs passed as parameters during query execution. To use parameters in your query, pass a *`query`* with `params` references (in dot notation)–for example: ``` query: "from(bucket: params.mybucket)\ |> range(start: params.rangeStart) |> limit(n:1)" ``` and pass *`params`* with the key-value pairs–for example: ``` params: { "mybucket": "environment", "rangeStart": "-30d" } ``` During query execution, InfluxDB passes *`params`* to your script and substitutes the values. #### Limitations * If you use *`params`*, you can’t use *`extern`*. `query`requiredstring The query script to execute. `type`string The type of query. Must be “flux”. Allowed:`flux` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/query" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "dialect": { "annotations": [ "group" ], "commentPrefix": "#", "dateTimeFormat": "RFC3339", "delimiter": ",", "header": true }, "extern": { "body": [ {} ], "imports": [ {} ], "name": "NAME", "package": { "name": {}, "type": "TYPE" }, "type": "TYPE" }, "now": "NOW", "params": {}, "query": "QUERY", "type": "flux" }' ``` #### Responses 200Success. The response body contains query results. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 429 #### InfluxDB Cloud: * returns this error if a **read** or **write** request exceeds your plan’s [adjustable service quotas](/influxdb/v2/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/v2/account-management/limits/#global-limits) * returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: * doesn’t return this error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks` ### List tasks Retrieves a list of [tasks](/influxdb/v2/reference/glossary/#task). To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. #### Related guide * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) #### Parameters ##### Query parameters `name`string A [task](/influxdb/v2/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. `after`string A [task](/influxdb/v2/reference/glossary/#task) ID. Only returns tasks created after the specified task. `user`string A [user](/influxdb/v2/reference/glossary/#user) ID. Only returns tasks owned by the specified user. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. `orgID`string An [organization](/influxdb/v2/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. `status`string A [task](/influxdb/v2/reference/glossary/#task) status. Only returns tasks that have the specified status (`active` or `inactive`). Allowed values:`active`, `inactive` `limit`integer The maximum number of [tasks](/influxdb/v2/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. To reduce the payload size, combine *`type=basic`* and *`limit`* (see *Request samples*). For more information about the `basic` response, see the *`type`* parameter. Default:`100` `type`string A [task](/influxdb/v2/reference/glossary/#task) type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). Allowed values:`basic`, `system` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of tasks. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `tasks`object[] `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks` ### Create a task Creates a [task](/influxdb/v2/reference/glossary/#task) and returns the task. #### Related guides * [Get started with tasks](/influxdb/v2/process-data/get-started/) * [Create a task](/influxdb/v2/process-data/manage-tasks/create-task/) * [Common tasks](/influxdb/v2/process-data/common-tasks/) * [Task configuration options](/influxdb/v2/process-data/task-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The task to create. Content-Type:`application/json` `description`string An optional description of the task. `flux`requiredstring The Flux script to run for this task. `org`string The name of the organization that owns this Task. `orgID`string The ID of the organization that owns this Task. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "flux": "FLUX", "org": "ORG", "orgID": "ORGID", "status": "active" }' ``` #### Responses 201Success. The response body contains a `tasks` list with the task. `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed for `org` or `orgID`. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}` ### Retrieve a task Retrieves a [task](/influxdb/v2/reference/glossary/#task). #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the task. `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/runs` ### Start a task run, overriding the schedule Schedules a task run to start immediately, ignoring scheduled runs. Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks. To *retry* a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). #### Parameters ##### Path parameters `taskID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request body Content-Type:`application/json` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)used for the run’s `now` option. Default is the server *now* time. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/runs" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "scheduledFor": "SCHEDULEDFOR" }' ``` #### Responses 201Success. The run is scheduled to start. `finishedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `flux`string Flux used for the task `id`string `links`object Example:`{"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}` `retry`string \ `self`string \ `task`string \ `log`object[] An array of logs associated with the run. `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `requestedAt`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) used for the run’s `now` option. `startedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `status`string Allowed:`scheduled`, `started`, `failed`, `success`, `canceled` `taskID`string 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/write` ### Write data Writes data to a bucket. Use this endpoint to send data in [line protocol](/influxdb/v2/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud * Does the following when you send a write request: 1. Validates the request and queues the write. 2. If queued, responds with *success* (HTTP `2xx` status code); *error* otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS * Validates the request and handles the write synchronously. * If all points were written successfully, responds with HTTP `2xx` status code; otherwise, returns the first line that failed. #### Required permissions * `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Write data with the InfluxDB API](/influxdb/v2/write-data/developer-tools/api) * [Optimize writes to InfluxDB](/influxdb/v2/write-data/best-practices/optimize-writes/) * [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/) #### Parameters ##### Query parameters `org`requiredstring An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * If you pass both `orgID` and `org`, they must both be valid. * Writes data to the bucket in the specified organization. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * If you pass both `orgID` and `org`, they must both be valid. * Writes data to the bucket in the specified organization. `bucket`requiredstring A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket. `precision`string The precision for unix timestamps in the line protocol batch. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `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-Type`string The format of the data in the request body. To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`. Allowed values:`text/plain`, `text/plain; charset=utf-8` Default:`text/plain; charset=utf-8` `Content-Length`integer The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the `max body` configuration option, the server responds with status code `413`. `Accept`string The content type that the client can understand. Writes only return a response body if they fail–for example, due to a formatting problem or quota limit. #### InfluxDB Cloud * Returns only `application/json` for format and limit errors. * Returns only `text/html` for some quota limit errors. #### InfluxDB OSS * Returns only `application/json` for format and limit errors. #### Related guides * [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/) Allowed values:`application/json` Default:`application/json` #### Request bodyrequired In the request body, provide data in [line protocol format](/influxdb/v2/reference/syntax/line-protocol/). To send compressed data, do the following: 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. 2. In your request, send the compressed data and the`Content-Encoding: gzip` header. #### Related guides * [Best practices for optimizing writes](/influxdb/v2/write-data/best-practices/optimize-writes/) Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/write?org=ORG&bucket=BUCKET" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000' ``` #### Responses 204 Success. #### InfluxDB Cloud * Validated and queued the request. * Handles the write asynchronously - the write might not have completed yet. #### InfluxDB OSS * Successfully wrote all points in the batch. #### Related guides * [How to check for write errors](/influxdb/v2/write-data/troubleshoot/) 400 Bad request. The response body contains detail about the error. InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket. #### InfluxDB Cloud * Returns this error for bucket schema conflicts. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring Code is the machine-readable error code. Allowed:`internal error`, `not found`, `conflict`, `invalid`, `empty value`, `unavailable` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `line`integer \ First line in the request body that contains malformed data. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 413 The request payload is too large. InfluxDB rejected the batch and did not write any data. #### InfluxDB Cloud: * Returns this error if the payload exceeds the 50MB size limit. * Returns `Content-Type: text/html` for this error. #### InfluxDB OSS: * Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. * Returns `Content-Type: application/json` for this error. `code`requiredstring Code is the machine-readable error code. Allowed:`invalid` `message`requiredstring Human-readable message. 429 Too many requests. #### InfluxDB Cloud * Returns this error if a **read** or **write** request exceeds your plan’s [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). * For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. * For limits that can’t reset (for example, **cardinality limit**), doesn’t return a `Retry-After` header. Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. #### InfluxDB OSS * Doesn’t return this error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 503 Service unavailable. * Returns this error if the server is temporarily unavailable to accept writes. * Returns a `Retry-After` header that describes when to try the write again. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. | Format | Value | | --- | --- | | Format | Value | | RFC3339 | "2006-01-02T15:04:05Z07:00" | | RFC3339Nano | "2006-01-02T15:04:05.999999999Z07:00" | --- # DBRPs Source: https://docs.influxdata.com/influxdb/v2/api/dbrps/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB OSS v2 buckets. GET`/api/v2/dbrps` ### List database retention policy mappings Lists database retention policy (DBRP) mappings. #### Related guide * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) #### Parameters ##### Query parameters `orgID`string An organization ID. Only returns DBRP mappings for the specified organization. `org`string An organization name. Only returns DBRP mappings for the specified organization. `id`string A DBPR mapping ID. Only returns the specified DBRP mapping. `bucketID`string A bucket ID. Only returns DBRP mappings that belong to the specified bucket. `default`boolean Specifies filtering on default `db`string A database. Only returns DBRP mappings that belong to the 1.x database. `rp`string A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). Specifies the 1.x retention policy to filter on. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dbrps" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of database retention policy mappings. `content`object[] `bucketID`requiredstring A bucket ID. Identifies the bucket used as the target for the translation. `database`requiredstring A database name. Identifies the InfluxDB v1 database. `default`requiredboolean If set to `true`, this DBRP mapping is the default retention policy for the database (specified by the `database` property’s value). `id`requiredstring The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgID`requiredstring An organization ID. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `retention_policy`requiredstring A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. `virtual`boolean Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. 400Bad request. The request has one or more invalid parameters. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/dbrps` ### Add a database retention policy mapping Creates a database retention policy (DBRP) mapping and returns the mapping. Use this endpoint to add InfluxDB 1.x API compatibility to your InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a DBRP mapping in order to query and write using the InfluxDB 1.x API. object. #### Related guide * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The database retention policy mapping to add. Note that *`retention_policy`* is a required parameter in the request body. The value of *`retention_policy`* can be any arbitrary `string` name or value, with the default value commonly set as `autogen`. The value of *`retention_policy`* isn’t a [retention\_policy](/influxdb/v2/reference/glossary/#retention-policy-rp) Content-Type:`application/json` `bucketID`requiredstring A bucket ID. Identifies the bucket used as the target for the translation. `database`requiredstring A database name. Identifies the InfluxDB v1 database. `default`boolean Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property’s value). `org`string An organization name. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `orgID`string An organization ID. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `retention_policy`requiredstring A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/dbrps" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucketID": "BUCKETID", "database": "DATABASE", "default": false, "org": "ORG", "orgID": "ORGID", "retention_policy": "RETENTION_POLICY" }' ``` #### Responses 201Created. The response body contains the database retention policy mapping. `bucketID`requiredstring A bucket ID. Identifies the bucket used as the target for the translation. `database`requiredstring A database name. Identifies the InfluxDB v1 database. `default`requiredboolean If set to `true`, this DBRP mapping is the default retention policy for the database (specified by the `database` property’s value). `id`requiredstring The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgID`requiredstring An organization ID. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `retention_policy`requiredstring A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. `virtual`boolean Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. 400Bad request. The mapping in the request has one or more invalid IDs. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/dbrps/{dbrpID}` ### Retrieve a database retention policy mapping Retrieves the specified retention policy (DBRP) mapping. #### Related guide * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) #### Parameters ##### Path parameters `dbrpID`requiredstring A DBRP mapping ID. Specifies the DBRP mapping. ##### Query parameters `orgID`string An organization ID. Specifies the organization that owns the DBRP mapping. `org`string An organization name. Specifies the organization that owns the DBRP mapping. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dbrps/{dbrpID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the DBRP mapping. `content`object `bucketID`requiredstring A bucket ID. Identifies the bucket used as the target for the translation. `database`requiredstring A database name. Identifies the InfluxDB v1 database. `default`requiredboolean If set to `true`, this DBRP mapping is the default retention policy for the database (specified by the `database` property’s value). `id`requiredstring The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgID`requiredstring An organization ID. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `retention_policy`requiredstring A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. `virtual`boolean Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. 400Bad Request. Query parameters contain invalid values. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dbrps/{dbrpID}` ### Update a database retention policy mapping #### Parameters ##### Path parameters `dbrpID`requiredstring A DBRP mapping ID. Specifies the DBRP mapping. ##### Query parameters `orgID`string An organization ID. Specifies the organization that owns the DBRP mapping. `org`string An organization name. Specifies the organization that owns the DBRP mapping. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Updates the database retention policy (DBRP) mapping and returns the mapping. Use this endpoint to modify the *retention policy* (`retention_policy` property) of a DBRP mapping. #### Related guide * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) Content-Type:`application/json` `default`boolean Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property’s value). To remove the default mapping, set to `false`. `retention_policy`string A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dbrps/{dbrpID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "default": false, "retention_policy": "RETENTION_POLICY" }' ``` #### Responses 200An updated mapping `content`object `bucketID`requiredstring A bucket ID. Identifies the bucket used as the target for the translation. `database`requiredstring A database name. Identifies the InfluxDB v1 database. `default`requiredboolean If set to `true`, this DBRP mapping is the default retention policy for the database (specified by the `database` property’s value). `id`requiredstring The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgID`requiredstring An organization ID. Identifies the [organization](/influxdb/v2/reference/glossary/#organization) that owns the mapping. `retention_policy`requiredstring A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. `virtual`boolean Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. 400Bad Request. Query parameters contain invalid values. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/dbrps/{dbrpID}` ### Delete a database retention policy Deletes the specified database retention policy (DBRP) mapping. #### Related guide * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) #### Parameters ##### Path parameters `dbrpID`requiredstring A DBRP mapping ID. Only returns the specified DBRP mapping. ##### Query parameters `orgID`string An organization ID. Specifies the organization that owns the DBRP mapping. `org`string An organization name. Specifies the organization that owns the DBRP mapping. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/dbrps/{dbrpID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The delete is accepted. 400Bad Request. Query parameters contain invalid values. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/) --- # Debug Source: https://docs.influxdata.com/influxdb/v2/api/debug/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Generate Go runtime profiling and trace reports for troubleshooting and performance analysis of an InfluxDB OSS v2 instance. GET`/debug/pprof/all` ### Retrieve all runtime profiles Collects samples and returns reports for the following [Go runtime profiles](https://pkg.go.dev/runtime/pprof): * **allocs**: All past memory allocations * **block**: Stack traces that led to blocking on synchronization primitives * **cpu**: (Optional) Program counters sampled from the executing stack. Include by passing the `cpu` query parameter with a [duration](/influxdb/v2/reference/glossary/#duration) value. Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile). * **goroutine**: All current goroutines * **heap**: Memory allocations for live objects * **mutex**: Holders of contended mutexes * **threadcreate**: Stack traces that led to the creation of new OS threads #### Parameters ##### Query parameters `cpu`string \ Collects and returns CPU profiling data for the specified [duration](/influxdb/v2/reference/glossary/#duration). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/all" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/allocs` ### Retrieve the memory allocations runtime profile Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of all past memory allocations.**allocs** is the same as the **heap** profile, but changes the default [pprof](https://pkg.go.dev/runtime/pprof)display to **-alloc\_space**, the total number of bytes allocated since the program began (including garbage-collected bytes). #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/allocs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/block` ### Retrieve the block runtime profile Collects samples and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of stack traces that led to blocking on synchronization primitives. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/block" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/cmdline` ### Retrieve the command line invocation Returns the command line that invoked InfluxDB. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/cmdline" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Command line invocation. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/goroutine` ### Retrieve the goroutines runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of all current goroutines. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text with comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/goroutine" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/heap` ### Retrieve the heap runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of memory allocations for live objects. To run **garbage collection** before sampling, pass the `gc` query parameter with a value of `1`. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. `gc`integer \ * `0`: (Default) don’t force garbage collection before sampling. * `1`: Force garbage collection before sampling. Allowed values:`0`, `1` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/heap" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/mutex` ### Retrieve the mutual exclusion (mutex) runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of lock contentions. The profile contains stack traces of holders of contended mutual exclusions (mutexes). #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/mutex" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/profile` ### Retrieve the CPU runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of program counters on the executing stack. #### Parameters ##### Query parameters `seconds`string \ Number of seconds to collect profile data. Default is `30` seconds. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/profile" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/threadcreate` ### Retrieve the threadcreate runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of stack traces that led to the creation of new OS threads. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/threadcreate" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/trace` ### Retrieve the runtime execution trace Collects profile data and returns trace execution events for the current program. #### Parameters ##### Query parameters `seconds`string \ Number of seconds to collect profile data. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/trace" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Trace file](https://pkg.go.dev/runtime/trace) compatible with the [Golang `trace` command](https://pkg.go.dev/cmd/trace). defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Delete Source: https://docs.influxdata.com/influxdb/v2/api/delete/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Delete time series data from an InfluxDB OSS v2 bucket by specifying a time range and optional tag predicate. POST`/api/v2/delete` ### Delete data Deletes data from a bucket. Use this endpoint to delete points from a bucket in a specified time range. #### InfluxDB Cloud * Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. If queued, responds with *success* (HTTP `2xx` status code); *error* otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS * Validates the request, handles the delete synchronously, and then responds with success or failure. #### Required permissions * `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Delete data](/influxdb/v2/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). * Learn how InfluxDB handles [deleted tags](/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/)and [deleted fields](/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). #### Parameters ##### Query parameters `org`string An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * Deletes data from the bucket in the specified organization. * If you pass both `orgID` and `org`, they must both be valid. `bucket`string A bucket name or ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * Deletes data from the bucket in the specified organization. * If you pass both `orgID` and `org`, they must both be valid. `bucketID`string A bucket ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Time range parameters and an optional **delete predicate expression**. To select points to delete within the specified time range, pass a**delete predicate expression** in the `predicate` property of the request body. If you don’t pass a `predicate`, InfluxDB deletes all data with timestamps in the specified time range. #### Related guides * [Delete data](/influxdb/v2/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). Content-Type:`application/json` `predicate`string An expression in [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/). Example:`"tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"` `start`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. `stop`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/delete" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")", "start": "START", "stop": "STOP" }' ``` #### Responses 204 Success. #### InfluxDB Cloud * Validated and queued the request. * Handles the delete asynchronously - the deletion might not have completed yet. An HTTP `2xx` status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request. Because writes are asynchronous, data might not yet be written when you receive the response. #### InfluxDB OSS * Deleted the data. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Headers Source: https://docs.influxdata.com/influxdb/v2/api/headers/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) InfluxDB OSS v2 API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB OSS v2 API endpoints. Some endpoints may use other headers for functions 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-Encoding`| string |Compression applied to the request body (e.g., gzip).| | `Content-Length` | integer | The size of the entity-body, in bytes. | | `Content-Type` | string | The format of the data in the request body. | | 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-Encoding | string | Compression applied to the request body (e.g., gzip). | | Content-Length | integer | The size of the entity-body, in bytes. | | Content-Type | string | The format of the data in the request body. | --- # Health Source: https://docs.influxdata.com/influxdb/v2/api/health/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Check the health and readiness of an InfluxDB OSS v2 instance. GET`/health` ### Retrieve the health of the instance Returns the health of the instance. `--health-auth-mode` and `--hardening-enabled` reduce the response body for callers without operator permissions. Those callers don’t receive check messages, measure groups, `version`, or `commit`. The status code never changes. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/health" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The instance is healthy. The response body contains the health check items and status. `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. 503The instance is unhealthy.`message` contains the message of the first failing check. `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Labels Source: https://docs.influxdata.com/influxdb/v2/api/labels/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage labels for organizing InfluxDB OSS v2 resources such as dashboards, tasks, and buckets. GET`/api/v2/labels` ### List all labels #### Parameters ##### Query parameters `orgID`string The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of labels. `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/labels` ### Create a label #### Request bodyrequired The label to create. Content-Type:`application/json` `name`requiredstring `orgID`requiredstring `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME", "orgID": "ORGID", "properties": { "color": "ffb3b3", "description": "this is a description" } }' ``` #### Responses 201Success. The label was created. `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/labels/{labelID}` ### Retrieve a label #### Parameters ##### Path parameters `labelID`requiredstring The ID of the label to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the label. `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/labels/{labelID}` ### Update a label #### Parameters ##### Path parameters `labelID`requiredstring The ID of the label to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A label update. Content-Type:`application/json` `name`string `properties`object Example:`{"color":"ffb3b3","description":"this is a description"}` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME", "properties": { "color": "ffb3b3", "description": "this is a description" } }' ``` #### Responses 200Success. The response body contains the updated label. `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/labels/{labelID}` ### Delete a label #### Parameters ##### Path parameters `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The delete was accepted. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Legacy Authorizations Source: https://docs.influxdata.com/influxdb/v2/api/legacy-authorizations/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) GET`/legacy/authorizations` ### List all legacy authorizations #### Parameters ##### Query parameters `userID`string A user ID. Only returns legacy authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `user`string A user name. Only returns legacy authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `orgID`string An organization ID. Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `org`string An organization name. Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `token`string An authorization name token. Only returns legacy authorizations with the specified name. `authID`string An authorization ID. Returns the specified legacy authorization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/legacy/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of legacy `authorizations`. `authorizations`object[] `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/v2/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/v2/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/v2/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx`CLI commands–after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/legacy/authorizations` ### Create a legacy authorization Creates a legacy authorization and returns the legacy authorization. #### Required permissions * `write-users USER_ID` if you pass the `userID` property in the request body. *`USER_ID`* is the ID of the user that you want to scope the authorization to. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The legacy authorization to create. Content-Type:`application/json` `description`string A description of the token. `orgID`requiredstring The organization ID. Identifies the organization that the authorization is scoped to. `permissions`requiredobject[] The list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `id`string A resource ID. Identifies a specific resource. `name`string The name of the resource.*Note: not all resource types have a `name` property*. `org`string An organization name. The organization that owns the resource. `orgID`string An organization ID. Identifies the organization that owns the resource. `type`requiredstring A resource type. Identifies the API resource’s type (or *kind*). Allowed:`authorizations`, `buckets`, `dashboards`, `orgs`, `tasks`, `telegrafs`, `users`, `variables`, `secrets`, `labels`, `views`, `documents`, `notificationRules`, `notificationEndpoints`, `checks`, `dbrp`, `annotations`, `sources`, `scrapers`, `notebooks`, `remotes`, `replications`, `instance`, `flows`, `functions`, `subscriptions` `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The name that you provide for the authorization. `userID`string The user ID. Identifies the user that the authorization is scoped to. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/legacy/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "orgID": "ORGID", "permissions": [ { "action": "read", "resource": {} } ], "status": "active", "token": "TOKEN", "userID": "USERID" }' ``` #### Responses 201Created. The legacy authorization is created. The response body contains the newly created legacy authorization. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401Unauthorized. The API token passed doesn’t have the permissions necessary for the request. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/legacy/authorizations/{authID}` ### Retrieve a legacy authorization #### Parameters ##### Path parameters `authID`requiredstring The ID of the legacy authorization to get. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/legacy/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Legacy authorization details defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/legacy/authorizations/{authID}` ### Update a legacy authorization to be active or inactive #### Parameters ##### Path parameters `authID`requiredstring The ID of the legacy authorization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Legacy authorization to update Content-Type:`application/json` `description`string A description of the token. `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/legacy/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "status": "active" }' ``` #### Responses 200The active or inactive legacy authorization defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/legacy/authorizations/{authID}` ### Delete a legacy authorization #### Parameters ##### Path parameters `authID`requiredstring The ID of the legacy authorization to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/legacy/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Legacy authorization deleted defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/legacy/authorizations/{authID}/password` ### Set a legacy authorization password #### Parameters ##### Path parameters `authID`requiredstring The ID of the legacy authorization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired New password Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/legacy/authorizations/{authID}/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Legacy authorization password set defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Legacy Query Source: https://docs.influxdata.com/influxdb/v2/api/legacy-query/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) GET`/query` ### Query with the 1.x compatibility API Queries InfluxDB using InfluxQL. #### Parameters ##### Query parameters `u`string The InfluxDB 1.x username to authenticate the request. `p`string The InfluxDB 1.x password to authenticate the request. `db`requiredstring The database to query data from. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket). For more information, see [Database and retention policy mapping](/influxdb/v2/api/influxdb-1x/dbrp/). `rp`string The retention policy to query data from. This is mapped to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket). For more information, see [Database and retention policy mapping](/influxdb/v2/api/influxdb-1x/dbrp/). `q`requiredstring The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon (`;`). `epoch`string A unix timestamp precision. Formats timestamps as [unix (epoch) timestamps](/influxdb/v2/reference/glossary/#unix-timestamp) the specified precision instead of [RFC3339 timestamps](/influxdb/v2/reference/glossary/#rfc3339-timestamp) with nanosecond precision. Allowed values:`ns`, `u`, `µ`, `ms`, `s`, `m`, `h` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept`string Allowed values:`application/json`, `application/csv`, `text/csv`, `application/x-msgpack` Default:`application/json` `Accept-Encoding`string The content encoding (usually a compression algorithm) that the client can understand. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/json` Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/query?db=DB&q=Q" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Query results `results`object or object One of:object Or:object `error`string `partial`boolean True if the resultset is not complete–the response data is chunked; otherwise, false or omitted. `series`object[] An array of series objects–the results of the query. A series of rows shares the same group key returned from the execution of a statement. If a property is not present, it is assumed to be `null`. `columns`string[] An array of column names `name`string The name of the series `partial`boolean True if the series is not complete–the response data is chunked; otherwise, false or omitted. `tags`object A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`. `values`array[] An array of rows, where each row is an array of values. `statement_id`integer An integer that represents the statement’s position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results. 429 #### InfluxDB Cloud: * returns this error if a **read** or **write** request exceeds your plan’s [adjustable service quotas](/influxdb/v2/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/v2/account-management/limits/#global-limits) * returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: * doesn’t return this error. defaultError processing query `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Legacy Write Source: https://docs.influxdata.com/influxdb/v2/api/legacy-write/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) POST`/write` ### Write time series data into InfluxDB in a V1-compatible format #### Parameters ##### Query parameters `u`string The InfluxDB 1.x username to authenticate the request. `p`string The InfluxDB 1.x password to authenticate the request. `db`requiredstring Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. `rp`string Retention policy name. `precision`string Write precision. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Encoding`string When present, its value indicates to the database that compression is applied to the line protocol body. Allowed values:`gzip`, `identity` Default:`identity` #### Request bodyrequired Line protocol body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/write?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1.0' ``` #### Responses 204Write data is correctly formatted and accepted for writing to the bucket. 400Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. `code`requiredstring Code is the machine-readable error code. Allowed:`internal error`, `not found`, `conflict`, `invalid`, `empty value`, `unavailable` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `line`integer \ First line in the request body that contains malformed data. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401Token doesn’t have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 403No token was sent and they are required. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 413Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. `code`requiredstring Code is the machine-readable error code. Allowed:`invalid` `message`requiredstring Human-readable message. 429Token is temporarily over quota. The Retry-After header describes when to try the write again. 503Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Metrics Source: https://docs.influxdata.com/influxdb/v2/api/metrics/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve internal metrics for an InfluxDB OSS v2 instance in Prometheus exposition format. GET`/metrics` ### Retrieve workload performance metrics Returns metrics about the workload performance of an InfluxDB instance. Use this endpoint to get performance, resource, and usage metrics. #### Related guides * For the list of metrics categories, see [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/). * Learn how to use InfluxDB to [scrape Prometheus metrics](/influxdb/v2/write-data/developer-tools/scrape-prometheus-metrics/). * Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/v2/reference/prometheus-metrics/). #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/metrics" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains metrics in[Prometheus plain-text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats)Metrics contain a name, an optional set of key-value pairs, and a value. The following descriptors precede each metric: * `HELP`: description of the metric * `TYPE`: [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, `gauge`, `histogram`, or `summary`) defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # NotificationEndpoints Source: https://docs.influxdata.com/influxdb/v2/api/notificationendpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage notification endpoints that receive alert notifications from InfluxDB OSS v2 monitoring checks. GET`/api/v2/notificationEndpoints` ### List all notification endpoints #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `orgID`requiredstring Only show notification endpoints that belong to specific organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationEndpoints?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of notification endpoints `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `notificationEndpoints`object[] defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/notificationEndpoints` ### Add a notification endpoint #### Request bodyrequired Notification endpoint to create Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/notificationEndpoints" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Notification endpoint created defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/notificationEndpoints/{endpointID}` ### Retrieve a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The notification endpoint requested defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/notificationEndpoints/{endpointID}` ### Update a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A new notification endpoint to replace the existing endpoint with Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200An updated notification endpoint 404The notification endpoint was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/notificationEndpoints/{endpointID}` ### Update a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Check update to apply Content-Type:`application/json` `description`string `name`string `status`string Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "status": "active" }' ``` #### Responses 200An updated notification endpoint 404The notification endpoint was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/notificationEndpoints/{endpointID}` ### Delete a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404The endpoint was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/notificationEndpoints/{endpointID}/labels` ### List all labels for a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a notification endpoint `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/notificationEndpoints/{endpointID}/labels` ### Add a label to a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The label was added to the notification endpoint `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}` ### Delete a label from a notification endpoint #### Parameters ##### Path parameters `endpointID`requiredstring The notification endpoint ID. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Endpoint or label not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # NotificationRules Source: https://docs.influxdata.com/influxdb/v2/api/notificationrules/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage notification rules that define when and how InfluxDB OSS v2 sends notifications to configured endpoints. GET`/api/v2/notificationRules` ### List all notification rules #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `orgID`requiredstring Only show notification rules that belong to a specific organization ID. `checkID`string Only show notifications that belong to the specific check ID. `tag`string Only return notification rules that “would match” statuses which contain the tag key value pairs provided. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationRules?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of notification rules `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `notificationRules`object[] defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/notificationRules` ### Add a notification rule #### Request bodyrequired Notification rule to create Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/notificationRules" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Notification rule created defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/notificationRules/{ruleID}` ### Retrieve a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationRules/{ruleID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The notification rule requested defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/notificationRules/{ruleID}` ### Update a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Notification rule update to apply Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/notificationRules/{ruleID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200An updated notification rule 404The notification rule was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/notificationRules/{ruleID}` ### Update a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Notification rule update to apply Content-Type:`application/json` `description`string `name`string `status`string Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/notificationRules/{ruleID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "status": "active" }' ``` #### Responses 200An updated notification rule 404The notification rule was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/notificationRules/{ruleID}` ### Delete a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/notificationRules/{ruleID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404The check was not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/notificationRules/{ruleID}/labels` ### List all labels for a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationRules/{ruleID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a notification rule `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/notificationRules/{ruleID}/labels` ### Add a label to a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/notificationRules/{ruleID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The label was added to the notification rule `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/notificationRules/{ruleID}/labels/{labelID}` ### Delete label from a notification rule #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/notificationRules/{ruleID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Rule or label not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Organizations Source: https://docs.influxdata.com/influxdb/v2/api/organizations/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage InfluxDB OSS v2 organizations, which are workspaces that group users, buckets, and resources. GET`/api/v2/orgs` ### List organizations Lists [organizations](/influxdb/v2/reference/glossary/#organization/). To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud * Only returns the organization that owns the token passed in the request. #### Related guides * [View organizations](/influxdb/v2/organizations/view-orgs/) #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `descending`boolean `org`string An organization name. Only returns the specified organization. `orgID`string An organization ID. Only returns the specified organization. `userID`string A user ID. Only returns organizations where the specified user is a member or owner. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of organizations. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgs`object[] `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/orgs` ### Create an organization Creates an [organization](/influxdb/v2/reference/glossary/#organization)and returns the newly created organization. #### InfluxDB Cloud * Doesn’t allow you to use this endpoint to create organizations. #### Related guides * [Manage organizations](/influxdb/v2/organizations) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The organization to create. Content-Type:`application/json` `description`string The description of the organization. `name`requiredstring The name of the organization. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/orgs" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME" }' ``` #### Responses 201Created. The response body contains the organization information. `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}` ### Retrieve an organization Retrieves an organization. Use this endpoint to retrieve information for a specific organization. #### Related guides * [View organizations](/influxdb/v2/organizations/view-orgs/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the organization information. `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. Organization not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/orgs/{orgID}` ### Update an organization Updates an organization. Use this endpoint to update properties (`name`, `description`) of an organization. Updating an organization’s name affects all resources that reference the organization by name, including the following: * Queries * Dashboards * Tasks * Telegraf configurations * Templates If you change an organization name, be sure to update the organization name in these resources as well. #### Related Guides * [Update an organization](/influxdb/v2/organizations/update-org/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The organization update to apply. Content-Type:`application/json` `description`string The description of the organization. `name`string The name of the organization. Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/orgs/{orgID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME" }' ``` #### Responses 200Success. The response body contains the updated organization. `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}` ### Delete an organization Deletes an organization. Deleting an organization from InfluxDB Cloud can’t be undone. Once deleted, all data associated with the organization is removed. #### InfluxDB Cloud * Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. Returns an HTTP `204` status code if queued; *error* otherwise. 3. Handles the delete asynchronously. #### InfluxDB OSS * Validates the request, handles the delete synchronously, and then responds with success or failure. #### Limitations * Only one organization can be deleted per request. #### Related guides * [Delete organizations](/influxdb/v2/organizations/delete-orgs/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Success. #### InfluxDB Cloud * The organization is queued for deletion. #### InfluxDB OSS * The organization is deleted. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. InfluxDB can’t find the organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}/members` ### List all members of an organization Lists all users that belong to an organization. InfluxDB [users](/influxdb/v2/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/v2/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Member permissions are separate from API token permissions. * Member permissions are used in the context of the InfluxDB UI. #### Required permissions * `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve members for. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to retrieve users for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all users within the organization. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. InfluxDB can’t find the organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/orgs/{orgID}/members` ### Add a member to an organization Add a user to an organization. InfluxDB [users](/influxdb/v2/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/v2/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Member permissions are separate from API token permissions. * Member permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The user to add to the organization. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/orgs/{orgID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Success. The response body contains the user information. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/members/{userID}` ### Remove a member from an organization Removes a member from an organization. Use this endpoint to remove a user’s member privileges for an organization. Removing member privileges removes the user’s `read` and `write` permissions from the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Member permissions are separate from API token permissions. * Member permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related guides * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to remove. `orgID`requiredstring The ID of the organization to remove a user from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer a member of the organization. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}/owners` ### List all owners of an organization Lists all owners of an organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions * `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a list of owners from. #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to list owners for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of organization owners `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 404Organization not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/orgs/{orgID}/owners` ### Add an owner to an organization Adds an owner to an organization. Use this endpoint to assign the organization `owner` role to a user. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization that you want to add an owner for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The user to add as an owner of the organization. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/orgs/{orgID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Success. The user is an owner of the organization. The response body contains the owner with role and user detail. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/owners/{userID}` ### Remove an owner from an organization Removes an [owner](/influxdb/v2/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member permissions from the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Owner permissions are separate from API token permissions. * Owner permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to remove. `orgID`requiredstring The ID of the organization to remove an owner from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer an owner of the organization. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Manage organizations](/influxdb/v2/organizations/) --- # Pagination Source: https://docs.influxdata.com/influxdb/v2/api/pagination/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) List endpoints in the InfluxDB OSS v2 API support pagination via query parameters. Use these parameters to page through large result sets. |Query parameter|Value type| Description | |---------------|----------|-----------------------------------------------------| | `limit` | integer | Maximum number of records to return (default: 20). | | `offset` | integer | Number of records to skip before returning results. | | `after` | string |Return records created after the specified record ID.| | `descending` | boolean | Sort results in descending order. | List responses include pagination metadata (such as total count or links to the next page) to help navigate through result pages. | Query parameter | Value type | Description | | --- | --- | --- | | Query parameter | Value type | Description | | limit | integer | Maximum number of records to return (default: 20). | | offset | integer | Number of records to skip before returning results. | | after | string | Return records created after the specified record ID. | | descending | boolean | Sort results in descending order. | --- # Ping Source: https://docs.influxdata.com/influxdb/v2/api/ping/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Check the availability of an InfluxDB OSS v2 instance. GET`/ping` ### Get the status of the instance Retrieves the status and InfluxDB version of the instance. Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP `204` status code to inform you the instance is available. #### InfluxDB Cloud * Isn’t versioned and doesn’t return `X-Influxdb-Version` in the headers. #### Related guides * [Influx ping](/influxdb/v2/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. Headers contain InfluxDB version information. HEAD`/ping` ### Get the status of the instance Returns the status and InfluxDB version of the instance. Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP `204` status code to inform you the instance is available. #### InfluxDB Cloud * Isn’t versioned and doesn’t return `X-Influxdb-Version` in the headers. #### Related guides * [Influx ping](/influxdb/v2/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request HEAD \ "http://localhost:8086/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. Headers contain InfluxDB version information. --- # Query Source: https://docs.influxdata.com/influxdb/v2/api/query/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve data, analyze queries, and get query suggestions. POST`/api/v2/query` ### Query data Retrieves data from buckets. Use this endpoint to send a Flux query request and retrieve data from a bucket. #### Rate limits (with InfluxDB Cloud) `read` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Query with the InfluxDB API](/influxdb/v2/query-data/execute-queries/influx-api/) * [Get started with Flux](/flux/v0.x/get-started/) #### Parameters ##### Query parameters `org`string An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or `orgID` parameter. * Queries the bucket in the specified organization. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or `orgID` parameter. * Queries the bucket in the specified organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept-Encoding`string The content encoding (usually a compression algorithm) that the client can understand. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/json`, `application/vnd.flux` #### Request body Flux query or specification to execute Content-Type:`application/json` `dialect`object Options for tabular data output. Default output is [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). `annotations`string[] Annotation rows to include in the results. An *annotation* is metadata associated with an object (column) in the data model. #### Related guides * See [Annotated CSV annotations](/influxdb/v2/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). `commentPrefix`string The character prefixed to comment strings. Default is a number sign (`#`). Default:`#` `dateTimeFormat`string The format for timestamps in results. Default is [`RFC3339` date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values | Format | Value | |-------------|---------------------------------------| | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | |`RFC3339Nano`|`"2006-01-02T15:04:05.999999999Z07:00"`| Allowed:`RFC3339`, `RFC3339Nano` Default:`RFC3339` `delimiter`string The separator used between cells. Default is a comma (`,`). Default:`,` `header`boolean If true, the results contain a header row. Default:`true` `extern`object Represents a source from a single file `body`object[] List of Flux statements `imports`object[] A list of package imports `as`object A valid Flux identifier `path`object Expressions begin and end with double quote marks `type`string Type of AST node `name`string The name of the file. `package`object Defines a package identifier `name`object A valid Flux identifier `type`string Type of AST node `type`string Type of AST node `now`string \ Specifies the time that should be reported as `now` in the query. Default is the server `now` time. `params`object Key-value pairs passed as parameters during query execution. To use parameters in your query, pass a *`query`* with `params` references (in dot notation)–for example: ``` query: "from(bucket: params.mybucket)\ |> range(start: params.rangeStart) |> limit(n:1)" ``` and pass *`params`* with the key-value pairs–for example: ``` params: { "mybucket": "environment", "rangeStart": "-30d" } ``` During query execution, InfluxDB passes *`params`* to your script and substitutes the values. #### Limitations * If you use *`params`*, you can’t use *`extern`*. `query`requiredstring The query script to execute. `type`string The type of query. Must be “flux”. Allowed:`flux` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/query" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "dialect": { "annotations": [ "group" ], "commentPrefix": "#", "dateTimeFormat": "RFC3339", "delimiter": ",", "header": true }, "extern": { "body": [ {} ], "imports": [ {} ], "name": "NAME", "package": { "name": {}, "type": "TYPE" }, "type": "TYPE" }, "now": "NOW", "params": {}, "query": "QUERY", "type": "flux" }' ``` #### Responses 200Success. The response body contains query results. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 429 #### InfluxDB Cloud: * returns this error if a **read** or **write** request exceeds your plan’s [adjustable service quotas](/influxdb/v2/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/v2/account-management/limits/#global-limits) * returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: * doesn’t return this error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/query/analyze` ### Analyze a Flux query Analyzes a [Flux query](/flux/v0.x/) for syntax errors and returns the list of errors. In the following sample query, `from()` is missing the property key. ``` ```json { "query": "from(: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")", "type": "flux" } ``` ``` If you pass this in a request to the `/api/v2/analyze` endpoint, InfluxDB returns an `errors` list that contains an error object for the missing key. #### Limitations * The endpoint doesn’t validate values in the query–for example: * The following sample query has correct syntax, but contains an incorrect `from()` property key: ``` { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")", "type": "flux" } ``` If you pass this in a request to the `/api/v2/analyze` endpoint, InfluxDB returns an empty `errors` list. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Type`string Allowed values:`application/json` #### Request body Flux query to analyze Content-Type:`application/json` `dialect`object Options for tabular data output. Default output is [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). `annotations`string[] Annotation rows to include in the results. An *annotation* is metadata associated with an object (column) in the data model. #### Related guides * See [Annotated CSV annotations](/influxdb/v2/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). `commentPrefix`string The character prefixed to comment strings. Default is a number sign (`#`). Default:`#` `dateTimeFormat`string The format for timestamps in results. Default is [`RFC3339` date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values | Format | Value | |-------------|---------------------------------------| | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | |`RFC3339Nano`|`"2006-01-02T15:04:05.999999999Z07:00"`| Allowed:`RFC3339`, `RFC3339Nano` Default:`RFC3339` `delimiter`string The separator used between cells. Default is a comma (`,`). Default:`,` `header`boolean If true, the results contain a header row. Default:`true` `extern`object Represents a source from a single file `body`object[] List of Flux statements `imports`object[] A list of package imports `as`object A valid Flux identifier `path`object Expressions begin and end with double quote marks `type`string Type of AST node `name`string The name of the file. `package`object Defines a package identifier `name`object A valid Flux identifier `type`string Type of AST node `type`string Type of AST node `now`string \ Specifies the time that should be reported as `now` in the query. Default is the server `now` time. `params`object Key-value pairs passed as parameters during query execution. To use parameters in your query, pass a *`query`* with `params` references (in dot notation)–for example: ``` query: "from(bucket: params.mybucket)\ |> range(start: params.rangeStart) |> limit(n:1)" ``` and pass *`params`* with the key-value pairs–for example: ``` params: { "mybucket": "environment", "rangeStart": "-30d" } ``` During query execution, InfluxDB passes *`params`* to your script and substitutes the values. #### Limitations * If you use *`params`*, you can’t use *`extern`*. `query`requiredstring The query script to execute. `type`string The type of query. Must be “flux”. Allowed:`flux` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/query/analyze" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "dialect": { "annotations": [ "group" ], "commentPrefix": "#", "dateTimeFormat": "RFC3339", "delimiter": ",", "header": true }, "extern": { "body": [ {} ], "imports": [ {} ], "name": "NAME", "package": { "name": {}, "type": "TYPE" }, "type": "TYPE" }, "now": "NOW", "params": {}, "query": "QUERY", "type": "flux" }' ``` #### Responses 200Success. The response body contains the list of `errors`. If the query syntax is valid, the endpoint returns an empty `errors` list. `errors`object[] `character`integer `column`integer `line`integer `message`string 400Bad request. InfluxDB is unable to parse the request. The response body contains detail about the problem. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/query/ast` ### Generate a query Abstract Syntax Tree (AST) Analyzes a Flux query and returns a complete package source [Abstract Syntax Tree (AST)](/influxdb/v2/reference/glossary/#abstract-syntax-tree-ast)for the query. Use this endpoint for deep query analysis such as debugging unexpected query results. A Flux query AST provides a semantic, tree-like representation with contextual information about the query. The AST illustrates how the query is distributed into different components for execution. #### Limitations * The endpoint doesn’t validate values in the query–for example: The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: ``` from(foo: "iot_center") |> range(start: -90d) |> filter(fn: (r) => r._measurement == "environment") ``` The following sample JSON shows how to pass the query in the request body: ``` from(foo: "iot_center") |> range(start: -90d) |> filter(fn: (r) => r._measurement == "environment") ``` The following code sample shows how to pass the query as JSON in the request body: ``` { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")" } ``` Passing this to `/api/v2/query/ast` will return a successful response with a generated AST. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Type`string Allowed values:`application/json` #### Request body The Flux query to analyze. Content-Type:`application/json` `query`requiredstring The Flux query script to be analyzed. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/query/ast" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "query": "QUERY" }' ``` #### Responses 200Success. The response body contains an Abstract Syntax Tree (AST) of the Flux query. `ast`object Represents a complete package source tree. `files`object[] Package files `body`object[] List of Flux statements `imports`object[] A list of package imports `name`string The name of the file. `package`object Defines a package identifier `type`string Type of AST node `package`string Package name `path`string Package import path `type`string Type of AST node 400Bad request. InfluxDB is unable to parse the request. The response body contains detail about the problem. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultInternal server error. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/query/suggestions` ### List Flux query suggestions Lists Flux query suggestions. Each suggestion contains a[Flux function](/flux/v0.x/stdlib/all-functions/)name and parameters. Use this endpoint to retrieve a list of Flux query suggestions used in the InfluxDB Flux Query Builder. #### Limitations * When writing a query, avoid using `_functionName()` helper functions exposed by this endpoint. Helper function names have an underscore (`_`) prefix and aren’t meant to be used directly in queries–for example: * To sort on a column and keep the top n records, use the`top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit`helper function. `top` uses `_sortLimit`. #### Related Guides * [List of all Flux functions](/flux/v0.x/stdlib/all-functions/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/query/suggestions" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of Flux query suggestions–function names used in the Flux Query Builder autocomplete suggestions. `funcs`object[] `name`string `params`object 301Moved Permanently. InfluxData has moved the URL of the endpoint. Use `/api/v2/query/suggestions` (without a trailing slash). defaultInternal server error. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/query/suggestions/{name}` ### Retrieve a query suggestion for a branching suggestion Retrieves a query suggestion that contains the name and parameters of the requested function. Use this endpoint to pass a branching suggestion (a Flux function name) and retrieve the parameters of the requested function. #### Limitations * Use `/api/v2/query/suggestions/{name}` (without a trailing slash).`/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a HTTP `301 Moved Permanently` status. * The function `name` must exist and must be spelled correctly. #### Related Guides * [List of all Flux functions](/flux/v0.x/stdlib/all-functions/) #### Parameters ##### Path parameters `name`requiredstring A [Flux function](/flux/v0.x/stdlib/all-functions/) name. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/query/suggestions/{name}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the function name and parameters. `name`string `params`object 500Internal server error. The value passed for *`name`* may have been misspelled. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. | Format | Value | | --- | --- | | Format | Value | | RFC3339 | "2006-01-02T15:04:05Z07:00" | | RFC3339Nano | "2006-01-02T15:04:05.999999999Z07:00" | | Format | Value | | --- | --- | | Format | Value | | RFC3339 | "2006-01-02T15:04:05Z07:00" | | RFC3339Nano | "2006-01-02T15:04:05.999999999Z07:00" | --- # Quick start Source: https://docs.influxdata.com/influxdb/v2/api/quick-start/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Authenticate, write, and query with the InfluxDB OSS v2 API: 1. Create an API token with write and read permissions for a bucket. For new installations, set up InfluxDB and create the initial admin token during the [onboarding process](/influxdb/v2/install/). 2. Check the status of the InfluxDB server. ``` curl "http://localhost:8086/health" ``` 3. Write data to a bucket using the `/api/v2/write` endpoint and[line protocol](/influxdb/v2/reference/syntax/line-protocol/). ``` curl --request POST \ "http://localhost:8086/api/v2/write?org=ORG&bucket=BUCKET&precision=s" \ --header "Authorization: Token YOUR_API_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --data-raw "home,room=Kitchen temp=72.0 1640995200 home,room=Living\ Room temp=71.5 1640995200" ``` If all data is written, the response is `204 No Content`. 4. Query data using the Flux `/api/v2/query` endpoint. ``` curl --request POST \ "http://localhost:8086/api/v2/query?org=ORG" \ --header "Authorization: Token YOUR_API_TOKEN" \ --header "Content-Type: application/vnd.flux" \ --data 'from(bucket: "BUCKET") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "home")' ``` Alternatively, query with InfluxQL using the v1-compatible `/query`endpoint. Target a v1 DBRP mapping (`database.retention_policy`) that points to your bucket: ``` curl --get "http://localhost:8086/query" \ --header "Authorization: Token YOUR_API_TOKEN" \ --data-urlencode "db=DATABASE" \ --data-urlencode "q=SELECT * FROM home WHERE time > now() - 1h" ``` For more information, see [Get started with InfluxDB OSS v2](/influxdb/v2/get-started/). #### Related * [Get started with InfluxDB OSS v2](/influxdb/v2/get-started/) * [Write data](/influxdb/v2/write-data/) * [Query data with Flux](/influxdb/v2/query-data/) --- # Ready Source: https://docs.influxdata.com/influxdb/v2/api/ready/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Check whether an InfluxDB OSS v2 instance is ready to accept requests. GET`/ready` ### Get the readiness of an instance at startup Returns the readiness of the instance. `--health-auth-mode` and `--hardening-enabled` can withhold `checks`from callers without operator permissions. They never change the status code. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/ready" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The instance is ready `checks`object[] Ready gates that haven’t passed. Omitted when `status` is `ready`. `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `started`string \ Example:`"2019-03-13T10:09:33.891196-04:00"` `status`string Allowed:`ready`, `starting` `up`string Example:`"14m45.911966424s"` `uptime`object Time since `started`, in float seconds. Example:`{"completed":94,"total":200,"unit":"shards"}` `unit`requiredstring Example:`"shards"` 503The instance is starting or shutting down.`checks` contains only the ready gates that haven’t passed. `checks`object[] Ready gates that haven’t passed. Omitted when `status` is `ready`. `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `started`string \ Example:`"2019-03-13T10:09:33.891196-04:00"` `status`string Allowed:`ready`, `starting` `up`string Example:`"14m45.911966424s"` `uptime`object Time since `started`, in float seconds. Example:`{"completed":94,"total":200,"unit":"shards"}` `unit`requiredstring Example:`"shards"` defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # RemoteConnections Source: https://docs.influxdata.com/influxdb/v2/api/remoteconnections/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage remote InfluxDB connections for replicating data from an InfluxDB OSS v2 instance to a remote InfluxDB instance. GET`/api/v2/remotes` ### List all remote connections #### Parameters ##### Query parameters `orgID`requiredstring The organization ID. `name`string `remoteURL`string \ ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/remotes?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200List of remote connections `remotes`object[] `allowInsecureTLS`requiredboolean `description`string `id`requiredstring `name`requiredstring `orgID`requiredstring `remoteOrgID`string `remoteURL`requiredstring \ 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/remotes` ### Register a new remote connection #### Request bodyrequired Content-Type:`application/json` `allowInsecureTLS`requiredboolean `description`string `name`requiredstring `orgID`requiredstring `remoteAPIToken`requiredstring `remoteOrgID`string `remoteURL`requiredstring \ Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/remotes" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "allowInsecureTLS": false, "description": "DESCRIPTION", "name": "NAME", "orgID": "ORGID", "remoteAPIToken": "REMOTEAPITOKEN", "remoteOrgID": "REMOTEORGID", "remoteURL": "REMOTEURL" }' ``` #### Responses 201Remote connection saved `allowInsecureTLS`requiredboolean `description`string `id`requiredstring `name`requiredstring `orgID`requiredstring `remoteOrgID`string `remoteURL`requiredstring \ 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/remotes/{remoteID}` ### Retrieve a remote connection #### Parameters ##### Path parameters `remoteID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/remotes/{remoteID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Remote connection `allowInsecureTLS`requiredboolean `description`string `id`requiredstring `name`requiredstring `orgID`requiredstring `remoteOrgID`string `remoteURL`requiredstring \ 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/remotes/{remoteID}` ### Update a remote connection #### Parameters ##### Path parameters `remoteID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `allowInsecureTLS`boolean `description`string `name`string `remoteAPIToken`string `remoteOrgID`string `remoteURL`string \ Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/remotes/{remoteID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "allowInsecureTLS": false, "description": "DESCRIPTION", "name": "NAME", "remoteAPIToken": "REMOTEAPITOKEN", "remoteOrgID": "REMOTEORGID", "remoteURL": "REMOTEURL" }' ``` #### Responses 200Updated information saved `allowInsecureTLS`requiredboolean `description`string `id`requiredstring `name`requiredstring `orgID`requiredstring `remoteOrgID`string `remoteURL`requiredstring \ 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/remotes/{remoteID}` ### Delete a remote connection #### Parameters ##### Path parameters `remoteID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/remotes/{remoteID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Remote connection info deleted. 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Replications Source: https://docs.influxdata.com/influxdb/v2/api/replications/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage replication streams that copy data from an InfluxDB OSS v2 bucket to a remote InfluxDB instance. GET`/api/v2/replications` ### List all replications #### Parameters ##### Query parameters `orgID`requiredstring The organization ID. `name`string `remoteID`string `localBucketID`string ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/replications?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200List of replications `replications`object[] `currentQueueSizeBytes`integer \ `description`string `dropNonRetryableData`boolean `id`requiredstring `latestErrorMessage`string `latestResponseCode`integer `localBucketID`requiredstring `maxQueueSizeBytes`requiredinteger \ `name`requiredstring `orgID`requiredstring `remainingBytesToBeSynced`integer \ `remoteBucketID`string `remoteBucketName`string `remoteID`requiredstring 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/replications` ### Register a new replication #### Parameters ##### Query parameters `validate`boolean If true, validate the replication, but don’t save it. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `description`string `dropNonRetryableData`boolean `localBucketID`requiredstring `maxAgeSeconds`requiredinteger \ Default:`604800` `maxQueueSizeBytes`requiredinteger \ Default:`67108860` `name`requiredstring `orgID`requiredstring `remoteBucketID`string `remoteBucketName`string `remoteID`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/replications" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "dropNonRetryableData": false, "localBucketID": "LOCALBUCKETID", "maxAgeSeconds": 604800, "maxQueueSizeBytes": 67108860, "name": "NAME", "orgID": "ORGID", "remoteBucketID": "REMOTEBUCKETID", "remoteBucketName": "REMOTEBUCKETNAME", "remoteID": "REMOTEID" }' ``` #### Responses 201Replication saved `currentQueueSizeBytes`integer \ `description`string `dropNonRetryableData`boolean `id`requiredstring `latestErrorMessage`string `latestResponseCode`integer `localBucketID`requiredstring `maxQueueSizeBytes`requiredinteger \ `name`requiredstring `orgID`requiredstring `remainingBytesToBeSynced`integer \ `remoteBucketID`string `remoteBucketName`string `remoteID`requiredstring 204Replication validated, but not saved 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/replications/{replicationID}` ### Retrieve a replication #### Parameters ##### Path parameters `replicationID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/replications/{replicationID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Replication `currentQueueSizeBytes`integer \ `description`string `dropNonRetryableData`boolean `id`requiredstring `latestErrorMessage`string `latestResponseCode`integer `localBucketID`requiredstring `maxQueueSizeBytes`requiredinteger \ `name`requiredstring `orgID`requiredstring `remainingBytesToBeSynced`integer \ `remoteBucketID`string `remoteBucketName`string `remoteID`requiredstring 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/replications/{replicationID}` ### Update a replication #### Parameters ##### Path parameters `replicationID`requiredstring ##### Query parameters `validate`boolean If true, validate the updated information, but don’t save it. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `description`string `dropNonRetryableData`boolean `maxAgeSeconds`integer \ `maxQueueSizeBytes`integer \ `name`string `remoteBucketID`string `remoteBucketName`string `remoteID`string Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/replications/{replicationID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "dropNonRetryableData": false, "maxAgeSeconds": 0, "maxQueueSizeBytes": 0, "name": "NAME", "remoteBucketID": "REMOTEBUCKETID", "remoteBucketName": "REMOTEBUCKETNAME", "remoteID": "REMOTEID" }' ``` #### Responses 200Updated information saved `currentQueueSizeBytes`integer \ `description`string `dropNonRetryableData`boolean `id`requiredstring `latestErrorMessage`string `latestResponseCode`integer `localBucketID`requiredstring `maxQueueSizeBytes`requiredinteger \ `name`requiredstring `orgID`requiredstring `remainingBytesToBeSynced`integer \ `remoteBucketID`string `remoteBucketName`string `remoteID`requiredstring 204Updated replication validated, but not saved 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/replications/{replicationID}` ### Delete a replication #### Parameters ##### Path parameters `replicationID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/replications/{replicationID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Replication deleted. 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/replications/{replicationID}/validate` ### Validate a replication #### Parameters ##### Path parameters `replicationID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/replications/{replicationID}/validate" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Replication is valid 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Resources Source: https://docs.influxdata.com/influxdb/v2/api/resources/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve a list of top-level resource types available in the InfluxDB OSS v2 API. GET`/api/v2/resources` ### List all known resources #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/resources" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200All resources targets defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Response codes Source: https://docs.influxdata.com/influxdb/v2/api/response-codes/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) InfluxDB OSS v2 API endpoints return standard HTTP status codes. The following table summarizes the most common response codes. | Status code | Meaning | |---------------------------|----------------------------------------------------------------| | `200 OK` | Success. | | `201 Created` | The resource was created. | | `204 No Content` |Success with no response body (typically after write or delete).| | `400 Bad Request` | Request parameters or body are malformed or invalid. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Credentials lack permission for the requested resource. | | `404 Not Found` | The requested resource does not exist. | | `413 Payload Too Large` | Request body exceeds the maximum allowed size. | |`422 Unprocessable Entity` | Request body is well-formed but semantically invalid. | | `429 Too Many Requests` | Rate limit exceeded. | |`500 Internal Server Error`| Unexpected server error. | | `503 Service Unavailable` | Server is overloaded or under maintenance. | | Status code | Meaning | | --- | --- | | Status code | Meaning | | 200 OK | Success. | | 201 Created | The resource was created. | | 204 No Content | Success with no response body (typically after write or delete). | | 400 Bad Request | Request parameters or body are malformed or invalid. | | 401 Unauthorized | Missing or invalid credentials. | | 403 Forbidden | Credentials lack permission for the requested resource. | | 404 Not Found | The requested resource does not exist. | | 413 Payload Too Large | Request body exceeds the maximum allowed size. | | 422 Unprocessable Entity | Request body is well-formed but semantically invalid. | | 429 Too Many Requests | Rate limit exceeded. | | 500 Internal Server Error | Unexpected server error. | | 503 Service Unavailable | Server is overloaded or under maintenance. | --- # Restore Source: https://docs.influxdata.com/influxdb/v2/api/restore/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Restore InfluxDB OSS v2 data from a backup, including time series data and metadata. POST`/api/v2/restore/bucket/{bucketID}`Deprecated ### Overwrite storage metadata for a bucket with shard info from a backup. #### Parameters ##### Path parameters `bucketID`requiredstring The bucket ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Type`string Allowed values:`application/octet-stream` Default:`application/octet-stream` #### Request bodyrequired Database info serialized as protobuf. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/restore/bucket/{bucketID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1.0' ``` #### Responses 200ID mappings for shards in bucket. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/restore/bucketMetadata` ### Create a new bucket pre-seeded with shard info from a backup. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Metadata manifest for a bucket. Content-Type:`application/json` `bucketID`requiredstring `bucketName`requiredstring `defaultRetentionPolicy`requiredstring `description`string `organizationID`requiredstring `organizationName`requiredstring `retentionPolicies`requiredobject[] `duration`requiredinteger \ `name`requiredstring `replicaN`requiredinteger `shardGroupDuration`requiredinteger \ `shardGroups`requiredobject[] `deletedAt`string \ `endTime`requiredstring \ `id`requiredinteger \ `shards`requiredobject[] `startTime`requiredstring \ `truncatedAt`string \ `subscriptions`requiredobject[] `destinations`requiredstring[] `mode`requiredstring `name`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/restore/bucketMetadata" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucketID": "BUCKETID", "bucketName": "BUCKETNAME", "defaultRetentionPolicy": "DEFAULTRETENTIONPOLICY", "description": "DESCRIPTION", "organizationID": "ORGANIZATIONID", "organizationName": "ORGANIZATIONNAME", "retentionPolicies": [ { "duration": 0, "name": "NAME", "replicaN": 0, "shardGroupDuration": 0, "shardGroups": [], "subscriptions": [] } ] }' ``` #### Responses 201ID mappings for shards in new bucket. `id`requiredstring New ID of the restored bucket `name`requiredstring `shardMappings`requiredobject[] `newId`requiredinteger \ `oldId`requiredinteger \ defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/restore/kv` ### Overwrite the embedded KV store on the server with a backed-up snapshot. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Encoding`string The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/octet-stream` Default:`application/octet-stream` #### Request bodyrequired Full KV snapshot. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/restore/kv" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1.0' ``` #### Responses 200KV store successfully overwritten. `token`string token is the root token for the instance after restore (this is overwritten during the restore) 204KV store successfully overwritten. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/restore/shards/{shardID}` ### Restore a TSM snapshot into a shard. #### Parameters ##### Path parameters `shardID`requiredstring The shard ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Encoding`string The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/octet-stream` Default:`application/octet-stream` #### Request bodyrequired TSM snapshot. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/restore/shards/{shardID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1.0' ``` #### Responses 204TSM snapshot successfully restored. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/restore/sql` ### Overwrite the embedded SQL store on the server with a backed-up snapshot. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Content-Encoding`string The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. Allowed values:`gzip`, `identity` Default:`identity` `Content-Type`string Allowed values:`application/octet-stream` Default:`application/octet-stream` #### Request bodyrequired Full SQL snapshot. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/restore/sql" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'measurement,tag=value field=1.0' ``` #### Responses 204SQL store successfully overwritten. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Routes Source: https://docs.influxdata.com/influxdb/v2/api/routes/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve top-level routes for the InfluxDB OSS v2 API. GET`/api/v2` ### List all top level routes Retrieves all the top level routes for the InfluxDB API. #### Limitations * Only returns top level routes–for example, the response contains`"tasks":"/api/v2/tasks"`, and doesn’t contain resource-specific routes for tasks (`/api/v2/tasks/TASK_ID/...`). #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains key-value pairs with the resource name and top-level route. `authorizations`string \ `backup`string \ `buckets`string \ `checks`string \ `dashboards`string \ `delete`string \ `external`object `statusFeed`string \ `flags`string \ `invocableScripts`string \ `labels`string \ `me`string \ `notificationEndpoints`string \ `notificationRules`string \ `orgs`string \ `plugins`string \ `query`object `analyze`string \ `ast`string \ `self`string \ `suggestions`string \ `restore`string \ `scrapers`string \ `setup`string \ `signin`string \ `signout`string \ `sources`string \ `swagger`string \ `system`object `debug`string \ `health`string \ `metrics`string \ `ready`string \ `tasks`string \ `telegraf`object `plugins`string \ `telegrafs`string \ `users`string \ `variables`string \ `write`string \ --- # Rules Source: https://docs.influxdata.com/influxdb/v2/api/rules/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Manage notification rules in InfluxDB OSS v2. GET`/api/v2/notificationRules/{ruleID}/query` ### Retrieve a notification rule query #### Parameters ##### Path parameters `ruleID`requiredstring The notification rule ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/notificationRules/{ruleID}/query" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The notification rule query requested `flux`string 400Invalid request `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 404Notification rule not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Scraper Targets Source: https://docs.influxdata.com/influxdb/v2/api/scraper-targets/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage Prometheus scraper targets that collect metrics and write them to InfluxDB OSS v2 buckets. GET`/api/v2/scrapers` ### List all scraper targets #### Parameters ##### Query parameters `name`string Specifies the name of the scraper target. `id`array List of scraper target IDs to return. If both `id` and `owner` are specified, only `id` is used. `orgID`string Specifies the organization ID of the scraper target. `org`string Specifies the organization name of the scraper target. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/scrapers" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200All scraper targets `configurations`object[] `allowInsecure`boolean Skip TLS verification on endpoint. `bucket`string The bucket name. `bucketID`string The ID of the bucket to write to. `id`string `links`object Example:`{"bucket":"/api/v2/buckets/1","members":"/api/v2/scrapers/1/members","organization":"/api/v2/orgs/1","owners":"/api/v2/scrapers/1/owners","self":"/api/v2/scrapers/1"}` `bucket`string \ URI of resource. `members`string \ URI of resource. `organization`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `name`string The name of the scraper target. `org`string The name of the organization. `orgID`string The organization ID. `type`string The type of the metrics to be parsed. Allowed:`prometheus` `url`string The URL of the metrics endpoint. Example:`"http://localhost:9090/metrics"` POST`/api/v2/scrapers` ### Create a scraper target #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Scraper target to create Content-Type:`application/json` `allowInsecure`boolean Skip TLS verification on endpoint. `bucketID`string The ID of the bucket to write to. `name`string The name of the scraper target. `orgID`string The organization ID. `type`string The type of the metrics to be parsed. Allowed:`prometheus` `url`string The URL of the metrics endpoint. Example:`"http://localhost:9090/metrics"` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/scrapers" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "allowInsecure": false, "bucketID": "BUCKETID", "name": "NAME", "orgID": "ORGID", "type": "prometheus", "url": "http://localhost:9090/metrics" }' ``` #### Responses 201Scraper target created defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/scrapers/{scraperTargetID}` ### Retrieve a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The identifier of the scraper target. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The scraper target defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/scrapers/{scraperTargetID}` ### Update a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The identifier of the scraper target. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Scraper target update to apply Content-Type:`application/json` `allowInsecure`boolean Skip TLS verification on endpoint. `bucketID`string The ID of the bucket to write to. `name`string The name of the scraper target. `orgID`string The organization ID. `type`string The type of the metrics to be parsed. Allowed:`prometheus` `url`string The URL of the metrics endpoint. Example:`"http://localhost:9090/metrics"` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "allowInsecure": false, "bucketID": "BUCKETID", "name": "NAME", "orgID": "ORGID", "type": "prometheus", "url": "http://localhost:9090/metrics" }' ``` #### Responses 200Scraper target updated defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/scrapers/{scraperTargetID}` ### Delete a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The identifier of the scraper target. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Scraper target deleted defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/scrapers/{scraperTargetID}/labels` ### List all labels for a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of labels for a scraper target. `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/scrapers/{scraperTargetID}/labels` ### Add a label to a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The newly added label `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/scrapers/{scraperTargetID}/labels/{labelID}` ### Delete a label from a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. `labelID`requiredstring The label ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Scraper target not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/scrapers/{scraperTargetID}/members` ### List all users with member privileges for a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of scraper target members `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/scrapers/{scraperTargetID}/members` ### Add a member to a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as member Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Member added to scraper targets defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/scrapers/{scraperTargetID}/members/{userID}` ### Remove a member from a scraper target #### Parameters ##### Path parameters `userID`requiredstring The ID of member to remove. `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Member removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/scrapers/{scraperTargetID}/owners` ### List all owners of a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of scraper target owners `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/scrapers/{scraperTargetID}/owners` ### Add an owner to a scraper target #### Parameters ##### Path parameters `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as owner Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Scraper target owner added defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/scrapers/{scraperTargetID}/owners/{userID}` ### Remove an owner from a scraper target #### Parameters ##### Path parameters `userID`requiredstring The ID of owner to remove. `scraperTargetID`requiredstring The scraper target ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/scrapers/{scraperTargetID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Owner removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Secrets Source: https://docs.influxdata.com/influxdb/v2/api/secrets/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage secrets (key-value pairs) for use in InfluxDB OSS v2 Flux scripts and tasks. GET`/api/v2/orgs/{orgID}/secrets` ### List all secret keys for an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all secret keys defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/orgs/{orgID}/secrets` ### Update secrets in an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Secret key value pairs to update/add Content-Type:`application/json` Example request body ```json { "apikey": "abc123xyz" } ``` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"apikey":"abc123xyz"}' ``` #### Responses 204Keys successfully patched defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}` ### Delete a secret from an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. `secretID`requiredstring The secret ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets/{secretID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Keys successfully deleted defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/orgs/{orgID}/secrets/delete`Deprecated ### Delete secrets from an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Secret key to delete Content-Type:`application/json` `secrets`string[] Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets/delete" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "secrets": [ "SECRETS" ] }' ``` #### Responses 204Keys successfully patched defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Security and access endpoints Source: https://docs.influxdata.com/influxdb/v2/api/security-and-access-endpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Endpoints for managing authentication and access control in InfluxDB OSS v2. GET`/api/v2/authorizations` ### List authorizations Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. #### InfluxDB Cloud * InfluxDB Cloud doesn’t expose [API token](/influxdb/v2/reference/glossary/#token)values in `GET /api/v2/authorizations` responses; returns `token: redacted` for all authorizations. #### Required permissions To retrieve an authorization, the request must use an API token that has the following permissions: * `read-authorizations` * `read-user` for the user that the authorization is scoped to #### Related guides * [View tokens](/influxdb/v2/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb/v2/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb/v2/reference/glossary/#organization). `token`string An API [token](/influxdb/v2/reference/glossary/#token) value. Specifies an authorization by its `token` property value and returns the authorization. #### InfluxDB OSS * Doesn’t support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. #### Limitations * The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn’t exist, then the response body contains an empty list. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains a list of authorizations. If the response body is missing authorizations that you expect, check that the API token used in the request has `read-user` permission for the users (`userID` property value) in those authorizations. #### InfluxDB OSS * **Warning**: The response body contains authorizations with their[API token](/influxdb/v2/reference/glossary/#token) values in clear text. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. `authorizations`object[] `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/v2/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/v2/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/v2/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx`CLI commands–after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/authorizations` ### Create an authorization Creates an authorization and returns the authorization with the generated API [token](/influxdb/v2/reference/glossary/#token). Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. The API token is the authorization’s `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. * InfluxDB allows access to the API token value immediately after the authorization is created. * You can’t change access (read/write) permissions for an API token after it’s created. * Tokens stop working when the user who created the token is deleted. We recommend the following for managing your tokens: * Create a generic user to create and manage tokens for writing data. * Store your tokens in a secure password vault for future access. #### Required permissions * `write-authorizations` * `write-user` for the user that the authorization is scoped to #### Related guides * [Create a token](/influxdb/v2/security/tokens/create-token/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The authorization to create. Content-Type:`application/json` `description`string A description of the token. `orgID`requiredstring An organization ID. Specifies the organization that owns the authorization. `permissions`requiredobject[] A list of permissions for an authorization. In the list, provide at least one `permission` object. In a `permission`, the `resource.type` property grants access to all resources of the specified type. To grant access to only a specific resource, specify the`resource.id` property. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `id`string A resource ID. Identifies a specific resource. `name`string The name of the resource.*Note: not all resource types have a `name` property*. `org`string An organization name. The organization that owns the resource. `orgID`string An organization ID. Identifies the organization that owns the resource. `type`requiredstring A resource type. Identifies the API resource’s type (or *kind*). Allowed:`authorizations`, `buckets`, `dashboards`, `orgs`, `tasks`, `telegrafs`, `users`, `variables`, `secrets`, `labels`, `views`, `documents`, `notificationRules`, `notificationEndpoints`, `checks`, `dbrp`, `annotations`, `sources`, `scrapers`, `notebooks`, `remotes`, `replications`, `instance`, `flows`, `functions`, `subscriptions` `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `userID`string A user ID. Specifies the user that the authorization is scoped to. When a user authenticates with username and password, InfluxDB generates a *user session* with all the permissions specified by all the user’s authorizations. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "orgID": "ORGID", "permissions": [ { "action": "read", "resource": {} } ], "status": "active", "userID": "USERID" }' ``` #### Responses 201Success. The authorization is created. The response body contains the authorization. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/authorizations/{authID}` ### Retrieve an authorization Retrieves an authorization. Use this endpoint to retrieve information about an API token, including the token’s permissions and the user that the token is scoped to. #### InfluxDB OSS * InfluxDB OSS returns[API token](/influxdb/v2/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides * [View tokens](/influxdb/v2/security/tokens/view-tokens/) #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the authorization. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/authorizations/{authID}` ### Update an API token to be active or inactive Updates an authorization. Use this endpoint to set an API token’s status to be *active* or *inactive*. InfluxDB rejects requests that use inactive API tokens. #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired In the request body, provide the authorization properties to update. Content-Type:`application/json` `description`string A description of the token. `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "status": "active" }' ``` #### Responses 200Success. The response body contains the updated authorization. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/authorizations/{authID}` ### Delete an authorization Deletes an authorization. Use the endpoint to delete an API token. If you want to disable an API token instead of delete it,[update the authorization’s status to `inactive`](#operation/PatchAuthorizationsID). #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The authorization is deleted. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs` ### List organizations Lists [organizations](/influxdb/v2/reference/glossary/#organization/). To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud * Only returns the organization that owns the token passed in the request. #### Related guides * [View organizations](/influxdb/v2/organizations/view-orgs/) #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `descending`boolean `org`string An organization name. Only returns the specified organization. `orgID`string An organization ID. Only returns the specified organization. `userID`string A user ID. Only returns organizations where the specified user is a member or owner. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of organizations. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `orgs`object[] `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}` ### Retrieve an organization Retrieves an organization. Use this endpoint to retrieve information for a specific organization. #### Related guides * [View organizations](/influxdb/v2/organizations/view-orgs/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the organization information. `createdAt`string \ `defaultStorageType`string Discloses whether the organization uses TSM or IOx. Allowed:`tsm`, `iox` `description`string `id`string `links`object Example:`{"buckets":"/api/v2/buckets?org=myorg","dashboards":"/api/v2/dashboards?org=myorg","labels":"/api/v2/orgs/1/labels","members":"/api/v2/orgs/1/members","owners":"/api/v2/orgs/1/owners","secrets":"/api/v2/orgs/1/secrets","self":"/api/v2/orgs/1","tasks":"/api/v2/tasks?org=myorg"}` `buckets`string \ URI of resource. `dashboards`string \ URI of resource. `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `secrets`string \ URI of resource. `self`string \ URI of resource. `tasks`string \ URI of resource. `name`requiredstring `status`string If inactive, the organization is inactive. Allowed:`active`, `inactive` Default:`active` `updatedAt`string \ 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. Organization not found. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}/members` ### List all members of an organization Lists all users that belong to an organization. InfluxDB [users](/influxdb/v2/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/v2/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Member permissions are separate from API token permissions. * Member permissions are used in the context of the InfluxDB UI. #### Required permissions * `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve members for. #### Related guides * [Manage users](/influxdb/v2/users/) * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to retrieve users for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all users within the organization. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. InfluxDB can’t find the organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/members/{userID}` ### Remove a member from an organization Removes a member from an organization. Use this endpoint to remove a user’s member privileges for an organization. Removing member privileges removes the user’s `read` and `write` permissions from the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Member permissions are separate from API token permissions. * Member permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related guides * [Manage members](/influxdb/v2/organizations/members/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to remove. `orgID`requiredstring The ID of the organization to remove a user from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer a member of the organization. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}/owners` ### List all owners of an organization Lists all owners of an organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions * `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a list of owners from. #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization to list owners for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of organization owners `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 404Organization not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/owners/{userID}` ### Remove an owner from an organization Removes an [owner](/influxdb/v2/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member permissions from the organization. #### InfluxDB Cloud * Doesn’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations * Owner permissions are separate from API token permissions. * Owner permissions are used in the context of the InfluxDB UI. #### Required permissions * `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related endpoints * [Authorizations](#tag/Authorizations-(API-tokens)) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to remove. `orgID`requiredstring The ID of the organization to remove an owner from. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is no longer an owner of the organization. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/orgs/{orgID}/secrets` ### List all secret keys for an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all secret keys defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}` ### Delete a secret from an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. `secretID`requiredstring The secret ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets/{secretID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Keys successfully deleted defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/orgs/{orgID}/secrets/delete`Deprecated ### Delete secrets from an organization #### Parameters ##### Path parameters `orgID`requiredstring The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Secret key to delete Content-Type:`application/json` `secrets`string[] Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/orgs/{orgID}/secrets/delete" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "secrets": [ "SECRETS" ] }' ``` #### Responses 204Keys successfully patched defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/signin` ### Create a user session. Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication)for a [user](/influxdb/v2/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the`Basic` scheme and the base64-encoded username and password. For syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for syntax and more information. If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the `Set-Cookie` response header. InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance. #### User sessions with authorizations * In InfluxDB Cloud, a user session inherits all the user’s permissions for the organization. * In InfluxDB OSS, a user session inherits all the user’s permissions for all the organizations that the user belongs to. #### Related endpoints * [Signout](#tag/Signout) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/signin" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is authenticated. The `Set-Cookie` response header contains the session cookie. 401 Unauthorized. This error may be caused by one of the following problems: * The user doesn’t have access. * The user passed incorrect credentials in the request. * The credentials are formatted incorrectly in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 403Forbidden. The user account is disabled. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnsuccessful authentication. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/signout` ### Expire a user session Expires a user session specified by a session cookie. Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint. For example, the `POST /api/v2/signout` endpoint represents the third step in the following three-step process to authenticate a user, retrieve the `user` resource, and then expire the session: 1. Send a request with the user’s [Basic authentication credentials](#section/Authentication/BasicAuthentication)to the `POST /api/v2/signin` endpoint to create a user session and generate a session cookie. 2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie from step 1 to retrieve user information. 3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session cookie to expire the session. *See the complete example in request samples.* InfluxDB stores user sessions in memory only. If a user doesn’t sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance. To learn more about cookies in HTTP requests, see[Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). #### Related endpoints * [Signin](#tag/Signin) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/signout" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The session is expired. 401Unauthorized. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultThe session expiry is unsuccessful. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/users` ### List users Lists [users](/influxdb/v2/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. #### Required permissions for InfluxDB OSS | Action | Permission required |Restriction| |--------------------|----------------------------------------------------------------|-----------| | List all users |*[Operator token](/influxdb/v2/security/tokens/#operator-token)*| | |List a specific user| `read-users` or `read-user USER_ID` | | *`USER_ID`* is the ID of the user that you want to retrieve. #### Related guides * [View users](/influxdb/v2/users/view-users/). #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `after`string A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `name`string A user name. Only lists the specified [user](/influxdb/v2/reference/glossary/#user). `id`string A user ID. Only lists the specified [user](/influxdb/v2/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response contains a list of `users`. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 401Unauthorized. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/users/{userID}` ### Retrieve a user Retrieves a [user](/influxdb/v2/reference/glossary/#user). #### Related guides * [Manage users](/influxdb/v2/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Retrieves the specified [user](/influxdb/v2/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the user. `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/users/{userID}/password` ### Update a password Updates a user password. #### InfluxDB Cloud * Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides * [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) * [InfluxDB OSS - Change your password](/influxdb/v2/users/change-password/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to set the password for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The new password to set for the user. Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/users/{userID}/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Success. The password is updated. 400 Bad request. #### InfluxDB Cloud * Doesn’t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS * Doesn’t understand a value passed in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/users/{userID}/password` ### Update a password Updates a user password. Use this endpoint to let a user authenticate with[Basic authentication credentials](#section/Authentication/BasicAuthentication)and set a new password. #### InfluxDB Cloud * Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides * [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) * [InfluxDB OSS - Change your password](/influxdb/v2/users/change-password/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to set the password for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The new password to set for the user. Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/users/{userID}/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Success. The password is updated. 400 Bad request. #### InfluxDB Cloud * Doesn’t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS * Doesn’t understand a value passed in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [View tokens](/influxdb/v2/security/tokens/view-tokens/) | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | List all users | Operator token | | | List a specific user | read-users or read-user USER_ID | | --- # Setup Source: https://docs.influxdata.com/influxdb/v2/api/setup/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Configure a new InfluxDB OSS v2 instance, including creating the initial user, organization, bucket, and API token. GET`/api/v2/setup` ### Check if database has default user, org, bucket Returns `true` if no default user, organization, or bucket has been created. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200allowed true or false `allowed`boolean If `true`, the InfluxDB instance hasn’t had initial setup;`false` otherwise. POST`/api/v2/setup` ### Set up initial user, org and bucket Post an onboarding request to set up initial user, org and bucket. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Source to create Content-Type:`application/json` `bucket`requiredstring `org`requiredstring `password`string `retentionPeriodHrs`integer Retention period *in nanoseconds* for the new bucket. This key’s name has been misleading since OSS 2.0 GA, please transition to use `retentionPeriodSeconds` `retentionPeriodSeconds`integer \ `token`string Authentication token to set on the initial user. If not specified, the server will generate a token. `username`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucket": "BUCKET", "org": "ORG", "password": "PASSWORD", "retentionPeriodHrs": 0, "retentionPeriodSeconds": 0, "token": "TOKEN", "username": "USERNAME" }' ``` #### Responses 201Created default user, bucket, org `auth`object `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/v2/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/v2/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/v2/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx`CLI commands–after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `bucket`string `org`string `user`string defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Set up InfluxDB](/influxdb/v2/get-started/) --- # Signin Source: https://docs.influxdata.com/influxdb/v2/api/signin/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create a user session by signing in with username and password credentials. POST`/api/v2/signin` ### Create a user session. Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication)for a [user](/influxdb/v2/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the`Basic` scheme and the base64-encoded username and password. For syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for syntax and more information. If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the `Set-Cookie` response header. InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance. #### User sessions with authorizations * In InfluxDB Cloud, a user session inherits all the user’s permissions for the organization. * In InfluxDB OSS, a user session inherits all the user’s permissions for all the organizations that the user belongs to. #### Related endpoints * [Signout](#tag/Signout) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/signin" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is authenticated. The `Set-Cookie` response header contains the session cookie. 401 Unauthorized. This error may be caused by one of the following problems: * The user doesn’t have access. * The user passed incorrect credentials in the request. * The credentials are formatted incorrectly in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 403Forbidden. The user account is disabled. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnsuccessful authentication. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Signout Source: https://docs.influxdata.com/influxdb/v2/api/signout/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) End a user session by signing out. POST`/api/v2/signout` ### Expire a user session Expires a user session specified by a session cookie. Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint. For example, the `POST /api/v2/signout` endpoint represents the third step in the following three-step process to authenticate a user, retrieve the `user` resource, and then expire the session: 1. Send a request with the user’s [Basic authentication credentials](#section/Authentication/BasicAuthentication)to the `POST /api/v2/signin` endpoint to create a user session and generate a session cookie. 2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie from step 1 to retrieve user information. 3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session cookie to expire the session. *See the complete example in request samples.* InfluxDB stores user sessions in memory only. If a user doesn’t sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance. To learn more about cookies in HTTP requests, see[Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). #### Related endpoints * [Signin](#tag/Signin) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/signout" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The session is expired. 401Unauthorized. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultThe session expiry is unsuccessful. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Sources Source: https://docs.influxdata.com/influxdb/v2/api/sources/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Manage data sources configured in InfluxDB OSS v2. GET`/api/v2/sources` ### List all sources #### Parameters ##### Query parameters `org`string The name of the organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/sources" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of sources `links`object `self`string \ `sources`object[] `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/sources` ### Create a source #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Source to create Content-Type:`application/json` `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/sources" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "default": false, "defaultRP": "DEFAULTRP", "id": "ID", "insecureSkipVerify": false, "languages": [ "flux" ], "links": { "buckets": "BUCKETS", "health": "HEALTH", "query": "QUERY", "self": "SELF" }, "metaUrl": "METAURL", "name": "NAME", "orgID": "ORGID", "password": "PASSWORD", "sharedSecret": "SHAREDSECRET", "telegraf": "TELEGRAF", "token": "TOKEN", "type": "v1", "url": "URL", "username": "USERNAME" }' ``` #### Responses 201Created Source `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/sources/{sourceID}` ### Retrieve a source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/sources/{sourceID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A source `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string 404Source not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/sources/{sourceID}` ### Update a Source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Source update Content-Type:`application/json` `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/sources/{sourceID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "default": false, "defaultRP": "DEFAULTRP", "id": "ID", "insecureSkipVerify": false, "languages": [ "flux" ], "links": { "buckets": "BUCKETS", "health": "HEALTH", "query": "QUERY", "self": "SELF" }, "metaUrl": "METAURL", "name": "NAME", "orgID": "ORGID", "password": "PASSWORD", "sharedSecret": "SHAREDSECRET", "telegraf": "TELEGRAF", "token": "TOKEN", "type": "v1", "url": "URL", "username": "USERNAME" }' ``` #### Responses 200Created Source `default`boolean `defaultRP`string `id`string `insecureSkipVerify`boolean `languages`string[] `links`object `buckets`string `health`string `query`string `self`string `metaUrl`string \ `name`string `orgID`string `password`string `sharedSecret`string `telegraf`string `token`string `type`string Allowed:`v1`, `v2`, `self` `url`string \ `username`string 404Source not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/sources/{sourceID}` ### Delete a source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/sources/{sourceID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404View not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/sources/{sourceID}/buckets` ### Get buckets in a source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Query parameters `org`string The name of the organization. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/sources/{sourceID}/buckets" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A source `buckets`object[] `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `org`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `write`string \ URI of resource. `name`requiredstring `orgID`string `retentionRules`requiredobject[] Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2/reference/glossary/#retention-period). #### InfluxDB Cloud * `retentionRules` is required. #### InfluxDB OSS * `retentionRules` isn’t required. `everySeconds`requiredinteger \ The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. Default:`2592000` Example:`86400` `shardGroupDurationSeconds`integer \ The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud * Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS * Default value depends on the[bucket retention period](/influxdb/v2/reference/internals/shards/#shard-group-duration). `type`string Allowed:`expire` Default:`expire` `rp`string `schemaType`string Allowed:`implicit`, `explicit` `type`string Allowed:`user`, `system` Default:`user` `updatedAt`string \ `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 404Source not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/sources/{sourceID}/health` ### Get the health of a source #### Parameters ##### Path parameters `sourceID`requiredstring The source ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/sources/{sourceID}/health" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The source is healthy `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. 503The source is not healthy `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Supported operations Source: https://docs.influxdata.com/influxdb/v2/api/supported-operations/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) The InfluxDB OSS v2 API supports create, read, update, and delete operations on resources. Most endpoints follow standard HTTP method conventions: |Operation | HTTP Method | Description | |----------|--------------|---------------------------------------| |**Write** | `POST` | Send data or create a resource. | | **Read** | `GET` |Retrieve a resource or list resources. | |**Update**|`PUT`, `PATCH`|Replace or modify an existing resource.| |**Delete**| `DELETE` | Remove a resource. | | Operation | HTTP Method | Description | | --- | --- | --- | | Operation | HTTP Method | Description | | Write | POST | Send data or create a resource. | | Read | GET | Retrieve a resource or list resources. | | Update | PUT , PATCH | Replace or modify an existing resource. | | Delete | DELETE | Remove a resource. | --- # System information endpoints Source: https://docs.influxdata.com/influxdb/v2/api/system-information-endpoints/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Endpoints for retrieving system-level information about the InfluxDB OSS v2 instance. GET`/api/v2/config` ### Retrieve runtime configuration Returns the active runtime configuration of the InfluxDB instance. In InfluxDB v2.2+, use this endpoint to view your active runtime configuration, including flags and environment variables. #### Related guides * [View your runtime server configuration](/influxdb/v2/reference/config-options/#view-your-runtime-server-configuration) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/config" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the active runtime configuration of the InfluxDB instance. `config`object 401Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/resources` ### List all known resources #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/resources" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200All resources targets defaultInternal server error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2` ### List all top level routes Retrieves all the top level routes for the InfluxDB API. #### Limitations * Only returns top level routes–for example, the response contains`"tasks":"/api/v2/tasks"`, and doesn’t contain resource-specific routes for tasks (`/api/v2/tasks/TASK_ID/...`). #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains key-value pairs with the resource name and top-level route. `authorizations`string \ `backup`string \ `buckets`string \ `checks`string \ `dashboards`string \ `delete`string \ `external`object `statusFeed`string \ `flags`string \ `invocableScripts`string \ `labels`string \ `me`string \ `notificationEndpoints`string \ `notificationRules`string \ `orgs`string \ `plugins`string \ `query`object `analyze`string \ `ast`string \ `self`string \ `suggestions`string \ `restore`string \ `scrapers`string \ `setup`string \ `signin`string \ `signout`string \ `sources`string \ `swagger`string \ `system`object `debug`string \ `health`string \ `metrics`string \ `ready`string \ `tasks`string \ `telegraf`object `plugins`string \ `telegrafs`string \ `users`string \ `variables`string \ `write`string \ GET`/debug/pprof/all` ### Retrieve all runtime profiles Collects samples and returns reports for the following [Go runtime profiles](https://pkg.go.dev/runtime/pprof): * **allocs**: All past memory allocations * **block**: Stack traces that led to blocking on synchronization primitives * **cpu**: (Optional) Program counters sampled from the executing stack. Include by passing the `cpu` query parameter with a [duration](/influxdb/v2/reference/glossary/#duration) value. Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile). * **goroutine**: All current goroutines * **heap**: Memory allocations for live objects * **mutex**: Holders of contended mutexes * **threadcreate**: Stack traces that led to the creation of new OS threads #### Parameters ##### Query parameters `cpu`string \ Collects and returns CPU profiling data for the specified [duration](/influxdb/v2/reference/glossary/#duration). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/all" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/allocs` ### Retrieve the memory allocations runtime profile Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of all past memory allocations.**allocs** is the same as the **heap** profile, but changes the default [pprof](https://pkg.go.dev/runtime/pprof)display to **-alloc\_space**, the total number of bytes allocated since the program began (including garbage-collected bytes). #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/allocs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/block` ### Retrieve the block runtime profile Collects samples and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of stack traces that led to blocking on synchronization primitives. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/block" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/cmdline` ### Retrieve the command line invocation Returns the command line that invoked InfluxDB. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/cmdline" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Command line invocation. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/goroutine` ### Retrieve the goroutines runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of all current goroutines. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text with comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/goroutine" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/heap` ### Retrieve the heap runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of memory allocations for live objects. To run **garbage collection** before sampling, pass the `gc` query parameter with a value of `1`. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. `gc`integer \ * `0`: (Default) don’t force garbage collection before sampling. * `1`: Force garbage collection before sampling. Allowed values:`0`, `1` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/heap" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/mutex` ### Retrieve the mutual exclusion (mutex) runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of lock contentions. The profile contains stack traces of holders of contended mutual exclusions (mutexes). #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/mutex" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/profile` ### Retrieve the CPU runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of program counters on the executing stack. #### Parameters ##### Query parameters `seconds`string \ Number of seconds to collect profile data. Default is `30` seconds. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/profile" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/threadcreate` ### Retrieve the threadcreate runtime profile Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)report of stack traces that led to the creation of new OS threads. #### Parameters ##### Query parameters `debug`integer \ * `0`: (Default) Return the report as a gzip-compressed protocol buffer. * `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. Allowed values:`0`, `1` `seconds`string \ Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/threadcreate" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible with [pprof](https://github.com/google/pprof) analysis and visualization tools. If debug is enabled (`?debug=1`), response body contains a human-readable profile. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/debug/pprof/trace` ### Retrieve the runtime execution trace Collects profile data and returns trace execution events for the current program. #### Parameters ##### Query parameters `seconds`string \ Number of seconds to collect profile data. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/debug/pprof/trace" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200[Trace file](https://pkg.go.dev/runtime/trace) compatible with the [Golang `trace` command](https://pkg.go.dev/cmd/trace). defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/health` ### Retrieve the health of the instance Returns the health of the instance. `--health-auth-mode` and `--hardening-enabled` reduce the response body for callers without operator permissions. Those callers don’t receive check messages, measure groups, `version`, or `commit`. The status code never changes. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/health" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The instance is healthy. The response body contains the health check items and status. `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. 503The instance is unhealthy.`message` contains the message of the first failing check. `checks`object[] `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/metrics` ### Retrieve workload performance metrics Returns metrics about the workload performance of an InfluxDB instance. Use this endpoint to get performance, resource, and usage metrics. #### Related guides * For the list of metrics categories, see [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/). * Learn how to use InfluxDB to [scrape Prometheus metrics](/influxdb/v2/write-data/developer-tools/scrape-prometheus-metrics/). * Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/v2/reference/prometheus-metrics/). #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/metrics" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains metrics in[Prometheus plain-text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats)Metrics contain a name, an optional set of key-value pairs, and a value. The following descriptors precede each metric: * `HELP`: description of the metric * `TYPE`: [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, `gauge`, `histogram`, or `summary`) defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/ping` ### Get the status of the instance Retrieves the status and InfluxDB version of the instance. Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP `204` status code to inform you the instance is available. #### InfluxDB Cloud * Isn’t versioned and doesn’t return `X-Influxdb-Version` in the headers. #### Related guides * [Influx ping](/influxdb/v2/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. Headers contain InfluxDB version information. GET`/ready` ### Get the readiness of an instance at startup Returns the readiness of the instance. `--health-auth-mode` and `--hardening-enabled` can withhold `checks`from callers without operator permissions. They never change the status code. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/ready" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The instance is ready `checks`object[] Ready gates that haven’t passed. Omitted when `status` is `ready`. `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `started`string \ Example:`"2019-03-13T10:09:33.891196-04:00"` `status`string Allowed:`ready`, `starting` `up`string Example:`"14m45.911966424s"` `uptime`object Time since `started`, in float seconds. Example:`{"completed":94,"total":200,"unit":"shards"}` `unit`requiredstring Example:`"shards"` 503The instance is starting or shutting down.`checks` contains only the ready gates that haven’t passed. `checks`object[] Ready gates that haven’t passed. Omitted when `status` is `ready`. `checks`object[] `checks`object[] `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `commit`string Build commit. Returned only at the top level. `message`string Status detail. For a failing check, may contain the raw error text. `name`requiredstring `status`requiredstring Allowed:`pass`, `fail` `version`string Build version. Returned only at the top level. `started`string \ Example:`"2019-03-13T10:09:33.891196-04:00"` `status`string Allowed:`ready`, `starting` `up`string Example:`"14m45.911966424s"` `uptime`object Time since `started`, in float seconds. Example:`{"completed":94,"total":200,"unit":"shards"}` `unit`requiredstring Example:`"shards"` defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Tasks Source: https://docs.influxdata.com/influxdb/v2/api/tasks/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB OSS v2. GET`/api/v2/tasks` ### List tasks Retrieves a list of [tasks](/influxdb/v2/reference/glossary/#task). To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. #### Related guide * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) #### Parameters ##### Query parameters `name`string A [task](/influxdb/v2/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. `after`string A [task](/influxdb/v2/reference/glossary/#task) ID. Only returns tasks created after the specified task. `user`string A [user](/influxdb/v2/reference/glossary/#user) ID. Only returns tasks owned by the specified user. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. `orgID`string An [organization](/influxdb/v2/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. `status`string A [task](/influxdb/v2/reference/glossary/#task) status. Only returns tasks that have the specified status (`active` or `inactive`). Allowed values:`active`, `inactive` `limit`integer The maximum number of [tasks](/influxdb/v2/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. To reduce the payload size, combine *`type=basic`* and *`limit`* (see *Request samples*). For more information about the `basic` response, see the *`type`* parameter. Default:`100` `type`string A [task](/influxdb/v2/reference/glossary/#task) type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). Allowed values:`basic`, `system` ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of tasks. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `tasks`object[] `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks` ### Create a task Creates a [task](/influxdb/v2/reference/glossary/#task) and returns the task. #### Related guides * [Get started with tasks](/influxdb/v2/process-data/get-started/) * [Create a task](/influxdb/v2/process-data/manage-tasks/create-task/) * [Common tasks](/influxdb/v2/process-data/common-tasks/) * [Task configuration options](/influxdb/v2/process-data/task-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The task to create. Content-Type:`application/json` `description`string An optional description of the task. `flux`requiredstring The Flux script to run for this task. `org`string The name of the organization that owns this Task. `orgID`string The ID of the organization that owns this Task. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "flux": "FLUX", "org": "ORG", "orgID": "ORGID", "status": "active" }' ``` #### Responses 201Success. The response body contains a `tasks` list with the task. `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed for `org` or `orgID`. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}` ### Retrieve a task Retrieves a [task](/influxdb/v2/reference/glossary/#task). #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the task. `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/tasks/{taskID}` ### Update a task Updates a task and then cancels all scheduled runs of the task. Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. To update a task, pass an object that contains the updated key-value pairs. To activate or inactivate a task, set the `status` property.*`"status": "inactive"`* cancels scheduled runs and prevents manual runs of the task. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired An object that contains updated task properties to apply. Content-Type:`application/json` `cron`string Update the ‘cron’ option in the flux script. `description`string Update the description of the task. `every`string Update the ’every’ option in the flux script. `flux`string The Flux script that the task runs. `name`string Update the ’name’ option in the flux script. `offset`string Update the ‘offset’ option in the flux script. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/tasks/{taskID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cron": "CRON", "description": "DESCRIPTION", "every": "EVERY", "flux": "FLUX", "name": "NAME", "offset": "OFFSET", "status": "active" }' ``` #### Responses 200Success. The response body contains the updated task. `authorizationID`string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. `createdAt`string \ `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. `description`string A description of the task. `every`string \ The interval ([duration literal](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`requiredstring \ The Flux script that the task executes. `id`requiredstring `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}` `labels`string \ URI of resource. `logs`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `runs`string \ URI of resource. `self`string \ URI of resource. `name`requiredstring The name of the task. `offset`string \ A [duration](/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. `org`string An [organization](/influxdb/v2/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/v2/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/v2/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the[`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `updatedAt`string \ 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/tasks/{taskID}` ### Delete a task Deletes a task and associated records. Use this endpoint to delete a task and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/tasks/{taskID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The task and runs are deleted. Scheduled runs are canceled. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/labels` ### List labels for a task Retrieves a list of all labels for a task. Labels may be used for grouping and filtering tasks. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to retrieve labels for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of all labels for the task. `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/labels` ### Add a label to a task Adds a label to a task. Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to label. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired An object that contains a *`labelID`* to add to the task. Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201Success. The response body contains a list of all labels for the task. `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/tasks/{taskID}/labels/{labelID}` ### Delete a label from a task Deletes a label from a task. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to delete the label from. `labelID`requiredstring The ID of the label to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/tasks/{taskID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The label is deleted. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/logs` ### Retrieve all logs for a task Retrieves a list of all logs for a [task](/influxdb/v2/reference/glossary/#task). When an InfluxDB task runs, a “run” record is created in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. #### Parameters ##### Path parameters `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/logs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. `events`object[] `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/members`Deprecated ### List all task members **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](/influxdb/v2/reference/glossary/#task). #### Parameters ##### Path parameters `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains a list of `users` that have the `member` role for a task. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/members`Deprecated ### Add a member to a task **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a user to members of a task and returns the member. #### Parameters ##### Path parameters `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A user to add as a member of the task. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Created. The user is added to task members. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/tasks/{taskID}/members/{userID}`Deprecated ### Remove a member from a task **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](/influxdb/v2/reference/glossary/#task). #### Parameters ##### Path parameters `userID`requiredstring The ID of the member to remove. `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/tasks/{taskID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Member removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/owners`Deprecated ### List all owners of a task **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Retrieves all users that have owner permission for a task. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to retrieve owners for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response contains a list of `users` that have the `owner` role for the task. If the task has no owners, the response contains an empty `users` array. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/owners`Deprecated ### Add an owner for a task **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Assigns a task `owner` role to a user. Use this endpoint to create a *resource owner* for the task. A *resource owner* is a user with `role: owner` for a specific resource. #### Parameters ##### Path parameters `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired A user to add as an owner of the task. Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Created. The task `owner` role is assigned to the user. The response body contains the resource owner with role and user detail. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/tasks/{taskID}/owners/{userID}`Deprecated ### Remove an owner from a task **Deprecated**: Tasks don’t use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Parameters ##### Path parameters `userID`requiredstring The ID of the owner to remove. `taskID`requiredstring The task ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/tasks/{taskID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Owner removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/runs` ### List runs for a task Retrieves a list of runs for a [task](/influxdb/v2/process-data/). To limit which task runs are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to get runs for. Only returns runs for this task. ##### Query parameters `after`string A task run ID. Only returns runs created after this run. `limit`integer Limits the number of task runs returned. Default is `100`. Default:`100` `afterTime`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. `beforeTime`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before this time. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/runs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of task runs. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. `runs`object[] `finishedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `flux`string Flux used for the task `id`string `links`object Example:`{"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}` `retry`string \ `self`string \ `task`string \ `log`object[] An array of logs associated with the run. `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `requestedAt`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) used for the run’s `now` option. `startedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `status`string Allowed:`scheduled`, `started`, `failed`, `success`, `canceled` `taskID`string 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/runs` ### Start a task run, overriding the schedule Schedules a task run to start immediately, ignoring scheduled runs. Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks. To *retry* a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). #### Parameters ##### Path parameters `taskID`requiredstring ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request body Content-Type:`application/json` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)used for the run’s `now` option. Default is the server *now* time. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/runs" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "scheduledFor": "SCHEDULEDFOR" }' ``` #### Responses 201Success. The run is scheduled to start. `finishedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `flux`string Flux used for the task `id`string `links`object Example:`{"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}` `retry`string \ `self`string \ `task`string \ `log`object[] An array of logs associated with the run. `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `requestedAt`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) used for the run’s `now` option. `startedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `status`string Allowed:`scheduled`, `started`, `failed`, `success`, `canceled` `taskID`string 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/runs/{runID}` ### Retrieve a run for a task. Retrieves a specific run for a [task](/influxdb/v2/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to retrieve runs for. `runID`requiredstring The ID of the run to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/runs/{runID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the task run. `finishedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `flux`string Flux used for the task `id`string `links`object Example:`{"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}` `retry`string \ `self`string \ `task`string \ `log`object[] An array of logs associated with the run. `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `requestedAt`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) used for the run’s `now` option. `startedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `status`string Allowed:`scheduled`, `started`, `failed`, `success`, `canceled` `taskID`string 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/tasks/{taskID}/runs/{runID}` ### Cancel a running task Cancels a running [task](/influxdb/v2/reference/glossary/#task). Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud * Doesn’t support this operation. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to cancel. `runID`requiredstring The ID of the task run to cancel. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/tasks/{taskID}/runs/{runID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Success. The `DELETE` is accepted and the run will be cancelled. #### InfluxDB Cloud * Doesn’t support this operation. * Doesn’t return this status. 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 405 Method not allowed. #### InfluxDB Cloud * Always returns this error; doesn’t support cancelling tasks. #### InfluxDB OSS * Doesn’t return this error. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/tasks/{taskID}/runs/{runID}/logs` ### Retrieve all logs for a run Retrieves all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. Use this endpoint to help analyze task performance and troubleshoot failed task runs. #### Parameters ##### Path parameters `taskID`requiredstring The ID of the task to get logs for. `runID`requiredstring The ID of the run to get logs for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/tasks/{taskID}/runs/{runID}/logs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains an `events` list with logs for the task run. Each log event `message` contains detail about the event. If a run fails, InfluxDB logs an event with the reason for the failure. `events`object[] `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/tasks/{taskID}/runs/{runID}/retry` ### Retry a task run Queues a [task](/influxdb/v2/reference/glossary/#task) run to retry and returns the scheduled run. To manually start a *new* task run, use the[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations * The task must be *active* (`status: "active"`). #### Parameters ##### Path parameters `taskID`requiredstring A [task](/influxdb/v2/reference/glossary/#task) ID. Specifies the task to retry. `runID`requiredstring A [task](/influxdb/v2/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)to list task runs. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request body Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/tasks/{taskID}/runs/{runID}/retry" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json; charset=utf-8" ``` #### Responses 200Success. The response body contains the queued run. `finishedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `flux`string Flux used for the task `id`string `links`object Example:`{"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}` `retry`string \ `self`string \ `task`string \ `log`object[] An array of logs associated with the run. `message`string A description of the event that occurred. Example:`"Halt and catch fire"` `runID`string The ID of the task run that generated the event. `time`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `requestedAt`string \ The time ([RFC3339Nano date/time format](/influxdb/v2/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `scheduledFor`string \ The time [RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp) used for the run’s `now` option. `startedAt`string \ The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. Example:`"2006-01-02T15:04:05.999999999Z07:00"` `status`string Allowed:`scheduled`, `started`, `failed`, `success`, `canceled` `taskID`string 400 Bad request. The response body contains detail about the error. InfluxDB may return this error for the following reasons: * The task has `status: inactive`. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Get started with tasks](/influxdb/v2/process-data/get-started/) --- # Telegraf Plugins Source: https://docs.influxdata.com/influxdb/v2/api/telegraf-plugins/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Retrieve available Telegraf plugin configuration templates for use with InfluxDB OSS v2. GET`/api/v2/telegraf/plugins` ### List all Telegraf plugins #### Parameters ##### Query parameters `type`string The type of plugin desired. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegraf/plugins" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of Telegraf plugins. `os`string `plugins`object[] `config`string `description`string `name`string `type`string `version`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Telegrafs Source: https://docs.influxdata.com/influxdb/v2/api/telegrafs/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage Telegraf agent configurations that collect and write data to InfluxDB OSS v2. GET`/api/v2/telegrafs` ### List all Telegraf configurations #### Parameters ##### Query parameters `orgID`string The organization ID the Telegraf config belongs to. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegrafs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of Telegraf configurations `configurations`object[] `config`string `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object Example:`{"lables":"/api/v2/telegrafs/1/labels","members":"/api/v2/telegrafs/1/members","owners":"/api/v2/telegrafs/1/owners","self":"/api/v2/telegrafs/1"}` `labels`string \ URI of resource. `members`string \ URI of resource. `owners`string \ URI of resource. `self`string \ URI of resource. `metadata`object `buckets`string[] `name`string `orgID`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/telegrafs` ### Create a Telegraf configuration #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Telegraf configuration to create Content-Type:`application/json` `config`string `description`string `metadata`object `buckets`string[] `name`string `orgID`string `plugins`object[] `alias`string `config`string `description`string `name`string `type`string Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/telegrafs" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "config": "CONFIG", "description": "DESCRIPTION", "metadata": { "buckets": [ "BUCKETS" ] }, "name": "NAME", "orgID": "ORGID", "plugins": [ { "alias": "ALIAS", "config": "CONFIG", "description": "DESCRIPTION", "name": "NAME", "type": "TYPE" } ] }' ``` #### Responses 201Telegraf configuration created defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/telegrafs/{telegrafID}` ### Retrieve a Telegraf configuration #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `Accept`string Allowed values:`application/toml`, `application/json`, `application/octet-stream` Default:`application/toml` Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Telegraf configuration details defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/telegrafs/{telegrafID}` ### Update a Telegraf configuration #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Telegraf configuration update to apply Content-Type:`application/json` `config`string `description`string `metadata`object `buckets`string[] `name`string `orgID`string `plugins`object[] `alias`string `config`string `description`string `name`string `type`string Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "config": "CONFIG", "description": "DESCRIPTION", "metadata": { "buckets": [ "BUCKETS" ] }, "name": "NAME", "orgID": "ORGID", "plugins": [ { "alias": "ALIAS", "config": "CONFIG", "description": "DESCRIPTION", "name": "NAME", "type": "TYPE" } ] }' ``` #### Responses 200An updated Telegraf configurations defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/telegrafs/{telegrafID}` ### Delete a Telegraf configuration #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/telegrafs/{telegrafID}/labels` ### List all labels for a Telegraf config #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a Telegraf config `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/telegrafs/{telegrafID}/labels` ### Add a label to a Telegraf config #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The label added to the Telegraf config `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/telegrafs/{telegrafID}/labels/{labelID}` ### Delete a label from a Telegraf config #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. `labelID`requiredstring The label ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Telegraf config not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/telegrafs/{telegrafID}/members` ### List all users with member privileges for a Telegraf config #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of Telegraf config members `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`member` Default:`member` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/telegrafs/{telegrafID}/members` ### Add a member to a Telegraf config #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as member Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Member added to Telegraf config defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/telegrafs/{telegrafID}/members/{userID}` ### Remove a member from a Telegraf config #### Parameters ##### Path parameters `userID`requiredstring The ID of the member to remove. `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Member removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/telegrafs/{telegrafID}/owners` ### List all owners of a Telegraf configuration #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Returns Telegraf configuration owners as a ResourceOwners list `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `role`string Allowed:`owner` Default:`owner` `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/telegrafs/{telegrafID}/owners` ### Add an owner to a Telegraf configuration #### Parameters ##### Path parameters `telegrafID`requiredstring The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as owner Content-Type:`application/json` `id`requiredstring The ID of the user to add to the resource. `name`string The name of the user to add to the resource. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201Telegraf configuration owner was added. Returns a ResourceOwner that references the User. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/telegrafs/{telegrafID}/owners/{userID}` ### Remove an owner from a Telegraf config #### Parameters ##### Path parameters `userID`requiredstring The ID of the owner to remove. `telegrafID`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/telegrafs/{telegrafID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Owner removed defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Templates Source: https://docs.influxdata.com/influxdb/v2/api/templates/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Export and apply InfluxDB templates, and manage template stacks for InfluxDB OSS v2. GET`/api/v2/stacks` ### List installed stacks Lists installed InfluxDB stacks. To limit stacks in the response, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all installed stacks for the organization. #### Related guides * [View InfluxDB stacks](/influxdb/v2/influxdb-templates/stacks/). #### Parameters ##### Query parameters `orgID`requiredstring An organization ID. Only returns stacks owned by the specified [organization](/influxdb/v2/reference/glossary/#organization). #### InfluxDB Cloud * Doesn’t require this parameter; InfluxDB only returns resources allowed by the API token. `name`string A stack name. Finds stack `events` with this name and returns the stacks. Repeatable. To filter for more than one stack name, repeat this parameter with each name–for example: * `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` `stackID`string A stack ID. Only returns the specified stack. Repeatable. To filter for more than one stack ID, repeat this parameter with each ID–for example: * `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/stacks?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of stacks. `stacks`object[] `createdAt`string \ `events`object[] `description`string `eventType`string `name`string `resources`object[] `sources`string[] `updatedAt`string \ `urls`string[] `id`string `orgID`string 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/stacks` ### Create a stack Creates or initializes a stack. Use this endpoint to *manually* initialize a new stack with the following optional information: * Stack name * Stack description * URLs for template manifest files To automatically create a stack when applying templates, use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). #### Required permissions * `write` permission for the organization #### Related guides * [Initialize an InfluxDB stack](/influxdb/v2/influxdb-templates/stacks/init/). * [Use InfluxDB templates](/influxdb/v2/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). #### Request bodyrequired The stack to create. Content-Type:`application/json` `description`string `name`string `orgID`string `urls`string[] Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/stacks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "name": "NAME", "orgID": "ORGID", "urls": [ "URLS" ] }' ``` #### Responses 201Success. Returns the newly created stack. `createdAt`string \ `events`object[] `description`string `eventType`string `name`string `resources`object[] `apiVersion`string `associations`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `links`object `resourceID`string `templateMetaName`string `sources`string[] `updatedAt`string \ `urls`string[] `id`string `orgID`string 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/stacks/{stack_id}` ### Retrieve a stack #### Parameters ##### Path parameters `stack_id`requiredstring The identifier of the stack. Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/stacks/{stack_id}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Returns the stack. `createdAt`string \ `events`object[] `description`string `eventType`string `name`string `resources`object[] `apiVersion`string `associations`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `links`object `resourceID`string `templateMetaName`string `sources`string[] `updatedAt`string \ `urls`string[] `id`string `orgID`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/stacks/{stack_id}` ### Update a stack #### Parameters ##### Path parameters `stack_id`requiredstring The identifier of the stack. #### Request bodyrequired The stack to update. Content-Type:`application/json` `additionalResources`object[] `kind`requiredstring `resourceID`requiredstring `templateMetaName`string `description`string `name`string `templateURLs`string[] Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/stacks/{stack_id}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "additionalResources": [ { "kind": "KIND", "resourceID": "RESOURCEID", "templateMetaName": "TEMPLATEMETANAME" } ], "description": "DESCRIPTION", "name": "NAME", "templateURLs": [ "TEMPLATEURLS" ] }' ``` #### Responses 200Returns the updated stack. `createdAt`string \ `events`object[] `description`string `eventType`string `name`string `resources`object[] `apiVersion`string `associations`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `links`object `resourceID`string `templateMetaName`string `sources`string[] `updatedAt`string \ `urls`string[] `id`string `orgID`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/stacks/{stack_id}` ### Delete a stack and associated resources #### Parameters ##### Path parameters `stack_id`requiredstring The identifier of the stack. ##### Query parameters `orgID`requiredstring The identifier of the organization. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/stacks/{stack_id}?orgID=ORGID" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204The stack and its associated resources were deleted. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/stacks/{stack_id}/uninstall` ### Uninstall a stack #### Parameters ##### Path parameters `stack_id`requiredstring The identifier of the stack. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/stacks/{stack_id}/uninstall" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Returns the uninstalled stack. `createdAt`string \ `events`object[] `description`string `eventType`string `name`string `resources`object[] `apiVersion`string `associations`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `links`object `resourceID`string `templateMetaName`string `sources`string[] `updatedAt`string \ `urls`string[] `id`string `orgID`string defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/templates/apply` ### Apply or dry-run a template Applies a template to create or update a [stack](/influxdb/v2/influxdb-templates/stacks/) of InfluxDB[resources](/influxdb/v2/reference/cli/influx/export/all/#resources). The response contains the diff of changes and the stack ID. Use this endpoint to install an InfluxDB template to an organization. Provide template URLs or template objects in your request. To customize which template resources are installed, use the `actions`parameter. By default, when you apply a template, InfluxDB installs the template to create and update stack resources and then generates a diff of the changes. If you pass `dryRun: true` in the request body, InfluxDB validates the template and generates the resource diff, but doesn’t make any changes to your instance. #### Custom values for templates * Some templates may contain [environment references](/influxdb/v2/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. To provide custom values for environment references, pass the *`envRefs`*property in the request body. For more information and examples, see how to[define environment references](/influxdb/v2/influxdb-templates/use/#define-environment-references). * Some templates may contain queries that use[secrets](/influxdb/v2/security/secrets/). To provide custom secret values, pass the *`secrets`* property in the request body. Don’t expose secret values in templates. For more information, see [how to pass secrets when installing a template](/influxdb/v2/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions * `write` permissions for resource types in the template. #### Rate limits (with InfluxDB Cloud) * Adjustable service quotas apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Use templates](/influxdb/v2/influxdb-templates/use/) * [Stacks](/influxdb/v2/influxdb-templates/stacks/) #### Request bodyrequired Parameters for applying templates. Content-Type:`application/json` `actions`object[] A list of `action` objects. Actions let you customize how InfluxDB applies templates in the request. You can use the following actions to prevent creating or updating resources: * A `skipKind` action skips template resources of a specified `kind`. * A `skipResource` action skips template resources with a specified `metadata.name`and `kind`. `dryRun`boolean Only applies a dry run of the templates passed in the request. * Validates the template and generates a resource diff and summary. * Doesn’t install templates or make changes to the InfluxDB instance. `envRefs`object An object with key-value pairs that map to **environment references** in templates. Environment references in templates are `envRef` objects with an `envRef.key`property. To substitute a custom environment reference value when applying templates, pass `envRefs` with the `envRef.key` and the value. When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. For more examples, see how to [define environment references](/influxdb/v2/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: * `metadata.name` * `spec.endpointName` * `spec.associations.name` For more information about including environment references in template fields, see how to[include user-definable resource names](/influxdb/v2/influxdb-templates/create/#include-user-definable-resource-names). `orgID`string Organization ID. InfluxDB applies templates to this organization. The organization owns all resources created by the template. To find your organization, see how to[view organizations](/influxdb/v2/organizations/view-orgs/). `remotes`object[] A list of URLs for template files. To apply a template manifest file located at a URL, pass `remotes`with an array that contains the URL. `contentType`string `url`requiredstring `secrets`object An object with key-value pairs that map to **secrets** in queries. Queries may reference secrets stored in InfluxDB–for example, the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD`secrets and then uses them to connect to a PostgreSQL database: ```js import "sql" import "influxdata/influxdb/secrets" username = secrets.get(key: "POSTGRES_USERNAME") password = secrets.get(key: "POSTGRES_PASSWORD") sql.from( driverName: "postgres", dataSourceName: "postgresql://${username}:${password}@localhost:5432", query: "SELECT * FROM example_table", ) ``` To define secret values in your `/api/v2/templates/apply` request, pass the `secrets` parameter with key-value pairs–for example: ```json { ... "secrets": { "POSTGRES_USERNAME": "pguser", "POSTGRES_PASSWORD": "foo" } ... } ``` InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. Once stored, you can’t view secret values in InfluxDB. #### Related guides * [How to pass secrets when installing a template](/influxdb/v2/influxdb-templates/use/#pass-secrets-when-installing-a-template) `stackID`string ID of the stack to update. To apply templates to an existing stack in the organization, use the `stackID` parameter. If you apply templates without providing a stack ID, InfluxDB initializes a new stack with all new resources. To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. #### Related guides * [Stacks](/influxdb/v2/influxdb-templates/stacks/) * [View stacks](/influxdb/v2/influxdb-templates/stacks/view/) `template`object A template object to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Pass `template` to apply only one template object. If you use `template`, you can’t use the `templates` parameter. If you want to apply multiple template objects, use `templates` instead. `contentType`string `contents`object[] `apiVersion`string Example:`"influxdata.com/v2alpha1"` `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `metadata`object Metadata properties used for the resource when the template is applied. `spec`object Configuration properties used for the resource when the template is applied. Key-value pairs map to the specification for the resource. The following code samples show `spec` configurations for template resources: * A bucket: ```json { "spec": { "name": "iot_center", "retentionRules": [{ "everySeconds": 2.592e+06, "type": "expire" }] } } ``` * A variable: ```json { "spec": { "language": "flux", "name": "Node_Service", "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", tag: \"service\")", "type": "query" } } ``` `sources`string[] `templates`object[] A list of template objects to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Use the `templates` parameter to apply multiple template objects. If you use `templates`, you can’t use the `template` parameter. `contentType`string `contents`object[] `apiVersion`string Example:`"influxdata.com/v2alpha1"` `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `metadata`object Metadata properties used for the resource when the template is applied. `spec`object Configuration properties used for the resource when the template is applied. Key-value pairs map to the specification for the resource. The following code samples show `spec` configurations for template resources: * A bucket: ```json { "spec": { "name": "iot_center", "retentionRules": [{ "everySeconds": 2.592e+06, "type": "expire" }] } } ``` * A variable: ```json { "spec": { "language": "flux", "name": "Node_Service", "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", tag: \"service\")", "type": "query" } } ``` `sources`string[] Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/templates/apply" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "actions": [ {} ], "dryRun": false, "envRefs": {}, "orgID": "ORGID", "remotes": [ { "contentType": "CONTENTTYPE", "url": "URL" } ], "secrets": {}, "stackID": "STACKID", "template": { "contentType": "CONTENTTYPE", "contents": [ {} ], "sources": [ "SOURCES" ] }, "templates": [ { "contentType": "CONTENTTYPE", "contents": [], "sources": [] } ] }' ``` #### Responses 200Success. The template dry run succeeded. The response body contains a resource diff of changes that the template would have made if installed. No resources were created or updated. The diff and summary won’t contain IDs for resources that didn’t exist at the time of the dry run. `diff`object `buckets`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `checks`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object or object or object `old`object or object or object `stateStatus`string `templateMetaName`string `dashboards`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `labelMappings`object[] `labelID`string `labelName`string `labelTemplateMetaName`string `resourceID`string `resourceName`string `resourceTemplateMetaName`string `resourceType`string `status`string `labels`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `notificationEndpoints`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object or object or object or object `old`object or object or object or object `stateStatus`string `templateMetaName`string `notificationRules`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `tasks`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `telegrafConfigs`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `variables`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `errors`object[] `fields`string[] `indexes`integer[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `reason`string `sources`string[] `stackID`string `summary`object `buckets`object[] `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `retentionPeriod`integer `templateMetaName`string `checks`object[] `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `templateMetaName`string `dashboards`object[] `charts`object[] `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `templateMetaName`string `labelMappings`object[] `labelID`string `labelName`string `labelTemplateMetaName`string `resourceID`string `resourceName`string `resourceTemplateMetaName`string `resourceType`string `status`string `labels`object[] `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `name`string `orgID`string `properties`object `templateMetaName`string `missingEnvRefs`string[] `missingSecrets`string[] `notificationEndpoints`object[] `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `templateMetaName`string `notificationRules`object[] `description`string `endpointID`string `endpointTemplateMetaName`string `endpointType`string `envReferences`object[] `every`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `messageTemplate`string `name`string `offset`string `status`string `statusRules`object[] `tagRules`object[] `templateMetaName`string `tasks`object[] `cron`string `description`string `envReferences`object[] `every`string `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `name`string `offset`string `query`string `status`string `templateMetaName`string `telegrafConfigs`object[] `config`string `description`string `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `metadata`object `name`string `orgID`string `templateMetaName`string `variables`object[] `arguments`object or object or object `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `templateMetaName`string 201Success. The template applied successfully. The response body contains the stack ID, a diff, and a summary. The diff compares the initial state to the state after the template installation. The summary contains newly created resources. `diff`object `buckets`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `checks`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object or object or object `old`object or object or object `stateStatus`string `templateMetaName`string `dashboards`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `labelMappings`object[] `labelID`string `labelName`string `labelTemplateMetaName`string `resourceID`string `resourceName`string `resourceTemplateMetaName`string `resourceType`string `status`string `labels`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `notificationEndpoints`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object or object or object or object `old`object or object or object or object `stateStatus`string `templateMetaName`string `notificationRules`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `tasks`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `telegrafConfigs`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `variables`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `new`object `old`object `stateStatus`string `templateMetaName`string `errors`object[] `fields`string[] `indexes`integer[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `reason`string `sources`string[] `stackID`string `summary`object `buckets`object[] `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `retentionPeriod`integer `templateMetaName`string `checks`object[] `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `templateMetaName`string `dashboards`object[] `charts`object[] `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `templateMetaName`string `labelMappings`object[] `labelID`string `labelName`string `labelTemplateMetaName`string `resourceID`string `resourceName`string `resourceTemplateMetaName`string `resourceType`string `status`string `labels`object[] `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `name`string `orgID`string `properties`object `templateMetaName`string `missingEnvRefs`string[] `missingSecrets`string[] `notificationEndpoints`object[] `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `templateMetaName`string `notificationRules`object[] `description`string `endpointID`string `endpointTemplateMetaName`string `endpointType`string `envReferences`object[] `every`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `messageTemplate`string `name`string `offset`string `status`string `statusRules`object[] `tagRules`object[] `templateMetaName`string `tasks`object[] `cron`string `description`string `envReferences`object[] `every`string `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `name`string `offset`string `query`string `status`string `templateMetaName`string `telegrafConfigs`object[] `config`string `description`string `envReferences`object[] `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `metadata`object `name`string `orgID`string `templateMetaName`string `variables`object[] `arguments`object or object or object `description`string `envReferences`object[] `id`string `kind`string Allowed:`Bucket`, `Check`, `CheckDeadman`, `CheckThreshold`, `Dashboard`, `Label`, `NotificationEndpoint`, `NotificationEndpointHTTP`, `NotificationEndpointPagerDuty`, `NotificationEndpointSlack`, `NotificationRule`, `Task`, `Telegraf`, `Variable` `labelAssociations`object[] `name`string `orgID`string `templateMetaName`string 422 Unprocessable entity. The error may indicate one of the following problems: * The template failed validation. * You passed a parameter combination that InfluxDB doesn’t support. 500 Internal server error. #### InfluxDB Cloud * Returns this error if creating one of the template resources (bucket, dashboard, task, user) exceeds your plan’s adjustable service quotas. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/templates/export` ### Export a new template #### Request body Export resources as an InfluxDB template. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/templates/export" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 200The template was created successfully. Returns the newly created template. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [InfluxDB templates](/influxdb/v2/influxdb-templates/) --- # Users Source: https://docs.influxdata.com/influxdb/v2/api/users/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage users that have access to InfluxDB OSS v2 organizations and resources. GET`/api/v2/me` ### Retrieve the currently authenticated user #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/me" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the currently authenticated user. `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/me/password` ### Update a password Updates the password for the signed-in [user](/influxdb/v2/reference/glossary/#user). This endpoint represents the third step in the following three-step process to let a user with a user session update their password: 1. Pass the user’s [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin`endpoint to create a user session and generate a session cookie. 2. From the response in the first step, extract the session cookie (`Set-Cookie`) header. 3. Pass the following in a request to the `PUT /api/v2/me/password` endpoint: * The `Set-Cookie` header from the second step * The `Authorization Basic` header with the user’s *Basic authentication* credentials * `{"password": "NEW_PASSWORD"}` in the request body #### InfluxDB Cloud * Doesn’t let you manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update your password. #### Related endpoints * [Signin](#tag/Signin) * [Signout](#tag/Signout) * [Users](#tag/Users) #### Related guides * [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) * [InfluxDB OSS - Change your password](/influxdb/v2/users/change-password/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The new password. Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/me/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Success. The password is updated. 400 Bad request. #### InfluxDB Cloud * Doesn’t let you manage user passwords through the API; always responds with this status. #### InfluxDB OSS * Doesn’t understand a value passed in the request. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. defaultUnsuccessful authentication `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/users` ### List users Lists [users](/influxdb/v2/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. #### Required permissions for InfluxDB OSS | Action | Permission required |Restriction| |--------------------|----------------------------------------------------------------|-----------| | List all users |*[Operator token](/influxdb/v2/security/tokens/#operator-token)*| | |List a specific user| `read-users` or `read-user USER_ID` | | *`USER_ID`* is the ID of the user that you want to retrieve. #### Related guides * [View users](/influxdb/v2/users/view-users/). #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `limit`integer Limits the number of records returned. Default is `20`. Default:`20` `after`string A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination). `name`string A user name. Only lists the specified [user](/influxdb/v2/reference/glossary/#user). `id`string A user ID. Only lists the specified [user](/influxdb/v2/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response contains a list of `users`. `links`object `self`string \ `users`object[] `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 401Unauthorized. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/users` ### Create a user Creates a [user](/influxdb/v2/reference/glossary/#user) that can access InfluxDB. Returns the user. Use this endpoint to create a user that can sign in to start a user session through one of the following interfaces: * InfluxDB UI * `/api/v2/signin` InfluxDB API endpoint * InfluxDB CLI This endpoint represents the first two steps in a four-step process to allow a user to authenticate with a username and password, and then access data in an organization: 1. Create a user: send a `POST` request to `POST /api/v2/users`. The `name` property is required. 2. Extract the user ID (`id` property) value from the API response for *step 1*. 3. Create an authorization (and API token) for the user: send a `POST` request to [`POST /api/v2/authorizations`](#operation/PostAuthorizations), passing the user ID (`id`) from *step 2*. 4. Create a password for the user: send a `POST` request to [`POST /api/v2/users/USER_ID/password`](#operation/PostUsersIDPassword), passing the user ID from *step 2*. #### Required permissions | Action | Permission required |Restriction| |-------------|----------------------------------------------------------------|-----------| |Create a user|*[Operator token](/influxdb/v2/security/tokens/#operator-token)*| | #### Related guides * [Create a user](/influxdb/v2/users/create-user/) * [Create an API token scoped to a user](/influxdb/v2/security/tokens/create-token/#create-a-token-scoped-to-a-user) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The user to create. Content-Type:`application/json` `id`string The user ID. `name`requiredstring The user name. `status`string If `inactive`, the user is inactive. Default is `active`. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME", "status": "active" }' ``` #### Responses 201Success. The response body contains the user. `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 401Unauthorized. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 422 Unprocessable entity. The error may indicate one of the following problems: * The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors. * You passed a parameter combination that InfluxDB doesn’t support. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/users/{userID}` ### Retrieve a user Retrieves a [user](/influxdb/v2/reference/glossary/#user). #### Related guides * [Manage users](/influxdb/v2/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Retrieves the specified [user](/influxdb/v2/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the user. `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/users/{userID}` ### Update a user Updates a [user](/influxdb/v2/reference/glossary/#user) and returns the user. #### Required permissions | Action | Permission required | |-------------|-------------------------------------| |Update a user|`write-users` or `write-user USER_ID`| *`USER_ID`* is the ID of the user that you want to update. #### Related guides * [Manage users](/influxdb/v2/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired In the request body, provide the user properties to update. Content-Type:`application/json` `id`string The user ID. `name`requiredstring The user name. `status`string If `inactive`, the user is inactive. Default is `active`. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME", "status": "active" }' ``` #### Responses 200Success. The response body contains the user. `id`string The user ID. `links`object Example:`{"self":"/api/v2/users/1"}` `self`string \ `name`requiredstring The user name. `status`string The status of a user. An inactive user can’t read or write resources. Allowed:`active`, `inactive` Default:`active` 400 Bad request. The response body contains detail about the error. #### InfluxDB OSS * Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/users/{userID}` ### Delete a user Deletes a [user](/influxdb/v2/reference/glossary/#user). #### Required permissions | Action | Permission required | |-------------|-------------------------------------| |Delete a user|`write-users` or `write-user USER_ID`| *`USER_ID`* is the ID of the user that you want to delete. #### Related guides * [Manage users](/influxdb/v2/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Specifies the [user](/influxdb/v2/reference/glossary/#user) to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user is deleted. 400Bad request. The response body contains detail about the error. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/users/{userID}/password` ### Update a password Updates a user password. #### InfluxDB Cloud * Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides * [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) * [InfluxDB OSS - Change your password](/influxdb/v2/users/change-password/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to set the password for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The new password to set for the user. Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/users/{userID}/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Success. The password is updated. 400 Bad request. #### InfluxDB Cloud * Doesn’t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS * Doesn’t understand a value passed in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/users/{userID}/password` ### Update a password Updates a user password. Use this endpoint to let a user authenticate with[Basic authentication credentials](#section/Authentication/BasicAuthentication)and set a new password. #### InfluxDB Cloud * Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides * [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) * [InfluxDB OSS - Change your password](/influxdb/v2/users/change-password/) #### Parameters ##### Path parameters `userID`requiredstring The ID of the user to set the password for. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The new password to set for the user. Content-Type:`application/json` `password`requiredstring Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/users/{userID}/password" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "password": "PASSWORD" }' ``` #### Responses 204Success. The password is updated. 400 Bad request. #### InfluxDB Cloud * Doesn’t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS * Doesn’t understand a value passed in the request. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Manage users](/influxdb/v2/users/) | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | List all users | Operator token | | | List a specific user | read-users or read-user USER_ID | | | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | Create a user | Operator token | | | Action | Permission required | | --- | --- | | Action | Permission required | | Update a user | write-users or write-user USER_ID | | Action | Permission required | | --- | --- | | Action | Permission required | | Delete a user | write-users or write-user USER_ID | --- # Variables Source: https://docs.influxdata.com/influxdb/v2/api/variables/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Create and manage variables for use in InfluxDB OSS v2 dashboards. GET`/api/v2/variables` ### List all variables #### Parameters ##### Query parameters `org`string The name of the organization. `orgID`string The organization ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/variables" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of variables for an organization `variables`object[] `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ Example request body ```json { "variables": [ { "arguments": { "type": "constant", "values": [ "howdy", "hello", "hi", "yo", "oy" ] }, "id": "1221432", "name": ":ok:", "selected": [ "hello" ] }, { "arguments": { "type": "map", "values": { "a": "fdjaklfdjkldsfjlkjdsa", "b": "dfaksjfkljekfajekdljfas", "c": "fdjksajfdkfeawfeea" } }, "id": "1221432", "name": ":ok:", "selected": [ "c" ] }, { "arguments": { "language": "flux", "query": "from(bucket: \"foo\") |\u003e showMeasurements()", "type": "query" }, "id": "1221432", "name": ":ok:", "selected": [ "host" ] } ] } ``` 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/variables` ### Create a variable #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Variable to create Content-Type:`application/json` `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/variables" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "arguments": { "type": "query", "values": {} }, "createdAt": "CREATEDAT", "description": "DESCRIPTION", "id": "ID", "labels": [ { "id": "ID", "name": "NAME", "orgID": "ORGID", "properties": { "color": "ffb3b3", "description": "this is a description" } } ], "links": { "labels": "LABELS", "org": "ORG", "self": "SELF" }, "name": "NAME", "orgID": "ORGID", "selected": [ "SELECTED" ], "updatedAt": "UPDATEDAT" }' ``` #### Responses 201Variable created `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/variables/{variableID}` ### Retrieve a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/variables/{variableID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Variable found `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ 404Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PUT`/api/v2/variables/{variableID}` ### Replace a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Variable to replace Content-Type:`application/json` `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request PUT \ "http://localhost:8086/api/v2/variables/{variableID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "arguments": { "type": "query", "values": {} }, "createdAt": "CREATEDAT", "description": "DESCRIPTION", "id": "ID", "labels": [ { "id": "ID", "name": "NAME", "orgID": "ORGID", "properties": { "color": "ffb3b3", "description": "this is a description" } } ], "links": { "labels": "LABELS", "org": "ORG", "self": "SELF" }, "name": "NAME", "orgID": "ORGID", "selected": [ "SELECTED" ], "updatedAt": "UPDATEDAT" }' ``` #### Responses 200Variable updated `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/variables/{variableID}` ### Update a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Variable update to apply Content-Type:`application/json` `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/variables/{variableID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "arguments": { "type": "query", "values": {} }, "createdAt": "CREATEDAT", "description": "DESCRIPTION", "id": "ID", "labels": [ { "id": "ID", "name": "NAME", "orgID": "ORGID", "properties": { "color": "ffb3b3", "description": "this is a description" } } ], "links": { "labels": "LABELS", "org": "ORG", "self": "SELF" }, "name": "NAME", "orgID": "ORGID", "selected": [ "SELECTED" ], "updatedAt": "UPDATEDAT" }' ``` #### Responses 200Variable updated `arguments`requiredobject or object or object One of:object `type`string Allowed:`query` `values`object `language`string `query`string Or:object `type`string Allowed:`constant` `values`string[] Or:object `type`string Allowed:`map` `values`object `createdAt`string \ `description`string `id`string `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object `labels`string \ `org`string \ `self`string \ `name`requiredstring `orgID`requiredstring `selected`string[] `updatedAt`string \ defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/variables/{variableID}` ### Delete a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/variables/{variableID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Variable deleted defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/variables/{variableID}/labels` ### List all labels for a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/variables/{variableID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of all labels for a variable `labels`object[] `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/variables/{variableID}/labels` ### Add a label to a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring A label ID. Specifies the label to attach. Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/variables/{variableID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201The newly added label `label`object `id`string `name`string `orgID`string `properties`object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example:`{"color":"ffb3b3","description":"this is a description"}` `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/variables/{variableID}/labels/{labelID}` ### Delete a label from a variable #### Parameters ##### Path parameters `variableID`requiredstring The variable ID. `labelID`requiredstring The label ID to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "http://localhost:8086/api/v2/variables/{variableID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Delete has been accepted 404Variable not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Views Source: https://docs.influxdata.com/influxdb/v2/api/views/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Manage cell views within InfluxDB OSS v2 dashboards. GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Retrieve the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The dashboard ID. `cellID`requiredstring The cell ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A dashboard cells view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view` ### Update the view for a cell #### Parameters ##### Path parameters `dashboardID`requiredstring The ID of the dashboard to update. `cellID`requiredstring The ID of the cell to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Content-Type:`application/json` `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map Example request[Ask AI about this](#) ```sh curl --request PATCH \ "http://localhost:8086/api/v2/dashboards/{dashboardID}/cells/{cellID}/view" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "links": { "self": "SELF" }, "name": "NAME", "properties": { "adaptiveZoomHide": false, "axes": {}, "colors": [], "decimalPlaces": {}, "generateXAxisTicks": [], "generateYAxisTicks": [], "hoverDimension": "auto", "legendColorizeRows": false, "legendHide": false, "legendOpacity": 0, "legendOrientationThreshold": 0, "note": "NOTE", "position": "overlaid", "prefix": "PREFIX", "queries": [], "shadeBelow": false, "shape": "chronograf-v2", "showNoteWhenEmpty": false, "staticLegend": {}, "suffix": "SUFFIX", "timeFormat": "TIMEFORMAT", "type": "line-plus-single-stat", "xColumn": "XCOLUMN", "xTickStart": 0, "xTickStep": 0, "xTotalTicks": 0, "yColumn": "YCOLUMN", "yTickStart": 0, "yTickStep": 0, "yTotalTicks": 0 } }' ``` #### Responses 200Updated cell view `id`string `links`object `self`string `name`requiredstring `properties`requiredobject or object or object or object or object or object or object or object or object or object or object or object or object or object One of:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `generateXAxisTicks`string[] `generateYAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `timeFormat`string `type`requiredstring Allowed:`line-plus-single-stat` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colorMapping`object A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. Example:`{"configcat_deployments-autopromotionblocker":"#663cd0","measurement_birdmigration_europe":"#663cd0","series_id_1":"#edf529","series_id_2":"#edf529"}` `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shadeBelow`boolean `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`xy` `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`single-stat` Or:object `binCount`requiredinteger `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `fillColumns`requiredstring[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `position`requiredstring Allowed:`overlaid`, `stacked` `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`histogram` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `note`requiredstring `prefix`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `suffix`requiredstring `tickPrefix`requiredstring `tickSuffix`requiredstring `type`requiredstring Allowed:`gauge` Or:object `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `decimalPlaces`requiredobject Indicates whether decimal places should be enforced, and how many digits it should show. `digits`integer \ The number of digits after decimal to display `isEnforced`boolean Indicates whether decimal point setting should be enforced `fieldOptions`requiredobject[] fieldOptions represent the fields retrieved by the query with customization options `displayName`string The name that a field is renamed to by the user. `internalName`string The calculated name of a field. `visible`boolean Indicates whether this field should be visible on the table. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `tableOptions`requiredobject `fixFirstColumn`boolean fixFirstColumn indicates whether the first column of the table should be locked `sortBy`object Describes a field that can be renamed and made visible or invisible. `verticalTimeAxis`boolean verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically `wrapping`string Wrapping describes the text wrapping style to be used in table views Allowed:`truncate`, `wrap`, `single-line` `timeFormat`requiredstring timeFormat describes the display format for time values according to moment.js date formatting `type`requiredstring Allowed:`table` Or:object `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showAll`requiredboolean `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`simple-table` Or:object `note`requiredstring `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`markdown` Or:object `adaptiveZoomHide`boolean `check`object or object or object One of:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `level`string The state to record if check matches a criteria. Allowed:`UNKNOWN`, `OK`, `INFO`, `CRIT`, `WARN` `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `reportZero`boolean If only zero values reported since time, trigger an alert `staleTime`string String duration for time that a series is considered stale and should not trigger deadman. `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `timeSince`string String duration before deadman triggers. `type`requiredstring Allowed:`deadman` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `every`string Check repetition interval. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `offset`string Duration to delay after the schedule, before executing check. `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `statusMessageTemplate`string The template used to generate and write a status message. `tags`object[] List of tags to write to each status. `taskID`string The ID of the task associated with this check. `thresholds`object[] `type`requiredstring Allowed:`threshold` `updatedAt`string \ Or:object `createdAt`string \ `description`string An optional description of the check. `id`string `labels`object[] `lastRunError`string `lastRunStatus`string Allowed:`failed`, `success`, `canceled` `latestCompleted`string \ A timestamp ([RFC3339 date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. `links`object Example:`{"labels":"/api/v2/checks/1/labels","members":"/api/v2/checks/1/members","owners":"/api/v2/checks/1/owners","query":"/api/v2/checks/1/query","self":"/api/v2/checks/1"}` `name`requiredstring `orgID`requiredstring The ID of the organization that owns this check. `ownerID`string The ID of creator used to create this check. `query`requiredobject `status`string `inactive` cancels scheduled runs and prevents manual runs of the task. Allowed:`active`, `inactive` `taskID`string The ID of the task associated with this check. `type`requiredstring Allowed:`custom` `updatedAt`string \ `checkID`requiredstring `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `type`requiredstring Allowed:`check` Or:object `adaptiveZoomHide`boolean `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `symbolColumns`requiredstring[] `timeFormat`string `type`requiredstring Allowed:`scatter` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `adaptiveZoomHide`boolean `binSize`requirednumber `colors`requiredstring[] Colors define color encoding of data into a visualization `generateXAxisTicks`string[] `generateYAxisTicks`string[] `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`heatmap` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yColumn`requiredstring `yDomain`requirednumber[] `yPrefix`requiredstring `ySuffix`requiredstring `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `colors`requiredstring[] Colors define color encoding of data into a visualization `fillColumns`requiredstring[] `generateXAxisTicks`string[] `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `timeFormat`string `type`requiredstring Allowed:`mosaic` `xAxisLabel`requiredstring `xColumn`requiredstring `xDomain`requirednumber[] `xPrefix`requiredstring `xSuffix`requiredstring `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yAxisLabel`requiredstring `yDomain`requirednumber[] `yLabelColumnSeparator`string `yLabelColumns`string[] `yPrefix`requiredstring `ySeriesColumns`requiredstring[] `ySuffix`requiredstring Or:object `adaptiveZoomHide`boolean `axes`requiredobject The viewport for a View’s visualizations `x`requiredobject Axis used in a visualization. `y`requiredobject Axis used in a visualization. `colors`requiredobject[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `generateXAxisTicks`string[] `generateYAxisTicks`string[] `geom`requiredstring Allowed:`line`, `step`, `stacked`, `bar`, `monotoneX`, `stepBefore`, `stepAfter` `hoverDimension`string Allowed:`auto`, `x`, `y`, `xy` `legendColorizeRows`boolean `legendHide`boolean `legendOpacity`number \ `legendOrientationThreshold`integer `lowerColumn`string `mainColumn`string `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `staticLegend`object StaticLegend represents the options specific to the static legend `colorizeRows`boolean `heightRatio`number \ `opacity`number \ `orientationThreshold`integer `show`boolean `valueAxis`string `widthRatio`number \ `timeFormat`string `type`requiredstring Allowed:`band` `upperColumn`string `xColumn`string `xTickStart`number \ `xTickStep`number \ `xTotalTicks`integer `yColumn`string `yTickStart`number \ `yTickStep`number \ `yTotalTicks`integer Or:object `allowPanAndZoom`requiredboolean If true, map zoom and pan controls are enabled on the dashboard view Default:`true` `center`requiredobject Coordinates of the center of the map `lat`requirednumber \ Latitude of the center of the map `lon`requirednumber \ Longitude of the center of the map `colors`object[] Colors define color encoding of data into a visualization `hex`requiredstring The hex number of the color `id`requiredstring The unique ID of the view color. `name`requiredstring The user-facing name of the hex color. `type`requiredstring Type is how the color is used. Allowed:`min`, `max`, `threshold`, `scale`, `text`, `background` `value`requirednumber \ The data value mapped to this color. `detectCoordinateFields`requiredboolean If true, search results get automatically regroupped so that lon,lat and value are treated as columns Default:`true` `latLonColumns`object Object type to define lat/lon columns `lat`requiredobject Object type for key and column definitions `lon`requiredobject Object type for key and column definitions `layers`requiredobject[] List of individual layers shown in the map `mapStyle`string Define map type - regular, satellite etc. `note`requiredstring `queries`requiredobject[] `builderConfig`object `editMode`string Allowed:`builder`, `advanced` `name`string `text`string The text of the Flux query. `s2Column`string String to define the column `shape`requiredstring Allowed:`chronograf-v2` `showNoteWhenEmpty`requiredboolean If true, will display note when empty `type`requiredstring Allowed:`geo` `useS2CellID`boolean If true, S2 column is used to calculate lat/lon `zoom`requirednumber \ Zoom level used for initial display of the map 404Cell or dashboard not found `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultUnexpected error `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Write Source: https://docs.influxdata.com/influxdb/v2/api/write/ [Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml) Write time series data to [buckets](/influxdb/v2/reference/glossary/#bucket). POST`/api/v2/write` ### Write data Writes data to a bucket. Use this endpoint to send data in [line protocol](/influxdb/v2/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud * Does the following when you send a write request: 1. Validates the request and queues the write. 2. If queued, responds with *success* (HTTP `2xx` status code); *error* otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS * Validates the request and handles the write synchronously. * If all points were written successfully, responds with HTTP `2xx` status code; otherwise, returns the first line that failed. #### Required permissions * `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides * [Write data with the InfluxDB API](/influxdb/v2/write-data/developer-tools/api) * [Optimize writes to InfluxDB](/influxdb/v2/write-data/best-practices/optimize-writes/) * [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/) #### Parameters ##### Query parameters `org`requiredstring An organization name or ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * If you pass both `orgID` and `org`, they must both be valid. * Writes data to the bucket in the specified organization. `orgID`string An organization ID. #### InfluxDB Cloud * Doesn’t use the `org` parameter or `orgID` parameter. * Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS * Requires either the `org` parameter or the `orgID` parameter. * If you pass both `orgID` and `org`, they must both be valid. * Writes data to the bucket in the specified organization. `bucket`requiredstring A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket. `precision`string The precision for unix timestamps in the line protocol batch. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context `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-Type`string The format of the data in the request body. To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`. Allowed values:`text/plain`, `text/plain; charset=utf-8` Default:`text/plain; charset=utf-8` `Content-Length`integer The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the `max body` configuration option, the server responds with status code `413`. `Accept`string The content type that the client can understand. Writes only return a response body if they fail–for example, due to a formatting problem or quota limit. #### InfluxDB Cloud * Returns only `application/json` for format and limit errors. * Returns only `text/html` for some quota limit errors. #### InfluxDB OSS * Returns only `application/json` for format and limit errors. #### Related guides * [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/) Allowed values:`application/json` Default:`application/json` #### Request bodyrequired In the request body, provide data in [line protocol format](/influxdb/v2/reference/syntax/line-protocol/). To send compressed data, do the following: 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. 2. In your request, send the compressed data and the`Content-Encoding: gzip` header. #### Related guides * [Best practices for optimizing writes](/influxdb/v2/write-data/best-practices/optimize-writes/) Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "http://localhost:8086/api/v2/write?org=ORG&bucket=BUCKET" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: text/plain" \ --data-raw 'airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000' ``` #### Responses 204 Success. #### InfluxDB Cloud * Validated and queued the request. * Handles the write asynchronously - the write might not have completed yet. #### InfluxDB OSS * Successfully wrote all points in the batch. #### Related guides * [How to check for write errors](/influxdb/v2/write-data/troubleshoot/) 400 Bad request. The response body contains detail about the error. InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket. #### InfluxDB Cloud * Returns this error for bucket schema conflicts. #### InfluxDB OSS * Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization. `code`requiredstring Code is the machine-readable error code. Allowed:`internal error`, `not found`, `conflict`, `invalid`, `empty value`, `unavailable` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `line`integer \ First line in the request body that contains malformed data. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: * `"organization name \"my-org\" not found"` * `"organization not found"`: indicates you passed an ID that did not match an organization. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 413 The request payload is too large. InfluxDB rejected the batch and did not write any data. #### InfluxDB Cloud: * Returns this error if the payload exceeds the 50MB size limit. * Returns `Content-Type: text/html` for this error. #### InfluxDB OSS: * Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. * Returns `Content-Type: application/json` for this error. `code`requiredstring Code is the machine-readable error code. Allowed:`invalid` `message`requiredstring Human-readable message. 429 Too many requests. #### InfluxDB Cloud * Returns this error if a **read** or **write** request exceeds your plan’s [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). * For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. * For limits that can’t reset (for example, **cardinality limit**), doesn’t return a `Retry-After` header. Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. #### InfluxDB OSS * Doesn’t return this error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 503 Service unavailable. * Returns this error if the server is temporarily unavailable to accept writes. * Returns a `Retry-After` header that describes when to try the write again. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. --- # Get started with InfluxDB Source: https://docs.influxdata.com/influxdb/v2/get-started/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB 2.10 is the platform purpose-built to collect, store, process and visualize time series data.**Time series data** is a sequence of data points indexed in time order. Data points typically consist of successive measurements made from the same source and are used to track changes over time. Examples of time series data include: * Industrial sensor data * Server performance metrics * Heartbeats per minute * Electrical activity in the brain * Rainfall measurements * Stock prices This multi-part tutorial walks you through writing time series data to InfluxDB 2.10, querying that data, processing and alerting on the data, and then visualizing the data. ## Key concepts before you get started Before you get started using InfluxDB, it’s important to understand how time series data is organized and stored in InfluxDB and some key definitions that are used throughout this documentation. ### Data organization The InfluxDB data model organizes time series data into buckets and measurements. A bucket can contain multiple measurements. Measurements contain multiple tags and fields. * **Bucket**: Named location where time series data is stored. A bucket can contain multiple *measurements*. * **Measurement**: Logical grouping for time series data. All *points* in a given measurement should have the same *tags*. A measurement contains multiple *tags* and *fields*. * **Tags**: Key-value pairs with values that differ, but do not change often. Tags are meant for storing metadata for each point–for example, something to identify the source of the data like host, location, station, etc. * **Fields**: Key-value pairs with values that change over time–for example: temperature, pressure, stock price, etc. * **Timestamp**: Timestamp associated with the data. When stored on disk and queried, all data is ordered by time. *For detailed information and examples of the InfluxDB data model, see[Data elements](/influxdb/v2/reference/key-concepts/data-elements/).* ### Important definitions The following are important definitions to understand when using InfluxDB: * **Point**: Single data record identified by its *measurement, tag keys, tag values, field key, and timestamp*. * **Series**: A group of points with the same*measurement, tag keys, and tag values*. ##### Example InfluxDB query results | \_time |\_measurement| city |country| \_field |\_value| |:-------------------|:------------|:-----|:------|:----------|------:| |2022-01-01T12:00:00Z| weather |London| UK |temperature| 12.0 | |2022-02-01T12:00:00Z| weather |London| UK |temperature| 12.1 | |2022-03-01T12:00:00Z| weather |London| UK |temperature| 11.5 | |2022-04-01T12:00:00Z| weather |London| UK |temperature| 5.9 | | \_time |\_measurement| city |country| \_field |\_value| |:-------------------|:------------|:------|:------|:----------|------:| |2022-01-01T12:00:00Z| weather |Cologne| DE |temperature| 13.2 | |2022-02-01T12:00:00Z| weather |Cologne| DE |temperature| 11.5 | |2022-03-01T12:00:00Z| weather |Cologne| DE |temperature| 10.2 | |2022-04-01T12:00:00Z| weather |Cologne| DE |temperature| 7.9 | ## Tools to use Throughout this tutorial, there are multiple tools you can use to interact with InfluxDB 2.10. Examples are provided for each of the following: * [InfluxDB user interface (UI)](#influxdb-user-interface-ui) * [`influx` CLI](#influx-cli) * [InfluxDB HTTP API](#influxdb-http-api) ### InfluxDB user interface (UI) The InfluxDB UI provides a web-based visual interface for interacting with and managing InfluxDB. The UI is packaged with InfluxDB and runs as part of the InfluxDB service. To access the UI, with InfluxDB running, visit [localhost:8086](http://localhost:8086) in your browser. ### `influx` CLI The `influx` CLI lets you interact with and manage InfluxDB 2.10 from a command line. The CLI is packaged separately from InfluxDB and must be downloaded and installed separately. For detailed CLI installation instructions, see[Use the influx CLI](/influxdb/v2/tools/influx-cli/). ### InfluxDB HTTP API The [InfluxDB API](/influxdb/v2/reference/api/) provides a simple way to interact with the InfluxDB 2.10 using HTTP(S) clients. Examples in this tutorial use cURL, but any HTTP(S) client will work. > [!Note] > #### InfluxDB client libraries > > [InfluxDB client libraries](/influxdb/v2/api-guide/client-libraries/) are > language-specific clients that interact with the InfluxDB HTTP API. > Examples for client libraries are not provided in this tutorial, but these can > be used to perform all the actions outlined in this tutorial. ## Authorization **InfluxDB 2.10 requires authentication** using [API tokens](/influxdb/v2/admin/tokens/). Each API token is associated with a user and a specific set of permissions for InfluxDB resources. [Set up InfluxDB](/influxdb/v2/get-started/setup/) ![InfluxDB University](/svgs/influxdbu-full-white.svg) #### InfluxDB Essentials Learn how to write, query, and visualize data in InfluxDB in this **free** InfluxDB University course. [Take the course](https://university.influxdata.com/courses/influxdb-essentials-tutorial/) [get-started](/influxdb/v2/tags/get-started/) | _time | _measurement | city | country | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | city | country | _field | _value | | 2022-01-01T12:00:00Z | weather | London | UK | temperature | 12.0 | | 2022-02-01T12:00:00Z | weather | London | UK | temperature | 12.1 | | 2022-03-01T12:00:00Z | weather | London | UK | temperature | 11.5 | | 2022-04-01T12:00:00Z | weather | London | UK | temperature | 5.9 | | _time | _measurement | city | country | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | city | country | _field | _value | | 2022-01-01T12:00:00Z | weather | Cologne | DE | temperature | 13.2 | | 2022-02-01T12:00:00Z | weather | Cologne | DE | temperature | 11.5 | | 2022-03-01T12:00:00Z | weather | Cologne | DE | temperature | 10.2 | | 2022-04-01T12:00:00Z | weather | Cologne | DE | temperature | 7.9 | --- # Get started processing data Source: https://docs.influxdata.com/influxdb/v2/get-started/process/ * 4 / 5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Now that you know the [basics of querying data from InfluxDB](/influxdb/v2/get-started/query/), let’s go beyond a basic query and begin to process the queried data. “Processing” data could mean transforming, aggregating, downsampling, or alerting on data. This tutorial covers the following data processing use cases: * [Remap or assign values in your data](#remap-or-assign-values-in-your-data) * [Group data](#group-data) * [Aggregate or select specific data](#aggregate-or-select-specific-data) * [Pivot data into a relational schema](#pivot-data-into-a-relational-schema) * [Downsample data](#downsample-data) * [Automate processing with InfluxDB tasks](#automate-processing-with-influxdb-tasks) > [!Note] > Most data processing operations require manually editing Flux queries. > If you’re using the **InfluxDB Data Explorer**, switch to the **Script Editor**instead of using the **Query Builder.** ## Remap or assign values in your data Use the [`map()` function](/flux/v0/stdlib/universe/map/) to iterate over each row in your data and update the values in that row.`map()` is one of the most useful functions in Flux and will help you accomplish many of they data processing operations you need to perform. [](#learn-more-about-how-map-works) Learn more about how `map()` works `map()` takes a single parameter, `fn`.`fn` takes an anonymous function that reads each row as a[record](/flux/v0/data-types/composite/record/) named `r`. In the `r` record, each key-value pair represents a column and its value. For example: ```js r = { _time: 2020-01-01T00:00:00Z, _measurement: "home", room: "Kitchen", _field: "temp", _value: 21.0, } ``` | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2020-01-01T00:00:00Z| home |Kitchen| temp | 21.0 | The `fn` function modifies the `r` record in any way you need and returns a new record for the row. For example, using the record above: ``` (r) => ({ _time: r._time, _field: "temp_F", _value: (r._value * 1.8) + 32.0}) // Returns: {_time: 2020-01-01T00:00:00Z, _field: "temp_F", _value: 69.8} ``` | \_time |\_field|\_value| |--------------------|-------|-------| |2020-01-01T00:00:00Z|temp\_F| 69.8 | Notice that some of the columns were dropped from the original row record. This is because the `fn` function explicitly mapped the `_time`, `_field`, and `_value` columns. To retain existing columns and only update or add specific columns, use the`with` operator to extend your row record. For example, using the record above: ``` (r) => ({r with _value: (r._value * 1.8) + 32.0, degrees: "F"}) // Returns: // { // _time: 2020-01-01T00:00:00Z, // _measurement: "home", // room: "Kitchen", // _field: "temp", // _value: 69.8, // degrees: "F", // } ``` | \_time |\_measurement| room |\_field|\_value|degrees| |--------------------|-------------|-------|-------|-------|-------| |2020-01-01T00:00:00Z| home |Kitchen| temp | 69.8 | F | ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "hum") |> map(fn: (r) => ({r with _value: r._value / 100.0})) ``` ### Map examples [](#perform-mathematical-operations) Perform mathematical operations `map()` lets your perform mathematical operations on your data. For example, using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field to return room temperatures in °C. 2. Use `map()` to iterate over each row and convert the °C temperatures in the`_value` column to °F using the equation: `°F = (°C * 1.8) + 32.0`. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> map(fn: (r) => ({r with _value: (r._value * 1.8) + 32.0})) ``` [Input](#input)[Output](#output-2)Click to view output > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > > [!Note] > `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field| \_value | |--------------------|-------------|-------|-------|-----------------| |2022-01-01T14:00:00Z| home |Kitchen| temp |73.03999999999999| |2022-01-01T15:00:00Z| home |Kitchen| temp | 72.86 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 72.32 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 72.86 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 73.94 | |2022-01-01T19:00:00Z| home |Kitchen| temp |73.58000000000001| |2022-01-01T20:00:00Z| home |Kitchen| temp | 72.86 | | \_time |\_measurement| room |\_field| \_value | |--------------------|-------------|-----------|-------|-----------------| |2022-01-01T14:00:00Z| home |Living Room| temp | 72.14 | |2022-01-01T15:00:00Z| home |Living Room| temp | 72.14 | |2022-01-01T16:00:00Z| home |Living Room| temp | 72.32 | |2022-01-01T17:00:00Z| home |Living Room| temp | 72.68 | |2022-01-01T18:00:00Z| home |Living Room| temp |73.03999999999999| |2022-01-01T19:00:00Z| home |Living Room| temp | 72.5 | |2022-01-01T20:00:00Z| home |Living Room| temp |71.96000000000001| [](#conditionally-assign-a-state) Conditionally assign a state Within a `map()` function, you can use [conditional expressions](/flux/v0/spec/expressions/#conditional-expressions) (if/then/else) to conditionally assign values. For example, using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `co` field to return carbon monoxide parts per million (ppm) readings in each room. 2. Use `map()` to iterate over each row, evaluate the value in the `_value`column, and then conditionally assign a state: * If the carbon monoxide is less than 10 ppm, assign the state: **ok**. * Otherwise, assign the state: **warning**. Store the state in a **state** column. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "co") |> map(fn: (r) => ({r with state: if r._value < 10 then "ok" else "warning"})) ``` [Input](#input-2)[Output](#output-3)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| co | 1 | |2022-01-01T15:00:00Z| home |Kitchen| co | 3 | |2022-01-01T16:00:00Z| home |Kitchen| co | 7 | |2022-01-01T17:00:00Z| home |Kitchen| co | 9 | |2022-01-01T18:00:00Z| home |Kitchen| co | 18 | |2022-01-01T19:00:00Z| home |Kitchen| co | 22 | |2022-01-01T20:00:00Z| home |Kitchen| co | 26 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| co | 1 | |2022-01-01T15:00:00Z| home |Living Room| co | 1 | |2022-01-01T16:00:00Z| home |Living Room| co | 4 | |2022-01-01T17:00:00Z| home |Living Room| co | 5 | |2022-01-01T18:00:00Z| home |Living Room| co | 9 | |2022-01-01T19:00:00Z| home |Living Room| co | 14 | |2022-01-01T20:00:00Z| home |Living Room| co | 17 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| state | |--------------------|-------------|-------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| co | 1 | ok | |2022-01-01T15:00:00Z| home |Kitchen| co | 3 | ok | |2022-01-01T16:00:00Z| home |Kitchen| co | 7 | ok | |2022-01-01T17:00:00Z| home |Kitchen| co | 9 | ok | |2022-01-01T18:00:00Z| home |Kitchen| co | 18 |warning| |2022-01-01T19:00:00Z| home |Kitchen| co | 22 |warning| |2022-01-01T20:00:00Z| home |Kitchen| co | 26 |warning| | \_time |\_measurement| room |\_field|\_value| state | |--------------------|-------------|-----------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| co | 1 | ok | |2022-01-01T15:00:00Z| home |Living Room| co | 1 | ok | |2022-01-01T16:00:00Z| home |Living Room| co | 4 | ok | |2022-01-01T17:00:00Z| home |Living Room| co | 5 | ok | |2022-01-01T18:00:00Z| home |Living Room| co | 9 | ok | |2022-01-01T19:00:00Z| home |Living Room| co | 14 |warning| |2022-01-01T20:00:00Z| home |Living Room| co | 17 |warning| [](#alert-on-data) Alert on data `map()` lets you execute more complex operations on a per row basis. Using a [Flux block (`{}`)](/flux/v0/spec/blocks/) in the `fn` function, you can create scoped variables and execute other functions within the context of each row. For example, you can send a message to [Slack](https://slack.com). > [!Note] > For this example to actually send messages to Slack, you need to[set up a Slack app that can send and receive messages](https://api.slack.com/messaging/sending). For example, using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Import the [`slack` package](/flux/v0/stdlib/slack/). 2. Query the `co` field to return carbon monoxide parts per million (ppm) readings in each room. 3. Use `map()` to iterate over each row, evaluate the value in the `_value`column, and then conditionally assign a state: * If the carbon monoxide is less than 10 ppm, assign the state: **ok**. * Otherwise, assign the state: **warning**. Store the state in a **state** column. 4. Use [`filter()`](/flux/v0/stdlib/universe/filter/) to return only rows with **warning** in the state column. 5. Use `map()` to iterate over each row. In your `fn` function, use a [Flux block (`{}`)](/flux/v0/spec/blocks/) to: 1. Create a `responseCode` variable that uses [`slack.message()`](/flux/v0/stdlib/slack/message/)to send a message to Slack using data from the input row.`slack.message()` returns the response code of the Slack API request as an integer. 2. Use a `return` statement to return a new row record. The new row should extend the input row with a new column, **sent**, with a boolean value determined by the `responseCode` variable. `map()` sends a message to Slack for each row piped forward into the function. ```js import "slack" from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "co") |> map(fn: (r) => ({r with state: if r._value < 10 then "ok" else "warning"})) |> filter(fn: (r) => r.state == "warning") |> map( fn: (r) => { responseCode = slack.message( token: "mYSlacK70k3n", color: "#ff0000", channel: "#alerts", text: "Carbon monoxide is at dangerous levels in the ${r.room}: ${r._value} ppm.", ) return {r with sent: responseCode == 200} }, ) ``` [Input](#input-3)[Output](#output-4)Click to view output The following input represents the data filtered by the **warning** state. `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| state | |--------------------|-------------|-------|-------|-------|-------| |2022-01-01T18:00:00Z| home |Kitchen| co | 18 |warning| |2022-01-01T19:00:00Z| home |Kitchen| co | 22 |warning| |2022-01-01T20:00:00Z| home |Kitchen| co | 26 |warning| | \_time |\_measurement| room |\_field|\_value| state | |--------------------|-------------|-----------|-------|-------|-------| |2022-01-01T19:00:00Z| home |Living Room| co | 14 |warning| |2022-01-01T20:00:00Z| home |Living Room| co | 17 |warning| The output includes a **sent** column indicating the if the message was sent. `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| state |sent| |--------------------|-------------|-------|-------|-------|-------|----| |2022-01-01T18:00:00Z| home |Kitchen| co | 18 |warning|true| |2022-01-01T19:00:00Z| home |Kitchen| co | 22 |warning|true| |2022-01-01T20:00:00Z| home |Kitchen| co | 26 |warning|true| | \_time |\_measurement| room |\_field|\_value| state |sent| |--------------------|-------------|-----------|-------|-------|-------|----| |2022-01-01T19:00:00Z| home |Living Room| co | 14 |warning|true| |2022-01-01T20:00:00Z| home |Living Room| co | 17 |warning|true| With the results above, you would receive the following messages in Slack: > > > Carbon monoxide is at dangerous levels in the Kitchen: 18 ppm. > Carbon monoxide is at dangerous levels in the Kitchen: 22 ppm. > Carbon monoxide is at dangerous levels in the Living Room: 14 ppm. > Carbon monoxide is at dangerous levels in the Kitchen: 26 ppm. > Carbon monoxide is at dangerous levels in the Living Room: 17 ppm. > > > [!Note] > You can also use the [InfluxDB checks and notifications system](/influxdb/v2/monitor-alert/)as a user interface for configuring checks and alerting on data. ## Group data Use the [`group()` function](/flux/v0/stdlib/universe/group/) to regroup your data by specific column values in preparation for further processing. ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> group(columns: ["room", "_field"]) ``` > [!Note] > Understanding data grouping and why it matters is important, but may be too much > for this “getting started” tutorial. > For more information about how data is grouped and why it matters, see the[Flux data model](/flux/v0/get-started/data-model/) documentation. By default, `from()` returns data queried from InfluxDB grouped by series (measurement, tags, and field key). Each table in the returned stream of tables represents a group. Each table contains the same values for the columns that data is grouped by. This grouping is important as you [aggregate data](#aggregate-or-select-specific-data). ### Group examples [](#group-data-by-specific-columns) Group data by specific columns Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` and `hum` fields. 2. Use `group()` to group by only the `_field` column. ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T10:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp" or r._field == "hum") |> group(columns: ["_field"]) ``` [Input](#input-4)[Output](#output-5)Click to view output The following data is output from the last `filter()` and piped forward into `group()`: `_start` and `_stop` columns have been omitted. Group key instance = [\_measurement=home, room=Kitchen, \_field=hum] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| hum | 35.9 | |2022-01-01T09:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T10:00:00Z| home |Kitchen| hum | 36.1 | Group key instance = [\_measurement=home, room=Living Room, \_field=hum] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | Group key instance = [\_measurement=home, room=Kitchen, \_field=temp] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| temp | 21 | |2022-01-01T09:00:00Z| home |Kitchen| temp | 23 | |2022-01-01T10:00:00Z| home |Kitchen| temp | 22.7 | Group key instance = [\_measurement=home, room=Living Room, \_field=temp] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | When grouped by `_field`, all rows with the `temp` field will be in one table and all the rows with the `hum` field will be in another.`_measurement` and `room` columns no longer affect how rows are grouped. `_start` and `_stop` columns have been omitted. Group key instance = [\_field=hum] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home | Kitchen | hum | 35.9 | |2022-01-01T09:00:00Z| home | Kitchen | hum | 36.2 | |2022-01-01T10:00:00Z| home | Kitchen | hum | 36.1 | |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | Group key instance = [\_field=temp] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home | Kitchen | temp | 21 | |2022-01-01T09:00:00Z| home | Kitchen | temp | 23 | |2022-01-01T10:00:00Z| home | Kitchen | temp | 22.7 | |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | [](#ungroup-data) Ungroup data Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` and `hum` fields. 2. Use `group()` without any parameters to “ungroup” data or group by no columns. The default value of the `columns` parameter is an empty array (`[]`). ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T10:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp" or r._field == "hum") |> group() ``` [Input](#input-5)[Output](#output-6)Click to view output The following data is output from the last `filter()` and piped forward into `group()`: `_start` and `_stop` columns have been omitted. Group key instance = [\_measurement=home, room=Kitchen, \_field=hum] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| hum | 35.9 | |2022-01-01T09:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T10:00:00Z| home |Kitchen| hum | 36.1 | Group key instance = [\_measurement=home, room=Living Room, \_field=hum] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | Group key instance = [\_measurement=home, room=Kitchen, \_field=temp] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| temp | 21 | |2022-01-01T09:00:00Z| home |Kitchen| temp | 23 | |2022-01-01T10:00:00Z| home |Kitchen| temp | 22.7 | Group key instance = [\_measurement=home, room=Living Room, \_field=temp] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | When ungrouped, a data is returned in a single table. `_start` and `_stop` columns have been omitted. Group key instance = [] | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home | Kitchen | hum | 35.9 | |2022-01-01T09:00:00Z| home | Kitchen | hum | 36.2 | |2022-01-01T10:00:00Z| home | Kitchen | hum | 36.1 | |2022-01-01T08:00:00Z| home | Kitchen | temp | 21 | |2022-01-01T09:00:00Z| home | Kitchen | temp | 23 | |2022-01-01T10:00:00Z| home | Kitchen | temp | 22.7 | |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | ## Aggregate or select specific data Use Flux [aggregate](/flux/v0/function-types/#aggregates)or [selector](/flux/v0/function-types/#selectors) functions to return aggregate or selected values from **each** input table. ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "co" or r._field == "hum" or r._field == "temp") |> mean() ``` > [!Note] > #### Aggregate over time > > If you want to query aggregate values over time, this is a form of[downsampling](#downsample-data). ### Aggregate functions [Aggregate functions](/flux/v0/function-types/#aggregates) drop columns that are **not** in the [group key](/flux/v0/get-started/data-model/#group-key)and return a single row for each input table with the aggregate value of that table. #### Aggregate examples [](#calculate-the-average-temperature-for-each-room) Calculate the average temperature for each room Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field. By default, `from()` returns the data grouped by`_measurement`, `room` and `_field`, so each table represents a room. 2. Use `mean()` to return the average temperature from each room. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> mean() ``` [Input](#input-6)[Output](#output-7)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. |\_measurement| room |\_field| \_value | |-------------|-------|-------|------------------| | home |Kitchen| temp |22.814285714285713| |\_measurement| room |\_field| \_value | |-------------|-----------|-------|-----------------| | home |Living Room| temp |22.44285714285714| [](#calculate-the-overall-average-temperature-of-all-rooms) Calculate the overall average temperature of all rooms Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field. 2. Use `group()` to **ungroup** the data into a single table. By default,`from()` returns the data grouped by`_measurement`, `room` and `_field`. To get the overall average, you need to structure all results as a single table. 3. Use `mean()` to return the average temperature. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> group() |> mean() ``` [Input](#input-7)[Output](#output-8)Click to view output The following input data represents the ungrouped data that is piped forward into `mean()`. `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home | Kitchen | temp | 22.8 | |2022-01-01T15:00:00Z| home | Kitchen | temp | 22.7 | |2022-01-01T16:00:00Z| home | Kitchen | temp | 22.4 | |2022-01-01T17:00:00Z| home | Kitchen | temp | 22.7 | |2022-01-01T18:00:00Z| home | Kitchen | temp | 23.3 | |2022-01-01T19:00:00Z| home | Kitchen | temp | 23.1 | |2022-01-01T20:00:00Z| home | Kitchen | temp | 22.7 | |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_value | |------------------| |22.628571428571426| [](#count-the-number-of-points-reported-per-room-across-all-fields) Count the number of points reported per room across all fields Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query all fields by simply filtering by the `home` measurement. 2. The fields in the `home` measurement are different types. Use `toFloat()` to cast all field values to floats. 3. Use `group()` to group the data by `room`. 4. Use `count()` to return the number of rows in each input table. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> toFloat() |> group(columns: ["room"]) |> count() ``` ##### Output `_start` and `_stop` columns have been omitted. | room |\_value| |-------|-------| |Kitchen| 21 | | room |\_value| |-----------|-------| |Living Room| 21 | > [!Note] > #### Assign a new aggregate timestamp > > `_time` is generally not part of the group key and will be dropped when using > aggregate functions. To assign a new timestamp to aggregate points, duplicate > the `_start` or `_stop` column, which represent the query bounds, as the > new `_time` column. > > ``` > from(bucket: "get-started") > |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) > |> filter(fn: (r) => r._measurement == "home") > |> filter(fn: (r) => r._field == "temp") > |> mean() > |> duplicate(column: "_stop", as: "_time") > ``` ### Selector functions [Selector functions](/flux/v0/function-types/#selectors) return one or more columns from each input table and retain all columns and their values. #### Selector examples [](#return-the-first-temperature-from-each-room) Return the first temperature from each room Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field. 2. Use [`first()`](/flux/v0/stdlib/universe/first/) to return the first row from each table. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> first() ``` [Input](#input-8)[Output](#output-9)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | [](#return-the-last-temperature-from-each-room) Return the last temperature from each room Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field. 2. Use [`last()`](/flux/v0/stdlib/universe/last/) to return the last row from each table. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> last() ``` [Input](#input-9)[Output](#output-10)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | [](#return-the-maximum-temperature-from-each-room) Return the maximum temperature from each room Using the [data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data): 1. Query the `temp` field. 2. Use [`max()`](/flux/v0/stdlib/universe/max/) to return the row with the highest value in the `_value` column from each table. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> max() ``` [Input](#input-10)[Output](#output-11)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | ## Pivot data into a relational schema If coming from relational SQL or SQL-like query languages, such as InfluxQL, the data model that Flux uses is different than what you’re used to. Flux returns multiple tables where each table contains a different field. A “relational” schema structures each field as a column in each row. Use the [`pivot()` function](/flux/v0/stdlib/universe/pivot/) to pivot data into a “relational” schema based on timestamps. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "co" or r._field == "hum" or r._field == "temp") |> filter(fn: (r) => r.room == "Kitchen") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") ``` [](#view-input-and-pivoted-output) View input and pivoted output [Input](#input-11)[Output](#output-12)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| co | 1 | |2022-01-01T15:00:00Z| home |Kitchen| co | 3 | |2022-01-01T16:00:00Z| home |Kitchen| co | 7 | |2022-01-01T17:00:00Z| home |Kitchen| co | 9 | |2022-01-01T18:00:00Z| home |Kitchen| co | 18 | |2022-01-01T19:00:00Z| home |Kitchen| co | 22 | |2022-01-01T20:00:00Z| home |Kitchen| co | 26 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| hum | 36.3 | |2022-01-01T15:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T16:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T17:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T18:00:00Z| home |Kitchen| hum | 36.9 | |2022-01-01T19:00:00Z| home |Kitchen| hum | 36.6 | |2022-01-01T20:00:00Z| home |Kitchen| hum | 36.5 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |co |hum |temp| |--------------------|-------------|-------|---|----|----| |2022-01-01T14:00:00Z| home |Kitchen| 1 |36.3|22.8| |2022-01-01T15:00:00Z| home |Kitchen| 3 |36.2|22.7| |2022-01-01T16:00:00Z| home |Kitchen| 7 | 36 |22.4| |2022-01-01T17:00:00Z| home |Kitchen| 9 | 36 |22.7| |2022-01-01T18:00:00Z| home |Kitchen|18 |36.9|23.3| |2022-01-01T19:00:00Z| home |Kitchen|22 |36.6|23.1| |2022-01-01T20:00:00Z| home |Kitchen|26 |36.5|22.7| ## Downsample data Downsampling data is a strategy that improve performance at query time and also optimizes long-term data storage. Simply put, downsampling reduces the number of points returned by a query without losing the general trends in the data. *For more information about downsampling data, see[Downsample data](/influxdb/v2/process-data/common-tasks/downsample-data/).* The most common way to downsample data is by time intervals or “windows.” For example, you may want to query the last hour of data and return the average value for every five minute window. Use [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)to downsample data by specified time intervals: * Use the `every` parameter to specify the duration of each window. * Use the `fn` parameter to specify what [aggregate](/flux/v0/function-types/#aggregates)or [selector](/flux/v0/function-types/#selectors) function to apply to each window. * *(Optional)* Use the `timeSrc` parameter to specify which column value to use to create the new aggregate timestamp for each window. The default is `_stop`. ```js from(bucket: "get-started") |> range(start: 2022-01-01T14:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field == "temp") |> aggregateWindow(every: 2h, fn: mean) ``` [](#view-input-and-downsampled-output) View input and downsampled output [Input](#input-12)[Output](#output-13)Click to view output `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | `_start` and `_stop` columns have been omitted. | \_time |\_measurement| room |\_field| \_value | |--------------------|-------------|-------|-------|------------------| |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.75 | |2022-01-01T18:00:00Z| home |Kitchen| temp |22.549999999999997| |2022-01-01T20:00:00Z| home |Kitchen| temp |23.200000000000003| |2022-01-01T20:00:01Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T16:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.65 | |2022-01-01T20:00:01Z| home |Living Room| temp | 22.2 | ## Automate processing with InfluxDB tasks [InfluxDB tasks](/influxdb/v2/process-data/get-started/) are scheduled queries that can perform any of the data processing operations described above. Generally tasks then use the [`to()` function](/flux/v0/stdlib/influxdata/influxdb/to/)to write the processed result back to InfluxDB. *For more information about creating and configuring tasks, see[Get started with InfluxDB tasks](/influxdb/v2/process-data/get-started/).* #### Example downsampling task ```js option task = { name: "Example task" every: 1d, } from(bucket: "get-started-downsampled") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "home") |> aggregateWindow(every: 2h, fn: mean) ``` [Query data](/influxdb/v2/get-started/query/)[Visualize data](/influxdb/v2/get-started/visualize/) #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [Get started with InfluxDB tasks](/influxdb/v2/process-data/get-started/) * [Get started with Flux](/flux/v0/get-started/) * [Flux standard library](/flux/v0/stdlib/) | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2020-01-01T00:00:00Z | home | Kitchen | temp | 21.0 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:00:00Z | temp_F | 69.8 | | _time | _measurement | room | _field | _value | degrees | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | degrees | | 2020-01-01T00:00:00Z | home | Kitchen | temp | 69.8 | F | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 73.03999999999999 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 72.86 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 72.32 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 72.86 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 73.94 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 73.58000000000001 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 72.86 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 72.14 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 72.14 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 72.32 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 72.68 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 73.03999999999999 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 72.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 71.96000000000001 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T15:00:00Z | home | Kitchen | co | 3 | | 2022-01-01T16:00:00Z | home | Kitchen | co | 7 | | 2022-01-01T17:00:00Z | home | Kitchen | co | 9 | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | co | 1 | | 2022-01-01T15:00:00Z | home | Living Room | co | 1 | | 2022-01-01T16:00:00Z | home | Living Room | co | 4 | | 2022-01-01T17:00:00Z | home | Living Room | co | 5 | | 2022-01-01T18:00:00Z | home | Living Room | co | 9 | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | | _time | _measurement | room | _field | _value | state | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | | 2022-01-01T14:00:00Z | home | Kitchen | co | 1 | ok | | 2022-01-01T15:00:00Z | home | Kitchen | co | 3 | ok | | 2022-01-01T16:00:00Z | home | Kitchen | co | 7 | ok | | 2022-01-01T17:00:00Z | home | Kitchen | co | 9 | ok | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | warning | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | warning | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | warning | | _time | _measurement | room | _field | _value | state | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | | 2022-01-01T14:00:00Z | home | Living Room | co | 1 | ok | | 2022-01-01T15:00:00Z | home | Living Room | co | 1 | ok | | 2022-01-01T16:00:00Z | home | Living Room | co | 4 | ok | | 2022-01-01T17:00:00Z | home | Living Room | co | 5 | ok | | 2022-01-01T18:00:00Z | home | Living Room | co | 9 | ok | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | warning | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | warning | | _time | _measurement | room | _field | _value | state | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | warning | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | warning | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | warning | | _time | _measurement | room | _field | _value | state | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | warning | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | warning | | _time | _measurement | room | _field | _value | state | sent | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | sent | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | warning | true | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | warning | true | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | warning | true | | _time | _measurement | room | _field | _value | state | sent | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | state | sent | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | warning | true | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | warning | true | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _measurement | room | _field | _value | | --- | --- | --- | --- | | _measurement | room | _field | _value | | home | Kitchen | temp | 22.814285714285713 | | _measurement | room | _field | _value | | --- | --- | --- | --- | | _measurement | room | _field | _value | | home | Living Room | temp | 22.44285714285714 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _value | | --- | | _value | | 22.628571428571426 | | room | _value | | --- | --- | | room | _value | | Kitchen | 21 | | room | _value | | --- | --- | | room | _value | | Living Room | 21 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T15:00:00Z | home | Kitchen | co | 3 | | 2022-01-01T16:00:00Z | home | Kitchen | co | 7 | | 2022-01-01T17:00:00Z | home | Kitchen | co | 9 | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | hum | 36.3 | | 2022-01-01T15:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T16:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T17:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T18:00:00Z | home | Kitchen | hum | 36.9 | | 2022-01-01T19:00:00Z | home | Kitchen | hum | 36.6 | | 2022-01-01T20:00:00Z | home | Kitchen | hum | 36.5 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | co | hum | temp | | --- | --- | --- | --- | --- | --- | | _time | _measurement | room | co | hum | temp | | 2022-01-01T14:00:00Z | home | Kitchen | 1 | 36.3 | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | 3 | 36.2 | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | 7 | 36 | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | 9 | 36 | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | 18 | 36.9 | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | 22 | 36.6 | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | 26 | 36.5 | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.75 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 22.549999999999997 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 23.200000000000003 | | 2022-01-01T20:00:01Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.65 | | 2022-01-01T20:00:01Z | home | Living Room | temp | 22.2 | --- # Get started querying data Source: https://docs.influxdata.com/influxdb/v2/get-started/query/ * 3 / 5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB supports many different tools for querying data, including: * InfluxDB user interface (UI) * [InfluxDB HTTP API](/influxdb/v2/reference/api/) * [`influx` CLI](/influxdb/v2/tools/influx-cli/) * [Chronograf](/chronograf/v1/) * [Grafana](/influxdb/v2/tools/grafana/) * [InfluxDB client libraries](/influxdb/v2/api-guide/client-libraries/) This tutorial walks you through the fundamentals of querying data in InfluxDB and focuses primarily on the two languages you can use to query your time series data: * **Flux**: A functional scripting language designed to query and process data from InfluxDB and other data sources. * **InfluxQL**: A SQL-like query language designed to query time series data from InfluxDB. > [!Note] > The examples in this section of the tutorial query the data from written in the[Get started writing data](/influxdb/v2/get-started/write/#write-line-protocol-to-influxdb) section. ###### On this page: * [Query data with Flux](#query-data-with-flux) * [Flux query basics](#flux-query-basics) * [Execute a Flux query](#execute-a-flux-query) * [Query data with InfluxQL](#query-data-with-influxql) * [InfluxQL query basics](#influxql-query-basics) * [Execute an InfluxQL query](#execute-an-influxql-query) ## Query data with Flux Flux is a functional scripting language that lets you query and process data from InfluxDB and [other data sources](/flux/v0/query-data/). > [!Note] > This is a brief introduction to writing Flux queries. > For a more in-depth introduction, see [Get started with Flux](/flux/v0/get-started/). ### Flux query basics When querying InfluxDB with Flux, there are three primary functions you use: * [from()](/flux/v0/stdlib/influxdata/influxdb/from/): Queries data from an InfluxDB bucket. * [range()](/flux/v0/stdlib/universe/range/): Filters data based on time bounds. Flux requires “bounded” queries—queries limited to a specific time range. * [filter()](/flux/v0/stdlib/universe/filter/): Filters data based on column values. Each row is represented by `r`and each column is represented by a property of `r`. You can apply multiple subsequent filters. To see how `from()` structures data into rows and tables when returned from InfluxDB,[view the data written in Get started writing to InfluxDB](/influxdb/v2/get-started/write/#view-the-written-data). [](#learn-more-about-how-filter-works) Learn more about how `filter()` works [`filter()`](/flux/v0/stdlib/universe/filter/) reads each row as a[record](/flux/v0/data-types/composite/record/) named `r`. In the `r` record, each key-value pair represents a column and its value. For example: ``` r = { _time: 2020-01-01T00:00:00Z, _measurement: "home", room: "Kitchen", _field: "temp", _value: 21.0, } ``` To filter rows, use [predicate expressions](/flux/v0/get-started/syntax-basics/#predicate-expressions)to evaluate the values of columns. Given the row record above: ``` (r) => r._measurement == "home" // Returns true (r) => r.room == "Kitchen" // Returns true (r) => r._field == "co" // Returns false (r) => r._field == "co" or r._field == "temp" // Returns true (r) => r._value <= 20.0 // Returns false ``` Rows that evaluate to `true` are included in the `filter()` output. Rows that evaluate to `false` are dropped from the `filter()` output. #### Pipe-forward operator Flux uses the pipe-forward operator (`|>`) to pipe the output of one function as input the next function as input. #### Query the example data The following Flux query returns the **co**, **hum**, and **temp** fields stored in the **home** measurement with timestamps **between 2022-01-01T08:00:00Z and 2022-01-01T20:00:01Z**. ```js from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp") ``` ### Execute a Flux query Use the **InfluxDB UI**, **`influx` CLI**, or **InfluxDB API** to execute Flux queries. [InfluxDB UI](#influxdb-ui)[influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) 1. Visit[localhost:8086](http://localhost:8086) in a browser to log in and access the InfluxDB UI. 2. In the left navigation bar, click **Data Explorer**. Data Explorer 1. The InfluxDB Data Explorer provides two options for querying data with Flux: * [Query Builder](#query-builder) *(default)*: Visual query builder that lets you select the time range, measurement, tags, and fields to query. * [Script Editor](#script-editor): In-browser code editor for composing and running Flux scripts. #### Query builder #### **To build and execute a Flux query with the query builder**: 1. In the **FROM** column, select the bucket to query. For this tutorial, select the **get-started** bucket. 2. In the next **filter** column, select **\_measurement** from the column dropdown menu, and then select the **home** measurement. 3. *(Optional)* To query a specific field or fields, in the next **filter**column, select **\_field** from the column dropdown menu, and then select the fields to query. In this tutorial, there are three fields: **co**, **hum**, and **temp**. 4. *(Optional)* To query by specific tag values, in the next **filter**column, select then tag column from the column dropdown menu, and then select the tag values to filter by. In this tutorial, the tag only tag column is **room**. 5. *(Optional)* In the **Aggregate Function** pane, select an aggregate or selector function to use to downsample the data. The default aggregate function is `mean`. 6. In the time range dropdown menu, select **Custom Time Range**, and select the following dates from the date selectors: * **Start**: 2022-01-01 08:00:00 * **Stop**: 2022-01-01 20:00:01 *Note the addition of one second to the stop time. In Flux, stop times are exclusive and will exclude points with that timestamp. By adding one second, the query will include all points to 2022-01-01 20:00:00*. 7. Click **Submit** to execute the query with the selected filters and operations and display the result. #### Script editor #### **To write and execute a Flux query with the query builder**: 1. In the Data Explorer, click **Script Editor**. 2. Write your Flux query in the Script Editor text field. ***Note**: You can either hand-write the functions or you can use the function list to the right of the script editor to search for and inject functions.* 1. Use `from()` and specify the bucket to query with the `bucket` parameter. For this tutorial, query the **get-started** bucket. 2. Use `range()` to specify the time range to query. The `start`parameter defines the earliest time to include in results. The `stop` parameter specifies the latest time (exclusively) to include in results. * **start**: 2022-01-01T08:00:00Z * **stop**: 2022-01-01T20:00:01Z *Note the addition of one second to the stop time. In Flux, stop times are exclusive and will exclude points with that timestamp. By adding one second, the query will include all points to 2022-01-01 20:00:00*. If you want to use the start and stop times selected in the time selection dropdown menu, use `v.timeRangeStart` and `v.timeRangeStop`as the values for the `start` and `stop` parameters. 3. Use `filter()` to filter results by the **home** measurement. 4. *(Optional)* Use `filter()` to filter results by a specific field. In this tutorial, there are three fields: **co**, **hum**, and **temp**. 5. *(Optional)* Use `filter()` to filter results by specific tag values. In this tutorial, there is one tag, **room**, with two potential values: **Living Room** or **Kitchen**. ``` from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp") ``` 3. Click **Submit** to execute the query with the selected filters and operations and display the result. 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Use the [`influx query` command](/influxdb/v2/reference/cli/influx/query/)to query InfluxDB using Flux. **Provide the following**: * String-encoded Flux query. * [Connection and authentication credentials](/influxdb/v2/get-started/setup/?t=influx+CLI#configure-authentication-credentials) ```sh influx query ' from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp") ' ``` To query data from InfluxDB using Flux and the InfluxDB HTTP API, send a request to the InfluxDB API [`/api/v2/query` endpoint](/influxdb/v2/api/query-data/)using the `POST` request method. ``` POST http://localhost:8086/api/v2/query ``` Include the following with your request: * **Headers**: * **Authorization**: Token \ * **Content-Type**: application/vnd.flux * **Accept**: application/csv * *(Optional)* **Accept-Encoding**: gzip * **Query parameters**: * **org**: InfluxDB organization name * **Request body**: Flux query as plain text The following example uses cURL and the InfluxDB API to query data with Flux: ```sh curl --request POST \ "$INFLUX_HOST/api/v2/query?org=$INFLUX_ORG&bucket=get-started" \ --header "Authorization: Token $INFLUX_TOKEN" \ --header "Content-Type: application/vnd.flux" \ --header "Accept: application/csv" \ --data 'from(bucket: "get-started") |> range(start: 2022-01-01T08:00:00Z, stop: 2022-01-01T20:00:01Z) |> filter(fn: (r) => r._measurement == "home") |> filter(fn: (r) => r._field== "co" or r._field == "hum" or r._field == "temp") ' ``` > [!Note] > The InfluxDB `/api/v2/query` endpoint returns query results in[annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/). ### Flux query results [](#view-flux-query-results) View Flux query results > [!Note] > `_start` and `_stop` columns have been omitted. > These columns, by default, represent the query time bounds and are added by `range()`. | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| co | 0 | |2022-01-01T09:00:00Z| home |Kitchen| co | 0 | |2022-01-01T10:00:00Z| home |Kitchen| co | 0 | |2022-01-01T11:00:00Z| home |Kitchen| co | 0 | |2022-01-01T12:00:00Z| home |Kitchen| co | 0 | |2022-01-01T13:00:00Z| home |Kitchen| co | 1 | |2022-01-01T14:00:00Z| home |Kitchen| co | 1 | |2022-01-01T15:00:00Z| home |Kitchen| co | 3 | |2022-01-01T16:00:00Z| home |Kitchen| co | 7 | |2022-01-01T17:00:00Z| home |Kitchen| co | 9 | |2022-01-01T18:00:00Z| home |Kitchen| co | 18 | |2022-01-01T19:00:00Z| home |Kitchen| co | 22 | |2022-01-01T20:00:00Z| home |Kitchen| co | 26 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| hum | 35.9 | |2022-01-01T09:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T10:00:00Z| home |Kitchen| hum | 36.1 | |2022-01-01T11:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T12:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T13:00:00Z| home |Kitchen| hum | 36.5 | |2022-01-01T14:00:00Z| home |Kitchen| hum | 36.3 | |2022-01-01T15:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T16:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T17:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T18:00:00Z| home |Kitchen| hum | 36.9 | |2022-01-01T19:00:00Z| home |Kitchen| hum | 36.6 | |2022-01-01T20:00:00Z| home |Kitchen| hum | 36.5 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| temp | 21 | |2022-01-01T09:00:00Z| home |Kitchen| temp | 23 | |2022-01-01T10:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T11:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T12:00:00Z| home |Kitchen| temp | 22.5 | |2022-01-01T13:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| co | 0 | |2022-01-01T09:00:00Z| home |Living Room| co | 0 | |2022-01-01T10:00:00Z| home |Living Room| co | 0 | |2022-01-01T11:00:00Z| home |Living Room| co | 0 | |2022-01-01T12:00:00Z| home |Living Room| co | 0 | |2022-01-01T13:00:00Z| home |Living Room| co | 0 | |2022-01-01T14:00:00Z| home |Living Room| co | 0 | |2022-01-01T15:00:00Z| home |Living Room| co | 1 | |2022-01-01T16:00:00Z| home |Living Room| co | 4 | |2022-01-01T17:00:00Z| home |Living Room| co | 5 | |2022-01-01T18:00:00Z| home |Living Room| co | 9 | |2022-01-01T19:00:00Z| home |Living Room| co | 14 | |2022-01-01T20:00:00Z| home |Living Room| co | 17 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | |2022-01-01T11:00:00Z| home |Living Room| hum | 36 | |2022-01-01T12:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T13:00:00Z| home |Living Room| hum | 36 | |2022-01-01T14:00:00Z| home |Living Room| hum | 36.1 | |2022-01-01T15:00:00Z| home |Living Room| hum | 36.1 | |2022-01-01T16:00:00Z| home |Living Room| hum | 36 | |2022-01-01T17:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T18:00:00Z| home |Living Room| hum | 36.2 | |2022-01-01T19:00:00Z| home |Living Room| hum | 36.3 | |2022-01-01T20:00:00Z| home |Living Room| hum | 36.4 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | |2022-01-01T11:00:00Z| home |Living Room| temp | 22.2 | |2022-01-01T12:00:00Z| home |Living Room| temp | 22.2 | |2022-01-01T13:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | ## Query data with InfluxQL InfluxQL is a SQL-like query language similar to most SQL languages, but specifically designed to query time series data from InfluxDB 0.x and 1.x. > [!Note] > #### Map databases and retention policies to buckets > > Because InfluxQL was developed for earlier versions of InfluxDB, it depends on**databases and retention policies** (DBRP) which have been replaced by[buckets](/influxdb/v2/get-started/#data-organization) in InfluxDB 2.10. > To use InfluxQL with InfluxDB 2.10, first[map database and retention policy (DBRP) combinations to an InfluxDB bucket](/influxdb/v2/query-data/influxql/dbrp/). ### InfluxQL query basics When querying InfluxDB with InfluxQL, the most basic query includes the following statements and clauses: * `SELECT`: Specify which fields and tags to query. * `FROM`: Specify the measurement to query. Use the measurement name or a fully-qualified measurement name which includes the database and retention policy. For example: `db.rp.measurement`. * `WHERE`: *(Optional)* Filter data based on fields, tags, and time. The following InfluxQL query returns the **co**, **hum**, and **temp** fields and the **room** tag stored in the **home** measurement with timestamps**between 2022-01-01T08:00:00Z and 2022-01-01T20:00:00Z**. ```sql SELECT co,hum,temp,room FROM "get-started".autogen.home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` > [!Note] > These are just the fundamentals of the InfluxQL syntax. > For more in-depth information, see the [InfluxQL documentation](/influxdb/v2/query-data/influxql/). ### Execute an InfluxQL query Use the **`influx` CLI**, or **InfluxDB API** to execute InfluxQL queries. [InfluxDB UI](#influxdb-ui-2)[influx CLI](#influx-cli-2)[InfluxDB API](#influxdb-api-2) > [!Note] > #### The influxdb UI does not support InfluxQL > > The InfluxDB 2.10 UI does not provide a way to query data with InfluxQL. > For a user interface that builds and executes InfluxQL queries, consider using[Chronograf](/influxdb/v2/tools/chronograf/) or[Grafana](/influxdb/v2/tools/grafana/) with InfluxDB 2.10. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Use the [`influx v1 shell` command](/influxdb/v2/reference/cli/influx/v1/shell/)to start an InfluxQL shell and query InfluxDB using InfluxQL. Provide the following: * [Connection and authentication credentials](/influxdb/v2/get-started/setup/?t=influx+CLI#configure-authentication-credentials) ``` influx v1 shell ``` 3. Enter an InfluxQL query and press `Enter ↵`. ``` SELECT co,hum,temp,room FROM "get-started".autogen.home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` To query data from InfluxDB using InfluxQL and the InfluxDB HTTP API, send a request to the InfluxDB API [`/query` 1.X compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/query/)using the `POST` request method. ``` POST http://localhost:8086/query ``` Include the following with your request: * **Headers**: * **Authorization**: Token \ * **Accept**: application/json * *(Optional)* **Accept-Encoding**: gzip * **Query parameters**: * **db**: Database to query. * **rp**: Retention policy to query data from. * **q**: InfluxQL query to execute. * **epoch**: *(Optional)* Return results with[Unix timestamps](/influxdb/v2/reference/glossary/#unix-timestamp) of a specified precision instead of [RFC3339 timestamps](/influxdb/v2/reference/glossary/#rfc3339-timestamp). The following precisions are available: * `ns` - nanoseconds * `u` or `µ` - microseconds * `ms` - milliseconds * `s` - seconds * `m` - minutes * `h` - hours * **Request body**: Flux query as plain text The following example uses cURL and the InfluxDB API to query data with InfluxQL: ```sh curl --get "$INFLUX_HOST/query?org=$INFLUX_ORG&bucket=get-started" \ --header "Authorization: Token $INFLUX_TOKEN" \ --data-urlencode "db=get-started" \ --data-urlencode "rp=autogen" \ --data-urlencode "q=SELECT co,hum,temp,room FROM home WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z'" ``` > [!Note] > The InfluxDB `/write` 1.x compatibility endpoint returns query results in JSON format. ### InfluxQL query results [](#view-influxql-query-results) View InfluxQL query results | time | room |co |hum |temp| |--------------------|-----------|---|----|----| |2022-01-01T08:00:00Z| Kitchen | 0 |35.9| 21 | |2022-01-01T08:00:00Z|Living Room| 0 |35.9|21.1| |2022-01-01T09:00:00Z| Kitchen | 0 |36.2| 23 | |2022-01-01T09:00:00Z|Living Room| 0 |35.9|21.4| |2022-01-01T10:00:00Z| Kitchen | 0 |36.1|22.7| |2022-01-01T10:00:00Z|Living Room| 0 | 36 |21.8| |2022-01-01T11:00:00Z| Kitchen | 0 | 36 |22.4| |2022-01-01T11:00:00Z|Living Room| 0 | 36 |22.2| |2022-01-01T12:00:00Z| Kitchen | 0 | 36 |22.5| |2022-01-01T12:00:00Z|Living Room| 0 |35.9|22.2| |2022-01-01T13:00:00Z| Kitchen | 1 |36.5|22.8| |2022-01-01T13:00:00Z|Living Room| 0 | 36 |22.4| |2022-01-01T14:00:00Z| Kitchen | 1 |36.3|22.8| |2022-01-01T14:00:00Z|Living Room| 0 |36.1|22.3| |2022-01-01T15:00:00Z| Kitchen | 3 |36.2|22.7| |2022-01-01T15:00:00Z|Living Room| 1 |36.1|22.3| |2022-01-01T16:00:00Z| Kitchen | 7 | 36 |22.4| |2022-01-01T16:00:00Z|Living Room| 4 | 36 |22.4| |2022-01-01T17:00:00Z| Kitchen | 9 | 36 |22.7| |2022-01-01T17:00:00Z|Living Room| 5 |35.9|22.6| |2022-01-01T18:00:00Z| Kitchen |18 |36.9|23.3| |2022-01-01T18:00:00Z|Living Room| 9 |36.2|22.8| |2022-01-01T19:00:00Z| Kitchen |22 |36.6|23.1| |2022-01-01T19:00:00Z|Living Room|14 |36.3|22.5| |2022-01-01T20:00:00Z| Kitchen |26 |36.5|22.7| |2022-01-01T20:00:00Z|Living Room|17 |36.4|22.2| **Congratulations!** You’ve learned the basics of querying data in InfluxDB. For a deep dive into all the ways you can query InfluxDB, see the[Query data in InfluxDB](/influxdb/v2/query-data/) section of documentation. Let’s move on to more advanced data processing queries and automating queries with InfluxDB tasks. [Write data](/influxdb/v2/get-started/write/)[Process data](/influxdb/v2/get-started/process/) #### Related * [Query data in InfluxDB](/influxdb/v2/query-data/) | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T09:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T10:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T11:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T12:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T13:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T14:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T15:00:00Z | home | Kitchen | co | 3 | | 2022-01-01T16:00:00Z | home | Kitchen | co | 7 | | 2022-01-01T17:00:00Z | home | Kitchen | co | 9 | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | 2022-01-01T11:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T12:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T13:00:00Z | home | Kitchen | hum | 36.5 | | 2022-01-01T14:00:00Z | home | Kitchen | hum | 36.3 | | 2022-01-01T15:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T16:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T17:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T18:00:00Z | home | Kitchen | hum | 36.9 | | 2022-01-01T19:00:00Z | home | Kitchen | hum | 36.6 | | 2022-01-01T20:00:00Z | home | Kitchen | hum | 36.5 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T11:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T12:00:00Z | home | Kitchen | temp | 22.5 | | 2022-01-01T13:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | co | 0 | | 2022-01-01T09:00:00Z | home | Living Room | co | 0 | | 2022-01-01T10:00:00Z | home | Living Room | co | 0 | | 2022-01-01T11:00:00Z | home | Living Room | co | 0 | | 2022-01-01T12:00:00Z | home | Living Room | co | 0 | | 2022-01-01T13:00:00Z | home | Living Room | co | 0 | | 2022-01-01T14:00:00Z | home | Living Room | co | 0 | | 2022-01-01T15:00:00Z | home | Living Room | co | 1 | | 2022-01-01T16:00:00Z | home | Living Room | co | 4 | | 2022-01-01T17:00:00Z | home | Living Room | co | 5 | | 2022-01-01T18:00:00Z | home | Living Room | co | 9 | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T11:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T12:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T13:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T14:00:00Z | home | Living Room | hum | 36.1 | | 2022-01-01T15:00:00Z | home | Living Room | hum | 36.1 | | 2022-01-01T16:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T17:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T18:00:00Z | home | Living Room | hum | 36.2 | | 2022-01-01T19:00:00Z | home | Living Room | hum | 36.3 | | 2022-01-01T20:00:00Z | home | Living Room | hum | 36.4 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | 2022-01-01T11:00:00Z | home | Living Room | temp | 22.2 | | 2022-01-01T12:00:00Z | home | Living Room | temp | 22.2 | | 2022-01-01T13:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | | time | room | co | hum | temp | | --- | --- | --- | --- | --- | | time | room | co | hum | temp | | 2022-01-01T08:00:00Z | Kitchen | 0 | 35.9 | 21 | | 2022-01-01T08:00:00Z | Living Room | 0 | 35.9 | 21.1 | | 2022-01-01T09:00:00Z | Kitchen | 0 | 36.2 | 23 | | 2022-01-01T09:00:00Z | Living Room | 0 | 35.9 | 21.4 | | 2022-01-01T10:00:00Z | Kitchen | 0 | 36.1 | 22.7 | | 2022-01-01T10:00:00Z | Living Room | 0 | 36 | 21.8 | | 2022-01-01T11:00:00Z | Kitchen | 0 | 36 | 22.4 | | 2022-01-01T11:00:00Z | Living Room | 0 | 36 | 22.2 | | 2022-01-01T12:00:00Z | Kitchen | 0 | 36 | 22.5 | | 2022-01-01T12:00:00Z | Living Room | 0 | 35.9 | 22.2 | | 2022-01-01T13:00:00Z | Kitchen | 1 | 36.5 | 22.8 | | 2022-01-01T13:00:00Z | Living Room | 0 | 36 | 22.4 | | 2022-01-01T14:00:00Z | Kitchen | 1 | 36.3 | 22.8 | | 2022-01-01T14:00:00Z | Living Room | 0 | 36.1 | 22.3 | | 2022-01-01T15:00:00Z | Kitchen | 3 | 36.2 | 22.7 | | 2022-01-01T15:00:00Z | Living Room | 1 | 36.1 | 22.3 | | 2022-01-01T16:00:00Z | Kitchen | 7 | 36 | 22.4 | | 2022-01-01T16:00:00Z | Living Room | 4 | 36 | 22.4 | | 2022-01-01T17:00:00Z | Kitchen | 9 | 36 | 22.7 | | 2022-01-01T17:00:00Z | Living Room | 5 | 35.9 | 22.6 | | 2022-01-01T18:00:00Z | Kitchen | 18 | 36.9 | 23.3 | | 2022-01-01T18:00:00Z | Living Room | 9 | 36.2 | 22.8 | | 2022-01-01T19:00:00Z | Kitchen | 22 | 36.6 | 23.1 | | 2022-01-01T19:00:00Z | Living Room | 14 | 36.3 | 22.5 | | 2022-01-01T20:00:00Z | Kitchen | 26 | 36.5 | 22.7 | | 2022-01-01T20:00:00Z | Living Room | 17 | 36.4 | 22.2 | --- # Set up InfluxDB Source: https://docs.influxdata.com/influxdb/v2/get-started/setup/ * 1 / 5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). As you get started with this tutorial, do the following to make sure everything you need is in place. * [Run the initial setup process](#run-initial-setup-process) * [Create an All Access API token](#create-an-all-access-api-token) * [Configure authentication credentials](#configure-authentication-credentials) * [Create a bucket](#create-a-bucket) 1. **Run the initial setup process**. After you [install and start InfluxDB](/influxdb/v2/install/), run the initial setup process to create the following: * An [organization](/influxdb/v2/admin/organizations/) with the name you provide. * A [bucket](/influxdb/v2/admin/buckets/) with the name you provide. * An admin [authorization](/influxdb/v2/admin/tokens/) with the following properties: * The username and password that you provide. * An API [Operator token](/influxdb/v2/admin/tokens/#operator-token). * Read-write permissions for all resources in the InfluxDB instance. You can use the InfluxDB UI, the `influx` CLI, or the HTTP API to run the setup process. * To run an interactive setup that prompts you for the required information, use the InfluxDB user interface (UI) or the `influx` command line interface (CLI). * To automate the setup–for example, with a script that you write– use the `influx` command line interface (CLI) or the `/api/v2/setup` InfluxDB API endpoint. #### Automated setup with Docker #### If you installed InfluxDB using [Docker with initial setup options](/influxdb/v2/install/?t=docker/#install-and-setup-influxdb-in-a-container), then you’ve already completed the setup process. [Set up with the UI](#set-up-with-the-ui)[Set up with the CLI](#set-up-with-the-cli)[Set up with the API](#set-up-with-the-api) 1. With InfluxDB running, visit [http://localhost:8086](http://localhost:8086). 2. Click **Get Started** #### Set up your initial user #### 1. Enter a **Username** for your initial user. 2. Enter a **Password** and **Confirm Password** for your user. 3. Enter your initial **Organization Name**. 4. Enter your initial **Bucket Name**. 5. Click **Continue**. 6. Copy the provided **operator API token** and store it for safe keeping. We recommend using a password manager or a secret store to securely store sensitive tokens. Your InfluxDB instance is now initialized. 1. Download and install the `influx` CLI, which provides a simple way to interact with InfluxDB from a command line. For detailed installation and setup instructions, see [Use the influx CLI](/influxdb/v2/tools/influx-cli/). 2. Use the `influx setup` CLI command to initialize your InfluxDB instance–choose one of the following: * **Set up with prompts**. To setup interactively, enter the following command: ``` influx setup ``` The command walks you through the initial setup process by prompting for a username, password, organization, bucket, and retention period. * **Set up non-interactively**. To run setup non-interactively (for example, in your automation scripts), pass [command line flags](/influxdb/v2/reference/cli/influx/setup/#flags) for the initialization values, and pass the `-f, --force` flag to bypass the final confirmation prompt–for example, enter the following command: ``` influx setup \ --username USERNAME \ --password PASSWORD \ --token TOKEN \ --org ORG_NAME \ --bucket BUCKET_NAME \ --force ``` Replace the following: * `USERNAME`: A name for your initial admin [user](/influxdb/v2/admin/users/) * `PASSWORD`: A password for your initial admin [user](/influxdb/v2/admin/users/) * `TOKEN`: A string value to set for the [*operator* token](/influxdb/v2/admin/tokens/#operator-token). If you don’t include this flag, InfluxDB generates a token for you and stores it in an[`influx` CLI connection configuration](/influxdb/v2/tools/influx-cli/#provide-required-authentication-credentials). * `ORG_NAME`: A name for your initial [organization](/influxdb/v2/admin/organizations/) * `BUCKET_NAME`: A name for your initial [bucket](/influxdb/v2/admin/buckets/) InfluxDB is initialized with an[Operator token](/influxdb/v2/admin/tokens/#operator-token),[user](/influxdb/v2/reference/glossary/#user),[organization](/influxdb/v2/reference/glossary/#organization), and [bucket](/influxdb/v2/reference/glossary/#bucket). The output is similar to the following: ``` User Organization Bucket USERNAME ORGANIZATION_NAME BUCKET_NAME ``` InfluxDB stores these values in a `default` connection configuration that provides your InfluxDB URL, organization, and API token to `influx` CLI commands. For information about connection configurations, see [`influx config`](/influxdb/v2/reference/cli/influx/config/). Send a request to the following HTTP API endpoint: ``` POST http://localhost:8086/api/v2/setup ``` The `POST /api/v2/setup` API endpoint doesn’t require authentication In the request body, specify values for the initial username, password, organization, bucket, and an optional Operator token–for example: ``` curl http://localhost:8090/api/v2/setup \ --data '{ "username": "USERNAME", "password": "PASSWORD", "token": "TOKEN", "bucket": "BUCKET_NAME", "org": "ORG_NAME" }' ``` Replace the following: * `USERNAME`: A name for your initial admin [user](/influxdb/v2/admin/users/) * `PASSWORD`: A password for your initial admin [user](/influxdb/v2/admin/users/) * `ORG_NAME`: A name for your initial [organization](/influxdb/v2/admin/organizations/) * `BUCKET_NAME`: A name for your initial [bucket](/influxdb/v2/admin/buckets/) * `TOKEN`: A string value to set for the [*operator* token](/influxdb/v2/admin/tokens/#operator-token). If you don’t include this flag, InfluxDB generates a token for you. The response body contains the created resources, including the [Operator token](/influxdb/v2/admin/tokens/#operator-token) and its list of permissions. We recommend using a password manager or a secret store to securely store sensitive tokens. For more options and details, see the [`POST /api/v2/setup` API endpoint documentation](/influxdb/v2/api/setup/). 2. Recommended: **Create an All Access API token.** During the [InfluxDB initial set up process](/influxdb/v2/install/#set-up-influxdb), you created an admin user and [Operator token](/influxdb/v2/admin/tokens/#operator-token)that have permissions to manage everything in your InfluxDB instance. While you can use your Operator token to interact with InfluxDB, we recommend creating an [All Access token](/influxdb/v2/admin/tokens/#all-access-token) that is scoped to an organization, and then using this token to manage InfluxDB. Use the **InfluxDB UI**, **`influx` CLI**, or **InfluxDB API** to create an All Access token. [InfluxDB UI](#influxdb-ui)[influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) 1. Visit[localhost:8086](http://localhost:8086) in a browser to log in and access the InfluxDB UI. 2. Navigate to **Load Data** \> **API Tokens** using the left navigation bar. 3. Click **+ Generate API token** and select**All Access API Token**. 4. Enter a description for the API token and click **✓ Save**. 5. Copy the generated token and store it for safe keeping. 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Use the [`influx auth create` command](/influxdb/v2/reference/cli/influx/auth/create/)to create an All Access token. Provide the following: * `--all-access` flag * `--host` flag with your [InfluxDB host URL](/influxdb/v2/reference/urls/) * `-o, --org` or `--org-id` flags with your InfluxDB organization name or[ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * `-t, --token` flag with your Operator token ``` influx auth create \ --all-access \ --host http://localhost:8086 \ --org \ --token ``` 3. Copy the generated token and store it for safe keeping. Send a request to the InfluxDB API `/api/v2/authorizations` endpoint using the `POST` request method. ``` POST http://localhost:8086/api/v2/authorizations ``` Include the following with your request: * **Headers**: * **Authorization**: Token \ * **Content-Type**: application/json * **Request body**: JSON body with the following properties: * **status**: `"active"` * **description**: API token description * **orgID**: [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **permissions**: Array of objects where each object represents permissions for an InfluxDB resource type or a specific resource. Each permission contains the following properties: * **action**: “read” or “write” * **resource**: JSON object that represents the InfluxDB resource to grant permission to. Each resource contains at least the following properties: * **orgID**: [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **type**: Resource type.*For information about what InfluxDB resource types exist, use the[`/api/v2/resources` endpoint](/influxdb/v2/api/resources/).* The following example uses cURL and the InfluxDB API to generate an All Access token: ``` export INFLUX_HOST=http://localhost:8086 export INFLUX_ORG_ID= export INFLUX_TOKEN= curl --request POST \ "$INFLUX_HOST/api/v2/authorizations" \ --header "Authorization: Token $INFLUX_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --data '{ "status": "active", "description": "All access token for get started tutorial", "orgID": "'"$INFLUX_ORG_ID"'", "permissions": [ {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "authorizations"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "authorizations"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "buckets"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "buckets"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dashboards"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dashboards"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "orgs"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "orgs"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "sources"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "sources"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "tasks"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "tasks"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "telegrafs"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "telegrafs"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "users"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "users"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "variables"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "variables"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "scrapers"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "scrapers"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "secrets"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "secrets"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "labels"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "labels"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "views"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "views"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "documents"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "documents"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationRules"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationRules"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationEndpoints"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notificationEndpoints"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "checks"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "checks"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dbrp"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "dbrp"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notebooks"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "notebooks"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "annotations"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "annotations"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "remotes"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "remotes"}}, {"action": "read", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "replications"}}, {"action": "write", "resource": {"orgID": "'"$INFLUX_ORG_ID"'", "type": "replications"}} ] } ' ``` [](#) The response body contains a JSON object with the following properties: * **id**: API Token ID * **token**: API Token (Important) * **status**: Token status * **description**: Token description * **orgID**: InfluxDB organization ID the token is associated with * **org**: InfluxDB organization name the token is associated with * **userID**: User ID the token is associated with * **user**: Username the token is associated with * **permissions**: List of permissions for organization resources **Copy the generated `token` and store it for safe keeping.** We recommend using a password manager or a secret store to securely store sensitive tokens. 3. **Configure authentication credentials**. As you go through this tutorial, interactions with InfluxDB 2.10require your InfluxDB **host**, **organization name or ID**, and your **API token**. How you provide credentials depends on which client you use to interact with InfluxDB. When configuring your token, if you [created an All Access token](#create-an-all-access-api-token), use that token to interact with InfluxDB. Otherwise, use the Operator token that you created during the setup process. [InfluxDB UI](#influxdb-ui-2)[influx CLI](#influx-cli-2)[InfluxDB API](#influxdb-api-2) When managing InfluxDB through the InfluxDB UI, authentication credentials are provided automatically using credentials associated with the user you log in with. There are three ways to provided authentication credentials to the `influx` CLI: [](#cli-connection-configurations-recommended) CLI connection configurations *(Recommended)* The `influx` CLI lets you specify connection configuration presets that let you store and quickly switch between multiple sets of InfluxDB connection credentials. A connection configuration stores your credentials to avoid having to pass your InfluxDB API token with each `influx` command. If you [set up InfluxDB](#set-up-influxdb) using the CLI, it creates a default[connection configuration](/influxdb/v2/reference/cli/influx/config/) for you. Use the [`influx config create` command](/influxdb/v2/reference/cli/influx/config/create/)to manually create a new CLI connection configuration for the All Access token you created in the preceding step. Include the following flags: ``` influx config create \ --config-name get-started \ --host-url http://localhost:8086 \ --org ORG_NAME \ --token API_TOKEN ``` Replace the following: * `get-started`: Connection configuration name. Examples in this tutorial use `get-started`. * `http://localhost:8086`: [InfluxDB host URL](/influxdb/v2/reference/urls/). * `ORG`: [your organization name](/influxdb/v2/admin/organizations/view-orgs/). * `API_TOKEN`: [your API token](/influxdb/v2/admin/tokens/view-tokens/). *For more information about `influx` CLI connection configurations, see[Install and use the `influx` CLI](/influxdb/v2/tools/influx-cli/#set-up-the-influx-cli).* [](#environment-variables) Environment variables The `influx` CLI checks for specific environment variables and, if present, uses those environment variables to populate authentication credentials. Set the following environment variables in your command line session: * `INFLUX_HOST`: [InfluxDB host URL](/influxdb/v2/reference/urls/). * `INFLUX_ORG`: InfluxDB organization name. * `INFLUX_ORG_ID`: InfluxDB [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id). * `INFLUX_TOKEN`: InfluxDB API token. ``` export INFLUX_HOST=localhost:8086 export INFLUX_ORG= export INFLUX_ORG_ID= export INFLUX_TOKEN= ``` Replace the following: * ``: The name of your [organization](/influxdb/v2/admin/organizations/) * ``: Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * ``: Your [All Access token](#create-an-all-access-api-token) or operator [token](/influxdb/v2/admin/tokens/) [](#command-line-flags) Command line flags Use the following `influx` CLI flags to provide required credentials to commands: * `--host`: [InfluxDB host URL](/influxdb/v2/reference/urls/). * `-o`, `--org` or `--org-id`: InfluxDB organization name or[ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id). * `-t`, `--token`: InfluxDB API token. > [!Note] > All `influx` CLI examples in this getting started tutorial assume your InfluxDB**host**, **organization**, and **token** are provided by either the[active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials)or by environment variables. When using the InfluxDB API, provide the required connection credentials in the following ways: * **InfluxDB host**: The domain and port to send HTTP(S) requests to. * **InfluxDB API Token**: Include an `Authorization` header that uses either the`Bearer` or `Token` scheme and your InfluxDB [API token](/influxdb/v2/admin/tokens/)–for example: ``` Authorization: Bearer 0xxx0o0XxXxx00Xxxx000xXXxoo0== ``` * **InfluxDB organization name or ID**: Depending on the API endpoint used, pass this as part of the URL path, query string, or in the request body. All API examples in this tutorial use **cURL** from a command line. To provide all the necessary credentials to the example cURL commands, set the following environment variables in your command line session. ``` export INFLUX_HOST=http://localhost:8086 export INFLUX_ORG= export INFLUX_ORG_ID= export INFLUX_TOKEN= ``` Replace the following: * ``: The name of your [organization](/influxdb/v2/admin/organizations/) * ``: Your [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * ``: Your [All Access token](#create-an-all-access-api-token) or Operator token 4. Optional: **Create a bucket**. In the [initial setup process](#run-initial-setup-process), you created a bucket. You can use that bucket or create one specifically for this getting started tutorial. All examples in this tutorial assume a bucket named*get-started*. Use the **InfluxDB UI**, **`influx` CLI**, or **InfluxDB API** to create a new bucket. [InfluxDB UI](#influxdb-ui-3)[influx CLI](#influx-cli-3)[InfluxDB API](#influxdb-api-3) 1. Visit[localhost:8086](http://localhost:8086) in a browser to log in and access the InfluxDB UI. 2. Navigate to **Load Data** \> **Buckets** using the left navigation bar. 3. Click **+ Create bucket**. 4. Provide a bucket name (get-started) and select Neverto create a bucket with an infinite [retention period](/influxdb/v2/reference/glossary/#retention-period). 5. Click **Create**. 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Use the [`influx bucket create` command](/influxdb/v2/reference/cli/influx/bucket/create/) to create a bucket. **Provide the following**: * `-n, --name` flag with the bucket name. * [Connection and authentication credentials](#configure-authentication-credentials) ``` influx bucket create --name get-started ``` To create a bucket using the InfluxDB HTTP API, send a request to the InfluxDB API `/api/v2/buckets` endpoint using the `POST` request method. ``` POST http://localhost:8086/api/v2/buckets ``` Include the following with your request: * **Headers**: * **Authorization**: Token `INFLUX_TOKEN` * **Content-Type**: `application/json` * **Request body**: JSON object with the following properties: * **org**: InfluxDB organization name * **name**: Bucket name * **retentionRules**: List of retention rule objects that define the bucket’s retention period. Each retention rule object has the following properties: * **type**: `"expire"` * **everySeconds**: Retention period duration in seconds.`0` indicates the retention period is infinite. The following example shows how to use cURL and the InfluxDB API to create a bucket: ``` export INFLUX_HOST=http://localhost:8086 export INFLUX_ORG_ID= export INFLUX_TOKEN= curl --request POST \ "$INFLUX_HOST/api/v2/buckets" \ --header "Authorization: Token $INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "orgID": "'"$INFLUX_ORG_ID"'", "name": "get-started", "retentionRules": [ { "type": "expire", "everySeconds": 0 } ] }' ``` [Get started](/influxdb/v2/get-started/)[Write data](/influxdb/v2/get-started/write/) #### Related * [Install InfluxDB OSS v2](/influxdb/v2/install/) * [InfluxDB configuration options](/influxdb/v2/reference/config-options/) * [Manage API tokens](/influxdb/v2/admin/tokens/) * [Manage buckets](/influxdb/v2/admin/buckets/) * [Install and use the influx CLI](/influxdb/v2/tools/influx-cli/) --- # Get started visualizing data Source: https://docs.influxdata.com/influxdb/v2/get-started/visualize/ * 5 / 5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). There are many tools you can use to visualize your time series data including the InfluxDB user interface (UI), [Chronograf](/influxdb/v2/tools/chronograf/), and[Grafana](/influxdb/v2/tools/grafana/). This tutorial walks you through using the **InfluxDB UI** to create a simple dashboard. Dashboards are a powerful way of displaying time series data and can help to identify trends and anomalies. A dashboard is comprised of one or more dashboard cells. A **dashboard cell** visualizes the results of a query using one of the available [visualization types](/influxdb/v2/visualize-data/visualization-types/). * [Create a dashboard](#create-a-dashboard) * [Create dashboard cells](#create-dashboard-cells) * [Create and use dashboard variables](#create-and-use-dashboard-variables) * [Create a custom dashboard variable](#create-a-custom-dashboard-variable) * [Use a custom dashboard variable](#use-a-custom-dashboard-variable) ## Create a dashboard 1. With InfluxDB running, visit [localhost:8086](http://localhost:8086) in your browser to access the InfluxDB UI. 2. Log in and select **Dashboards** in the left navigation bar. Dashboards 3. Click **+ Create Dashboard** and select **New Dashboard**. 4. Click ***Name this Dashboard*** and provide a name for the dashboard. For this tutorial, we’ll use **“Getting Started Dashboard”**. ## Create dashboard cells With your new dashboard created and named, add a new dashboard cell: 1. Click **Add Cell**. 2. Click ***Name this Cell*** and provide a name for the cell. For this tutorial, we’ll use **“Room temperature”**. 3. *(Optional)* Select the visualization type from the visualization drop-down menu. There are many different [visualization types](/influxdb/v2/visualize-data/visualization-types/)available. For this tutorial, use the default **Graph** visualization. 4. Use the query time range selector to select an absolute time range that covers includes the time range of the[data written in “Get started writing to InfluxDB”](/influxdb/v2/get-started/write/#view-the-written-data):**2022-01-01T08:00:00Z** to **2022-01-01T20:00:01Z**. 1. The query time range selector defaults to querying data from the last hour ( **Past 1h**). Click the time range selector drop-down menu and select **Custom Time Range**. [](#view-time-range-selector) View time range selector InfluxDB time range selector 2. Use the date picker to select the stop and stop date and time or manually enter the following start and stop times: * **Start**: 2022-01-01 08:00:00 * **Stop**: 2022-01-01 20:00:01 3. Click **Apply Time Range**. 5. Use the **Query Builder** to select the measurement, fields, and tags to query: 1. In the **From** column, select the **get-started** bucket. 2. In the **Filter** column, select the **home** measurement. 3. In the next **Filter** column, select the **temp** field. 4. In the next **Filter** column, select the **room** tag and the **Kitchen** tag value. 6. Click **Submit** to run the query and visualize the results. InfluxDB Query Builder 7. Click **✓** to save the cell and return to the dashboard. ## Create and use dashboard variables InfluxDB dashboard cells use **dashboard variables** to dynamically change specific parts of cell queries. The query builder automatically builds queries using the following[predefined dashboard variables](/influxdb/v2/visualize-data/variables/#predefined-dashboard-variables), each controlled by selections in your dashboard: * `v.timeRangeStart`: Start time of the queried time range specified by the time range selector. * `v.timeRangeStop`: Stop time of the queried time range specified by the time range selector. * `v.windowPeriod`: Window period used downsample data to one point per pixel in a cell visualization. The value of this variable is determined by the pixel-width of the cell. ### Create a custom dashboard variable Let’s create a custom dashboard variable that we can use to change the field displayed by your dashboard cell. 1. Select **Settings \> Variables** in the left navigation bar. Settings 2. Click **+ Create Variable** and select **New Variable**. 3. Name your variable. For this tutorial, name the variable, **“room”**. 4. Select the default **Query** dashboard variable type. This variable type uses the results of a query to populate the list of potential variable values. *For information about the other dashboard variable types, see [Variable types](/influxdb/v2/visualize-data/variables/variable-types/).* 5. Enter the following Flux query to return all the different `room` tag values in your `get-started` bucket from the [Unix epoch](/influxdb/v2/reference/glossary/#unix-timestamp). ``` import "influxdata/influxdb/schema" schema.tagValues(bucket: "get-started", tag: "room", start: time(v: 0)) ``` 6. Click **Create Variable**. ### Use a custom dashboard variable 1. Navigate to your **Getting Started Dashboard** by clicking **Dashboards** in the left navigation bar and the clicking on the name of your dashboard. Dashboards 2. Click the on the **Room temperature** cell and select **Configure**. 3. Click **Script Editor** to edit the Flux query directly. 4. On line 5 of the Flux query, replace `"Kitchen"` with `v.room` to use the selected value of the `room` dashboard variable. ``` from(bucket: "get-started") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r["_measurement"] == "home") |> filter(fn: (r) => r["_field"] == "temp") |> filter(fn: (r) => r["room"] == v.room) |> aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false) |> yield(name: "mean") ``` 5. Click **✓** to save the cell and return to the dashboard. 6. Refresh the browser to reload the dashboard. 7. Use the **room variable** drop-down menu to select the room to display recorded temperatures from. InfluxDB dashboard variable selection *For more information about creating custom dashboard variables, see[Use and manage dashboard variables](/influxdb/v2/visualize-data/variables/).* [Process data](/influxdb/v2/get-started/process/) ## Congratulations! You have walked through the[basics of setting up, writing, querying, processing, and visualizing](/influxdb/v2/get-started/)data with InfluxDB 2.10. Feel free to dive in deeper to each of these topics: * [Write data to InfluxDB](/influxdb/v2/write-data/) * [Query data in InfluxDB](/influxdb/v2/query-data/) * [Process data with InfluxDB](/influxdb/v2/process-data/) * [Visualize data with the InfluxDB UI](/influxdb/v2/visualize-data/) #### Related * [Visualize data with the InfluxDB UI](/influxdb/v2/visualize-data/) * [Visualization types](/influxdb/v2/visualize-data/visualization-types/) * [Use Chronograf with InfluxDB OSS](/influxdb/v2/tools/chronograf/) * [Use Grafana with InfluxDB OSS](/influxdb/v2/tools/grafana/) --- # Get started writing data Source: https://docs.influxdata.com/influxdb/v2/get-started/write/ * 2 / 5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB provides many different options for ingesting or writing data, including the following: * Influx user interface (UI) * [InfluxDB HTTP API](/influxdb/v2/reference/api/) * [`influx` CLI](/influxdb/v2/tools/influx-cli/) * [Telegraf](/telegraf/v1/) * [InfluxDB client libraries](/influxdb/v2/api-guide/client-libraries/) This tutorial walks you through the fundamental of using **line protocol** to write data to InfluxDB. If using tools like Telegraf or InfluxDB client libraries, they will build the line protocol for you, but it’s good to understand how line protocol works. ## Line protocol All data written to InfluxDB is written using **line protocol**, a text-based format that lets you provide the necessary information to write a data point to InfluxDB.*This tutorial covers the basics of line protocol, but for detailed information, see the [Line protocol reference](/influxdb/v2/reference/syntax/line-protocol/).* ### Line protocol elements Each line of line protocol contains the following elements: \* Required * \* **measurement**: String that identifies the [measurement]() 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 key value pairs, each representing a field. Field keys are unquoted strings. *Spaces and commas must be escaped.*Field values can be [strings](/influxdb/v2/reference/syntax/line-protocol/#string) (quoted),[floats](/influxdb/v2/reference/syntax/line-protocol/#float),[integers](/influxdb/v2/reference/syntax/line-protocol/#integer),[unsigned integers](/influxdb/v2/reference/syntax/line-protocol/#uinteger), or [booleans](/influxdb/v2/reference/syntax/line-protocol/#boolean). * **timestamp**: [Unix timestamp](/influxdb/v2/reference/syntax/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 * **measurement**: 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. myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 *For schema design recommendations, see [InfluxDB schema design](/influxdb/v2/write-data/best-practices/schema-design/).* ## Construct line protocol With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB. 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: * **measurement**: `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 Data is collected hourly beginning at 2022-01-01T08:00:00Z (UTC) until 2022-01-01T20:00:00Z (UTC). The resulting line protocol would look something like the following: ##### Home sensor data line protocol ```sh 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 line protocol to InfluxDB Use the **InfluxDB UI**, **`influx` CLI**, or **InfluxDB API** to write the line protocol above to InfluxDB. [InfluxDB UI](#influxdb-ui)[influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) 1. Visit[localhost:8086](http://localhost:8086) in a browser to log in and access the InfluxDB UI. 2. Navigate to **Load Data** \> **Buckets** using the left navigation bar. Load Data 1. Click **Add Data** on the bucket you want to write the data to and select **Line Protocol**. 2. Select **Enter Manually**. 3. Important In the **Precision** drop-down menu above the line protocol text field, select **Seconds** (to match to precision of the timestamps in the line protocol). 4. Copy the [line protocol above](#home-sensor-data-line-protocol) and paste it into the line protocol text field. 5. Click **Write Data**. The UI will confirm that the data has been written successfully. 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Use the [`influx write` command](/influxdb/v2/reference/cli/influx/write/)to write the [line protocol above](#home-sensor-data-line-protocol) to InfluxDB. **Provide the following**: * `-b, --bucket` or `--bucket-id` flag with the bucket name or ID to write do. * `-p, --precision` flag with the timestamp precision (`s`). * String-encoded line protocol. * [Connection and authentication credentials](/influxdb/v2/get-started/setup/?t=influx+CLI#configure-authentication-credentials) ``` influx write \ --bucket get-started \ --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 " ``` To write data to InfluxDB using the InfluxDB HTTP API, send a request to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method. ``` POST http://localhost:8086/api/v2/write ``` Include the following with your request: * **Headers**: * **Authorization**: Token \ * **Content-Type**: text/plain; charset=utf-8 * **Accept**: application/json * **Query parameters**: * **org**: InfluxDB organization name * **bucket**: InfluxDB bucket name * **precision**: timestamp precision (default is `ns`) * **Request body**: Line protocol as plain text The following example uses cURL and the InfluxDB API to write line protocol to InfluxDB: ```sh export INFLUX_HOST=http://localhost:8086 export INFLUX_ORG= export INFLUX_TOKEN= curl --request POST \ "$INFLUX_HOST/api/v2/write?org=$INFLUX_ORG&bucket=get-started&precision=s" \ --header "Authorization: Token $INFLUX_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 " ``` [](#view-the-written-data) View the written data | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| co | 0 | |2022-01-01T09:00:00Z| home |Kitchen| co | 0 | |2022-01-01T10:00:00Z| home |Kitchen| co | 0 | |2022-01-01T11:00:00Z| home |Kitchen| co | 0 | |2022-01-01T12:00:00Z| home |Kitchen| co | 0 | |2022-01-01T13:00:00Z| home |Kitchen| co | 1 | |2022-01-01T14:00:00Z| home |Kitchen| co | 1 | |2022-01-01T15:00:00Z| home |Kitchen| co | 3 | |2022-01-01T16:00:00Z| home |Kitchen| co | 7 | |2022-01-01T17:00:00Z| home |Kitchen| co | 9 | |2022-01-01T18:00:00Z| home |Kitchen| co | 18 | |2022-01-01T19:00:00Z| home |Kitchen| co | 22 | |2022-01-01T20:00:00Z| home |Kitchen| co | 26 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| hum | 35.9 | |2022-01-01T09:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T10:00:00Z| home |Kitchen| hum | 36.1 | |2022-01-01T11:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T12:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T13:00:00Z| home |Kitchen| hum | 36.5 | |2022-01-01T14:00:00Z| home |Kitchen| hum | 36.3 | |2022-01-01T15:00:00Z| home |Kitchen| hum | 36.2 | |2022-01-01T16:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T17:00:00Z| home |Kitchen| hum | 36 | |2022-01-01T18:00:00Z| home |Kitchen| hum | 36.9 | |2022-01-01T19:00:00Z| home |Kitchen| hum | 36.6 | |2022-01-01T20:00:00Z| home |Kitchen| hum | 36.5 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-------|-------|-------| |2022-01-01T08:00:00Z| home |Kitchen| temp | 21 | |2022-01-01T09:00:00Z| home |Kitchen| temp | 23 | |2022-01-01T10:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T11:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T12:00:00Z| home |Kitchen| temp | 22.5 | |2022-01-01T13:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T14:00:00Z| home |Kitchen| temp | 22.8 | |2022-01-01T15:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T16:00:00Z| home |Kitchen| temp | 22.4 | |2022-01-01T17:00:00Z| home |Kitchen| temp | 22.7 | |2022-01-01T18:00:00Z| home |Kitchen| temp | 23.3 | |2022-01-01T19:00:00Z| home |Kitchen| temp | 23.1 | |2022-01-01T20:00:00Z| home |Kitchen| temp | 22.7 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| co | 0 | |2022-01-01T09:00:00Z| home |Living Room| co | 0 | |2022-01-01T10:00:00Z| home |Living Room| co | 0 | |2022-01-01T11:00:00Z| home |Living Room| co | 0 | |2022-01-01T12:00:00Z| home |Living Room| co | 0 | |2022-01-01T13:00:00Z| home |Living Room| co | 0 | |2022-01-01T14:00:00Z| home |Living Room| co | 0 | |2022-01-01T15:00:00Z| home |Living Room| co | 1 | |2022-01-01T16:00:00Z| home |Living Room| co | 4 | |2022-01-01T17:00:00Z| home |Living Room| co | 5 | |2022-01-01T18:00:00Z| home |Living Room| co | 9 | |2022-01-01T19:00:00Z| home |Living Room| co | 14 | |2022-01-01T20:00:00Z| home |Living Room| co | 17 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T09:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T10:00:00Z| home |Living Room| hum | 36 | |2022-01-01T11:00:00Z| home |Living Room| hum | 36 | |2022-01-01T12:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T13:00:00Z| home |Living Room| hum | 36 | |2022-01-01T14:00:00Z| home |Living Room| hum | 36.1 | |2022-01-01T15:00:00Z| home |Living Room| hum | 36.1 | |2022-01-01T16:00:00Z| home |Living Room| hum | 36 | |2022-01-01T17:00:00Z| home |Living Room| hum | 35.9 | |2022-01-01T18:00:00Z| home |Living Room| hum | 36.2 | |2022-01-01T19:00:00Z| home |Living Room| hum | 36.3 | |2022-01-01T20:00:00Z| home |Living Room| hum | 36.4 | | \_time |\_measurement| room |\_field|\_value| |--------------------|-------------|-----------|-------|-------| |2022-01-01T08:00:00Z| home |Living Room| temp | 21.1 | |2022-01-01T09:00:00Z| home |Living Room| temp | 21.4 | |2022-01-01T10:00:00Z| home |Living Room| temp | 21.8 | |2022-01-01T11:00:00Z| home |Living Room| temp | 22.2 | |2022-01-01T12:00:00Z| home |Living Room| temp | 22.2 | |2022-01-01T13:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T14:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T15:00:00Z| home |Living Room| temp | 22.3 | |2022-01-01T16:00:00Z| home |Living Room| temp | 22.4 | |2022-01-01T17:00:00Z| home |Living Room| temp | 22.6 | |2022-01-01T18:00:00Z| home |Living Room| temp | 22.8 | |2022-01-01T19:00:00Z| home |Living Room| temp | 22.5 | |2022-01-01T20:00:00Z| home |Living Room| temp | 22.2 | **Congratulations!** You have written data to InfluxDB. The method described above is the manual way of writing data, but there are other options available: * [Write data to InfluxDB using no-code solutions](/influxdb/v2/write-data/no-code/) * [Write data to InfluxDB using developer tools](/influxdb/v2/write-data/developer-tools/) With data now stored in InfluxDB, let’s query it. [Set up InfluxDB](/influxdb/v2/get-started/setup/)[Query data](/influxdb/v2/get-started/query/) #### Related * [Write data to InfluxDB](/influxdb/v2/write-data/) * [Best practices for writing data](/influxdb/v2/write-data/best-practices/) * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Telegraf documentation](/telegraf/v1/) | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T09:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T10:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T11:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T12:00:00Z | home | Kitchen | co | 0 | | 2022-01-01T13:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T14:00:00Z | home | Kitchen | co | 1 | | 2022-01-01T15:00:00Z | home | Kitchen | co | 3 | | 2022-01-01T16:00:00Z | home | Kitchen | co | 7 | | 2022-01-01T17:00:00Z | home | Kitchen | co | 9 | | 2022-01-01T18:00:00Z | home | Kitchen | co | 18 | | 2022-01-01T19:00:00Z | home | Kitchen | co | 22 | | 2022-01-01T20:00:00Z | home | Kitchen | co | 26 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T10:00:00Z | home | Kitchen | hum | 36.1 | | 2022-01-01T11:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T12:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T13:00:00Z | home | Kitchen | hum | 36.5 | | 2022-01-01T14:00:00Z | home | Kitchen | hum | 36.3 | | 2022-01-01T15:00:00Z | home | Kitchen | hum | 36.2 | | 2022-01-01T16:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T17:00:00Z | home | Kitchen | hum | 36 | | 2022-01-01T18:00:00Z | home | Kitchen | hum | 36.9 | | 2022-01-01T19:00:00Z | home | Kitchen | hum | 36.6 | | 2022-01-01T20:00:00Z | home | Kitchen | hum | 36.5 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Kitchen | temp | 21 | | 2022-01-01T09:00:00Z | home | Kitchen | temp | 23 | | 2022-01-01T10:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T11:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T12:00:00Z | home | Kitchen | temp | 22.5 | | 2022-01-01T13:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T14:00:00Z | home | Kitchen | temp | 22.8 | | 2022-01-01T15:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T16:00:00Z | home | Kitchen | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Kitchen | temp | 22.7 | | 2022-01-01T18:00:00Z | home | Kitchen | temp | 23.3 | | 2022-01-01T19:00:00Z | home | Kitchen | temp | 23.1 | | 2022-01-01T20:00:00Z | home | Kitchen | temp | 22.7 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | co | 0 | | 2022-01-01T09:00:00Z | home | Living Room | co | 0 | | 2022-01-01T10:00:00Z | home | Living Room | co | 0 | | 2022-01-01T11:00:00Z | home | Living Room | co | 0 | | 2022-01-01T12:00:00Z | home | Living Room | co | 0 | | 2022-01-01T13:00:00Z | home | Living Room | co | 0 | | 2022-01-01T14:00:00Z | home | Living Room | co | 0 | | 2022-01-01T15:00:00Z | home | Living Room | co | 1 | | 2022-01-01T16:00:00Z | home | Living Room | co | 4 | | 2022-01-01T17:00:00Z | home | Living Room | co | 5 | | 2022-01-01T18:00:00Z | home | Living Room | co | 9 | | 2022-01-01T19:00:00Z | home | Living Room | co | 14 | | 2022-01-01T20:00:00Z | home | Living Room | co | 17 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T09:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T10:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T11:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T12:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T13:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T14:00:00Z | home | Living Room | hum | 36.1 | | 2022-01-01T15:00:00Z | home | Living Room | hum | 36.1 | | 2022-01-01T16:00:00Z | home | Living Room | hum | 36 | | 2022-01-01T17:00:00Z | home | Living Room | hum | 35.9 | | 2022-01-01T18:00:00Z | home | Living Room | hum | 36.2 | | 2022-01-01T19:00:00Z | home | Living Room | hum | 36.3 | | 2022-01-01T20:00:00Z | home | Living Room | hum | 36.4 | | _time | _measurement | room | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | room | _field | _value | | 2022-01-01T08:00:00Z | home | Living Room | temp | 21.1 | | 2022-01-01T09:00:00Z | home | Living Room | temp | 21.4 | | 2022-01-01T10:00:00Z | home | Living Room | temp | 21.8 | | 2022-01-01T11:00:00Z | home | Living Room | temp | 22.2 | | 2022-01-01T12:00:00Z | home | Living Room | temp | 22.2 | | 2022-01-01T13:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T14:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T15:00:00Z | home | Living Room | temp | 22.3 | | 2022-01-01T16:00:00Z | home | Living Room | temp | 22.4 | | 2022-01-01T17:00:00Z | home | Living Room | temp | 22.6 | | 2022-01-01T18:00:00Z | home | Living Room | temp | 22.8 | | 2022-01-01T19:00:00Z | home | Living Room | temp | 22.5 | | 2022-01-01T20:00:00Z | home | Living Room | temp | 22.2 | --- # Install InfluxDB OSS v2 Source: https://docs.influxdata.com/influxdb/v2/install/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB v2 time series platform is purpose-built to collect, store, process and visualize metrics and events. * [Download and install InfluxDB v2](#download-and-install-influxdb-v2) * [Start InfluxDB](#start-influxdb) * [Download, install, and configure the `influx` CLI](#download-install-and-configure-the-influx-cli) ## Download and install InfluxDB v2 Recommended:: Before you open and install packages and downloaded files, use SHA checksum verification and GPG signature verification to ensure the files are intact and authentic. InfluxDB installation instructions for some OS versions include steps to verify downloaded files before you install them. For more information about SHA and GPG verifications, see the following: [](#choose-the-influxdata-key-pair-for-your-os-version) Choose the InfluxData key-pair for your OS version *Before running the installation steps, substitute the InfluxData key-pair compatible with your OS version:* For newer releases (for example, Ubuntu 20.04 LTS and newer, Debian Buster and newer) that support subkey verification: * GPG key file: [`influxdata-archive.key`](https://repos.influxdata.com/influxdata-archive.key) * Primary key fingerprint: `24C975CBA61A024EE1B631787C3D57159FC2F927` For older versions (for example, CentOS/RHEL 7, Ubuntu 18.04 LTS, or Debian Stretch) that don’t support subkeys for verification: * GPG key file: [`influxdata-archive_compat.key`](https://repos.influxdata.com/influxdata-archive_compat.key) * Signing key fingerprint: `9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E` [](#verify-download-integrity-using-sha-256) Verify download integrity using SHA-256 For each released binary, InfluxData publishes the SHA checksum that you can use to verify that the downloaded file is intact and hasn’t been corrupted. To use the SHA checksum to verify the downloaded file, do the following: 1. In the [downloads page](https://www.influxdata.com/downloads), select the **Version** and **Platform** for your download, and then copy the **SHA256:** checksum value. 2. Compute the SHA checksum of the downloaded file and compare it to the published checksum–for example, enter the following command in your terminal: ```bash # Use 2 spaces to separate the checksum from the filename echo "8d7872013cad3524fb728ca8483d0adc30125ad1af262ab826dcf5d1801159cf influxdb2-2.10.0_linux_amd64.tar.gz" \ | sha256sum --check - ``` Replace the following: * `8d7872013cad3524fb728ca8483d0adc30125ad1af262ab826dcf5d1801159cf`: the **SHA256:** checksum value that you copied from the downloads page If the checksums match, the output is the following; otherwise, an error message. ``` influxdb2-2.10.0_linux_amd64.tar.gz: OK ``` [](#verify-file-integrity-and-authenticity-using-gpg) Verify file integrity and authenticity using GPG InfluxData uses [GPG (GnuPG)](https://www.gnupg.org/software/) to sign released software and provides public key and encrypted private key (`.key` file) pairs that you can use to verify the integrity of packages and binaries from the InfluxData repository. Most operating systems include `gpg` by default.*If `gpg` isn’t available on your system, see[GnuPG download](https://gnupg.org/download/) and install instructions.* The following steps guide you through using GPG to verify InfluxDB binary releases: 1. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version). 2. Download and import the InfluxData public key. `gpg --import` outputs to stderr. The following example shows how to import the key, redirect the output to stdout, and then check for the expected key name: ```sh curl --silent --location https://repos.influxdata.com/influxdata-archive.key \ | gpg --import - 2>&1 \ | grep 'InfluxData Package Signing Key ' ``` Replace the following: * `https://repos.influxdata.com/influxdata-archive.key`: the InfluxData private key file compatible with your OS version If successful, the output is the following: ``` gpg: key 7C3D57159FC2F927: public key "InfluxData Package Signing Key " imported ``` 1. Download the signature file for the release by appending `.asc` to the download URL, and then use `gpg` to verify the download signature–for example, enter the following in your terminal: ``` curl --silent --location \ https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_darwin_amd64.tar.gz.asc \ | gpg --verify - ~/Downloads/influxdb2-2.10.0_darwin_amd64.tar.gz \ 2>&1 | grep 'InfluxData Package Signing Key ' ``` * `curl --silent --location`: Follows any server redirects and fetches the signature file silently (without progress meter). * `gpg --verify -`: Reads the signature from stdin and uses it to verify the the downloaded `influxdbv2` binary. If successful, the output is the following: ``` gpg: Good signature from "InfluxData Package Signing Key " [unknown] ``` *For security, InfluxData periodically rotates keys and publishes the new key pairs.* The following instructions include steps for downloading, verifying, and installing InfluxDB: [macOS](#macos)[Linux](#linux)[Windows](#windows)[Docker](#docker)[Kubernetes](#kubernetes)[Raspberry Pi](#raspberry-pi) To install InfluxDB, do one of the following: * [Install using Homebrew](#install-using-homebrew) * [Manually download and install for macOS](#manually-download-and-install-for-macos) > [!Tip] > We recommend using [Homebrew](https://brew.sh/) to install InfluxDB v2 on macOS. > [!Note] > #### InfluxDB and the influx CLI are separate packages > > The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the[`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and > versioned separately. > > *You’ll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli).* ### Install using Homebrew ```sh brew update brew install influxdb ``` ### Manually download and install for macOS 1. In your browser or your terminal, download the InfluxDB package. [InfluxDB v2 (macOS)](https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_darwin_amd64.tar.gz) ``` # Download using cURL curl --location -O \ "https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_darwin_amd64.tar.gz" ``` 2. Recommended:: Verify the integrity of the download–for example, enter the following command in your terminal: ```sh # Use 2 spaces to separate the checksum from the filename echo "224926fd77736a364cf28128f18927dda00385f0b6872a108477246a1252ae1b influxdb2-2.10.0_darwin_amd64.tar.gz" \ | shasum --algorithm 256 --quiet --check - ``` Replace the following: * `224926fd77736a364cf28128f18927dda00385f0b6872a108477246a1252ae1b`: the SHA checksum from the [downloads page](https://www.influxdata.com/downloads/#telegraf) 1. Unpackage the InfluxDB binary. Do one of the following: * In **Finder**, double-click the downloaded package file. * In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**), use `tar` to unpackage the file–for example, enter the following command to extract it into the current directory: ``` # Unpackage contents to the current working directory tar zxvf ./influxdb2-2.10.0_darwin_amd64.tar.gz ``` 2. Optional: Place the `influxd` binary in your `$PATH`–for example, copy the binary to `/usr/local/bin`: ``` # (Optional) Copy the influxd binary to your $PATH sudo cp influxdb2-2.10.0/influxd /usr/local/bin/ ``` With the `influxd` binary in your `$PATH` (`/usr/local/bin`), you can enter `influxd` in your terminal to start the server. If you choose not to move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server–for example: ``` ./influxdb2-2.10.0/influxd ``` [](#recommended--set-appropriate-directory-permissions) Recommended – Set appropriate directory permissions To prevent unwanted access to data, set the permissions on the influxdb `data-dir` to not be world readable. If installing on a server, set a umask of `0027` to properly permission all newly created files–for example, enter the following command in your terminal: ```bash chmod 0750 ~/.influxdbv2 ``` > [!Important] > Both InfluxDB 1.x and 2.x have associated `influxd` and `influx` binaries. > If InfluxDB 1.x binaries are already in your `$PATH`, run the v2 binaries in > place or rename them before putting them in your `$PATH`. > If you rename the binaries, all references to `influxd` and `influx` in this > documentation refer to your renamed binaries. []() To install InfluxDB on Linux, do one of the following: * [Install InfluxDB as a service with systemd](#install-influxdb-as-a-service-with-systemd) * [Manually download and install the influxd binary](#manually-download-and-install-the-influxd-binary) > [!Note] > #### InfluxDB and the influx CLI are separate packages > > The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the[`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and > versioned separately. > > *You’ll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli).* ### Install InfluxDB as a service with systemd 1. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version). 2. Run the command for your OS version to install the InfluxData key, add the InfluxData repository, and install `influxdb`. *Before running the command, replace the fingerprint and key filename with the key-pair from the preceding step.* ``` # Ubuntu and Debian # Add the InfluxData key to verify downloads and add the repository 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 /etc/apt/keyrings/influxdata-archive.gpg > /dev/null \ && echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \ | sudo tee /etc/apt/sources.list.d/influxdata.list # Install influxdb sudo apt-get update && sudo apt-get install influxdb2 ``` ``` # RedHat and CentOS # Add the InfluxData key to verify downloads 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 \ | tee /etc/pki/rpm-gpg/RPM-GPG-KEY-influxdata > /dev/null # Add the InfluxData repository to the repository list. cat < Active: active (running) ``` For information about where InfluxDB stores data on disk when running as a service, see [File system layout](/influxdb/v2/reference/internals/file-system-layout/?t=Linux#installed-as-a-package). #### Pass configuration options to the service You can use systemd to customize [InfluxDB configuration options](/influxdb/v2/reference/config-options/#configuration-options) and pass them to the InfluxDB service. 1. Edit the `/etc/default/influxdb2` service configuration file to assign configuration directives to `influxd` command line flags–for example, add one or more `=` lines like the following: ``` ARG1="--http-bind-address :8087" ARG2="--storage-wal-fsync-delay=15m" ``` 2. Edit the `/lib/systemd/system/influxdb.service` file to pass the variables to the `ExecStart` value: ``` ExecStart=/usr/bin/influxd $ARG1 $ARG2 ``` ### Manually download and install the influxd binary *If necessary, adjust the example file paths and utilities for your system.* 1. In your browser or your terminal, download the InfluxDB binary for your system architecture (AMD64 or ARM). [InfluxDB v2 (amd64)](https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_amd64.tar.gz)[InfluxDB v2 (arm)](https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_arm64.tar.gz) ``` # Use curl to download the amd64 binary. curl --location -O \ https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_amd64.tar.gz ``` ``` # Use curl to download the arm64 binary. curl --location -O \ https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_arm64.tar.gz ``` 2. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version). 3. Recommended:: Verify the authenticity of the downloaded binary–for example, enter the following command in your terminal. *Before running the command for your system, replace`https://repos.influxdata.com/influxdata-archive.key` with the key URL from the preceding step.* ``` # amd64 # Download and import the key curl --silent --location https://repos.influxdata.com/influxdata-archive.key \ | gpg --import - 2>&1 \ | grep 'InfluxData Package Signing Key ' \ && # Download and verify the binary's signature file curl --silent --location "https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_amd64.tar.gz.asc" \ | gpg --verify - influxdb2-2.10.0_linux_amd64.tar.gz \ 2>&1 | grep 'InfluxData Package Signing Key ' ``` ``` # arm64 # Download and import the key curl --silent --location https://repos.influxdata.com/influxdata-archive.key \ | gpg --import - 2>&1 \ | grep 'InfluxData Package Signing Key ' \ && # Download and verify the binary's signature file curl --silent --location "https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0_linux_arm64.tar.gz.asc" \ | gpg --verify - influxdb2-2.10.0_linux_arm64.tar.gz \ 2>&1 | grep 'InfluxData Package Signing Key ' ``` If successful, the output is similar to the following: ``` gpg: Good signature from "InfluxData Package Signing Key " [unknown] ``` 4. Extract the downloaded binary–for example, enter the following command for your system: ``` # amd64 tar xvzf ./influxdb2-2.10.0_linux_amd64.tar.gz ``` ``` # arm64 tar xvzf ./influxdb2-2.10.0_linux_arm64.tar.gz ``` 5. Optional: Place the extracted `influxd` executable binary in your system `$PATH`. ``` # amd64 sudo cp ./influxdb2-2.10.0/usr/bin/influxd /usr/local/bin/ ``` ``` # arm64 sudo cp ./influxdb2-2.10.0/usr/bin/influxd /usr/local/bin/ ``` If you choose to not move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server–for example: ``` ./influxdb2-2.10.0/usr/bin/influxd ``` [](#recommended--set-appropriate-directory-permissions) Recommended – Set appropriate directory permissions To prevent unwanted access to data, set the permissions on the influxdb`data-dir` to not be world readable. If installing on a server, we recommend setting a umask of `0027` to properly permission all newly created files. To set umask, use a UMask directive in a systemd unit file or run Influxdb as a specific user that has the umask properly set–for example, enter the following command in your terminal: ```sh chmod 0750 ~/.influxdbv2 ``` ### System requirements * Windows 10 * 64-bit AMD architecture * [Powershell](https://docs.microsoft.com/powershell/) or[Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/) > [!Important] > ### Command line examples > > Use **Powershell** or **WSL** to execute `influx` and `influxd` commands. > The command line examples in this documentation use `influx` and `influxd` as if > installed on the system `PATH`. > If these binaries are not installed on your `PATH`, replace `influx` and `influxd`in the provided examples with `./influx` and `./influxd` respectively. > [!Note] > #### InfluxDB and the influx CLI are separate packages > > The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the[`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and > versioned separately. > > *You’ll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli).* [InfluxDB v2 (Windows)](https://download.influxdata.com/influxdb/releases/influxdb2-2.10.0-windows_amd64.zip) Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename the files if desired. ```powershell Expand-Archive .\influxdb2-2.10.0-windows_amd64.zip -DestinationPath 'C:\Program Files\InfluxData\' mv 'C:\Program Files\InfluxData\influxdb2-2.10.0-windows-amd64' 'C:\Program Files\InfluxData\influxdb' ``` [](#recommended--set-appropriate-directory-permissions) Recommended – Set appropriate directory permissions To prevent unwanted access to data, we recommend setting the permissions on the influxdb `data-dir` to not be world readable–for example: enter the following commands in your terminal: ```powershell $acl = Get-Acl "C:\Users\\.influxdbv2" $accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule("everyone","Read","Deny") $acl.SetAccessRule($accessRule) $acl | Set-Acl "C:\Users\\.influxdbv2" ``` ### Install and set up InfluxDB in a container The following steps show how to use the[Docker CLI](https://docs.docker.com/reference/cli/docker/) to set up and run InfluxDB. but you can also[use Docker Compose](/influxdb/v2/install/use-docker-compose). *The following guide uses Docker mounted[volumes](https://docs.docker.com/storage/volumes/) to persist InfluxDB configuration and data. Persisting your data to a file system outside the container ensures that your data isn’t deleted if you delete the container.* 1. Install [Docker Desktop](https://www.docker.com/get-started/) for your system. 2. Start a Docker container from the[`influxdb` Docker Hub image](https://hub.docker.com/_/influxdb)–for example, in your terminal, enter the `docker run influxdb:2` command with command line flags for initial setup options and file system mounts. *If you don’t specify InfluxDB initial setup options, you can[set up manually](/influxdb/v2/get-started/setup/) later using the UI or CLI in a running container.* ```bash docker run \ --name influxdb2 \ --publish 8086:8086 \ --mount type=volume,source=influxdb2-data,target=/var/lib/influxdb2 \ --mount type=volume,source=influxdb2-config,target=/etc/influxdb2 \ --env DOCKER_INFLUXDB_INIT_MODE=setup \ --env DOCKER_INFLUXDB_INIT_USERNAME=ADMIN_USERNAME \ --env DOCKER_INFLUXDB_INIT_PASSWORD=ADMIN_PASSWORD \ --env DOCKER_INFLUXDB_INIT_ORG=ORG_NAME \ --env DOCKER_INFLUXDB_INIT_BUCKET=BUCKET_NAME \ influxdb:2 ``` The command passes the following arguments: * `--publish 8086:8086`: Exposes the InfluxDB[UI](/influxdb/v2/get-started/#influxdb-user-interface-ui) and[HTTP API](/influxdb/v2/reference/api/) on the host’s `8086` port. * `--mount type=volume,source=influxdb2-data,target=/var/lib/influxdb2`: Creates a volume named `influxdb2-data` mapped to the[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/?t=docker#file-system-layout)to persist data outside the container. * `--mount type=volume,source=influxdb2-config,target=/etc/influxdb2`: Creates a volume named `influxdb2-config` mapped to the[InfluxDB configuration directory](/influxdb/v2/reference/internals/file-system-layout/?t=docker#file-system-layout)to make configurations available outside the container. * `--env DOCKER_INFLUXDB_INIT_MODE=setup`: Environment variable that invokes the automated setup of the initial organization, user, bucket, and token when creating the container. * `--env DOCKER_INFLUXDB_INIT_`: Environment variables for initial setup options–replace the following with your own values: * `ADMIN_USERNAME`: The username for the initial [user](/influxdb/v2/admin/users/)–an admin user with an API [Operator token](/influxdb/v2/admin/tokens/#operator-token). * `ADMIN_PASSWORD`: The password for the initial [user](/influxdb/v2/admin/users/). * `ORG_NAME`: The name for the initial [organization](/influxdb/v2/admin/organizations/). * `BUCKET_NAME`: The name for the initial [bucket](/influxdb/v2/admin/buckets/). If successful, the command starts InfluxDB initialized with the user, organization, bucket, and *[Operator token](/influxdb/v2/admin/tokens/#operator-token)*, and logs to stdout. You can view the Operator token in the `/etc/influxdb2/influx-configs` file and use it to authorize[creating an All Access token](#examples). For more information, see [API token types](/influxdb/v2/admin/tokens/#api-token-types). *To run the InfluxDB container in[detached mode](https://docs.docker.com/engine/reference/run/#detached-vs-foreground), include the `--detach` flag in the `docker run` command.* For more InfluxDB configuration options, see the [`influxdb` Docker Hub image](https://hub.docker.com/_/influxdb)documentation. ### Run InfluxDB CLI commands in a container When you start a container using the `influxdb` Docker Hub image, it also installs the [`influx` CLI](/influxdb/v2/tools/influx-cli/) in the container. With InfluxDB setup and running in the container, you can use the Docker CLI[`docker exec`](https://docs.docker.com/reference/cli/docker/container/exec/)command to interact with the `influx` and `influxd` CLIs inside the container. #### Syntax ```bash docker exec -it ` ``` #### Examples ```bash # Create an All Access token docker exec -it influxdb2 influx auth create \ --all-access \ --token OPERATOR_TOKEN ``` ```bash # List CLI configurations docker exec -it influxdb2 influx config ls ``` ```bash # View the server configuration docker exec -it influxdb2 influx server-config # Inspect server details docker exec -it influxdb2 influxd inspect -d ``` ### Manage files in mounted volumes To copy files, such as the InfluxDB server `config.yml` file, between your local file system and a volume, use the[`docker container cp` command](https://docs.docker.com/reference/cli/docker/container/cp/). ### Install InfluxDB in a Kubernetes cluster The instructions below use **minikube** or **kind**, but the steps should be similar in any Kubernetes cluster. InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) available. 1. Install [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) or[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation). 2. Start a local cluster: ``` # with minikube minikube start ``` ``` # with kind kind create cluster ``` 3. Apply the [sample InfluxDB configuration](https://github.com/influxdata/docs-v2/blob/master/static/downloads/influxdb-k8-minikube.yaml) by running: ``` kubectl apply -f https://raw.githubusercontent.com/influxdata/docs-v2/master/static/downloads/influxdb-k8-minikube.yaml ``` This creates an `influxdb` Namespace, Service, and StatefulSet. A PersistentVolumeClaim is also created to store data written to InfluxDB. **Important**: always inspect YAML manifests before running `kubectl apply -f `! 4. Ensure the Pod is running: ``` kubectl get pods -n influxdb ``` 5. Ensure the Service is available: ``` kubectl describe service -n influxdb influxdb ``` You should see an IP address after `Endpoints` in the command’s output. 6. Forward port 8086 from inside the cluster to localhost: ``` kubectl port-forward -n influxdb service/influxdb 8086:8086 ``` ### Requirements To run InfluxDB on Raspberry Pi, you need: * a Raspberry Pi 4+ or 400 * a 64-bit operating system.Recommended:: a [64-bit version of Ubuntu](https://ubuntu.com/download/raspberry-pi)of Ubuntu Desktop or Ubuntu Server compatible with 64-bit Raspberry Pi. ### Install Linux binaries Follow the [Linux installation instructions](/influxdb/v2/install/?t=Linux#install-linux)to install InfluxDB on a Raspberry Pi. ### Monitor your Raspberry Pi Use the [InfluxDB Raspberry Pi template](/influxdb/cloud/monitor-alert/templates/infrastructure/raspberry-pi/)to easily configure collecting and visualizing system metrics for the Raspberry Pi. #### Monitor 32-bit Raspberry Pi systems If you have a 32-bit Raspberry Pi, [use Telegraf](/telegraf/v1/)to collect and send data to: * [InfluxDB OSS](/influxdb/v2/), running on a 64-bit system * InfluxDB Cloud with a [**Free Tier**](/influxdb/cloud/account-management/pricing-plans/#free-plan) account * InfluxDB Cloud with a paid [**Usage-Based**](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan) account with relaxed resource restrictions. ## Start InfluxDB If it isn’t already running, follow the instructions to start InfluxDB on your system: [macOS](#macos-2)[Linux](#linux-2)[Windows](#windows-2)[Docker](#docker-2)[Kubernetes](#kubernetes-2) To start InfluxDB, run the `influxd` daemon: ```bash influxd ``` #### (macOS Catalina and newer) Authorize the influxd binary macOS requires downloaded binaries to be signed by registered Apple developers. Currently, when you first attempt to run `influxd`, macOS will prevent it from running. To manually authorize the `influxd` binary, follow the instructions for your macOS version to allow downloaded applications. ##### Run InfluxDB on macOS Ventura 1. Follow the preceding instructions to attempt to start `influxd`. 2. Open **System Settings** and click **Privacy & Security**. 3. Under the **Security** heading, there is a message about “influxd” being blocked, click **Allow Anyway**. 4. When prompted, enter your password to allow the setting. 5. Close **System Settings**. 6. Attempt to start `influxd`. 7. A prompt appears with the message *“macOS cannot verify the developer of “influxd”…”"*. Click **Open**. ##### Run InfluxDB on macOS Catalina 1. Attempt to start `influxd`. 2. Open **System Preferences** and click **Security & Privacy**. 3. Under the **General** tab, there is a message about `influxd` being blocked. Click **Open Anyway**. We are in the process of updating the build process to ensure released binaries are signed by InfluxData. > [!Important] > #### “too many open files” errors > > After running `influxd`, you might see an error in the log output like the > following: > > ``` > too many open files > ``` > > To resolve this error, follow the[recommended steps](https://unix.stackexchange.com/a/221988/471569) to increase > file and process limits for your operating system version then restart `influxd`. If InfluxDB was installed as a systemd service, systemd manages the `influxd` daemon and no further action is required. If the binary was manually downloaded and added to the system `$PATH`, start the `influxd` daemon with the following command: ```bash influxd ``` In **Powershell**, navigate into `C:\Program Files\InfluxData\influxdb` and start InfluxDB by running the `influxd` daemon: ```powershell cd -Path 'C:\Program Files\InfluxData\influxdb' ./influxd ``` > [!Note] > #### Grant network access > > When starting InfluxDB for the first time, **Windows Defender** appears with > the following message: > > > > > > > Windows Defender Firewall has blocked some features of this app. > > > > > > 1. Select **Private networks, such as my home or work network**. > 2. Click **Allow access**. To use the Docker CLI to start an existing container, enter the following command: ```bash docker start influxdb2 ``` Replace `influxdb2` with the name of your container. To start a new container, follow instructions to [install and set up InfluxDB in a container](?t=docker#install-and-set-up-influxdb-in-a-container). To start InfluxDB using Kubernetes, follow instructions to [install InfluxDB in a Kubernetes cluster](?t=kubernetes#download-and-install-influxdb-v2). If successful, you can view the InfluxDB UI at [http://localhost:8086](http://localhost:8086). InfluxDB starts with default settings, including the following: * `http-bind-address=:8086`: Uses port `8086` (TCP) for InfluxDB UI and HTTP API client-server communication. * `reporting-disabled=false`: Sends InfluxDB telemetry information back to InfluxData. To override default settings, specify [configuration options](/influxdb/v2/reference/config-options) when starting InfluxDB–for example: [](#configure-the-port-or-address) Configure the port or address By default, the InfluxDB UI and HTTP API use port `8086`. To specify a different port or address, override the[`http-bind-address` option](/influxdb/v2/reference/config-options/#http-bind-address)when starting `influxd`–for example: [Linux](#linux-3)[Windows Powershell](#windows-powershell) ```bash influxd --http-bind-address ``` ```powershell ./influxd --http-bind-address ``` [](#opt-out-of-telemetry-reporting) Opt-out of telemetry reporting By default, InfluxDB sends telemetry data back to InfluxData. The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides information about what data is collected and how it is used. To opt-out of sending telemetry data back to InfluxData, specify the[`reporting-disabled` option](/influxdb/v2/reference/config-options/#reporting-disabled) when starting `influxd`–for example: [Linux](#linux-4)[Windows Powershell](#windows-powershell-2) ```bash influxd --reporting-disabled ``` ```powershell ./influxd --reporting-disabled ``` For information about InfluxDB v2 default settings and how to override them, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/). With InfluxDB installed and initialized, [get started](/influxdb/v2/get-started/) writing and querying data. ## Download, install, and configure the `influx` CLI Recommended:: Install the `influx` CLI, which provides a simple way to interact with InfluxDB from a command line. For detailed installation and setup instructions, see [Use the influx CLI](/influxdb/v2/tools/influx-cli/). > [!Note] > #### InfluxDB and the influx CLI are separate packages > > The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the[`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and > versioned separately. > Some install methods (for example, the InfluxDB Docker Hub image) include both. #### Related * [influx auth](/influxdb/v2/reference/cli/influx/auth/) * [influx config](/influxdb/v2/reference/cli/influx/config/) * [influx - InfluxDB command line interface](/influxdb/v2/reference/cli/influx/) * [Manage API tokens](/influxdb/v2/admin/tokens/) [install](/influxdb/v2/tags/install/) --- # Upgrade InfluxDB Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ### [Upgrade from InfluxDB 2.x to 2.10](/influxdb/v2/install/upgrade/v2-to-v2/) To upgrade from InfluxDB 2.0 beta 16 or earlier to 2.10, manually upgrade all resources and data to the latest version by completing these steps. ### [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) Explore different methods for upgrading from InfluxDB 1.x to InfluxDB 2.10 and choose the best one for your use case. ### [Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0](/influxdb/v2/install/upgrade/v2-beta-to-v2/) To upgrade from InfluxDB 2.0 beta 16 or earlier to 2.10, first follow these steps to upgrade your InfluxDB beta instance, data, and resources to InfluxDB 2.0. ### [Downgrade InfluxDB](/influxdb/v2/install/upgrade/downgrade/) To downgrade from InfluxDB 2.10 to a previous 2.x version, use the `influxd downgrade` command to downgrade the metadata schema used by `influxd` to match the metadata schema of a older release. [upgrade](/influxdb/v2/tags/upgrade/) --- # Downgrade InfluxDB Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/downgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To downgrade from InfluxDB 2.10 to a previous 2.x version, use the `influxd downgrade` command to downgrade the metadata schema used by`influxd` to match the metadata schema of a older release. InfluxDB does not guarantee backwards-compatibility with older releases in its embedded metadata stores. Attempting to start an older `influxd` binary with a BoltDB or SQLite file that has been migrated to a newer schema will result in a startup error similar to: ``` Error: up: reading migrations: migration "...": migration specification not found ``` **To downgrade from InfluxDB 2.10 to a previous 2.x version**: 1. Run `influxd downgrade` using the **2.10 `influxd` binary**. Specify the previous InfluxDB version to downgrade to. For example, to downgrade to InfluxDB 2.0: ``` influxd downgrade 2.0 ``` 2. Install the **earlier version** of InfluxDB by following the[InfluxDB v2 installation instructions](/influxdb/v2/install/). 3. Start InfluxDB with the **earlier versioned `influxd` binary**. #### Related * [influxd downgrade](/influxdb/v2/reference/cli/influxd/downgrade/) --- # Upgrade from InfluxDB 1.x to 2.10 Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v1-to-v2/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Explore different methods for upgrading from InfluxDB 1.x to InfluxDB 2.10 and determine which best suits your use case. Consider the following: #### Do you want to migrate all your time series data? [Automatically upgrade to InfluxDB 2.10](/influxdb/v2/upgrade/v1-to-v2/automatic-upgrade/). #### Do you want to selectively migrate your time series data? [Manually upgrade to InfluxDB 2.10](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/). #### Are you using Docker? [Upgrade to the 2.x Docker image](/influxdb/v2/upgrade/v1-to-v2/docker/). #### Are you using continuous queries (CQs)? After you upgrade (automatically, manually, or using Docker),[migrate your 1.x CQs to InfluxDB 2.10 tasks](/influxdb/v2/upgrade/v1-to-v2/migrate-cqs/). --- # Automatically upgrade from InfluxDB 1.x to 2.10 Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influxd upgrade` command to upgrade InfluxDB 1.x to InfluxDB 2.10. The [`influxd upgrade`](/influxdb/v2/reference/cli/influxd/upgrade/) command is part of the **v2 `influxd` service** and provides an in-place upgrade from InfluxDB 1.x to InfluxDB 2.10. > [!Note] > To complete the upgrade process, ensure that you are using the**InfluxDB 2.10 `influxd` binary** that includes the`influxd upgrade` command. The upgrade process does the following: 1. Reads the existing InfluxDB 1.x configuration file and generates an equivalent InfluxDB 2.10 configuration file at `~/.influxdbv2/config.toml`or at a custom path specified with the `--v2-config-path` flag. 2. Upgrades metadata and storage engine paths to `~/.influxdbv2/meta` and`~/.influxdbv2/engine`, respectively (unless otherwise specified). 3. Writes existing data and write ahead log (WAL) files into InfluxDB2.10 [buckets](/influxdb/v2/reference/glossary/#bucket). 4. Creates [database and retention policy (DBRP) mappings](/influxdb/v2/reference/api/influxdb-1x/dbrp/)required to query data with InfluxQL. 5. Reads existing metadata and migrates non-admin users, passwords, and permissions into a 1.x authorization–compatible store within `~/influxdbv2/influxdb.bolt`. When starting InfluxDB 2.10 after running `influxdb upgrade`, InfluxDB must build a new time series index (TSI). Depending on the volume of data present, this may take some time. ## Important considerations before you begin Before upgrading to InfluxDB 2.10, consider the following guidelines. Some or all might apply to your specific installation and use case. The sections below contain our recommendations for addressing possible gaps in the upgrade process. Consider whether you need to address any of the following before upgrading. * [Available operating system, container, and platform support](#available-operating-system-container-and-platform-support) * [Continuous queries](#continuous-queries) * [Supported protocols](#supported-protocols) * [Kapacitor](#kapacitor) * [User migration](#user-migration) * [Dashboards](#dashboards) * [Other data](#other-data) * [Secure by default](#secure-by-default) * [`inmem` indexing option](#in-memory-indexing-option) * [Interactive shell](#interactive-shell) ### Available operating system, container, and platform support InfluxDB 2.10 is currently available for macOS, Linux, and Windows. > [!Note] > InfluxDB 2.10 requires 64-bit operating systems. ### Continuous queries Continuous queries are replaced by **tasks** in InfluxDB 2.10. By default, `influxd upgrade` writes all continuous queries to `~/continuous_queries.txt`. To convert continuous queries to InfluxDB tasks, see[Migrate continuous queries to tasks](/influxdb/v2/upgrade/v1-to-v2/migrate-cqs/). ### Supported protocols InfluxDB 2.10 doesn’t directly support the alternate write protocols[supported in InfluxDB 1.x](/influxdb/v1/supported_protocols/)(CollectD, Graphite, OpenTSDB, Prometheus, UDP). Use [Telegraf](/telegraf/v1/) to translate these protocols to line protocol. ### Kapacitor You can continue to use Kapacitor with InfluxDB OSS 2.10 under the following scenarios: * Kapacitor Batch-style TICKscripts work with the 1.x read compatible API. Existing Kapacitor user credentials should continue to work using the [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). * InfluxDB 2.10 has no subscriptions API and does not support Kapacitor stream tasks. To continue using stream tasks, write data directly to both InfluxDB and Kapacitor. Use **Telegraf** and its [InfluxDB output plugin](/telegraf/v1/plugins/#output-influxdb)to write to Kapacitor and the [InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2)to write to InfluxDB v2. ##### Example Telegraf configuration ```toml # Write to Kapacitor [[outputs.influxdb]] urls = ["http://localhost:9092"] database = "example-db" retention_policy = "example-rp" # Write to InfluxDB 2.10 [[outputs.influxdb]] urls = ["http://localhost:8086"] database = "example-db" retention_policy = "example-rp" username = "v1-auth-username" password = "v1-auth-password" ``` ### User migration `influxd upgrade` migrates existing 1.x users and their permissions **except** the following users: * [1.x admin users](/influxdb/v1/administration/authentication_and_authorization/#admin-users) * [1.x non-admin users](/influxdb/v1/administration/authentication_and_authorization/#non-admin-users)that have not been granted any privileges [](#review-1x-user-privileges) Review 1.x user privileges **To review 1.x users with admin privileges**, run the following against your InfluxDB 1.x instance: ```sql SHOW USERS ``` Users with `admin` set to `true` will **not** be migrated. **To review the specific privileges granted to each 1.x user**, run the following for each user in your InfluxDB 1.x instance: ```sql SHOW GRANTS FOR "" ``` If no grants appear, the user will **not** be migrated. If using an admin user for visualization or Chronograf administrative functions,**create a new read-only user before upgrading**: ##### Create a read-only 1.x user ```bash CREATE USER WITH PASSWORD '' GRANT READ ON TO "" ``` InfluxDB 2.10 only grants admin privileges to the primary user set up during the InfluxDB 2.10 upgrade. This provides you the opportunity to reassess who to grant admin permissions to when setting up InfluxDB 2.10. ### Dashboards You can continue to use your existing dashboards and visualization tools with InfluxDB 2.10 via the [1.x `/query` compatibility API](/influxdb/v2/reference/api/influxdb-1x/query/). The upgrade process creates [DBRP mappings](/influxdb/v2/reference/api/influxdb-1x/dbrp/)to ensure existing users can execute InfluxQL queries with the appropriate permissions. However, if your dashboard tool is configured using a user with admin permissions, you will need to create a new read-only user with the appropriate database permissions *before* upgrading. This new username and password combination should be used within the data source configurations to continue to provide read-only access to the underlying data. Ensure your dashboards are all functioning before upgrading. ### Other data The 1.x `_internal` database is not migrated with the `influxd upgrade` command. To collect, store, and monitor similar internal InfluxDB metrics,[create an InfluxDB 2.10 scraper](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper/)to scrape data from the `/metrics` endpoint and store them in a bucket. ### Secure by default InfluxDB 2.10 requires authentication and does not support the InfluxDB 1.x `auth-enabled = false` configuration option. Before upgrading to 2.10, [enable authentication in your InfluxDB 1.x instance](/influxdb/v1/administration/authentication_and_authorization/#set-up-authentication)and test your credentials to ensure your applications, agents, and visualization tools can connect to InfluxDB. If you upgrade with `auth-enabled = false`, the upgrade may appear complete, but client requests to InfluxDB 2.10 may be silently ignored (you won’t see a notification that the request was denied). ### In-memory indexing option InfluxDB 2.10 doesn’t support[in-memory (`inmem`) indexing](/influxdb/v1/administration/config/#in-memory-inmem-index-settings). The following InfluxDB 1.x configuration options associated with `inmem`indexing are ignored in the upgrade process: * `max-series-per-database` * `max-values-per-tag` ### Interactive shell The InfluxDB 2.10 `influx` CLI includes an interactive**InfluxQL shell** for executing InfluxQL queries. To start an InfluxQL shell: 1. Download and install the [`influx` CLI](/influxdb/v2/tools/influx-cli/). 2. Set up your [`influx` CLI authentication credentials](/influxdb/v2/tools/influx-cli/#set-up-the-influx-cli). 3. Run the `influx v1 shell` command. For more information see: * [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) To build an interactive shell to execute **Flux** queries,[compile and build a command line Flux REPL from source](https://github.com/influxdata/flux/blob/master/README.md#getting-started). ## Perform the upgrade If you’ve considered the [guidance above](#important-considerations-before-you-begin)and are ready to proceed, follow these steps to upgrade your InfluxDB 1.x to InfluxDB 2.10. 1. [Download InfluxDB OSS 2.10](https://www.influxdata.com/downloads/). Unpackage the InfluxDB binaries and place them in your `$PATH`. 2. Stop your running InfluxDB 1.x instance. Make a backup copy of all 1.x data before upgrading: ``` cp -R .influxdb/ .influxdb_bak/ ``` 3. Use `influxd version` to ensure you are running InfluxDB 2.10 from the command line. The `influxd upgrade` command is only available in InfluxDB 2.10. 4. If your 1.x configuration file is at the[default location](/influxdb/v1/administration/config/#using-the-configuration-file), run: ``` influxd upgrade ``` #### Upgrade `.deb` packages #### When installed from a `.deb` package, InfluxDB 1.x and 2.x run under the `influxdb` user. If you’ve installed both versions from `.deb` packages, run the upgrade command as the `influxdb` user: ``` sudo -u influxdb influxd upgrade ``` If your 1.x configuration file is not at the default location, run: ``` influxd upgrade --config-file ``` To store the upgraded 2.10 configuration file in a custom location, include the `--v2-config-path` flag: ``` influxd upgrade --v2-config-path ``` 5. Follow the prompts to set up a new InfluxDB 2.10 instance. ``` Welcome to InfluxDB 2.10 upgrade! Please type your primary username: Please type your password: Please type your password again: Please type your primary organization name: Please type your primary bucket name: Please type your retention period in hours. Or press ENTER for infinite: You have entered: Username: Organization: Bucket: Retention Period: infinite Confirm? (y/n): y ``` The output of the upgrade prints to standard output. It is also saved (for troubleshooting and debugging) in the current directory to a file called `upgrade.log` located in the home directory of the user running`influxdb upgrade`. ## Post-upgrade ### Verify 1.x users were migrated to 2.10 To verify 1.x users were successfully migrated to 2.10, run[`influx v1 auth list`](/influxdb/v2/reference/cli/influx/v1/auth/list/). #### Add authorizations for external clients If your InfluxDB 1.x instance **did not have authentication enabled** and the`influx v1 auth list` doesn’t return any users, external clients connected to your 1.x instance will not be able to access InfluxDB 2.10, which requires authentication. **For these external clients to work with InfluxDB 2.10:** 1. [Manually create a v1-compatible authorization](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/#create-a-1x-compatible-authorization). 2. Update the client configuration to use the username and password associated with your v1-compatible authorization. #### Related * [influxd upgrade](/influxdb/v2/reference/cli/influxd/upgrade/) * [Manually upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/) * [Upgrade from InfluxDB 1.x to 2.10 with Docker](/influxdb/v2/install/upgrade/v1-to-v2/docker/) --- # Upgrade from InfluxDB 1.x to 2.10 with Docker Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v1-to-v2/docker/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the automated upgrade process built into the [InfluxDB 2.x Docker image](https://hub.docker.com/_/influxdb)to update InfluxDB 1.x Docker deployments to InfluxDB 2.x. * [Upgrade requirements](#upgrade-requirements) * [InfluxDB 2.x initialization credentials](#influxdb-2x-initialization-credentials) * [File system mounts](#file-system-mounts) * [Upgrade initialization mode](#upgrade-initialization-mode) * [Minimal upgrade](#minimal-upgrade) * [Upgrade with a custom InfluxDB 1.x configuration file](#upgrade-with-a-custom-influxdb-1x-configuration-file) * [Upgrade with custom paths](#upgrade-with-custom-paths) * [Use new InfluxDB tools](#use-new-influxdb-tools) * [Migrate continuous queries to tasks](#migrate-continuous-queries-to-tasks) * [Use the interactive InfluxQL shell](#use-the-interactive-influxql-shell) > [!Note] > #### Export continuous queries before upgrading > > The automated upgrade process **does not** migrate InfluxDB 1.x continuous queries (CQs) > to InfluxDB 2.x tasks (the 2.x equivalent). Export all of your CQs before upgrading to InfluxDB 2.x. > For information about exporting and migrating CQs to tasks, see[Migrate continuous queries to tasks](/influxdb/v2/upgrade/v1-to-v2/migrate-cqs/). ## Upgrade requirements InfluxDB 2.x provides a 1.x compatibility API, but expects a different storage layout on disk. To account for theses differences, the InfluxDB Docker image migrates 1.x data and into 2.x-compatible data automatically before booting the `influxd` server. * [InfluxDB 2.x initialization credentials](#influxdb-2x-initialization-credentials) * [File system mounts](#file-system-mounts) * [Upgrade initialization mode](#upgrade-initialization-mode) > [!Note] > To ensure InfluxDB reboots post-upgrade without overwriting migrated data, > the upgrade won’t run if an existing boltdb file is found at the[configured 2.x configuration path](#file-system-mounts). Find more information about the automated InfluxDB upgrade process, see [Automatically upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/automatic-upgrade/). ### InfluxDB 2.x initialization credentials The automated InfluxDB upgrade process bootstraps an initial admin user,[organization](/influxdb/v2/reference/glossary/#organization), and[bucket](/influxdb/v2/reference/glossary/#bucket) required by InfluxDB 2.x. Set the following [environment variables in your Docker container](https://docs.docker.com/search/?q=environment%20variables)to provide setup credentials: * `DOCKER_INFLUXDB_INIT_USERNAME`: Username to set for the admin user (Required). * `DOCKER_INFLUXDB_INIT_PASSWORD`: Password to set for the admin user (Required). * `DOCKER_INFLUXDB_INIT_ORG`: Name to set for the initial organization (Required). * `DOCKER_INFLUXDB_INIT_BUCKET`: Name to set for the initial bucket (Required). * `DOCKER_INFLUXDB_INIT_RETENTION`: Duration for the initial bucket’s retention period. If not set, the initial bucket will retain data forever. * `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN`: API token to associate with the admin user. If not set, InfluxDB automatically generates a token. ### File system mounts The InfluxDB upgrade process requires extra volumes to be mounted into the 2.x container. Use **environment variables** and **Docker mounts** to specify and configure the appropriate mount paths for the following: * 1.x data on disk * Custom 1.x configuration file (if any) * 2.x data on disk (`/var/lib/influxdb2`) * 2.x configuration directory (`/etc/influxdb2`) The InfluxDB upgrade process searches for mounted 1.x data and configuration files in the following priority order: 1. 1.x configuration file specified by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` environment variable 2. 1.x data directory specified by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_DIR` environment variable 3. 1.x configuration file mounted at `/etc/influxdb/influxdb.conf` 4. 1.x data directory mounted at `/var/lib/influxdb` > [!Note] > #### Avoid data loss > > By default, the automated upgrade process generates both data and configuration files > under `/var/lib/influxdb2` and `/etc/influxdb2`. > We recommend mounting volumes at both paths to avoid losing data. ### Upgrade initialization mode Set the `DOCKER_INFLUXDB_INIT_MODE` environment variable to `upgrade`. ## Minimal upgrade If you’re currently running a minimal InfluxDB 1.x deployment similar to: ```sh docker run -p 8086:8086 \ -v influxdb:/var/lib/influxdb \ influxdb:1.8 ``` **To upgrade this minimal deployment to InfluxDB 2.x:** 1. Stop the running InfluxDB 1.x container. 2. Start the InfluxDB container with the following: * Volume mount for the InfluxDB 1.x data directory * Volume mount for the InfluxDB 2.x data directory * InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable * InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables * `influxdb:2.10` Docker image ``` docker run -p 8086:8086 \ -v influxdb:/var/lib/influxdb \ -v influxdb2:/var/lib/influxdb2 \ -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ -e DOCKER_INFLUXDB_INIT_ORG=my-org \ -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ influxdb:2.10 ``` ## Upgrade with a custom InfluxDB 1.x configuration file If you’re currently running an InfluxDB 1.x deployment with a custom configuration file similar to: ```sh docker run -p 8086:8086 \ -v influxdb:/var/lib/influxdb \ -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \ influxdb:1.8 ``` **To upgrade an InfluxDB 1.x deployment with a custom configuration file to InfluxDB 2.x:** 1. Stop the running InfluxDB 1.x container. 2. Start the InfluxDB container with the following: * Volume mount for the InfluxDB 1.x data directory * Volume mount for the InfluxDB 1.x configuration file * Volume mount for the InfluxDB 2.x data directory (`/var/lib/influxdb2`) * Volume mount for the InfluxDB 2.x configuration directory (`/etc/influxdb2`) * InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable * InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables * `influxdb:2.10` Docker image ```sh docker run -p 8086:8086 \ -v influxdb:/var/lib/influxdb \ -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \ -v influxdb2:/var/lib/influxdb2 \ -v influxdb2:/etc/influxdb2 \ -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ -e DOCKER_INFLUXDB_INIT_ORG=my-org \ -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ influxdb:2.10 ``` ## Upgrade with custom paths If you’re currently running an InfluxDB 1.x deployment with the data directory and configuration file mounted at custom paths similar to: ```sh docker run -p 8086:8086 \ -v influxdb:/root/influxdb/data \ -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ influxdb:1.8 -config /root/influxdb/influxdb.conf ``` **To upgrade an InfluxDB 1.x deployment with custom paths to InfluxDB 2.x:** 1. Stop the running InfluxDB 1.x container. 2. Decide to either **keep using custom paths** or **use InfluxDB 2.x default paths**. [Keep using custom paths](#keep-using-custom-paths)[Use InfluxDB 2.x defaults](#use-influxdb-2x-defaults) To retain your custom InfluxDB 1.x paths, start the InfluxDB container with the following: * Volume mount for the InfluxDB 1.x data directory * Volume mount for the InfluxDB 1.x configuration file * Volume mount for the InfluxDB 2.x data directory * Volume mount for the InfluxDB 2.x configuration directory * InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable * InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables * InfluxDB 2.x [v1 configuration file path](#file-system-mounts) environment variable: * `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` * InfluxDB 1.x custom path environment variables: * `INFLUXD_CONFIG_PATH` * `INFLUXD_BOLT_PATH` * `INFLUXD_ENGINE_PATH` * `influxdb:2.10` Docker image ```sh docker run -p 8086:8086 \ -v influxdb:/root/influxdb/data \ -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ -v influxdb2:/root/influxdb2/data \ -v influxdb2:/root/influxdb2 \ -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ -e DOCKER_INFLUXDB_INIT_ORG=my-org \ -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ -e INFLUXD_CONFIG_PATH=/root/influxdb2/config.toml \ -e INFLUXD_BOLT_PATH=/root/influxdb2/influxdb.bolt \ -e INFLUXD_ENGINE_PATH=/root/influxdb2/engine \ influxdb:2.10 ``` To use default InfluxDB 2.x paths, start the InfluxDB container with the following: * Volume mount for the InfluxDB 1.x data directory * Volume mount for the InfluxDB 1.x configuration file * Volume mount for the InfluxDB 2.x data directory (`/var/lib/influxdb2`) * Volume mount for the InfluxDB 2.x configuration directory (`/etc/influxdb2`) * InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable * InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables * InfluxDB 2.x [v1 configuration file path](#file-system-mounts) environment variable: * `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` * `influxdb:2.10` Docker image ```sh docker run -p 8086:8086 \ -v influxdb:/root/influxdb/data \ -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ -v influxdb2:/var/lib/influxdb2 \ -v influxdb2:/etc/influxdb2 \ -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ -e DOCKER_INFLUXDB_INIT_ORG=my-org \ -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ influxdb:2.10 ``` ## Use the interactive InfluxQL shell The InfluxDB 2.10 `influx` CLI includes an interactive **InfluxQL shell** for executing InfluxQL queries. The InfluxDB 2.10 Docker image includes the `influx` CLI. To start an InfluxQL shell: 1. Start a bash session in your InfluxDB container: ``` docker exec -it influxdb /bin/bash ``` 2. Set up your [`influx` CLI authentication credentials](/influxdb/v2/tools/influx-cli/#set-up-the-influx-cli). 3. Run the `influx v1 shell` command. For more information, see: * [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) To build an interactive shell to execute **Flux** queries,[compile and build a command line Flux REPL from source](https://github.com/influxdata/flux/blob/master/README.md#getting-started). --- # Manually upgrade from InfluxDB 1.x to 2.10 Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To manually upgrade from InfluxDB 1.x to InfluxDB 2.10: 1. [Install InfluxDB 2.10](#install-influxdb-21) 2. [Migrate custom configuration settings](#migrate-custom-configuration-settings) 3. [Create DBRP mappings](#create-dbrp-mappings) 4. [Create authorizations](#create-authorizations) 5. [Migrate time series data](#migrate-time-series-data) 6. [Migrate continuous queries](#migrate-continuous-queries) 7. [Query data with InfluxQL](#query-data-with-influxql) ## Install InfluxDB 2.10 [Download, install, and set up InfluxDB 2.10](/influxdb/v2/get-started/). > [!Note] > #### Required 2.x credentials > > All InfluxDB 2.10 `influx` CLI examples below assume the required **host**,**organization**, and **API token** credentials are provided by your[`influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials). ## Migrate custom configuration settings If you’re using custom configuration settings in your InfluxDB 1.x instance, do the following: 1. Compare 1.x and 2.10 configuration settings: [](#view-configuration-option-parity) View configuration option parity | 1.x configuration option | 2.10 configuration option | |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------| | **[data]** | | | dir | [engine-path](/influxdb/v2/reference/config-options/#engine-path) | | wal-dir | [engine-path](/influxdb/v2/reference/config-options/#engine-path) | | wal-fsync-delay | [storage-wal-fsync-delay](/influxdb/v2/reference/config-options/#storage-wal-fsync-delay) | | index-version | | | trace-logging-enabled | | | query-log-enabled | | | strict-error-handling | | | validate-keys | [storage-validate-keys](/influxdb/v2/reference/config-options/#storage-validate-keys) | | cache-max-memory-size | [storage-cache-max-memory-size](/influxdb/v2/reference/config-options/#storage-cache-max-memory-size) | | cache-snapshot-memory-size | [storage-cache-snapshot-memory-size](/influxdb/v2/reference/config-options/#storage-cache-snapshot-memory-size) | |cache-snapshot-write-cold-duration|[storage-cache-snapshot-write-cold-duration](/influxdb/v2/reference/config-options/#storage-cache-snapshot-write-cold-duration)| | compact-full-write-cold-duration | [storage-compact-full-write-cold-duration](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration) | | max-concurrent-compactions | [storage-max-concurrent-compactions](/influxdb/v2/reference/config-options/#storage-max-concurrent-compactions) | | compact-throughput | (not exposed as a separate option; see `storage-compact-throughput` notes) | | compact-throughput-burst | [storage-compact-throughput-burst](/influxdb/v2/reference/config-options/#storage-compact-throughput-burst) | | tsm-use-madv-willneed | [storage-tsm-use-madv-willneed](/influxdb/v2/reference/config-options/#storage-tsm-use-madv-willneed) | | max-series-per-database | | | max-values-per-tag | | | max-index-log-file-size | [storage-max-index-log-file-size](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size) | | series-id-set-cache-size | [storage-series-id-set-cache-size](/influxdb/v2/reference/config-options/#storage-series-id-set-cache-size) | | | | | **[retention]** | | | check-interval | [storage-retention-check-interval](/influxdb/v2/reference/config-options/#storage-retention-check-interval) | | | | | **[shard-precreation]** | | | check-interval | [storage-shard-precreator-check-interval](/influxdb/v2/reference/config-options/#storage-shard-precreator-check-interval) | | advance-period | [storage-shard-precreator-advance-period](/influxdb/v2/reference/config-options/#storage-shard-precreator-advance-period) | | | | | **[http]** | | | flux-enabled | | | flux-log-enabled | [flux-log-enabled](/influxdb/v2/reference/config-options/#flux-log-enabled) | | bind-address | [http-bind-address](/influxdb/v2/reference/config-options/#http-bind-address) | | auth-enabled | | | realm | | | log-enabled | | | suppress-write-log | | | access-log-path | | | access-log-status-filters | | | write-tracing | | | pprof-enabled | [pprof-disabled](/influxdb/v2/reference/config-options/#pprof-disabled) | | pprof-auth-enabled | | | debug-pprof-enabled | | | ping-auth-enabled | | | https-enabled | | | https-certificate | [tls-cert](/influxdb/v2/reference/config-options/#tls-cert) | | https-private-key | [tls-key](/influxdb/v2/reference/config-options/#tls-key) | | shared-secret | | | max-row-limit | | | max-connection-limit | | | unix-socket-enabled | | | bind-socket | | | max-body-size | | | max-concurrent-write-limit | | | max-enqueued-write-limit | | | enqueued-write-timeout | [http-write-timeout](/influxdb/v2/reference/config-options/#http-write-timeout) | | | | | **[logging]** | | | format | | | level | [log-level](/influxdb/v2/reference/config-options/#log-level) | | suppress-logo | | | | | | **[tls]** | | | ciphers | [tls-strict-ciphers](/influxdb/v2/reference/config-options/#tls-strict-ciphers) | | min-version | [tls-min-version](/influxdb/v2/reference/config-options/#tls-min-version) | | max-version | | #### 1.x configuration groups not in 2.10 #### The following 1.x configuration groups **do not** apply to InfluxDB 2.10: * meta * coordinator * monitor * subscriber * graphite * collectd * opentsdb * udp * continuous\_queries 2. Apply your 1.x custom settings to the comparable InfluxDB 2.10 settings using`influxd` flags, environment variables, or a 2.10 configuration file. For more information about configuring InfluxDB 2.10, see[Configuration options](/influxdb/v2/reference/config-options/). 3. **Restart `influxd`**. ## Create DBRP mappings InfluxDB database and retention policy (DBRP) mappings associate database and retention policy combinations with InfluxDB 2.10 [buckets](/influxdb/v2/reference/glossary/#bucket). These mappings allow InfluxDB 1.x clients to successfully query and write to InfluxDB 2.10 buckets while using the 1.x DBRP convention. *For more information about DBRP mapping, see[Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).* **To map a DBRP combination to an InfluxDB 2.10 bucket:** 1. **Create a bucket** [Create an InfluxDB 2.10 bucket](/influxdb/v2/admin/buckets/create-bucket/). We recommend creating a bucket for each unique 1.x database and retention policy combination using the following naming convention: ``` # Naming convention db-name/rp-name # Example telegraf/autogen ``` 2. **Create a DBRP mapping** Use the [`influx v1 dbrp create` command](/influxdb/v2/reference/cli/influx/v1/dbrp/create/)to create a DBRP mapping. Provide the following: * database name * retention policy name *(not retention period)* * [bucket ID](/influxdb/v2/admin/buckets/view-buckets/) * *(optional)* `--default` flag if you want the retention policy to be the default retention policy for the specified database [DB with one RP](#db-with-one-rp)[DB with multiple RPs](#db-with-multiple-rps) ``` influx v1 dbrp create \ --db example-db \ --rp example-rp \ --bucket-id 00xX00o0X001 \ --default ``` ``` # Create telegraf/autogen DBRP mapping with autogen # as the default RP for the telegraf DB influx v1 dbrp create \ --db telegraf \ --rp autogen \ --bucket-id 00xX00o0X001 \ --default # Create telegraf/downsampled-daily DBRP mapping that # writes to a different bucket influx v1 dbrp create \ --db telegraf \ --rp downsampled-daily \ --bucket-id 00xX00o0X002 ``` 3. **Confirm the DBRP mapping was created** Use the [`influx v1 dbrp list`](/influxdb/v2/reference/cli/influx/v1/dbrp/list/) to list existing DBRP mappings. ``` influx v1 dbrp list ``` For information about managing DBRP mappings, see the[`influx v1 dbrp` command documentation](/influxdb/v2/reference/cli/influx/v1/dbrp/). ## Create authorizations InfluxDB 2.10 requires authentication and provides two authentication methods: * [Token authentication](#token-authentication) * [1.x compatible authorizations](#1x-compatible-authorizations) ### Token authentication Use [InfluxDB 2.10 token authentication](/influxdb/v2/admin/tokens/) to authenticate requests to InfluxDB 2.10. ##### Recommended if: * Your 1.x instance **does not have authentication enabled**. > [!Note] > #### Use tokens with basic authentication > > To use tokens with InfluxDB clients that require an InfluxDB username and password, > provide an arbitrary user name and pass the token as the password. ### 1.x-compatible authorizations InfluxDB 2.10 provides a [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/)that lets you authenticate using a username and password as in InfluxDB 1.x. If authentication is enabled in your InfluxDB 1.x instance,[create a 1.x-compatible authorization](#create-a-1x-compatible-authorization)with the same username and password as your InfluxDB 1.x instance to allow external clients to connect to your InfluxDB 2.10 instance without any change. ##### Recommended if: * Your 1.x instance **has authentication enabled**. * You’re using **InfluxDB 1.x clients or client libraries** configured with InfluxDB usernames and passwords. > [!Note] > 1.x compatibility authorizations are separate from credentials used to log > into the InfluxDB 2.10 user interface (UI). #### Create a 1.x-compatible authorization Use the InfluxDB 2.10 [`influx v1 auth create` command](/influxdb/v2/reference/cli/influx/v1/auth/create/)to create a 1.x-compatible authorization that grants read/write permissions to specific 2.10 buckets. Provide the following: * list of [bucket IDs](/influxdb/v2/admin/buckets/view-buckets/) to grant read or write permissions to * new v1 auth username * new v1 auth password *(when prompted)* [Single bucket](#single-bucket)[Multiple buckets](#multiple-buckets) ```sh influx v1 auth create \ --read-bucket 00xX00o0X001 \ --write-bucket 00xX00o0X001 \ --username example-user ``` ```sh influx v1 auth create \ --read-bucket 00xX00o0X001 \ --read-bucket 00xX00o0X002 \ --write-bucket 00xX00o0X001 \ --write-bucket 00xX00o0X002 \ --username example-user ``` For information about managing 1.x compatible authorizations, see the[`influx v1 auth` command documentation](/influxdb/v2/reference/cli/influx/v1/auth/). ## Migrate time series data To migrate time series data from your InfluxDB 1.x instance to InfluxDB 2.10: 1. Use the **InfluxDB 1.x** [`influx_inspect export` command](/influxdb/v1/tools/influx_inspect/#export)to export time series data as line protocol. Include the `-lponly` flag to exclude comments and the data definition language (DDL) from the output file. *We recommend exporting each DBRP combination separately to easily write data to a corresponding InfluxDB 2.10 bucket.* ``` # Syntax influx_inspect export \ -database \ -retention \ -out \ -lponly # Example influx_inspect export \ -database example-db \ -retention example-rp \ -out /path/to/example-db_example-rp.lp \ -lponly ``` 2. Use the **InfluxDB 2.10** [`influx write` command](/influxdb/v2/reference/cli/influx/write/)to write the exported line protocol to InfluxDB 2.10. ``` # Syntax influx write \ --bucket \ --file # Example influx write \ --bucket example-db/example-rp \ --file /path/to/example-db_example-rp.lp ``` 3. Repeat steps 1-2 for each bucket. ## Migrate continuous queries For information about migrating InfluxDB 1.x continuous queries to InfluxDB 2.10 tasks, see [Migrate continuous queries to tasks](/influxdb/v2/upgrade/v1-to-v2/migrate-cqs/). ## Query data with InfluxQL InfluxDB 2.10 supports querying data with both Flux and InfluxQL. For more information about querying InfluxDB 2.10 with InfluxQL, see [Query data with InfluxQL](/influxdb/v2/query-data/influxql/). #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [Migrate continuous queries to tasks](/influxdb/v2/install/upgrade/v1-to-v2/migrate-cqs/) | 1.x configuration option | 2.10 configuration option | | --- | --- | | 1.x configuration option | 2.10 configuration option | | [data] | | | dir | engine-path | | wal-dir | engine-path | | wal-fsync-delay | storage-wal-fsync-delay | | index-version | | | trace-logging-enabled | | | query-log-enabled | | | strict-error-handling | | | validate-keys | storage-validate-keys | | cache-max-memory-size | storage-cache-max-memory-size | | cache-snapshot-memory-size | storage-cache-snapshot-memory-size | | cache-snapshot-write-cold-duration | storage-cache-snapshot-write-cold-duration | | compact-full-write-cold-duration | storage-compact-full-write-cold-duration | | max-concurrent-compactions | storage-max-concurrent-compactions | | compact-throughput | (not exposed as a separate option; see storage-compact-throughput notes) | | compact-throughput-burst | storage-compact-throughput-burst | | tsm-use-madv-willneed | storage-tsm-use-madv-willneed | | max-series-per-database | | | max-values-per-tag | | | max-index-log-file-size | storage-max-index-log-file-size | | series-id-set-cache-size | storage-series-id-set-cache-size | | | | | [retention] | | | check-interval | storage-retention-check-interval | | | | | [shard-precreation] | | | check-interval | storage-shard-precreator-check-interval | | advance-period | storage-shard-precreator-advance-period | | | | | [http] | | | flux-enabled | | | flux-log-enabled | flux-log-enabled | | bind-address | http-bind-address | | auth-enabled | | | realm | | | log-enabled | | | suppress-write-log | | | access-log-path | | | access-log-status-filters | | | write-tracing | | | pprof-enabled | pprof-disabled | | pprof-auth-enabled | | | debug-pprof-enabled | | | ping-auth-enabled | | | https-enabled | | | https-certificate | tls-cert | | https-private-key | tls-key | | shared-secret | | | max-row-limit | | | max-connection-limit | | | unix-socket-enabled | | | bind-socket | | | max-body-size | | | max-concurrent-write-limit | | | max-enqueued-write-limit | | | enqueued-write-timeout | http-write-timeout | | | | | [logging] | | | format | | | level | log-level | | suppress-logo | | | | | | [tls] | | | ciphers | tls-strict-ciphers | | min-version | tls-min-version | | max-version | | --- # Migrate continuous queries to tasks Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v1-to-v2/migrate-cqs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB OSS 2.10 replaces 1.x continuous queries (CQs) with **InfluxDB tasks**. To migrate continuous queries to InfluxDB 2.10 tasks, do the following: 1. [Output all InfluxDB 1.x continuous queries](#output-all-influxdb-1x-continuous-queries) 2. [Convert continuous queries to Flux queries](#convert-continuous-queries-to-flux-queries) 3. [Create new InfluxDB tasks](#create-new-influxdb-tasks) ## Output all InfluxDB 1.x continuous queries If using the `influxd upgrade` command, by default, all continuous queries are output to `~/continuous_queries.txt` during the upgrade process. To customize the destination path of the continuous queries file, use the `--continuous-query-export-path` flag with the `influxd upgrade` command. ```sh influxd upgrade --continuous-query-export-path /path/to/continuous_queries.txt ``` **To manually output continuous queries:** 1. Use the **InfluxDB 1.x `influx` interactive shell** to run `SHOW CONTINUOUS QUERIES`: ``` $ influx Connected to http://localhost:8086 version InfluxDB shell version: > SHOW CONTINUOUS QUERIES ``` 2. Copy and save the displayed continuous queries. ## Convert continuous queries to Flux queries To migrate InfluxDB 1.x continuous queries to InfluxDB 2.10 tasks, convert the InfluxQL query syntax to Flux. The majority of continuous queries are simple downsampling queries and can be converted quickly using the [`aggregateWindow()` function](/flux/v0/stdlib/universe/aggregatewindow/). For example: ##### Example continuous query ```sql CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" BEGIN SELECT mean("example-field") INTO "my-db"."example-rp"."average-example-measurement" FROM "example-measurement" GROUP BY time(1h) END ``` ##### Equivalent Flux task ```js option task = {name: "downsample-daily", every: 1d} from(bucket: "my-db/") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field") |> aggregateWindow(every: 1h, fn: mean) |> set(key: "_measurement", value: "average-example-measurement") |> to(org: "example-org", bucket: "my-db/example-rp") ``` ### Convert InfluxQL continuous queries to Flux Review the following statements and clauses to see how to convert your CQs to Flux: * [ON clause](#on-clause) * [SELECT statement](#select-statement) * [INTO clause](#into-clause) * [FROM clause](#from-clause) * [AS clause](#as-clause) * [WHERE clause](#where-clause) * [GROUP BY clause](#group-by-clause) * [RESAMPLE clause](#resample-clause) #### ON clause The `ON` clause defines the database to query. In InfluxDB OSS 2.10, database and retention policy combinations are mapped to specific buckets (for more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/)). Use the [`from()` function](/flux/v0/stdlib/influxdata/influxdb/from/)to specify the bucket to query: ###### InfluxQL ```sql CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" -- ... ``` ###### Flux ``` from(bucket: "my-db/") // ... ``` #### SELECT statement The `SELECT` statement queries data by field, tag, and time from a specific measurement.`SELECT` statements can take many different forms and converting them to Flux depends on your use case. For information about Flux and InfluxQL function parity, see[Flux vs InfluxQL](/influxdb/v2/reference/syntax/flux/flux-vs-influxql/#influxql-and-flux-parity). See [other resources available to help](#other-helpful-resources). #### INTO clause The `INTO` clause defines the measurement to write results to.`INTO` also supports fully qualified measurements that include the database and retention policy. In InfluxDB OSS 2.10, database and retention policy combinations are mapped to specific buckets (for more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/)). To write to a measurement different than the measurement queried, use[`set()`](/flux/v0/stdlib/universe/set/) or[`map()`](/flux/v0/stdlib/universe/map/)to change the measurement name. Use the `to()` function to specify the bucket to write results to. ###### InfluxQL ```sql -- ... INTO "example-db"."example-rp"."example-measurement" -- ... ``` ###### Flux [set()](#set)[map()](#map) ```js // ... |> set(key: "_measurement", value: "example-measurement") |> to(bucket: "example-db/example-rp") ``` ```js // ... |> map(fn: (r) => ({ r with _measurement: "example-measurement"})) |> to(bucket: "example-db/example-rp") ``` ##### Write pivoted data to InfluxDB InfluxDB 1.x query results include a column for each field. InfluxDB 2.10 does not do this by default, but it is possible with[`pivot()`](/flux/v0/stdlib/universe/pivot)or [`schema.fieldsAsCols()`](/flux/v0/stdlib/influxdata/influxdb/schema/fieldsascols/). If you use `to()` to write *pivoted data* back to InfluxDB 2.10, each field column is stored as a tag. To write pivoted fields back to InfluxDB as fields, import the `experimental` package and use the [`experimental.to()` function](/flux/v0/stdlib/experimental/to/). ###### InfluxQL ```sql CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" BEGIN SELECT mean("example-field-1"), mean("example-field-2") INTO "example-db"."example-rp"."example-measurement" FROM "example-measurement" GROUP BY time(1h) END ``` ###### Flux ```js // ... from(bucket: "my-db/") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field-1" or r._field == "example-field-2") |> aggregateWindow(every: task.every, fn: mean) |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") |> experimental.to(bucket: "example-db/example-rp") ``` #### FROM clause The from clause defines the measurement to query. Use the [`filter()` function](/flux/v0/stdlib/universe/filter/)to specify the measurement to query. ###### InfluxQL ```sql -- ... FROM "example-measurement" -- ... ``` ###### Flux ```js // ... |> filter(fn: (r) => r._measurement == "example-measurement") ``` #### AS clause The `AS` clause changes the name of the field when writing data back to InfluxDB. Use [`set()`](/flux/v0/stdlib/universe/set/)or [`map()`](/flux/v0/stdlib/universe/map/)to change the field name. ###### InfluxQL ```sql -- ... AS newfield -- ... ``` ###### Flux [set()](#set-2)[map()](#map-2) ```js // ... |> set(key: "_field", value: "newfield") ``` ```js // ... |> map(fn: (r) => ({ r with _field: "newfield"})) ``` #### WHERE clause The `WHERE` clause uses predicate logic to filter results based on fields, tags, or timestamps. Use the [`filter()` function](/flux/v0/stdlib/universe/filter/)and Flux [comparison operators](/flux/v0/spec/operators/#comparison-operators)to filter results based on fields and tags. Use the [`range()` function](/flux/v0/stdlib/universe/range/) to filter results based on timestamps. ###### InfluxQL ```sql -- ... WHERE "example-tag" = "foo" AND time > now() - 7d ``` ###### Flux ```js // ... |> range(start: -7d) |> filter(fn: (r) => r["example-tag"] == "foo") ``` #### GROUP BY clause The InfluxQL `GROUP BY` clause groups data by specific tags or by time (typically to calculate an aggregate value for windows of time). ##### Group by tags Use the [`group()` function](/flux/v0/stdlib/universe/group/)to modify the [group key](/flux/v0/get-started/data-model/#group-key) and change how data is grouped. ###### InfluxQL ```sql -- ... GROUP BY "location" ``` ###### Flux ```js // ... |> group(columns: ["location"]) ``` ##### Group by time Use the [`aggregateWindow()` function](//flux/v0/stdlib/universe/aggregatewindow/)to group data into time windows and perform an aggregation on each window. In CQs, the interval specified in the `GROUP BY time()` clause determines the CQ execution interval. Use the `GROUP BY time()` interval to set the `every` task option. ###### InfluxQL ```sql -- ... SELECT MEAN("example-field") FROM "example-measurement" GROUP BY time(1h) ``` ###### Flux ```js option task = {name: "task-name", every: 1h} // ... |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field") |> aggregateWindow(every: task.every, fn: mean) ``` #### RESAMPLE clause The CQ `RESAMPLE` clause uses data from the last specified duration to calculate a new aggregate point. The `EVERY` interval in `RESAMPLE` defines how often the CQ runs. The `FOR` interval defines the total time range queried by the CQ. To accomplish this same functionality in a Flux task, set the `start` parameter in the `range()` function to the negative `FOR` duration. Define the task execution interval in the `task` options. For example: ###### InfluxQL ```sql CREATE CONTINUOUS QUERY "resample-example" ON "my-db" RESAMPLE EVERY 1m FOR 30m BEGIN SELECT exponential_moving_average(mean("example-field"), 30) INTO "resample-average-example-measurement" FROM "example-measurement" WHERE region = 'example-region' GROUP BY time(1m) END ``` ###### Flux ```js option task = {name: "resample-example", every: 1m} from(bucket: "my-db/") |> range(start: -30m) |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field" and r.region == "example-region") |> aggregateWindow(every: 1m, fn: mean) |> exponentialMovingAverage(n: 30) |> set(key: "_measurement", value: "resample-average-example-measurement") |> to(bucket: "my-db/") ``` ## Create new InfluxDB tasks After converting your continuous query to Flux, use the Flux query to[create a new task](/influxdb/v2/process-data/manage-tasks/create-task/). ## Other helpful resources The following resources are available and may be helpful when converting continuous queries to Flux tasks. ##### Documentation * [Get started with Flux](/flux/v0/get-started/) * [Query data with Flux](/influxdb/v2/query-data/flux/) * [Common tasks](/influxdb/v2/process-data/common-tasks/#downsample-data-with-influxdb) ##### Community * Post in the [InfluxData Community](https://community.influxdata.com/) * Ask in the [InfluxDB Community Slack](https://influxdata.com/slack) #### Related * [Get started with Flux and InfluxDB](/influxdb/v2/query-data/get-started/) * [Query data with Flux](/influxdb/v2/query-data/flux/) * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [Common data processing tasks](/influxdb/v2/process-data/common-tasks/) --- # Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0 Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v2-beta-to-v2/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.x, first follow these steps to upgrade your InfluxDB beta instance, data, and resources to[InfluxDB 2.0](https://github.com/influxdata/influxdb/releases/tag/v2.0.9). Depending on how you have set up your InfluxDB beta instance and the importance of your existing resources and data, you can determine which steps apply to you–for example, if you don’t want to migrate your data and resources, then you can skip those sections. 1. [Disable existing integrations](#1-disable-existing-integrations) 2. [Stop existing InfluxDB beta instance](#2-stop-existing-influxdb-beta-instance) 3. [(Optional) Rename existing InfluxDB binaries](#3-optional-rename-existing-influxdb-binaries) 4. [Move existing data and start the latest InfluxDB](#4-move-existing-data-and-start-the-latest-influxdb) 5. [Start old InfluxDB beta instance](#5-start-old-influxdb-beta-instance) 6. [Create configuration profiles for the InfluxDB CLI](#6-create-configuration-profiles-for-the-influxdb-cli) 7. [Copy all resources from old instance to the new one](#7-copy-all-resources-from-old-instance-to-the-new-one) 8. [Set up integrations to point to new instance](#8-set-up-integrations-to-point-to-new-instance) 9. [Load historical data into new instance](#9-load-historical-data-into-new-instance) 10. [Verify InfluxDB resources, data, and integrations](#verify-influxdb-resources-data-and-integrations) 11. [Upgrade to the latest InfluxDB v2 version](#upgrade-to-the-latest-influxdb-v2-version) ### Why is this manual process required? To ensure that existing InfluxQL integrations work with the latest release, we had to make breaking changes to the underlying storage engine for InfluxDB 2.0. > [!Note] > If you have questions while upgrading,[open an issue](https://github.com/influxdata/influxdb/issues)or join the [Community Slack workspace](https://influxcommunity.slack.com/) to > get immediate help. ## 1. Disable existing integrations To begin, shut off all integrations that are reading from, writing to, or monitoring your InfluxDB instance. This includes Telegraf, client libraries, and any custom applications. ## 2. Stop existing InfluxDB beta instance Next, shut down your existing InfluxDB beta instance. You can manually stop the individual process using **Control+c**(or by finding the process ID with `ps aux | grep -i influxd` and using `sudo kill -9 `). If you’ve set `influxd` to run as a system process, follow the same steps you would use to disable any system process. ## 3. (Optional) Rename existing InfluxDB binaries To easily identify your existing InfluxDB binaries, rename them `influx_old` and `influxd_old`. This is helpful if you’ve installed the binaries in your `$PATH`. We use the names `influxd_old` for this guide, but you can use whatever you like. ## 4. Move existing data and start the latest InfluxDB If you haven’t already,[download and install InfluxDB 2.0](https://github.com/influxdata/influxdb/releases/tag/v2.0.9)for your system, but don’t run the setup process yet. Be careful not to overwrite the existing binaries. To move data between the two instances, first configure both the old and new instances of InfluxDB to run at the same time. If you download the latest InfluxDB beta and try to start it with existing data, most likely it won’t start and the following error message appears: ``` Incompatible InfluxDB 2.0 version found. Move all files outside of engine_path before influxd will start. ``` To avoid this error, run the following command to move your existing data to a another location (anywhere you like): ```sh mv ~/.influxdbv2 ~/.influxdbv2_old ``` Start the latest InfluxDB version by running: ```sh influxd ``` > [!Note] > If you were using specific [command line flags](/influxdb/v2/reference/cli/influxd/#flags) for InfluxDB beta, you can use those same command line flags. Because the data folder path has changed for InfluxDB v2, everything will be empty. You can visit http://localhost:8086 in your browser and see a setup page, but don’t go through the setup process yet. ## 5. Start old InfluxDB beta instance You can now start your old InfluxDB instance and point it to your old data directory: ```sh ./influxd_old \ --bolt-path ~/.influxdbv2_old/influxd.bolt \ --engine-path ~/.influxdbv2_old/engine ``` Double-check that InfluxDB is working by visiting your InfluxDB beta instance URL (probably http://localhost:9999) and logging in. Your data and resources should still be there. > [!Note] > If you see a “missing migration” error, manually edit your bolt file to remove > the migration–for example: > > 1. *Recommended*: **Backup your old `influxd.bolt` file**–manually editing this > file could cause you to lose all your data. > 2. Use [BoltBrowser](https://github.com/br0xen/boltbrowser) to open and edit > your old `influxd.bolt` file > 3. To remove the migration, highlight the record under the `migrationsv1` path > and press **D**. Now, the new instance and old instance of InfluxDB are running simultaneously. ## 6. Create configuration profiles for the InfluxDB CLI Next, set up your InfluxDB CLI to connect to your old and new instances. ### a. Configure old profile If you’ve used the CLI before, copy your existing `configs` file to your new data directory: ```sh cp ~/.influxdbv2_old/configs ~/.influxdbv2/configs ``` *Recommended*: rename the old configuration file to something like `influx_old`. ```toml [influx_old] url = "http://localhost:9999" token = "" org = "influxdata" active = true ``` If you’ve never used the CLI before, create a new configuration profile to connect to your old instance using the `influx config` command. ```sh influx config create \ --config-name influx_old \ --host-url http://localhost:9999 \ --org influxdata \ --token ``` To list configurations, enter the following command: ```sh influx config ls ``` The output lists the configuration profile for your old instance: ``` Active Name URL Org * influx_old http://localhost:9999 InfluxData ``` ### b. Configure new profile Next set up your new instance, which automatically creates a configuration profile for you. The `influx setup` command automatically creates a config profile named `default`. Make sure you don’t already have a profile with that name before you run the command. Run the `influx setup` command and answer the prompts. **Don’t use the same bucket name** as a bucket in your existing instance. Otherwise, a name collision and file conflict occurs when you try to copy your resources. You’ll delete this dummy bucket later, after you migrate your resources. ```sh influx setup ``` The command prompts you to configure credentials: ``` Welcome to InfluxDB 2.0! Please type your primary username: admin Please type your password: Please type your password again: Please type your primary organization name: InfluxData Please type your primary bucket name: dummy_bucket Please type your retention period in hours. Or press ENTER for infinite.: You have entered: Username: admin Organization: InfluxData Bucket: dummy_bucket Retention Period: infinite Confirm? (y/n): y Config default has been stored in /Users/rsavage/.influxdbv2/configs. User Organization Bucket admin InfluxData dummy_bucket ``` You now have two config profiles: one named `default` that points to your new instance, and one named `influx_old` that points to your old instance. ```sh $ influx config ls Active Name URL Org default http://localhost:8086 InfluxData * influx_old http://localhost:9999 InfluxData ``` You can now send commands to each of them as needed using the [`-c, --active-config`](/influxdb/v2/reference/cli/influx/#commands) option in the CLI. ## 7. Copy all resources from old instance to the new one Use config profiles to export all resources from the old instance and apply them to your new instance. (The only things that will not be copied over are [scraper configurations](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/). You will need to manually reconfigure those.) Copy all your existing InfluxDB resources, such as dashboards, tasks, and alerts, to your new instance by running the following command: ```sh influx export all -c influx_old | influx apply -c default ``` (To learn more about this command, see[`influx export`](/influxdb/v2/reference/cli/influx/export/) and[`influx apply`](/influxdb/v2/reference/cli/influx/apply/).) The output is a list of the resources created in your new instance. If successful, you can delete the bucket created during the setup. ```sh LABELS +add | -remove | unchanged +-----+------------------------+----+---------------+---------+-------------+ | +/- | METADATA NAME | ID | RESOURCE NAME | COLOR | DESCRIPTION | +-----+------------------------+----+---------------+---------+-------------+ | + | tasty-northcutt-c9c001 | | something | #326BBA | | +-----+------------------------+----+---------------+---------+-------------+ | TOTAL | 1 | +-----+------------------------+----+---------------+---------+-------------+ ​ BUCKETS +add | -remove | unchanged +-----+------------------------+----+---------------+------------------+-------------+ | +/- | METADATA NAME | ID | RESOURCE NAME | RETENTION PERIOD | DESCRIPTION | +-----+------------------------+----+---------------+------------------+-------------+ | + | fasting-taussig-c9c007 | | apps | 0s | | +-----+------------------------+----+---------------+------------------+-------------+ +-----+------------------------+----+---------------+------------------+-------------+ | + | great-davinci-c9c005 | | new_telegraf | 0s | | +-----+------------------------+----+---------------+------------------+-------------+ +-----+------------------------+----+---------------+------------------+-------------+ | + | stubborn-hugle-c9c003 | | telegraf | 719h59m59s | | +-----+------------------------+----+---------------+------------------+-------------+ | TOTAL | 3 | +-----+------------------------+----+---------------+------------------+-------------+ ``` Now, you have all the resources from your old instance stored in your new instance. Sign in to your new instance (by default http://localhost:8086) and take a look. You will see dashboards, but you haven’t yet migrated your old data. ## 8. Set up integrations to point to new instance Re-enable any integrations you disabled in step 2. You will need to re-enable Telegraf, client libraries, custom applications, or third-party data sinks using new tokens and credentials. ## 9. Load historical data into new instance Use the CLI to export and then re-import your data using the command below. (For the range, pick a time before your bucket’s retention period, or something a really long time ago if you have an unlimited retention period.) ```sh influx query -c influx_old \ 'from(bucket: "my-bucket") |> range(start: -3y)' --raw > my-bucket.csv ``` Then write to the new bucket: ```sh influx write -c default --format csv -b my-bucket -f my-bucket.csv ``` Repeat that process for each bucket. ## Verify InfluxDB resources, data, and integrations Verify that the latest version of InfluxDB 2.10 is running with all your resources, data, and integrations configured. Double-check that everything is there and it is working as expected. Once you’re set up with the latest InfluxDB, you can safely turn off your old instance and archive the previous data directory. ## Upgrade to the latest InfluxDB v2 version Follow steps to [upgrade from InfluxDB 2.0 to the latest InfluxDB 2.x version](/influxdb/v2/install/upgrade/v2-to-v2/). #### Related * [Upgrade from InfluxDB 2.x to 2.10](/influxdb/v2/install/upgrade/v2-to-v2/) --- # Upgrade from InfluxDB 2.x to 2.10 Source: https://docs.influxdata.com/influxdb/v2/install/upgrade/v2-to-v2/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Upgrade to InfluxDB 2.10 from an earlier version of InfluxDB 2.x. > [!Note] > #### InfluxDB 2.0 beta-16 or earlier > > If you’re upgrading from InfluxDB 2.0 beta-16 or earlier, you must first[upgrade to InfluxDB 2.0](/influxdb/v2/install/upgrade/v2-beta-to-v2/), > and then complete the steps below. [macOS](#macos)[Linux](#linux)[Windows](#windows)[Docker](#docker) Do one of the following: * [Use homebrew to upgrade](#use-homebrew-to-upgrade) * [Manually upgrade](#manually-upgrade) ### Use homebrew to upgrade ```sh brew upgrade influxdb ``` ### Manually upgrade To manually upgrade, [download and install the latest version of InfluxDB 2.10 for macOS](/influxdb/v2/install/?t=macos/#manually-download-and-install-for-macos)in place of your current 2.x version. [Download and install the latest version of InfluxDB 2.10 for Linux](/influxdb/v2/install/?t=Linux#download-and-install-influxdb-v2)in place of your current 2.x version. [Download and install the latest version of InfluxDB 2.10 for Windows](/influxdb/v2/install/?t=Windows)in place of your current 2.x version. To upgrade to InfluxDB 2.10 with Docker, update your Docker image to use the latest InfluxDB image. ```sh influxdb:2.10.0 ``` #### Related * [influxd downgrade](/influxdb/v2/reference/cli/influxd/downgrade/) * [Install InfluxDB OSS v2](/influxdb/v2/install/) --- # Install InfluxDB using Docker Compose Source: https://docs.influxdata.com/influxdb/v2/install/use-docker-compose/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use Docker Compose to install and set up InfluxDB v2, the time series platform purpose-built to collect, store, process and visualize metrics and events. * [Set up using Docker Compose secrets](#set-up-using-docker-compose-secrets) * [Run InfluxDB CLI commands in a container](#run-influxdb-cli-commands-in-a-container) * [Manage files in mounted volumes](#manage-files-in-mounted-volumes) ## Set up using Docker Compose secrets > [!Tip] > When you use Docker Compose to create an InfluxDB container, you can use > Compose [`secrets`](https://docs.docker.com/compose/use-secrets/) to control > access to sensitive credentials such as username, password, and token and > prevent leaking them in your `docker inspect` output. The `influxdb` Docker image provides the following environment variables to use with Compose `secrets`: * `DOCKER_INFLUXDB_INIT_USERNAME_FILE`: the container’s path to the file that contains the username for your initial [user](/influxdb/v2/admin/users/). * `DOCKER_INFLUXDB_INIT_PASSWORD_FILE`: the container’s path to the file that contains the password for your initial [user](/influxdb/v2/admin/users/). * `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE`: the container’s path to the file that contains a token to use for your initial[Operator token](/influxdb/v2/admin/tokens/#operator-token). If you don’t specify an initial token, InfluxDB generates one for you. Follow steps to set up and run InfluxDB using Docker Compose and `secrets`: 1. If you haven’t already, install[Docker Desktop](https://www.docker.com/get-started/) for your system. 2. Copy the following `compose.yaml` into your project directory. ``` # compose.yaml services: influxdb2: image: influxdb:2 ports: - 8086:8086 environment: DOCKER_INFLUXDB_INIT_MODE: setup DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token DOCKER_INFLUXDB_INIT_ORG: docs DOCKER_INFLUXDB_INIT_BUCKET: home secrets: - influxdb2-admin-username - influxdb2-admin-password - influxdb2-admin-token volumes: - type: volume source: influxdb2-data target: /var/lib/influxdb2 - type: volume source: influxdb2-config target: /etc/influxdb2 secrets: influxdb2-admin-username: file: ~/.env.influxdb2-admin-username influxdb2-admin-password: file: ~/.env.influxdb2-admin-password influxdb2-admin-token: file: ~/.env.influxdb2-admin-token volumes: influxdb2-data: influxdb2-config: ``` *For more information about initialization environment variables, see the [upgrade guide](/influxdb/v2/install/upgrade/v1-to-v2/docker/).* 3. For each secret in `compose.yaml`, create a file that contains the secret value–for example: * `~/.env.influxdb2-admin-username`: ``` admin ``` * `~/.env.influxdb2-admin-password`: ``` MyInitialAdminPassword ``` * `~/.env.influxdb2-admin-token`: ``` MyInitialAdminToken0== ``` 4. To set up and run InfluxDB, enter the following command in your terminal: ``` docker compose up influxdb2 ``` At runtime, the `influxdb` image: 1. Mounts `secrets` files from your host filesystem to `/run/secrets/`in the container. 2. Assigns the environment variables to the specified files–for example: ``` environment: DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token ``` 3. Retrieves the secrets from the mounted files and runs setup. 4. Starts InfluxDB. 5. Runs any custom initialization scripts mounted inside the container’s`/docker-entrypoint-initdb.d/` path. If successful, InfluxDB initializes the user, password, organization, bucket, and *[Operator token](/influxdb/v2/admin/tokens/#operator-token)*, and then logs to stdout. You can view the InfluxDB UI at [http://localhost:8086](http://localhost:8086). Although Docker prevents inadvertently exposing secrets (for example, in`docker inspect` output), a user that has access to the running container’s filesystem can view the secrets. ### Run InfluxDB CLI commands in a container After you start a container using the `influxdb` Docker Hub image, you can[use `docker exec` with the `influx` and `influxd`CLIs](/influxdb/v2/install/?t=Docker#run-influxdb-cli-commands-in-a-container) inside the container. ### Manage files in mounted volumes To copy files, such as the InfluxDB server `config.yml` file, between your local file system and a volume, use the[`docker container cp` command](https://docs.docker.com/reference/cli/docker/container/cp/). For more InfluxDB and Docker configuration options, see the [`influxdb` Docker Hub image](https://hub.docker.com/_/influxdb)documentation. #### Related * [Install InfluxDB OSS v2](/influxdb/v2/install/) * [Upgrade from InfluxDB 1.x to 2.10 with Docker](/influxdb/v2/install/upgrade/v1-to-v2/docker/) * [influx auth](/influxdb/v2/reference/cli/influx/auth/) * [influx config](/influxdb/v2/reference/cli/influx/config/) * [influx - InfluxDB command line interface](/influxdb/v2/reference/cli/influx/) * [Manage API tokens](/influxdb/v2/admin/tokens/) [install](/influxdb/v2/tags/install/) --- # Monitor data and send alerts Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Monitor your time series data and send alerts by creating checks, notification rules, and notification endpoints. Or use [community templates to monitor](/influxdb/v2/monitor-alert/templates/) supported environments. ## Overview 1. A [check](/influxdb/v2/reference/glossary/#check) in InfluxDB queries data and assigns a status with a `_level` based on specific conditions. 2. InfluxDB stores the output of a check in the `statuses` measurement in the `_monitoring` system bucket. 3. [Notification rules](/influxdb/v2/reference/glossary/#notification-rule) check data in the `statuses`measurement and, based on conditions set in the notification rule, send a message to a [notification endpoint](/influxdb/v2/reference/glossary/#notification-endpoint). 4. InfluxDB stores notifications in the `notifications` measurement in the `_monitoring` system bucket. ## Create an alert To get started, do the following: 1. [Create checks](/influxdb/v2/monitor-alert/checks/create/) to monitor data and assign a status. 2. [Add notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/create/)to send notifications to third parties. 3. [Create notification rules](/influxdb/v2/monitor-alert/notification-rules/create) to check statuses and send notifications to your notifications endpoints. ## Manage your monitoring and alerting pipeline ### [Manage checks](/influxdb/v2/monitor-alert/checks/) Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. ### [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) Create, read, update, and delete endpoints in the InfluxDB UI. ### [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) Manage notification rules in InfluxDB. ### [Monitor with templates](/influxdb/v2/monitor-alert/templates/) Use community templates to monitor data in many supported environments. Monitor infrastructure, networking, IoT, software, security, TICK stack, and more. ### [Send alert email](/influxdb/v2/monitor-alert/send-email/) Send an alert email. ### [Create custom checks](/influxdb/v2/monitor-alert/custom-checks/) Create custom checks with a Flux task. [monitor](/influxdb/v2/tags/monitor/)[alert](/influxdb/v2/tags/alert/)[checks](/influxdb/v2/tags/checks/)[notification](/influxdb/v2/tags/notification/)[endpoints](/influxdb/v2/tags/endpoints/) --- # Manage checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/checks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. Learn how to create and manage checks: ### [Create checks](/influxdb/v2/monitor-alert/checks/create/) Create a check in the InfluxDB UI. ### [View checks](/influxdb/v2/monitor-alert/checks/view/) View check details and statuses and notifications generated by checks in the InfluxDB UI. ### [Update checks](/influxdb/v2/monitor-alert/checks/update/) Update, rename, enable or disable checks in the InfluxDB UI. ### [Delete checks](/influxdb/v2/monitor-alert/checks/delete/) Delete checks in the InfluxDB UI. #### Related * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) [monitor](/influxdb/v2/tags/monitor/)[checks](/influxdb/v2/tags/checks/)[notifications](/influxdb/v2/tags/notifications/)[alert](/influxdb/v2/tags/alert/) --- # Create checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/checks/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create a check in the InfluxDB user interface (UI). Checks query data and apply a status to each point based on specified conditions. ## Parts of a check A check consists of two parts – a query and check configuration. #### Check query * Specifies the dataset to monitor. * May include tags to narrow results. #### Check configuration * Defines check properties, including the check interval and status message. * Evaluates specified conditions and applies a status (if applicable) to each data point: * `crit` * `warn` * `info` * `ok` * Stores status in the `_level` column. ## Check types There are two types of checks: * [threshold](#threshold-check) * [deadman](#deadman-check) #### Threshold check A threshold check assigns a status based on a value being above, below, inside, or outside of defined thresholds. #### Deadman check A deadman check assigns a status to data when a series or group doesn’t report in a specified amount of time. ## Create a check 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Click **Create** and select the [type of check](#check-types) to create. 3. Click **Name this check** in the top left corner and provide a unique name for the check, and then do the following: * [Configure the check query](#configure-the-check-query) * [Configure the check](#configure-the-check) 4. *(Optional)* In the **Name this check** field at the top, enter a unique name for the check. #### Configure the check query 1. Select the **bucket**, **measurement**, **field** and **tag sets** to query. 2. If creating a threshold check, select an **aggregate function**. Aggregate functions aggregate data between the specified check intervals and return a single value for the check to process. In the **Aggregate functions** column, select an interval from the interval drop-down list (for example, “Every 5 minutes”) and an aggregate function from the list of functions. 3. Click **Submit** to run the query and preview the results. To see the raw query results, click the **View Raw Data** toggle. #### Configure the check 1. Click **2. Configure Check** near the top of the window. 2. In the **Properties** column, configure the following: ##### Schedule Every ##### Select the interval to run the check (for example, “Every 5 minutes”). This interval matches the aggregate function interval for the check query.*Changing the interval here will update the aggregate function interval.* ##### Offset ##### Delay the execution of a task to account for any late data. Offset queries do not change the queried time range. > [!Note] > Your offset must be shorter than your [check interval](#schedule-every). ##### Tags ##### Add custom tags to the query output. Each custom tag appends a new column to each row in the query output. The column label is the tag key and the column value is the tag value. Use custom tags to associate additional metadata with the check. Common metadata tags across different checks lets you easily group and organize checks. You can also use custom tags in [notification rules](/influxdb/v2/monitor-alert/notification-rules/create/). 3. In the **Status Message Template** column, enter the status message template for the check. Use [Flux string interpolation](/flux/v0/data-types/basic/string/#interpolate-strings)to populate the message with data from the query. Check data is represented as a record, `r`. Access specific column values using dot notation: `r.columnName`. Use data from the following columns: * columns included in the query output * [custom tags](#tags) added to the query output * `_check_id` * `_check_name` * `_level` * `_source_measurement` * `_type` ###### Example status message template ###### ``` From ${r._check_name}: ${r._field} is ${r._level}. Its value is ${string(v: r.field_name)}. ``` When a check generates a status, it stores the message in the `_message` column. 4. Define check conditions that assign statuses to points. Condition options depend on your check type. ##### Configure a threshold check ##### 1. In the **Thresholds** column, click the status name (CRIT, WARN, INFO, or OK) to define conditions for that specific status. 2. From the **When value** drop-down list, select a threshold: is above, is below, is inside of, is outside of. 3. Enter a value or values for the threshold. You can also use the threshold sliders in the data visualization to define threshold values. ##### Configure a deadman check ##### 1. In the **Deadman** column, enter a duration for the deadman check in the **for** field. For example, `90s`, `5m`, `2h30m`, etc. 2. Use the **set status to** drop-down list to select a status to set on a dead series. 3. In the **And stop checking after** field, enter the time to stop monitoring the series. For example, `30m`, `2h`, `3h15m`, etc. 5. Click the green **✓** in the top right corner to save the check. ## Clone a check Create a new check by cloning an existing check. 1. Go to **Alerts \> Alerts** in the navigation on the left. Alerts 2. Click the icon next to the check you want to clone and then click **Clone**. #### Related * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Delete checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/checks/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). If you no longer need a check, use the InfluxDB user interface (UI) to delete it. Deleting a check cannot be undone. 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Click the icon, and then click **Confirm**. After a check is deleted, all statuses generated by the check remain in the `_monitoring`bucket until the retention period for the bucket expires. > [!Note] > You can also [disable a check](/influxdb/v2/monitor-alert/checks/update/#enable-or-disable-a-check)without having to delete it. #### Related * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Update checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/checks/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update checks in the InfluxDB user interface (UI). Common updates include: * [Update check queries and logic](#update-check-queries-and-logic) * [Enable or disable a check](#enable-or-disable-a-check) * [Rename a check](#rename-a-check) * [Add or update a check description](#add-or-update-a-check-description) * [Add a label to a check](#add-a-label-to-a-check) To update checks, select **Alerts \> Alerts** in the navigation menu on the left. Alerts ## Update check queries and logic 1. Click the name of the check you want to update. The check builder appears. 2. To edit the check query, click **1. Define Query** at the top of the check builder window. 3. To edit the check logic, click **2. Configure Check** at the top of the check builder window. *For details about using the check builder, see [Create checks](/influxdb/v2/monitor-alert/checks/create/).* ## Enable or disable a check Click the toggle next to a check to enable or disable it. ## Rename a check 1. Hover over the name of the check you want to update. 2. Click the icon that appears next to the check name. 3. Enter a new name and click out of the name field or press enter to save. *You can also rename a check in the [check builder](#update-check-queries-and-logic).* ## Add or update a check description 1. Hover over the check description you want to update. 2. Click the icon that appears next to the description. 3. Enter a new description and click out of the name field or press enter to save. ## Add a label to a check 1. Click ** Add a label** next to the check you want to add a label to. The **Add Labels** box appears. 2. To add an existing label, select the label from the list. 3. To create and add a new label: * In the search field, enter the name of the new label. The **Create Label** box opens. * In the **Description** field, enter an optional description for the label. * Select a color for the label. * Click **Create Label**. 4. To remove a label, click on the label. #### Related * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # View checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/checks/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View check details and statuses and notifications generated by checks in the InfluxDB user interface (UI). * [View a list of all checks](#view-a-list-of-all-checks) * [View check details](#view-check-details) * [View statuses generated by a check](#view-statuses-generated-by-a-check) * [View notifications triggered by a check](#view-notifications-triggered-by-a-check) To view checks, click **Alerts \> Alerts** in navigation menu on the left. Alerts ## View a list of all checks The **Checks** section of the Alerts landing page displays all existing checks. ## View check details Click the name of the check you want to view. The check builder appears. Here you can view the check query and logic. ## View statuses generated by a check 1. Click the icon on the check. 2. Click **View History**. The Statuses History page displays statuses generated by the selected check. #### Related * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Create custom checks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/custom-checks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). In the UI, you can create two kinds of [checks](/influxdb/v2/reference/glossary/#check):[`threshold`](/influxdb/v2/monitor-alert/checks/create/#threshold-check) and[`deadman`](/influxdb/v2/monitor-alert/checks/create/#deadman-check). Using a Flux task, you can create a custom check that provides a couple advantages: * Customize and transform the data you would like to use for the check. * Set up custom criteria for your alert (other than `threshold` and `deadman`). ## Create a task 1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. Tasks 2. Click **Create Task**. 3. In the **Name** field, enter a descriptive name, and then enter how often to run the task in the **Every** field (for example, `10m`). For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2/process-data/task-options/). 4. Enter the Flux script for your custom check, including the [`monitor.check`](/flux/v0/stdlib/influxdata/influxdb/monitor/check/) function. > [!Note] > Use the [`/api/v2/checks/{checkID}/query` API endpoint](/influxdb/v2/api/dashboards/)to see the Flux code for a check built in the UI. > This can be useful for constructing custom checks. ### Example: Monitor failed tasks The script below is fairly complex, and can be used as a framework for similar tasks. It does the following: * Import the necessary `influxdata/influxdb/monitor` package, and other packages for data processing. * Query the `_tasks` bucket to retrieve all statuses generated by your check. * Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. * Create a `check` object that specifies an ID, name, and type for the check. * Define the `ok` and `crit` statuses. * Execute the `monitor` function on the `check` using the `task_data`. #### Example alert task script ```js import "strings" import "regexp" import "influxdata/influxdb/monitor" import "influxdata/influxdb/schema" option task = {name: "Failed Tasks Check", every: 1h, offset: 4m} task_data = from(bucket: "_tasks") |> range(start: -task.every) |> filter(fn: (r) => r["_measurement"] == "runs") |> filter(fn: (r) => r["_field"] == "logs") |> map(fn: (r) => ({r with name: strings.split(v: regexp.findString(r: /option task = \{([^\}]+)/, v: r._value), t: "\\\\\\\"")[1]})) |> drop(columns: ["_value", "_start", "_stop"]) |> group(columns: ["name", "taskID", "status", "_measurement"]) |> map(fn: (r) => ({r with _value: if r.status == "failed" then 1 else 0})) |> last() check = { // 16 characters, alphanumeric _check_id: "0000000000000001", // Name string _check_name: "Failed Tasks Check", // Check type (threshold, deadman, or custom) _type: "custom", tags: {}, } ok = (r) => r["logs"] == 0 crit = (r) => r["logs"] == 1 messageFn = (r) => "The task: ${r.taskID} - ${r.name} has a status of ${r.status}" task_data |> schema["fieldsAsCols"]() |> monitor["check"](data: check, messageFn: messageFn, ok: ok, crit: crit) ``` > [!Note] > Creating a custom check does not send a notification email. > For information on how to create notification emails, see[Create notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/create),[Create notification rules](/influxdb/v2/monitor-alert/notification-rules/create), > and [Send alert email](/influxdb/v2/monitor-alert/send-email/) [alerts](/influxdb/v2/tags/alerts/)[checks](/influxdb/v2/tags/checks/)[tasks](/influxdb/v2/tags/tasks/)[Flux](/influxdb/v2/tags/flux/) --- # Manage notification endpoints Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-endpoints/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Notification endpoints store information to connect to a third-party service. Create a connection to a HTTP, Slack, or PagerDuty endpoint. ### [Create notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/create/) Create notification endpoints to send alerts on your time series data. ### [View notification endpoint history](/influxdb/v2/monitor-alert/notification-endpoints/view/) View notification endpoint details and history in the InfluxDB UI. ### [Update notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/update/) Update notification endpoints in the InfluxDB UI. ### [Delete notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/delete/) Delete a notification endpoint in the InfluxDB UI. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) [monitor](/influxdb/v2/tags/monitor/)[endpoints](/influxdb/v2/tags/endpoints/)[notifications](/influxdb/v2/tags/notifications/)[alert](/influxdb/v2/tags/alert/) --- # Create notification endpoints Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-endpoints/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To send notifications about changes in your data, start by creating a notification endpoint to a third-party service. After creating notification endpoints, [create notification rules](/influxdb/v2/monitor-alert/notification-rules/create) to send alerts to third-party services on [check statuses](/influxdb/v2/monitor-alert/checks/create). ## Create a notification endpoint 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Endpoints**. 3. Click **Create**. 4. From the **Destination** drop-down list, select a destination endpoint to send notifications to. 5. In the **Name** and **Description** fields, enter a name and description for the endpoint. 6. Enter information to connect to the endpoint: * **For HTTP**, enter the **URL** to send the notification. Select the **auth method** to use: **None** for no authentication. To authenticate with a username and password, select **Basic** and then enter credentials in the **Username** and **Password** fields. To authenticate with an API token, select **Bearer**, and then enter the API token in the **Token** field. * **For Slack**, create an [Incoming WebHook](https://api.slack.com/incoming-webhooks#posting_with_webhooks)in Slack, and then enter your webHook URL in the **Slack Incoming WebHook URL** field. * **For PagerDuty**: * [Create a new service](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-new-service),[add an integration for your service](https://support.pagerduty.com/docs/services-and-integrations#section-add-integrations-to-an-existing-service), and then enter the PagerDuty integration key for your new service in the **Routing Key** field. * The **Client URL** provides a useful link in your PagerDuty notification. Enter any URL that you’d like to use to investigate issues. This URL is sent as the `client_url` property in the PagerDuty trigger event. By default, the **Client URL** is set to your Monitoring & Alerting History page, and the following included in the PagerDuty trigger event: ``` { "client_url": "http://localhost:8086/orgs//alert-history" } ``` 7. Click **Create Notification Endpoint**. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) --- # Delete notification endpoints Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-endpoints/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). If notifications are no longer sent to an endpoint, complete the steps below to delete the endpoint, and then [update notification rules](/influxdb/v2/monitor-alert/notification-rules/update)with a new notification endpoint as needed. ## Delete a notification endpoint 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Endpoints** and find the rule you want to delete. 3. Click the icon on the notification you want to delete and then click **Confirm**. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) --- # Update notification endpoints Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-endpoints/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Complete the following steps to update notification endpoint details. To update the notification endpoint selected for a notification rule, see [update notification rules](/influxdb/v2/monitor-alert/notification-rules/update/). **To update a notification endpoint** 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Endpoints** and then do the following as needed: * [Update the name or description for notification endpoint](#update-the-name-or-description-for-notification-endpoint) * [Change endpoint details](#change-endpoint-details) * [Disable notification endpoint](#disable-notification-endpoint) * [Add a label to notification endpoint](#add-a-label-to-notification-endpoint) ## Update the name or description for notification endpoint 1. Hover over the name or description of the endpoint and click the pencil icon () to edit the field. 2. Click outside of the field to save your changes. ## Change endpoint details 1. Click the name of the endpoint to update. 2. Update details as needed, and then click **Edit Notification Endpoint**. For details about each field, see [Create notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/create/). ## Disable notification endpoint Click the toggle to disable the notification endpoint. ## Add a label to notification endpoint 1. Click ** Add a label** next to the endpoint you want to add a label to. The **Add Labels** box opens. 2. To add an existing label, select the label from the list. 3. To create and add a new label: * In the search field, enter the name of the new label. The **Create Label** box opens. * In the **Description** field, enter an optional description for the label. * Select a color for the label. * Click **Create Label**. 4. To remove a label, click on the label. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) --- # View notification endpoint history Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-endpoints/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View notification endpoint details and history in the InfluxDB user interface (UI). 1. In the navigation menu on the left, select **Alerts**. Alerts 2. Select **Notification Endpoints**. * [View notification endpoint details](#view-notification-endpoint-details) * [View history notification endpoint history](#view-notification-endpoint-history), including statues and notifications sent to the endpoint ## View notification endpoint details On the notification endpoints page: 1. Click the name of the notification endpoint you want to view. 2. View the notification endpoint destination, name, and information to connect to the endpoint. ## View notification endpoint history On the notification endpoints page, click the icon, and then click **View History**. The Check Statuses History page displays: * Statuses generated for the selected notification endpoint * Notifications sent to the selected notification endpoint #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification rules](/influxdb/v2/monitor-alert/notification-rules/) --- # Manage notification rules Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-rules/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles provide information on managing your notification rules: ### [Create notification rules](/influxdb/v2/monitor-alert/notification-rules/create/) Create notification rules to send alerts on your time series data. ### [View notification rules](/influxdb/v2/monitor-alert/notification-rules/view/) Update notification rules to update the notification message or change the schedule or conditions. ### [Update notification rules](/influxdb/v2/monitor-alert/notification-rules/update/) Update notification rules to update the notification message or change the schedule or conditions. ### [Delete notification rules](/influxdb/v2/monitor-alert/notification-rules/delete/) If you no longer need to receive an alert, delete the associated notification rule. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) [monitor](/influxdb/v2/tags/monitor/)[notifications](/influxdb/v2/tags/notifications/)[alert](/influxdb/v2/tags/alert/) --- # Create notification rules Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-rules/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Once you’ve set up checks and notification endpoints, create notification rules to alert you.*For details, see [Manage checks](/influxdb/v2/monitor-alert/checks/) and[Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/).* 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Rules** near to top of the page. * [Create a new notification rule in the UI](#create-a-new-notification-rule-in-the-ui) * [Clone an existing notification rule in the UI](#clone-an-existing-notification-rule-in-the-ui) ## Create a new notification rule 1. On the notification rules page, click **Create**. 2. Complete the **About** section: 3. In the **Name** field, enter a name for the notification rule. 4. In the **Schedule Every** field, enter how frequently the rule should run. 5. In the **Offset** field, enter an offset time. For example,if a task runs on the hour, a 10m offset delays the task to 10 minutes after the hour. Time ranges defined in the task are relative to the specified execution time. 6. In the **Conditions** section, build a condition using a combination of status and tag keys. * Next to **When status is equal to**, select a status from the drop-down field. * Next to **AND When**, enter one or more tag key-value pairs to filter by. 7. In the **Message** section, select an endpoint to notify. 8. Click **Create Notification Rule**. ## Clone an existing notification rule On the notification rules page, click the icon and select **Clone**. The cloned rule appears. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Delete notification rules Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-rules/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). If you no longer need to receive an alert, delete the associated notification rule. ## Delete a notification rule 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Rules** near to top of the page. 3. Click the icon on the notification rule you want to delete. 4. Click **Confirm**. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Update notification rules Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-rules/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update notification rules to update the notification message or change the schedule or conditions. 1. In the navigation menu on the left, select **Alerts \> Alerts**. Alerts 2. Select **Notification Rules** near to top of the page. * [Update the name or description for notification rules](#update-the-name-or-description-for-notification-rules) * [Enable or disable notification rules](#enable-or-disable-notification-rules) * [Add a label to notification rules](#add-a-label-to-notification-rules) ## Update the name or description for notification rules On the Notification Rules page: 1. Hover over the name or description of a rule and click the pencil icon () to edit the field. 2. Click outside of the field to save your changes. ## Enable or disable notification rules On the notification rules page, click the toggle to enable or disable the notification rule. ## Add a label to notification rules On the notification rules page: 1. Click ** Add a label**next to the rule you want to add a label to. The **Add Labels** box opens. 2. To add an existing label, select the label from the list. 3. To create and add a new label: * In the search field, enter the name of the new label. The **Create Label** box opens. * In the **Description** field, enter an optional description for the label. * Select a color for the label. * Click **Create Label**. 1. To remove a label, click on the label. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # View notification rules Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/notification-rules/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View notification rule details and statuses and notifications generated by notification rules in the InfluxDB user interface (UI). * [View a list of all notification rules](#view-a-list-of-all-notification-rules) * [View notification rule details](#view-notification-rule-details) * [View statuses generated by a check](#view-statuses-generated-by-a-notification-rule) * [View notifications triggered by a notification rule](#view-notifications-triggered-by-a-notification-rule) **To view notification rules:** 1. In the navigation menu on the left, select **Alerts**. Alerts 2. Select **Notification Rules** near to top of the page. ## View a list of all notification rules The **Notification Rules** section of the Alerts landing page displays all existing checks. ## View notification rule details Click the name of the check you want to view. The check builder appears. Here you can view the check query and logic. ## View statuses generated by a notification rule Click the icon on the notification rule, and then **View History**. The Statuses History page displays statuses generated by the selected check. ## View notifications triggered by a notification rule 1. Click the icon on the notification rule, and then **View History**. 2. In the top left corner, click **Notifications**. The Notifications History page displays notifications initiated by the selected notification rule. #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/) --- # Send alert email Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/send-email/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Send an alert email using a third-party service, such as [SendGrid](https://sendgrid.com/), [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), [Mailjet](https://www.mailjet.com/), or [Mailgun](https://www.mailgun.com/). To send an alert email, complete the following steps: 1. [Create a check](/influxdb/v2/monitor-alert/checks/create/#create-a-check-in-the-influxdb-ui) to identify the data to monitor and the status to alert on. 2. Set up your preferred email service (sign up, retrieve API credentials, and send test email): * **SendGrid**: See [Getting Started With the SendGrid API](https://sendgrid.com/docs/API_Reference/api_getting_started.html) * **AWS Simple Email Service (SES)**: See [Using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email.html). Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). * **Mailjet**: See [Getting Started with Mailjet](https://dev.mailjet.com/email/guides/getting-started/) * **Mailgun**: See [Mailgun Signup](https://signup.mailgun.com/new/signup) 3. [Create an alert email task](#create-an-alert-email-task) to call your email service and send an alert email. > [!Note] > In the procedure below, we use the **Task** page in the InfluxDB UI (user interface) to create a task. Explore other ways to [create a task](/influxdb/v2/process-data/manage-tasks/create-task/). ### Create an alert email task 1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. Tasks 2. Click **Create Task**. 3. In the **Name** field, enter a descriptive name, for example, **Send alert email**, and then enter how often to run the task in the **Every** field, for example, `10m`. For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2/process-data/task-options/). 4. In the right panel, enter the following detail in your **task script** (see [examples below](#examples)): * Import the [Flux HTTP package](/flux/v0/stdlib/http/). * (Optional) Store your API key as a secret for reuse. First, [add your API key as a secret](/influxdb/v2/admin/secrets/add/), and then import the [Flux InfluxDB Secrets package](/flux/v0/stdlib/influxdata/influxdb/secrets/). * Query the `statuses` measurement in the `_monitoring` bucket to retrieve all statuses generated by your check. * Set the time range to monitor; use the same interval that the task is scheduled to run. For example, `range (start: -task.every)`. * Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. * Use the `map()` function to evaluate the criteria to send an alert using `http.post()`. * Specify your email service `url` (endpoint), include applicable request `headers`, and verify your request `data` format follows the format specified for your email service. #### Examples [SendGrid](#sendgrid)[AWS SES](#aws-ses)[Mailjet](#mailjet)[Mailgun](#mailgun) The example below uses the SendGrid API to send an alert email when more than 3 critical statuses occur since the previous task run. ```js import "http" import "json" // Import the Secrets package if you store your API key as a secret. // For detail on how to do this, see Step 4 above. import "influxdata/influxdb/secrets" // Retrieve the secret if applicable. Otherwise, skip this line // and add the API key as the Bearer token in the Authorization header. SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") numberOfCrits = from(bucket: "_monitoring") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "statuses" and r._level == "crit") |> count() numberOfCrits |> map( fn: (r) => if r._value > 3 then {r with _value: http.post( url: "https://api.sendgrid.com/v3/mail/send", headers: {"Content-Type": "application/json", "Authorization": "Bearer ${SENDGRID_APIKEY}"}, data: json.encode( v: { "personalizations": [ { "to": [ { "email": "jane.doe@example.com" } ] } ], "from": { "email": "john.doe@example.com" }, "subject": "InfluxDB critical alert", "content": [ { "type": "text/plain", "value": "There have been ${r._value} critical statuses." } ] } ) )} else {r with _value: 0}, ) ``` The example below uses the AWS SES API v2 to send an alert email when more than 3 critical statuses occur since the last task run. > [!Note] > Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). We recommend signing your AWS API requests using the [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html). ```js import "http" import "json" // Import the Secrets package if you store your API credentials as secrets. // For detail on how to do this, see Step 4 above. import "influxdata/influxdb/secrets" // Retrieve the secrets if applicable. Otherwise, skip this line // and add the API key as the Bearer token in the Authorization header. AWS_AUTH_ALGORITHM = secrets.get(key: "AWS_AUTH_ALGORITHM") AWS_CREDENTIAL = secrets.get(key: "AWS_CREDENTIAL") AWS_SIGNED_HEADERS = secrets.get(key: "AWS_SIGNED_HEADERS") AWS_CALCULATED_SIGNATURE = secrets.get(key: "AWS_CALCULATED_SIGNATURE") numberOfCrits = from(bucket: "_monitoring") |> range(start: -task.every) |> filter(fn: (r) => r.measurement == "statuses" and r._level == "crit") |> count() numberOfCrits |> map( fn: (r) => if r._value > 3 then {r with _value: http.post( url: "https://email.your-aws-region.amazonaws.com/sendemail/v2/email/outbound-emails", headers: { "Content-Type": "application/json", "Authorization": "Bearer ${AWS_AUTH_ALGORITHM}${AWS_CREDENTIAL}${AWS_SIGNED_HEADERS}${AWS_CALCULATED_SIGNATURE}"}, data: json.encode(v: { "Content": { "Simple": { "Body": { "Text": { "Charset": "UTF-8", "Data": "There have been ${r._value} critical statuses." } }, "Subject": { "Charset": "UTF-8", "Data": "InfluxDB critical alert" } } }, "Destination": { "ToAddresses": [ "john.doe@example.com" ] } } ) )} else {r with _value: 0}, ) ``` For details on the request syntax, see [SendEmail API v2 reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html). The example below uses the Mailjet Send API to send an alert email when more than 3 critical statuses occur since the last task run. > [!Note] > To view your Mailjet API credentials, sign in to Mailjet and open the [API Key Management page](https://app.mailjet.com/account/api_keys). ```js import "http" import "json" // Import the Secrets package if you store your API keys as secrets. // For detail on how to do this, see Step 4 above. import "influxdata/influxdb/secrets" // Retrieve the secrets if applicable. Otherwise, skip this line // and add the API keys as Basic credentials in the Authorization header. MAILJET_APIKEY = secrets.get(key: "MAILJET_APIKEY") MAILJET_SECRET_APIKEY = secrets.get(key: "MAILJET_SECRET_APIKEY") numberOfCrits = from(bucket: "_monitoring") |> range(start: -task.every) |> filter(fn: (r) => r.measurement == "statuses" and "r.level" == "crit") |> count() numberOfCrits |> map( fn: (r) => if r._value > 3 then {r with _value: http.post( url: "https://api.mailjet.com/v3.1/send", headers: { "Content-type": "application/json", "Authorization": "Basic ${MAILJET_APIKEY}:${MAILJET_SECRET_APIKEY}" }, data: json.encode( v: { "Messages": [ { "From": {"Email": "jane.doe@example.com"}, "To": [{"Email": "john.doe@example.com"}], "Subject": "InfluxDB critical alert", "TextPart": "There have been ${r._value} critical statuses.", "HTMLPart": "

${r._value} critical statuses

There have been ${r._value} critical statuses.", }, ], }, ), ), } else {r with _value: 0}, ) ``` The example below uses the Mailgun API to send an alert email when more than 3 critical statuses occur since the last task run. > [!Note] > To view your Mailgun API keys, sign in to Mailjet and open [Account Security - API security](https://app.mailgun.com/app/account/security/api_keys). Mailgun requires that a domain be specified via Mailgun. A domain is automatically created for you when you first set up your account. You must include this domain in your `url` endpoint (for example, `https://api.mailgun.net/v3/YOUR_DOMAIN` or `https://api.eu.mailgun.net/v3/YOUR_DOMAIN`. If you’re using a free version of Mailgun, you can set up a maximum of five authorized recipients (to receive email alerts) for your domain. To view your Mailgun domains, sign in to Mailgun and view the [Domains page](https://app.mailgun.com/app/sending/domains). ```js import "http" import "json" // Import the Secrets package if you store your API key as a secret. // For detail on how to do this, see Step 4 above. import "influxdata/influxdb/secrets" // Retrieve the secret if applicable. Otherwise, skip this line // and add the API key as the Bearer token in the Authorization header. MAILGUN_APIKEY = secrets.get(key: "MAILGUN_APIKEY") numberOfCrits = from(bucket: "_monitoring") |> range(start: -task.every) |> filter(fn: (r) => r["_measurement"] == "statuses") |> filter(fn: (r) => r["_level"] == "crit") |> count() numberOfCrits |> map( fn: (r) => if r._value > 1 then {r with _value: http.post( url: "https://api.mailgun.net/v3/YOUR_DOMAIN/messages", headers: { "Content-type": "application/json", "Authorization": "Basic api:${MAILGUN_APIKEY}" }, data: json.encode(v: { "from": "Username ", "to": "email@example.com", "subject": "InfluxDB critical alert", "text": "There have been ${r._value} critical statuses." } ) )} else {r with _value: 0}, ) ``` #### Related * [Manage checks](/influxdb/v2/monitor-alert/checks/) [alert](/influxdb/v2/tags/alert/)[email](/influxdb/v2/tags/email/)[notifications](/influxdb/v2/tags/notifications/)[check](/influxdb/v2/tags/check/) --- # Monitor with templates Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor data in supported environments. ### [Monitor InfluxDB OSS using a template](/influxdb/v2/monitor-alert/templates/monitor/) Monitor your InfluxDB OSS instance using InfluxDB Cloud and a pre-built InfluxDB template. ### [Monitor infrastructure](/influxdb/v2/monitor-alert/templates/infrastructure/) Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. ### [Monitor networks](/influxdb/v2/monitor-alert/templates/networks/) Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. [monitor](/influxdb/v2/tags/monitor/)[templates](/influxdb/v2/tags/templates/) --- # Monitor infrastructure Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. ### [Monitor Amazon Web Services (AWS)](/influxdb/v2/monitor-alert/templates/infrastructure/aws/) Use the AWS CloudWatch Monitoring template to monitor data from Amazon Web Services (AWS), Amazon Elastic Compute Cloud (EC2), and Amazon Elastic Load Balancing (ELB) with the AWS CloudWatch Service. ### [Monitor Raspberry Pi](/influxdb/v2/monitor-alert/templates/infrastructure/raspberry-pi/) Use the Raspberry Pi system template to monitor your Raspberry Pi 4 or 400 Linux system. ### [Monitor Docker](/influxdb/v2/monitor-alert/templates/infrastructure/docker/) Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. ### [Monitor vSphere](/influxdb/v2/monitor-alert/templates/infrastructure/vshpere/) Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. ### [Monitor Windows](/influxdb/v2/monitor-alert/templates/infrastructure/windows/) Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. [monitor](/influxdb/v2/tags/monitor/)[templates](/influxdb/v2/tags/templates/)[infrastructure](/influxdb/v2/tags/infrastructure/) --- # Monitor Amazon Web Services (AWS) Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/aws/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [AWS CloudWatch Monitoring template](https://github.com/influxdata/community-templates/tree/master/aws_cloudwatch) to monitor data from [Amazon Web Services (AWS)](https://aws.amazon.com/), [Amazon Elastic Compute Cloud (EC2)](https://aws.amazon.com/ec2/), and [Amazon Elastic Load Balancing (ELB)](https://aws.amazon.com/elasticloadbalancing/) with the [AWS CloudWatch Service](https://aws.amazon.com/cloudwatch/). The AWS CloudWatch Monitoring template includes the following: * two [dashboards](/influxdb/v2/reference/glossary/#dashboard): * **AWS CloudWatch NLB (Network Load Balancers) Monitoring**: Displays data from the `cloudwatch_aws_network_elb measurement` * **AWS CloudWatch Instance Monitoring**: Displays data from the `cloudwatch_aws_ec2` measurement * two [buckets](/influxdb/v2/reference/glossary/#bucket): `kubernetes` and `cloudwatch` * two labels: `inputs.cloudwatch`, `AWS` * one variable: `v.bucket` * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/): [AWS CloudWatch input plugin](/telegraf/v1/plugins//#cloudwatch) ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/aws_cloudwatch/aws_cloudwatch.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on a server with network access to both the CloudWatch API and [InfluxDB v2 API](/influxdb/v2/reference/api/). 3. In your Telegraf configuration file (`telegraf.conf`), find the following example `influxdb_v2` output plugins, and then **replace** the `urls` to specify the servers to monitor: ``` ## k8s [[outputs.influxdb_v2]] urls = ["http://influxdb.monitoring:8086"] organization = "InfluxData" bucket = "kubernetes" token = "secret-token" ## cloudv2 sample [[outputs.influxdb_v2]] urls = ["$INFLUX_HOST"] token = "$INFLUX_TOKEN" organization = "$INFLUX_ORG" bucket = “cloudwatch" ``` 4. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). ## View the incoming data 1. In the InfluxDB user interface (UI), select **Dashboards** in the left navigation. Dashboards 2. Open your AWS dashboards, and then set the `v.bucket` variable to specify the bucket to query data from (`kubernetes` or `cloudwatch`). --- # Monitor Docker Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/docker/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). This template uses the [Docker input plugin](/telegraf/v1/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. The Docker Monitoring template includes the following: * one [dashboard](/influxdb/v2/reference/glossary/#dashboard): **Docker** * one [bucket](/influxdb/v2/reference/glossary/#bucket): `docker, 7d retention` * labels: Docker input plugin labels * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/): Docker input plugin * one variable: `bucket` * four [checks](/influxdb/v2/reference/glossary/#check): `Container cpu`, `mem`, `disk`, `non-zero exit` * one [notification endpoint](/influxdb/v2/reference/glossary/#notification-endpoint): `Http Post` * one [notification rule](/influxdb/v2/reference/glossary/#notification-rule): `Crit Alert` For more information about how checks, notification endpoints, and notifications rules work together, see [monitor data and send alerts](/influxdb/v2/monitor-alert/). ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). > [!Note] > Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2/reference/cli/influx/config/). 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on a server with network access to both the Docker containers and [InfluxDB v2 API](/influxdb/v2/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2/tools/telegraf-configs/), do the following: * Depending on how you run Docker, you may need to customize the [Docker input plugin](/telegraf/v1/plugins//#docker) configuration, for example, you may need to specify the `endpoint` value. * Set the following environment variables: * INFLUX\_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/v2/admin/organizations/view-orgs/). * INFLUX\_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). ## View incoming data 1. In the InfluxDB user interface (UI), select **Dashboards** in the left navigation. Dashboards 2. Open the **Docker** dashboard to start monitoring. --- # Monitor Raspberry Pi Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/raspberry-pi/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [Raspberry Pi Monitoring template](https://github.com/influxdata/community-templates/tree/master/raspberry-pi)to monitor your Raspberry Pi 4 or 400 Linux system. The Raspberry Pi template includes the following: * one [bucket](/influxdb/v2/reference/glossary/#bucket): `rasp-pi` (7d retention) * labels: `raspberry-pi` + Telegraf plugin labels * [Diskio input plugin](/telegraf/v1/plugins//#diskio) * [Mem input plugin](/telegraf/v1/plugins//#mem) * [Net input plugin](/telegraf/v1/plugins//#net) * [Processes input plugin](/telegraf/v1/plugins//#processes) * [Swap input plugin](/telegraf/v1/plugins//#swap) * [System input plugin](/telegraf/v1/plugins//#system) * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/) * one [dashboard](/influxdb/v2/reference/glossary/#dashboard): Raspberry Pi System * two variables: `bucket` and `linux_host` ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/raspberry-pi/raspberry-pi-system.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on your Raspberry Pi and ensure your Raspberry Pi has network access to the[InfluxDB API](/influxdb/v2/reference/api/). 3. Add the following environment variables to your Telegraf environment: * `INFLUX_HOST`: Your [InfluxDB URL](/influxdb/v2/reference/urls/) * `INFLUX_TOKEN`: Your [InfluxDB API token](/influxdb/v2/admin/tokens/) * `INFLUX_ORG`: Your InfluxDB organization name. ``` export INFLUX_HOST=http://localhost:8086 export INFLUX_TOKEN=mY5uP3rS3cr3T70keN export INFLUX_ORG=example-org ``` 4. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). ## View the incoming data 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). Dashboards 2. Click the Raspberry Pi System link to open your dashboard, then select `rasp-pi`as your bucket and select your linux\_host. --- # Monitor vSphere Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/vshpere/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). This template uses the [Docker input plugin](/telegraf/v1/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. The Docker Monitoring template includes the following: * one [dashboard](/influxdb/v2/reference/glossary/#dashboard): **vsphere** * one [bucket](/influxdb/v2/reference/glossary/#bucket): `vsphere` * label: vsphere * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/): InfluxDB v2 output plugin, vSphere input plugin * one variable: `bucket` ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/vsphere/vsphere.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). > [!Note] > Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2/reference/cli/influx/config/). 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on a server with network access to both the vSphere host and [InfluxDB v2 API](/influxdb/v2/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2/tools/telegraf-configs/), do the following: * Set the following environment variables: * INFLUX\_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/v2/admin/organizations/view-orgs/). * INFLUX\_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. * INFLUX\_BUCKET: Bucket to store data in. To use the bucket included, you must export the variable: `export INFLUX_BUCKET=vsphere` 4. * Set the host address to the vSphere and provide the `username` and `password` as variables: ``` vcenters = [ "https://$VSPHERE_HOST/sdk" ] username = "$vsphere-user" password = "$vsphere-password" ``` 5. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). ## View incoming data 1. In the InfluxDB user interface (UI), select **Dashboards** in the left navigation. Dashboards 2. Open the **vsphere** dashboard to start monitoring. --- # Monitor Windows Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/infrastructure/windows/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). The Windows System Monitoring template includes the following: * one [dashboard](/influxdb/v2/reference/glossary/#dashboard): **Windows System** * one [bucket](/influxdb/v2/reference/glossary/#bucket): `telegraf`, 7d retention * label: `Windows System Template`, Telegraf plugin labels: `outputs.influxdb_v2` * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/): InfluxDB v2 output plugin, Windows Performance Counters input plugin * two variables: `bucket`, `windows_host` ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/windows_system/windows_system.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). > [!Note] > Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2/reference/cli/influx/config/). 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on a server with network access to both the Windows system and [InfluxDB v2 API](/influxdb/v2/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2/tools/telegraf-configs/), do the following: * Set the following environment variables: * INFLUX\_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/v2/admin/organizations/view-orgs/). * INFLUX\_URL: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). 5. To monitor multiple Windows systems, repeat steps 1-4 for each system. ## View incoming data 1. In the InfluxDB user interface (UI), select **Dashboards** in the left navigation. Dashboards 2. Open the **Windows System** dashboard to start monitoring. > [!Note] > If you’re monitoring multiple Windows machines, switch between them using the `windows_host` filter at the top of the dashboard. --- # Monitor InfluxDB OSS using a template Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/monitor/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [InfluxDB Cloud](/influxdb/cloud/), the [InfluxDB Open Source (OSS) Metrics template](https://github.com/influxdata/community-templates/tree/master/influxdb2_oss_metrics), and [Telegraf](/telegraf/v1/) to monitor one or more InfluxDB OSS instances. Do the following: 1. [Review requirements](#review-requirements) 2. [Install the InfluxDB OSS Monitoring template](#install-the-influxdb-oss-monitoring-template) 3. [Set up InfluxDB OSS for monitoring](#set-up-influxdb-oss-for-monitoring) 4. [Set up Telegraf](#set-up-telegraf) 5. [View the Monitoring dashboard](#view-the-monitoring-dashboard) 6. (Optional) [Alert when metrics stop reporting](#alert-when-metrics-stop-reporting) 7. (Optional) [Create a notification endpoint and rule](#create-a-notification-endpoint-and-rule) ## Review requirements Before you begin, make sure you have access to the following: * InfluxDB Cloud account ([sign up for free here](https://cloud2.influxdata.com/signup)) * Command line access to a machine [running InfluxDB OSS 2.x](/influxdb/v2/install/) and permissions to install Telegraf on this machine * Internet connectivity from the machine running InfluxDB OSS 2.x and Telegraf to InfluxDB Cloud * Sufficient resource availability to install the template (InfluxDB Cloud Free Plan accounts include [resource limits](/influxdb/cloud/account-management/pricing-plans/#resource-limits/influxdb/cloud/account-management/pricing-plans/#resource-limits)) ## Install the InfluxDB OSS Monitoring template The InfluxDB OSS Monitoring template includes a Telegraf configuration that sends InfluxDB OSS metrics to an InfluxDB endpoint and a dashboard that visualizes the metrics. 1. [Log into your InfluxDB Cloud account](https://cloud2.influxdata.com/). 2. Go to **Settings \> Templates** in the navigation bar on the left Settings 3. Under **Paste the URL of the Template’s resource manifest file**, enter the following template URL: ``` https://raw.githubusercontent.com/influxdata/community-templates/master/influxdb2_oss_metrics/influxdb2_oss_metrics.yml ``` 4. Click **Lookup Template**, and then click **Install Template**. InfluxDB Cloud imports the template, which includes the following resources: * Dashboard `InfluxDB OSS Metrics` * Telegraf configuration `scrape-influxdb-oss-telegraf` * Bucket `oss_metrics` * Check `InfluxDB OSS Deadman` * Labels `influxdb2` and `prometheus` ## Set up InfluxDB OSS for monitoring By default, InfluxDB OSS 2.x has a `/metrics` endpoint available, which exports internal InfluxDB metrics in [Prometheus format](https://prometheus.io/docs/concepts/data_model/). 1. Ensure the `/metrics` endpoint is [enabled](/influxdb/v2/reference/config-options/#metrics-disabled). If you’ve changed the default settings to disable the `/metrics` endpoint,[re-enable these settings](/influxdb/v2/reference/config-options/#metrics-disabled). 2. Navigate to the `/metrics` endpoint of your InfluxDB OSS instance to view the InfluxDB OSS system metrics in your browser: ## Set up Telegraf Set up Telegraf to scrape metrics from InfluxDB OSS to send to your InfluxDB Cloud account. On each InfluxDB OSS instance you want to monitor, do the following: 1. [Install Telegraf](/telegraf/v1/introduction/installation/). 2. Set the following environment variables in your Telegraf environment: * `INFLUX_URL`: Your [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) * `INFLUX_ORG`: Your InfluxDB Cloud organization name 3. [In the InfluxDB Cloud UI](https://cloud2.influxdata.com/), go to **Load Data \> Telegraf** in the left navigation. Load Data 4. Click **Setup Instructions** under **Scrape InfluxDB OSS Metrics**. 5. Complete the Telegraf Setup instructions to start Telegraf using the Scrape InfluxDB OSS Metrics Telegraf configuration stored in InfluxDB Cloud. > [!Note] > For your API token, generate a new token or use an existing All Access token. If you run Telegraf as a service, edit your init script to set the environment variable and ensure its available to the service. Telegraf runs quietly in the background (no immediate output appears), and begins pushing metrics to the `oss_metrics` bucket in your InfluxDB Cloud account. ## View the Monitoring dashboard To see your data in real time, view the Monitoring dashboard. 1. Select **Dashboards** in your **InfluxDB Cloud** account. Dashboards 2. Click **InfluxDB OSS Metrics**. Metrics appear in your dashboard. 3. Customize your monitoring dashboard as needed. For example, send an alert in the following cases: * Users create a new task or bucket * You’re testing machine limits * [Metrics stop reporting](#alert-when-metrics-stop-reporting) ## Alert when metrics stop reporting The Monitoring template includes a [deadman check](/influxdb/cloud/monitor-alert/checks/create/#deadman-check) to verify metrics are reported at regular intervals. To alert when data stops flowing from InfluxDB OSS instances to your InfluxDB Cloud account, do the following: 1. [Customize the deadman check](#customize-the-deadman-check) to identify the fields you want to monitor. 2. [Create a notification endpoint and rule](#create-a-notification-endpoint-and-rule) to receive notifications when your deadman check is triggered. ### Customize the deadman check 1. To view the deadman check, click **Alerts** in the navigation bar of your **InfluxDB Cloud** account. Alerts 2. Choose a InfluxDB OSS field or create a new OSS field for your deadman alert: 1. Click **Create** and select **Deadman Check** in the dropdown menu. 2. Define your query with at least one field. 3. Click **Submit** and **Configure Check**. When metrics stop reporting, you’ll receive an alert. 3. Start under **Schedule Every**, set the amount of time to check for data. 4. Set the amount of time to wait before switching to a critical alert. 5. Click **✓** to save the check. ## Create a notification endpoint and rule To receive a notification message when your deadman check is triggered, create a [notification endpoint](#create-a-notification-endpoint) and [rule](#create-a-notification-rule). ### Create a notification endpoint InfluxData supports different endpoints: Slack, PagerDuty, and HTTP. Slack is free for all users, while PagerDuty and HTTP are exclusive to the Usage-Based Plan. #### Send a notification to Slack 1. Create a [Slack Webhooks](https://api.slack.com/messaging/webhooks). 2. Go to **Alerts \> Alerts** in the left navigation menu and then click **Notification Endpoints**. Alerts 3. Click **Create**, and enter a name and description for your Slack endpoint. 4. Enter your Slack Webhook under **Incoming Webhook URL** and click **Create Notification Endpoint**. #### Send a notification to PagerDuty or HTTP Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgrading your InfluxDB Cloud account](/influxdb/cloud/account-management/billing/#upgrade-to-usage-based-plan). ### Create a notification rule [Create a notification rule](/influxdb/cloud/monitor-alert/notification-rules/create/) to set rules for when to send a deadman alert message to your notification endpoint. 1. Go to **Alerts \> Alerts** in the left navigation menu and then click **Notification Rules**. Alerts 2. Click **Create**, and then provide the required information. 3. Click **Create Notification Rule**. #### Related * [influx apply](/influxdb/v2/reference/cli/influx/apply/) * [influx template](/influxdb/v2/reference/cli/influx/template/) [templates](/influxdb/v2/tags/templates/)[monitor](/influxdb/v2/tags/monitor/) --- # Monitor networks Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/networks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. ### [Monitor HAProxy](/influxdb/v2/monitor-alert/templates/networks/haproxy/) Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instance. [monitor](/influxdb/v2/tags/monitor/)[templates](/influxdb/v2/tags/templates/)[networks](/influxdb/v2/tags/networks/)[networking](/influxdb/v2/tags/networking/) --- # Monitor HAProxy Source: https://docs.influxdata.com/influxdb/v2/monitor-alert/templates/networks/haproxy/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instances. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). This template uses the [HAProxy input plugin](/telegraf/v1/plugins//#haproxy) to collect metrics stored in an HAProxy instance and display these metrics in a dashboard. The HAProxy for InfluxDB v2 template includes the following: * one [dashboard](/influxdb/v2/reference/glossary/#dashboard): **HAProxy** * one [bucket](/influxdb/v2/reference/glossary/#bucket): `haproxy` * label: `haproxy` * one [Telegraf configuration](/influxdb/v2/tools/telegraf-configs/): HAProxy input plugin, InfluxDB v2 output plugin * one variable: `bucket` ## Apply the template 1. Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to run the following command: ``` influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/haproxy/haproxy.yml ``` For more information, see [influx apply](/influxdb/v2/reference/cli/influx/apply/). > > > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2/reference/cli/influx/config/). > > 2. [Install Telegraf](/telegraf/v1/introduction/installation/) on a server with network access to both the HAProxy instances and [InfluxDB v2 API](/influxdb/v2/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2/tools/telegraf-configs/), do the following: * Set the following environment variables: * INFLUX\_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `haproxy` bucket. See how to [view tokens](/influxdb/v2/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/v2/admin/organizations/view-orgs/). * INFLUX\_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#start-telegraf). ## View incoming data 1. In the InfluxDB user interface (UI), select **Dashboards** in the left navigation. Dashboards 2. Open the **HAProxy** dashboard to start monitoring. --- # Process data with InfluxDB tasks Source: https://docs.influxdata.com/influxdb/v2/process-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Process and analyze your data with tasks in the InfluxDB **task engine**. Use tasks (scheduled Flux queries) to input a data stream and then analyze, modify, and act on the data accordingly. Discover how to create and manage tasks using the InfluxDB user interface (UI) the `influx` command line interface (CLI), and the InfluxDB `/api/v2` API. Find examples of data downsampling and other common tasks. > [!Note] > Tasks replace InfluxDB v1.x continuous queries. ### [Get started with tasks](/influxdb/v2/process-data/get-started/) Learn the basics of writing an InfluxDB task that processes data, and then performs an action, such as storing the modified data in a new bucket or sending an alert. ### [Manage tasks](/influxdb/v2/process-data/manage-tasks/) InfluxDB provides options for creating, reading, updating, and deleting tasks using the `influx` CLI, the InfluxDB UI, and the InfluxDB API. ### [Common data processing tasks](/influxdb/v2/process-data/common-tasks/) InfluxDB Tasks process data on specified schedules. This collection of articles walks through common use cases for InfluxDB tasks. ### [Task configuration options](/influxdb/v2/process-data/task-options/) Task options define specific information about a task such as its name, the schedule on which it runs, execution delays, and others. #### Related * [Tasks & InfluxDB](/resources/videos/influxdb-tasks/) [tasks](/influxdb/v2/tags/tasks/) --- # Common data processing tasks Source: https://docs.influxdata.com/influxdb/v2/process-data/common-tasks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles walk through common task use cases. ### [Downsample data with InfluxDB](/influxdb/v2/process-data/common-tasks/downsample-data/) How to create a task that downsamples data much like continuous queries in previous versions of InfluxDB. ### [Calculate a weekly mean](/influxdb/v2/process-data/common-tasks/calculate_weekly_mean/) Calculate a weekly mean and add it to a new bucket. ### [Convert results to JSON](/influxdb/v2/process-data/common-tasks/convert_results_to_json/) Use `json.encode()` to convert query results to JSON and `http.post()` to send them to a URL endpoint. [tasks](/influxdb/v2/tags/tasks/) --- # Calculate a weekly mean Source: https://docs.influxdata.com/influxdb/v2/process-data/common-tasks/calculate_weekly_mean/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Note] > This example uses [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). This example calculates a temperature weekly mean and stores it in a separate bucket. The sample query performs the following operations: * Uses [`filter()`](/flux/v0/stdlib/universe/filter/) to select records with the `average_temperature` measurement. * Uses [`range()`](/flux/v0/stdlib/universe/range/) to define the start time. * Uses [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/) to group records by week and compute the mean. * Sends the weekly mean to a new bucket (`weekly_means`). ```js option task = { name: "weekly-means", every: 1w, } from(bucket: "noaa") |> filter(fn: (r) => r._measurement == "average_temperature") |> range(start: 2019-09-01T11:24:00Z) |> aggregateWindow(every: 1w, fn: mean) |> to(bucket: "weekly_means") ``` ### Example results | \_start | \_stop |\_field| \_measurement | location | \_value | \_time | |--------------------|--------------------|-------|--------------------|-------------|-----------------|--------------------| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|coyote\_creek|80.31005917159763|2019-09-05T00:00:00Z| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|coyote\_creek|79.8422619047619 |2019-09-12T00:00:00Z| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|coyote\_creek|79.82710622710623|2019-09-19T00:00:00Z| | \_start | \_stop |\_field| \_measurement | location | \_value | \_time | |--------------------|--------------------|-------|--------------------|-------------|-----------------|--------------------| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|santa\_monica|80.19952494061758|2019-09-05T00:00:00Z| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|santa\_monica|80.01964285714286|2019-09-12T00:00:00Z| |2019-09-01T11:24:00Z|2020-10-19T20:39:49Z|degrees|average\_temperature|santa\_monica| 80.20451 | | [tasks](/influxdb/v2/tags/tasks/) | _start | _stop | _field | _measurement | location | _value | _time | | --- | --- | --- | --- | --- | --- | --- | | _start | _stop | _field | _measurement | location | _value | _time | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 80.31005917159763 | 2019-09-05T00:00:00Z | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 79.8422619047619 | 2019-09-12T00:00:00Z | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 79.82710622710623 | 2019-09-19T00:00:00Z | | _start | _stop | _field | _measurement | location | _value | _time | | --- | --- | --- | --- | --- | --- | --- | | _start | _stop | _field | _measurement | location | _value | _time | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.19952494061758 | 2019-09-05T00:00:00Z | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.01964285714286 | 2019-09-12T00:00:00Z | | 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.20451 | | --- # Convert results to JSON Source: https://docs.influxdata.com/influxdb/v2/process-data/common-tasks/convert_results_to_json/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Note] > This example uses [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). Send each record to a URL endpoint using the HTTP POST method. This example uses [`json.encode()`](/flux/v0/stdlib/json/encode/) to convert a value into JSON bytes, then uses [`http.post()`](/flux/v0/stdlib/http/post/) to send them to a URL endpoint. The following query: * Uses [`filter()`](/flux/v0/stdlib/universe/filter/) to filter the `average_temperature` measurement. * Uses [`mean()`](/flux/v0/stdlib/universe/mean/) to calculate the average value from results. * Uses [`map()`](/flux/v0/stdlib/universe/map/) to create a new column, `jsonStr`, and build a JSON object using column values from the query. It then byte-encodes the JSON object and stores it as a string in the `jsonStr` column. * Uses [`http.post()`](/flux/v0/stdlib/http/post/) to send the `jsonStr` value from each record to an HTTP endpoint. ```js import "http" import "json" from(bucket: "noaa") |> filter(fn: (r) => r._measurement == "average_temperature") |> mean() |> map(fn: (r) => ({r with jsonStr: string(v: json.encode(v: {"location": r.location, "mean": r._value}))})) |> map( fn: (r) => ({ r with status_code: http.post( url: "http://somehost.com/", headers: {x: "a", y: "b"}, data: bytes(v: r.jsonStr) ) }) ) ``` [tasks](/influxdb/v2/tags/tasks/) --- # Downsample data with InfluxDB Source: https://docs.influxdata.com/influxdb/v2/process-data/common-tasks/downsample-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). One of the most common use cases for InfluxDB tasks is downsampling data to reduce the overall disk usage as data collects over time. In previous versions of InfluxDB, continuous queries filled this role. This article walks through creating a continuous-query-like task that downsamples data by aggregating data within windows of time, then storing the aggregate value in a new bucket. ### Requirements To perform a downsampling task, you need to the following: ##### A “source” bucket The bucket from which data is queried. ##### A “destination” bucket A separate bucket where aggregated, downsampled data is stored. ##### Some type of aggregation To downsample data, it must be aggregated in some way. What specific method of aggregation you use depends on your specific use case, but examples include mean, median, top, bottom, etc. View [Flux’s aggregate functions](/flux/v0/function-types/#aggregates)for more information and ideas. ## Example downsampling task script The example task script below is a very basic form of data downsampling that does the following: 1. Defines a task named “cq-mem-data-1w” that runs once a week. 2. Defines a `data` variable that represents all data from the last 2 weeks in the`mem` measurement of the `system-data` bucket. 3. Uses the [`aggregateWindow()` function](/flux/v0/stdlib/universe/aggregatewindow/)to window the data into 1 hour intervals and calculate the average of each interval. 4. Stores the aggregated data in the `system-data-downsampled` bucket under the`my-org` organization. ```js // Task Options option task = {name: "cq-mem-data-1w", every: 1w} // Defines a data source data = from(bucket: "system-data") |> range(start: -duration(v: int(v: task.every) * 2)) |> filter(fn: (r) => r._measurement == "mem") data // Windows and aggregates the data in to 1h averages |> aggregateWindow(fn: mean, every: 1h) // Stores the aggregated data in a new bucket |> to(bucket: "system-data-downsampled", org: "my-org") ``` Again, this is a very basic example, but it should provide you with a foundation to build more complex downsampling tasks. ## Add your task Once your task is ready, see [Create a task](/influxdb/v2/process-data/manage-tasks/create-task) for information about adding it to InfluxDB. ## Things to consider * If there is a chance that data may arrive late, specify an `offset` in your task options long enough to account for late-data. * If running a task against a bucket with a finite retention period, schedule tasks to run prior to the end of the retention period to let downsampling tasks complete before data outside of the retention period is dropped. [tasks](/influxdb/v2/tags/tasks/) --- # Get started with InfluxDB tasks Source: https://docs.influxdata.com/influxdb/v2/process-data/get-started/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). An **InfluxDB task** is a scheduled Flux script that takes a stream of input data, modifies or analyzes it in some way, then writes the modified data back to InfluxDB or performs other actions. This article walks through writing a basic InfluxDB task that downsamples data and stores it in a new bucket. ## Components of a task Every InfluxDB task needs the following components. Their form and order can vary, but they are all essential parts of a task. * [Task options](#define-task-options) * [A data source](#define-a-data-source) * [Data processing or transformation](#process-or-transform-your-data) * [A destination](#define-a-destination) *[Skip to the full example task script](#full-example-flux-task-script)* ## Define task options Task options define the schedule, name, and other information about the task. The following example shows how to set task options in a Flux script: ```js option task = {name: "downsample_5m_precision", every: 1h, offset: 0m} ``` *See [Task configuration options](/influxdb/v2/process-data/task-options) for detailed information about each option.* *Note that InfluxDB doesn’t guarantee that a task will run at the scheduled time. See [View task run logs for a task](/influxdb/v2/process-data/manage-tasks/task-run-history)for detailed information on task service-level agreements (SLAs).* > [!Note] > The InfluxDB UI provides a form for defining task options. ## Retrieve and filter data A minimal Flux script uses the following functions to retrieve a specified amount of data from a data source and then filter the data based on time or column values: 1. [`from()`](/flux/v0/stdlib/influxdata/influxdb/from/): queries data from InfluxDB . 2. [`range()`](/flux/v0/stdlib/universe/range/): defines the time range to return data from. 3. [`filter()`](/flux/v0/stdlib/universe/filter/): filters data based on column values. The following sample Flux retrieves data from an InfluxDB bucket and then filters by the `_measurement` and `host` columns: ```js from(bucket: "example-bucket") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") ``` *To retrieve data from other sources, see [Flux input functions](/flux/v0/function-types/#inputs).* > [!Note] > #### Use task options in your Flux script > > InfluxDB stores options in a `task` option record that you can reference in your Flux script. > The following sample Flux uses the time range `-task.every`: > > ``` > from(bucket: "example-bucket") > |> range(start: -task.every) > |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") > ``` > > `task.every` is dot notation that references the `every` property of the `task` option record.`every` is defined as `1h`, therefore `-task.every` equates to `-1h`. > > Using task options to define values in your Flux script can make reusing your task easier. ## Process or transform your data Tasks run scripts automatically at regular intervals. Scripts process or transform data in some way–for example: downsampling, detecting anomalies, or sending notifications. Consider a task that runs hourly and downsamples data by calculating the average of set intervals. It uses [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)to group points into 5-minute (`5m`) windows and calculate the average of each window with [`mean()`](/flux/v0/stdlib/universe/mean/). The following sample code shows the Flux script with task options: ```js option task = {name: "downsample_5m_precision", every: 1h, offset: 0m} from(bucket: "example-bucket") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") |> aggregateWindow(every: 5m, fn: mean) ``` > [!Note] > #### Use offset to account for latent data > > Use the `offset` task option to account for potentially latent data (like data from edge devices). > A task that runs at one hour intervals (`every: 1h`) with an offset of five minutes (`offset: 5m`) > executes 5 minutes after the hour, but queries data from the original one-hour interval. *See [Common tasks](/influxdb/v2/process-data/common-tasks) for examples of tasks commonly used with InfluxDB.* ## Define a destination In most cases, you’ll want to send and store data after the task has transformed it. The destination could be a separate InfluxDB measurement or bucket. The example below uses [`to()`](/flux/v0/stdlib/universe/to)to write the transformed data back to another InfluxDB bucket: ```js // ... |> to(bucket: "example-downsampled", org: "my-org") ``` To write data into InfluxDB, `to()` requires the following columns: * `_time` * `_measurement` * `_field` * `_value` *To write data to other destinations, see[Flux output functions](/flux/v0/function-types/#outputs).* ## Full example Flux task script The following sample Flux combines all the components described in this guide: ```js // Task options option task = {name: "downsample_5m_precision", every: 1h, offset: 0m} // Data source from(bucket: "example-bucket") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") // Data processing |> aggregateWindow(every: 5m, fn: mean) // Data destination |> to(bucket: "example-downsampled") ``` To learn more about InfluxDB tasks and how they work, watch the following video: #### Related * [Manage tasks in InfluxDB](/influxdb/v2/process-data/manage-tasks/) * [Create a task](/influxdb/v2/process-data/manage-tasks/create-task/) * [Tasks & InfluxDB](/resources/videos/influxdb-tasks/) [tasks](/influxdb/v2/tags/tasks/) --- # Manage tasks in InfluxDB Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB provides multiple options for creating, reading, updating, and deleting (CRUD) tasks. The following articles walk through managing tasks with the InfluxDB user interface (UI), the `influx` command line interface (CLI), and the InfluxDB API. ### [Create a task](/influxdb/v2/process-data/manage-tasks/create-task/) Create a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. ### [View tasks](/influxdb/v2/process-data/manage-tasks/view-tasks/) View existing data processing tasks using the InfluxDB UI or the `influx` CLI. ### [Run a task](/influxdb/v2/process-data/manage-tasks/run-task/) Run a data processing task using the InfluxDB UI or the `influx` CLI. ### [View task run history and logs](/influxdb/v2/process-data/manage-tasks/task-run-history/) View task run histories and logs using the InfluxDB UI or the `influx` CLI. ### [Update a task](/influxdb/v2/process-data/manage-tasks/update-task/) Update a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. ### [Export a task](/influxdb/v2/process-data/manage-tasks/export-task/) Export a data processing task from InfluxDB using the InfluxDB UI. ### [Delete a task](/influxdb/v2/process-data/manage-tasks/delete-task/) Delete a task from InfluxDB using the InfluxDB UI or the `influx` CLI. [tasks](/influxdb/v2/tags/tasks/) --- # Create a task Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/create-task/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create tasks with the InfluxDB user interface (UI), `influx` command line interface (CLI), or `/api/v2` API. *Before creating a task, review the [basics for writing a task](/influxdb/v2/process-data/get-started).* * [InfluxDB UI](#create-a-task-in-the-influxdb-ui) * [`influx` CLI](#create-a-task-using-the-influx-cli) * [InfluxDB API](#create-a-task-using-the-influxdb-api) ## Create a task in the InfluxDB UI The InfluxDB UI provides multiple ways to create a task: * [Create a task from the Data Explorer](#create-a-task-from-the-data-explorer) * [Create a task in the Task UI](#create-a-task-in-the-task-ui) * [Import a task](#import-a-task) * [Create a task from a template](#create-a-task-from-a-template) * [Clone a task](#clone-a-task) ### Create a task from the Data Explorer 1. In the navigation menu on the left, select **Data Explorer**. Data Explorer 2. Build a query and click **Save As** in the upper right. 3. Select the **Task** heading. 4. Specify the task options. See [Task options](/influxdb/v2/process-data/task-options)for detailed information about each option. 5. Click **Save as Task**. ### Create a task in the Task UI 1. In the navigation menu on the left, select **Tasks**. Tasks 2. Click **Create Task** in the upper right. 3. In the left panel, specify the task options. See [Task options](/influxdb/v2/process-data/task-options) for detailed information about each option. 4. In the right panel, enter your task script. ##### Leave out the option tasks assignment ##### When creating a *new* task in the InfluxDB Task UI, leave the code editor empty. When you save the task, the Task UI uses the [task options](/influxdb/v2/process-data/task-options/) you specify in the **Task options** form to populate `option task = {task_options}` for you. When you edit the saved task, you’ll see the injected `option task = {task_options}`. 5. Click **Save** in the upper right. ### Import a task 1. In the navigation menu on the left, select **Tasks**. Tasks 2. Click **Create Task** in the upper right. 3. In the left panel, specify the task options. See [Task options](/influxdb/v2/process-data/task-options) for detailed information about each option. 4. Paste a raw Flux task in the code editor to the right of the task options fields. 5. Click **Save** in the upper right. ### Create a task from a template 1. In the navigation menu on the left, select **Settings** \> **Templates**. Settings 2. Find the template you want to use and click its **Resources** list to expand the list of resources. 3. In the **Resources** list, click the task you want to use. ### Clone a task 1. In the navigation menu on the left, select **Tasks**. Tasks 2. Find the task you would like to clone and click the icon located far right of the task name. 3. Click **Clone**. ## Create a task using the influx CLI Use the `influx task create` command to create a new task. It accepts either a file path or raw Flux. ### Create a task using a file ```sh # Syntax influx task create --org -f # Example influx task create --org my-org -f /tasks/cq-mean-1h.flux ``` ### Create a task using raw Flux ```sh influx task create --org my-org - # to open stdin pipe option task = { name: "task-name", every: 6h } # ... Task script ... # Linux & macOS: to close the pipe and submit the command # Windows: , then , then to close the pipe and submit the command ``` ## Create a task using the InfluxDB API Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/v2/api/tasks/) to create a task. ``` POST http://localhost:8086/api/v2/tasks/ ``` Provide the following in your API request: ##### Request headers * **Content-Type**: application/json * **Authorization**: Token *`INFLUX_API_TOKEN`* ##### Request body JSON object with the following fields: * **flux**: raw Flux task string that contains a [`task` option](/flux/v0/spec/options/) and a query. * **orgID**: your [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **status**: task status (“active” or “inactive”) * **description**: task description ```sh curl --request POST 'http://localhost:8086/api/v2/tasks' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --data-raw '{ "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\n\nfrom(bucket: \"telegraf\")\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "orgID": "INFLUX_ORG_ID", "status": "active", "description": "This task downsamples CPU data every hour" }' ``` #### Related * [influx task create](/influxdb/v2/reference/cli/influx/task/create/) --- # Delete a task Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/delete-task/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## Delete a task in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. Tasks 2. In the list of tasks, hover over the task you want to delete. 3. Click **Delete** on the far right. 4. Click **Confirm**. ## Delete a task with the influx CLI Use the `influx task delete` command to delete a task. ```sh # Syntax influx task delete -i # Example influx task delete -i 0343698431c35000 ``` *To find the task ID, see [how to view tasks](/influxdb/v2/process-data/manage-tasks/view-tasks/)* ## Delete a task using the InfluxDB API Use the [`/tasks/TASK_ID` InfluxDB API endpoint](/influxdb/v2/api/tasks/) to delete a task and all associated records (task runs, logs, and labels). ``` DELETE http://localhost:8086/api/v2/tasks/TASK_ID ``` *To find the task ID, see [how to view tasks](/influxdb/v2/process-data/manage-tasks/view-tasks/)* Once the task is deleted, InfluxDB cancels all scheduled runs of the task. If you want to disable a task instead of delete it, see how to[update the task status](/influxdb/v2/process-data/manage-tasks/update-task/) to `inactive`. #### Related * [influx task delete](/influxdb/v2/reference/cli/influx/task/delete/) --- # Export a task Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/export-task/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB lets you export tasks from the InfluxDB user interface (UI). Tasks are exported as downloadable JSON files. ## Export a task in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. Tasks 2. In the list of tasks, hover over the task you would like to export and click the icon that appears. 3. Select **Export**. 4. Your browser downloads the task JSON file. If prompted, choose a save location. --- # Run a task Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/run-task/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB data processing tasks generally run in defined intervals or at a specific time, however, you can manually run a task from the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB `/api/v2` API. ## Run a task from the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. Tasks 2. Hover over the task you want to run and click the icon. 3. Select **Run Task**. ## Run a task with the influx CLI Use the `influx task run retry` command to run a task. > [!Note] > To run a task from the `influx` CLI, the task must have already run at least once. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ```sh # List all tasks to find the ID of the task to run influx task list # Use the task ID to list previous runs of the task influx task run list --task-id=0000000000000000 # Use the task ID and run ID to retry a run influx task run retry --task-id=0000000000000000 --run-id=0000000000000000 ``` ### Retry failed task runs Use the [`influx task retry-failed` command](/influxdb/v2/reference/cli/influx/task/retry-failed/)to retry failed task runs. ```sh # Retry failed tasks for a specific task influx task retry-failed \ --id 0000000000000000 # Print information about runs that will be retried influx task retry-failed \ --dry-run # Retry failed task runs that occurred in a specific time range influx task retry-failed \ --after 2021-01-01T00:00:00Z \ --before 2021-01-01T23:59:59Z ``` ## Run a task with the InfluxDB API Use the [`/tasks/TASK_ID/runs` InfluxDB API endpoint](/influxdb/v2/api/tasks//-taskID-/runs)to manually start a task run. ``` POST http://localhost:8086/api/v2/tasks/TASK_ID/runs ``` ### Retry failed task runs Use the [`/tasks/TASK_ID/runs/RUN_ID/retry` InfluxDB API endpoint](/influxdb/v2/api/tasks//-taskID-/runs/-runID-/retry)to retry a task run. ``` POST http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/retry ``` #### Related * [influx task run](/influxdb/v2/reference/cli/influx/task/run/) * [influx task run retry](/influxdb/v2/reference/cli/influx/task/run/retry/) * [influx task retry-failed](/influxdb/v2/reference/cli/influx/task/retry-failed/) * [/influxdb/v2/api/tasks/](/influxdb/v2/api/tasks/) * [/influxdb/v2/api/tasks/](/influxdb/v2/api/tasks/) --- # View task run history and logs Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/task-run-history/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). When an InfluxDB task runs, a *run* record is created in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB `/api/v2` API to view task run histories and associated logs. InfluxDB doesn’t guarantee that a task will run at the scheduled time. During busy periods, tasks are added to the run queue and processed in order of submission. The scheduled start time and actual start time can be viewed in the logs under`scheduledFor` and `startedAt`. Task execution time doesn’t affect the time range queried. Tasks will query over the set time range as if executed on schedule regardless of delay. ## View a task’s run history in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. Tasks 2. Hover over the task you want to run and click the icon. 3. Select **View Task Runs**. ### View task run logs To view logs associated with a run, click **View Logs** next to the run in the task’s run history. ## View a task’s run history with the influx CLI Use the `influx task run list` command to view a task’s run history. ```sh # List all tasks to find the ID of the task to run influx task list # Use the task ID to view the run history of a task influx task run list --task-id=0000000000000000 ``` > [!Note] > Detailed run logs are not currently available in the `influx` CLI. To retry failed task runs, see how to [run tasks](/influxdb/v2/process-data/manage-tasks/run-task/). ## View logs for a task with the InfluxDB API Use the [`/api/v2/tasks/TASK_ID/logs` InfluxDB API endpoint](/influxdb/v2/api/tasks/)to view the log events for a task and exclude additional task metadata. ``` GET http://localhost:8086/api/v2/tasks/TASK_ID/logs ``` ## View a task’s run history with the InfluxDB API Use the [`/tasks/TASK_ID/runs` InfluxDB API endpoint](/influxdb/v2/api/tasks/)to view a task’s run history. ``` GET http://localhost:8086/api/v2/tasks/{taskID}/runs ``` ### View task run logs with the InfluxDB API To view logs associated with a run, use the[`/api/v2/tasks/TASK_ID/runs/RUN_ID/logs` InfluxDB API endpoint](/influxdb/v2/api/tasks/). ``` GET http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/logs ``` To retry failed task runs, see how to [run tasks](/influxdb/v2/process-data/manage-tasks/run-task/). #### Related * [influx task list](/influxdb/v2/reference/cli/influx/task/list/) * [influx task run list](/influxdb/v2/reference/cli/influx/task/run/list/) * [influx task retry-failed](/influxdb/v2/reference/cli/influx/task/retry-failed/) --- # Update a task Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/update-task/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## Update a task in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. Tasks Tasks 2. Find the task you would like to edit and click the icon located far right of the task name. 3. Click **Edit**. 4. Click **Save** in the upper right. #### Update a task Flux script 1. In the list of tasks, click the **Name** of the task you want to update. 2. In the left panel, modify the task options. 3. In the right panel, modify the task script. 4. Click **Save** in the upper right. #### Update the status of a task In the list of tasks, click the toggle to the left of the task you want to activate or inactivate. #### Update a task description 1. In the list of tasks, hover over the name of the task you want to update. 2. Click the pencil icon . 3. Click outside of the field or press `RETURN` to update. ## Update a task with the influx CLI Use the `influx task update` command to update or change the status of an existing task. *This command requires a task ID, which is available in the output of `influx task list`.* #### Update a task Flux script Pass the file path of your updated Flux script to the `influx task update` command with the ID of the task you want to update. Modified [task options](/influxdb/v2/process-data/task-options) defined in the Flux script are also updated. ```sh # Syntax influx task update -i -f ``` ```sh # Example influx task update -i 0343698431c35000 -f /tasks/cq-mean-1h.flux ``` #### Update the status of a task Pass the ID of the task you want to update to the `influx task update`command with the `--status` flag. *Possible arguments of the `--status` flag are `active` or `inactive`.* ```sh # Syntax influx task update -i --status < active | inactive > ``` ```sh # Example influx task update -i 0343698431c35000 --status inactive ``` ## Update a task with the InfluxDB API Use the [`/tasks/TASK_ID` InfluxDB API endpoint](/influxdb/v2/api/tasks/) to update properties of a task. ``` PATCH http://localhost:8086/api/v2/tasks/TASK_ID ``` In your request, pass the task ID and an object that contains the updated key-value pairs. To activate or inactivate a task, set the `status` property.`"status": "inactive"` cancels scheduled runs and prevents manual runs of the task.*To find the task ID, see [how to view tasks](/influxdb/v2/process-data/manage-tasks/view-tasks/).* Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. #### Related * [influx task update](/influxdb/v2/reference/cli/influx/task/update/) --- # View tasks Source: https://docs.influxdata.com/influxdb/v2/process-data/manage-tasks/view-tasks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## View tasks in the InfluxDB UI Click the **Tasks** icon in the left navigation to view the lists of tasks. Tasks ### Filter the list of tasks 1. Click the **Show Inactive** toggle to include or exclude inactive tasks in the list. 2. Enter text in the **Filter tasks** field to search for tasks by name or label. 3. Click the heading of any column to sort by that field. ## View tasks with the influx CLI Use the `influx task list` command to return a list of tasks. ```sh influx task list ``` #### Filter tasks using the CLI Other filtering options such as filtering by organization or user, or limiting the number of tasks returned, are available. See the [`influx task list` documentation](/influxdb/v2/reference/cli/influx/task/list)for information about other available flags. ## View tasks with the InfluxDB API Use the [`/tasks` InfluxDB API endpoint](/influxdb/v2/api/tasks/)to return a list of tasks. ``` GET http://localhost:8086/api/v2/tasks ``` #### Related * [influx task list](/influxdb/v2/reference/cli/influx/task/list/) --- # Task configuration options Source: https://docs.influxdata.com/influxdb/v2/process-data/task-options/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Task options define specific information about a task. They are set in a Flux script or in the InfluxDB user interface (UI). The following task options are available: * [name](#name) * [every](#every) * [cron](#cron) * [offset](#offset) > [!Note] > `every` and `cron` are mutually exclusive, but at least one is required. ## name The name of the task. ***Required***. ***Data type:** String* In Flux: ```js option task = { name: "taskName", // ... } ``` ## every The interval at which the task runs. This option also determines when the task first starts to run, depending on the specified time (in [duration literal](/flux/v0/spec/lexical-elements/#duration-literals)). ***Data type:** Duration* For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): `option task = {name: "aggregation", every: 1h}` The task first executes at 3:00pm, and subsequently every hour after that. In Flux: ```js option task = { // ... every: 1h, } ``` > [!Note] > In the InfluxDB UI, use the **Interval** field to set this option. ## cron The [cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. Cron scheduling is based on system time. ***Data type:** String* In Flux: ```js option task = { // ... cron: "0 * * * *", } ``` ## offset Delays the execution of the task but preserves the original time range. For example, if a task is to run on the hour, a `10m` offset will delay it to 10 minutes after the hour, but all time ranges defined in the task are relative to the specified execution time. A common use case is offsetting execution to account for data that may arrive late. ***Data type:** Duration* In Flux: ```js option task = { // ... offset: 10m, } ``` [tasks](/influxdb/v2/tags/tasks/)[flux](/influxdb/v2/tags/flux/) --- # Query data in InfluxDB Source: https://docs.influxdata.com/influxdb/v2/query-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Learn to query data stored in InfluxDB using Flux and tools such as the InfluxDB user interface and the ‘influx’ command line interface. ### [Get started with Flux and InfluxDB](/influxdb/v2/query-data/get-started/) Get started with Flux, the functional data scripting language, and learn the basics of writing a Flux query that queries InfluxDB. ### [Query data with Flux](/influxdb/v2/query-data/flux/) Guides that walk through both common and complex queries and use cases for Flux. ### [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) Use the InfluxDB v1 `/query` compatibility endpoint to query data in InfluxDB v2 using InfluxQL. ### [Execute queries](/influxdb/v2/query-data/execute-queries/) There are multiple ways to query data from InfluxDB including the InfluxDB UI, CLI, and API. ### [Common queries](/influxdb/v2/query-data/common-queries/) This collection of articles walks through common use cases for Flux queries. ### [Optimize Flux queries](/influxdb/v2/query-data/optimize-queries/) Optimize your Flux queries to reduce their memory and compute (CPU) requirements. ![InfluxDB University](/svgs/influxdbu-full-white.svg) #### InfluxDB Essentials Learn how to write, query, and visualize data in InfluxDB in this **free** InfluxDB University course. [Take the course](https://university.influxdata.com/courses/influxdb-essentials-tutorial/) [query](/influxdb/v2/tags/query/)[flux](/influxdb/v2/tags/flux/) --- # Common queries Source: https://docs.influxdata.com/influxdb/v2/query-data/common-queries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles walk through common queries using the[NOAA water database data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). ### [Operate on columns](/influxdb/v2/query-data/common-queries/operate-on-columns/) Find and count unique values, recalculate the `_value` column, and use values to calculate a new column. ### [Use multiple fields in a calculation](/influxdb/v2/query-data/common-queries/multiple-fields-in-calculations/) Query multiple fields, pivot results, and use multiple field values to calculate new values in query results. ### [Comparing values from different buckets](/influxdb/v2/query-data/common-queries/compare-values/) Compare the value from the latest point to an average value stored in another bucket. This is useful when using the average value to calculate a threshold check. ### [IoT sensor common queries](/influxdb/v2/query-data/common-queries/iot-common-queries/) Use Flux to address common IoT use cases that query data collected from sensors. > [!Note] > This list will continue to grow. > If you have suggestions, please [submit them to the InfluxData Community](https://community.influxdata.com/c/influxdb2). [queries](/influxdb/v2/tags/queries/) --- # Comparing values from different buckets Source: https://docs.influxdata.com/influxdb/v2/query-data/common-queries/compare-values/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Note] > This example uses [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). This example compares the value from the latest point to an average value stored in another bucket. This is useful when using the average value to calculate a [threshold check](/influxdb/v2/monitor-alert/checks/create/#threshold-check). The following query: * Uses [`range()`](/flux/v0/stdlib/universe/range/) to define a time range. * Gets the last value in the `means` bucket and compares it to the last value in the `noaa` bucket using [`last()`](/flux/v0/stdlib/universe/last/). * Uses [`join()`](/flux/v0/stdlib/universe/join/) to combine the results * Uses [`map()`](/flux/v0/stdlib/universe/map/) to calculate the differences ```js means = from(bucket: "weekly_means") |> range(start: 2019-09-01T00:00:00Z) |> last() |> keep(columns: ["_value", "location"]) latest = from(bucket: "noaa") |> range(start: 2019-09-01T00:00:00Z) |> filter(fn: (r) => r._measurement == "average_temperature") |> last() |> keep(columns: ["_value", "location"]) join(tables: {mean: means, reading: latest}, on: ["location"]) |> map(fn: (r) => ({r with deviation: r._value_reading - r._value_mean})) ``` ### Example results | location | \_value\_mean |\_value\_reading| deviation | |-------------|-----------------|----------------|-----------------| |coyote\_creek|79.82710622710623| 89 |9.172893772893772| |santa\_monica|80.20451339915374| 85 |4.79548660084626 | [queries](/influxdb/v2/tags/queries/) | location | _value_mean | _value_reading | deviation | | --- | --- | --- | --- | | location | _value_mean | _value_reading | deviation | | coyote_creek | 79.82710622710623 | 89 | 9.172893772893772 | | santa_monica | 80.20451339915374 | 85 | 4.79548660084626 | --- # IoT sensor common queries Source: https://docs.influxdata.com/influxdb/v2/query-data/common-queries/iot-common-queries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following scenarios illustrate common queries used to extract information from IoT sensor data: * [Calculate time in state](#calculate-time-in-state) * [Calculate time weighted average](#calculate-time-weighted-average) * [Calculate value between events](#calculate-value-between-events) * [Determine a state within existing values](#determine-a-state-within-existing-values) All scenarios below use the `machineProduction` sample dataset provided by the [InfluxDB `sample` package](/flux/v0/stdlib/influxdata/influxdb/sample/). For more information, see [Sample data](/influxdb/cloud/reference/sample-data/). ## Calculate time in state In this scenario, we look at whether a production line is running smoothly (`state`=`OK`) and what percentage of time the production line is running smoothly or not (`state`=`NOK`). If no points are recorded during the interval (`state`=`NaN`), you may opt to retrieve the last state prior to the interval. To visualize the time in state, see the [Mosaic visualization](#mosaic-visualization). **To calculate the percentage of time a machine spends in each state** 1. Import the [`contrib/tomhollingworth/events` package](/flux/v0/stdlib/contrib/tomhollingworth/events/). 2. Query the `state` field. 3. Use `events.duration()` to return the amount of time (in a specified unit) between each data point, and store the interval in the `duration` column. 4. Group columns by the status value column (in this case `_value`), `_start`, `_stop`, and other relevant dimensions. 5. Sum the `duration` column to calculate the total amount of time spent in each state. 6. Pivot the summed durations into the `_value` column. 7. Use `map()` to calculate the percentage of time spent in each state. ``` import "contrib/tomhollingworth/events" from(bucket: "machine") |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:30:00Z) |> filter(fn: (r) => r["_measurement"] == "machinery") |> filter(fn: (r) => r["_field"] == "state") |> events.duration(unit: 1h, columnName: "duration") |> group(columns: ["_value", "_start", "_stop", "station_id"]) |> sum(column: "duration") |> pivot(rowKey: ["_stop"], columnKey: ["_value"], valueColumn: "duration") |> map( fn: (r) => { totalTime = float(v: r.NOK + r.OK) return {r with NOK: float(v: r.NOK) / totalTime * 100.0, OK: float(v: r.OK) / totalTime * 100.0} }, ) ``` The query above focuses on a specific time range of state changes reported in the production line. * `range()` defines the time range to query. * `filter()` defines the field (`state`) and measurement (`machinery`) to filter by. * `events.duration()` calculates the time between points. * `group()` regroups the data by the field value, so points with `OK` and `NOK` field values are grouped into separate tables. * `sum()` returns the sum of durations spent in each state. The output of the query at this point is: |\_value|duration| |-------|--------| | NOK | 22 | |\_value|duration| |-------|--------| | OK | 172 | `pivot()` creates columns for each unique value in the `_value` column, and then assigns the associated duration as the column value. The output of the pivot operation is: |NOK|OK | |---|---| |22 |172| Given the output above, `map()` does the following: 1. Adds the `NOK` and `OK` values to calculate `totalTime`. 2. Divides `NOK` by `totalTime`, and then multiplies the quotient by 100. 3. Divides `OK` by `totalTime`, and then multiplies the quotient by 100. This returns: | NOK | OK | |-----------------|-----------------| |11.34020618556701|88.65979381443299| The result shows that 88.66% of time production is in the `OK` state, and that 11.34% of time, production is in the `NOK` state. #### Mosaic visualization The [mosaic visualization](/influxdb/v2/visualize-data/visualization-types/mosaic/) displays state changes over time. In this example, the mosaic visualization displays different colored tiles based on the `state` field. ```js from(bucket: "machine") |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:30:00Z) |> filter(fn: (r) => r._measurement == "machinery") |> filter(fn: (r) => r._field == "state") |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false) ``` When visualizing data, it is possible to have more data points than available pixels. To divide data into time windows that span a single pixel, use `aggregateWindow` with the `every` parameter set to `v.windowPeriod`. Use `last` as the aggregate `fn` to return the last value in each time window. Set `createEmpty` to `false` so results won’t include empty time windows. ## Calculate time weighted average To calculate the time-weighted average of data points, use the [`timeWeightedAvg()` function](/flux/v0/stdlib/universe/timeweightedavg/). The example below queries the `oil_temp` field in the `machinery` measurement. The `timeWeightedAvg()` function returns the time-weighted average of oil temperatures based on 5 second intervals. ```js from(bucket: "machine") |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-01T00:00:30Z) |> filter(fn: (r) => r._measurement == "machinery" and r._field == "oil_temp") |> timeWeightedAvg(unit: 5s) ``` ##### Output data |stationID| \_start | \_stop | \_value | |---------|------------------------|------------------------|------------------| | g1 |2021-08-01T01:00:00.000Z|2021-08-01T00:00:30.000Z|40.25396118491921 | | g2 |2021-08-01T01:00:00.000Z|2021-08-01T00:00:30.000Z| 40.6 | | g3 |2021-08-01T01:00:00.000Z|2021-08-01T00:00:30.000Z|41.384505595567866| | g4 |2021-08-01T01:00:00.000Z|2021-08-01T00:00:30.000Z|41.26735518634935 | ## Calculate value between events Calculate the value between events by getting the average value during a specific time range. The following scenario queries data starting when four production lines start and end. The following query calculates the average oil temperature for each grinding station during that period. ```js batchStart = 2021-08-01T00:00:00Z batchStop = 2021-08-01T00:00:20Z from(bucket: "machine") |> range(start: batchStart, stop: batchStop) |> filter(fn: (r) => r._measurement == "machinery" and r._field == "oil_temp") |> mean() ``` ##### Output |stationID| \_start | \_stop | \_value | |---------|------------------------|------------------------|------------------| | g1 |2021-08-01T01:00:00.000Z|2021-08-02T00:00:00.000Z| 40 | | g2 |2021-08-01T01:00:00.000Z|2021-08-02T00:00:00.000Z| 40.6 | | g3 |2021-08-01T01:00:00.000Z|2021-08-02T00:00:00.000Z|41.379999999999995| | g4 |2021-08-01T01:00:00.000Z|2021-08-02T00:00:00.000Z| 41.2 | ## Determine a state with existing values Use multiple existing values to determine a state. The following example calculates a state based on the difference between the `pressure` and `pressure-target` fields in the machine-production sample data. To determine a state by comparing existing fields: 1. Query the fields to compare (in this case, `pressure` and `pressure_target`). 2. (Optional) Use `aggregateWindow()` to window data into time-based windows and apply an aggregate function (like `mean()`) to return values that represent larger windows of time. 3. Use `pivot()` to shift field values into columns. 4. Use `map()` to compare or operate on the different field column values. 5. Use `map()` to assign a status (in this case, `needsMaintenance` based on the relationship of the field column values. ```js import "math" from(bucket: "machine") |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:00:00Z) |> filter(fn: (r) => r["_measurement"] == "machinery") |> filter(fn: (r) => r["_field"] == "pressure" or r["_field"] == "pressure_target") |> aggregateWindow(every: 12h, fn: mean) |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") |> map(fn: (r) => ({ r with pressureDiff: r.pressure - r.pressure_target })) |> map(fn: (r) => ({ r with needsMaintenance: if math.abs(x: r.pressureDiff) >= 15.0 then true else false })) ``` ##### Output | \_time |needsMaintenance| pressure | pressure\_target | pressureDiff |stationID| |------------------------|----------------|------------------|------------------|--------------------|---------| |2021-08-01T12:00:00.000Z| false |101.83929080014092|104.37786394078252|\-2.5385731406416028| g1 | |2021-08-02T00:00:00.000Z| false |96.04368008245874 |102.27698650674662|\-6.233306424287889 | g1 | | \_time |needsMaintenance| pressure | pressure\_target | pressureDiff |stationID| |------------------------|----------------|------------------|------------------|--------------------|---------| |2021-08-01T12:00:00.000Z| false |101.62490431541765|104.83915260886623|\-3.214248293448577 | g2 | |2021-08-02T00:00:00.000Z| false |94.52039415465273 |105.90869375273046|\-11.388299598077722| g2 | | \_time |needsMaintenance| pressure | pressure\_target | pressureDiff |stationID| |------------------------|----------------|-----------------|------------------|--------------------|---------| |2021-08-01T12:00:00.000Z| false |92.23774168403503|104.81867444768653|\-12.580932763651504| g3 | |2021-08-02T00:00:00.000Z| true |89.20867846153847|108.2579185520362 |\-19.049240090497733| g3 | | \_time |needsMaintenance| pressure | pressure\_target | pressureDiff |stationID| |------------------------|----------------|-----------------|------------------|--------------------|---------| |2021-08-01T12:00:00.000Z| false |94.40834093349847|107.6827757125155 |\-13.274434779017028| g4 | |2021-08-02T00:00:00.000Z| true |88.61785638936534|108.25471698113208|\-19.636860591766734| g4 | The table reveals that the `pressureDiff` value `-19.636860591766734` from station g4 and `-19.049240090497733` from station g3 are higher than 15, therefore there is a change in state that marks the `needMaintenance` value as “true” and would require that station to need work to turn that value back to `false`. [queries](/influxdb/v2/tags/queries/) | _value | duration | | --- | --- | | _value | duration | | NOK | 22 | | _value | duration | | --- | --- | | _value | duration | | OK | 172 | | NOK | OK | | --- | --- | | NOK | OK | | 22 | 172 | | NOK | OK | | --- | --- | | NOK | OK | | 11.34020618556701 | 88.65979381443299 | | stationID | _start | _stop | _value | | --- | --- | --- | --- | | stationID | _start | _stop | _value | | g1 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 40.25396118491921 | | g2 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 40.6 | | g3 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 41.384505595567866 | | g4 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 41.26735518634935 | | stationID | _start | _stop | _value | | --- | --- | --- | --- | | stationID | _start | _stop | _value | | g1 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 40 | | g2 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 40.6 | | g3 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 41.379999999999995 | | g4 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 41.2 | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | --- | --- | --- | --- | --- | --- | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | 2021-08-01T12:00:00.000Z | false | 101.83929080014092 | 104.37786394078252 | -2.5385731406416028 | g1 | | 2021-08-02T00:00:00.000Z | false | 96.04368008245874 | 102.27698650674662 | -6.233306424287889 | g1 | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | --- | --- | --- | --- | --- | --- | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | 2021-08-01T12:00:00.000Z | false | 101.62490431541765 | 104.83915260886623 | -3.214248293448577 | g2 | | 2021-08-02T00:00:00.000Z | false | 94.52039415465273 | 105.90869375273046 | -11.388299598077722 | g2 | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | --- | --- | --- | --- | --- | --- | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | 2021-08-01T12:00:00.000Z | false | 92.23774168403503 | 104.81867444768653 | -12.580932763651504 | g3 | | 2021-08-02T00:00:00.000Z | true | 89.20867846153847 | 108.2579185520362 | -19.049240090497733 | g3 | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | --- | --- | --- | --- | --- | --- | | _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | | 2021-08-01T12:00:00.000Z | false | 94.40834093349847 | 107.6827757125155 | -13.274434779017028 | g4 | | 2021-08-02T00:00:00.000Z | true | 88.61785638936534 | 108.25471698113208 | -19.636860591766734 | g4 | --- # Use multiple fields in a calculation Source: https://docs.influxdata.com/influxdb/v2/query-data/common-queries/multiple-fields-in-calculations/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To use values from multiple fields in a mathematic calculation, complete the following steps: 1. [Filter by fields required in your calculation](#filter-by-fields) 2. [Pivot fields into columns](#pivot-fields-into-columns) 3. [Perform the mathematic calculation](#perform-the-calculation) ## Filter by fields Use [`filter()`](/flux/v0/stdlib/universe/filter/)to return only the fields necessary for your calculation. Use the [`or` logical operator](/flux/v0/spec/operators/#logical-operators)to filter by multiple fields. The following example queries two fields, `A` and `B`: ```js from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._field == "A" or r._field == "B") ``` This query returns one or more tables for each field. For example: | \_time |\_field|\_value| |--------------------|-------|-------| |2021-01-01T00:00:00Z| A | 12.4 | |2021-01-01T00:00:15Z| A | 12.2 | |2021-01-01T00:00:30Z| A | 11.6 | |2021-01-01T00:00:45Z| A | 11.9 | | \_time |\_field|\_value| |--------------------|-------|-------| |2021-01-01T00:00:00Z| B | 3.1 | |2021-01-01T00:00:15Z| B | 4.8 | |2021-01-01T00:00:30Z| B | 2.2 | |2021-01-01T00:00:45Z| B | 3.3 | ## Pivot fields into columns Use [`pivot()`](/flux/v0/stdlib/universe/pivot/)to align multiple fields by time. > [!Note] > To correctly pivot on `_time`, points for each field must have identical timestamps. > If timestamps are irregular or do not align perfectly, see[Normalize irregular timestamps](/influxdb/v2/query-data/flux/manipulate-timestamps/#normalize-irregular-timestamps). ```js // ... |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") ``` Using the queried data [above](#filter-by-fields), this `pivot()` function returns: | \_time | A | B | |--------------------|----|---| |2021-01-01T00:00:00Z|12.4|3.1| |2021-01-01T00:00:15Z|12.2|4.8| |2021-01-01T00:00:30Z|11.6|2.2| |2021-01-01T00:00:45Z|11.9|3.3| ## Perform the calculation Use [`map()`](/flux/v0/stdlib/universe/map/)to perform the mathematic operation using column values as operands. The following example uses values in the `A` and `B` columns to calculate a new `_value` column: ```js // ... |> map(fn: (r) => ({ r with _value: r.A * r.B })) ``` Using the pivoted data above, this `map()` function returns: | \_time | A | B |\_value| |--------------------|----|---|-------| |2021-01-01T00:00:00Z|12.4|3.1| 38.44 | |2021-01-01T00:00:15Z|12.2|4.8| 58.56 | |2021-01-01T00:00:30Z|11.6|2.2| 25.52 | |2021-01-01T00:00:45Z|11.9|3.3| 39.27 | ## Full example query ```js from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._field == "A" or r._field == "B") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> map(fn: (r) => ({r with _value: r.A * r.B})) ``` [queries](/influxdb/v2/tags/queries/) | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2021-01-01T00:00:00Z | A | 12.4 | | 2021-01-01T00:00:15Z | A | 12.2 | | 2021-01-01T00:00:30Z | A | 11.6 | | 2021-01-01T00:00:45Z | A | 11.9 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2021-01-01T00:00:00Z | B | 3.1 | | 2021-01-01T00:00:15Z | B | 4.8 | | 2021-01-01T00:00:30Z | B | 2.2 | | 2021-01-01T00:00:45Z | B | 3.3 | | _time | A | B | | --- | --- | --- | | _time | A | B | | 2021-01-01T00:00:00Z | 12.4 | 3.1 | | 2021-01-01T00:00:15Z | 12.2 | 4.8 | | 2021-01-01T00:00:30Z | 11.6 | 2.2 | | 2021-01-01T00:00:45Z | 11.9 | 3.3 | | _time | A | B | _value | | --- | --- | --- | --- | | _time | A | B | _value | | 2021-01-01T00:00:00Z | 12.4 | 3.1 | 38.44 | | 2021-01-01T00:00:15Z | 12.2 | 4.8 | 58.56 | | 2021-01-01T00:00:30Z | 11.6 | 2.2 | 25.52 | | 2021-01-01T00:00:45Z | 11.9 | 3.3 | 39.27 | --- # Operate on columns Source: https://docs.influxdata.com/influxdb/v2/query-data/common-queries/operate-on-columns/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the following common queries to operate on columns: * [Find and count unique values in a column](#find-and-count-unique-values-in-a-column) * [Recalculate the \_values column](#recalculate-the-_values-column) * [Calculate a new column](#calculate-a-new-column) > [!Note] > These examples use [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). ## Find and count unique values in a column Find and count the number of unique values in a specified column. The following examples find and count unique locations where data was collected. ### Find unique values This query: * Uses [`group()`](/flux/v0/stdlib/universe/group/) to ungroup data and return results in a single table. * Uses [`keep()`](/flux/v0/stdlib/universe/keep/) and [`unique()`](/flux/v0/stdlib/universe/unique/) to return unique values in the specified column. ```js from(bucket: "noaa") |> range(start: -30d) |> group() |> keep(columns: ["location"]) |> unique(column: "location") ``` #### Example results | location | |-------------| |coyote\_creek| |santa\_monica| ### Count unique values This query: * Uses [`group()`](/flux/v0/stdlib/universe/group/) to ungroup data and return results in a single table. * Uses [`keep()`](/flux/v0/stdlib/universe/keep/), [`unique()`](/flux/v0/stdlib/universe/unique/), and then [`count()`](/flux/v0/stdlib/universe/count/) to count the number of unique values. ```js from(bucket: "noaa") |> group() |> unique(column: "location") |> count(column: "location") ``` #### Example results |location| |--------| | 2 | ## Recalculate the \_values column To recalculate the `_value` column, use the `with` operator in [`map()`](/flux/v0/stdlib/universe/map/) to overwrite the existing `_value` column. The following query: * Uses [`filter()`](/flux/v0/stdlib/universe/filter/) to filter the `average_temperature` measurement. * Uses [`map()`](/flux/v0/stdlib/universe/map/) to convert Fahrenheit temperature values into Celsius. ``` from(bucket: "noaa") |> filter(fn: (r) => r._measurement == "average_temperature") |> range(start: -30d) |> map(fn: (r) => ({r with _value: (float(v: r._value) - 32.0) * 5.0 / 9.0} )) ``` |\_field| \_measurement | \_start | \_stop | \_time | location | \_value | |-------|--------------------|--------------------|--------------------|--------------------|-------------|------------------| |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:00:00Z|coyote\_creek|27.77777777777778 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:06:00Z|coyote\_creek|22.77777777777778 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:12:00Z|coyote\_creek| 30 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:18:00Z|coyote\_creek|31.666666666666668| |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:24:00Z|coyote\_creek| 25 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:30:00Z|coyote\_creek|21.11111111111111 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:36:00Z|coyote\_creek|28.88888888888889 | |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:42:00Z|coyote\_creek|24.444444444444443| |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:48:00Z|coyote\_creek|29.444444444444443| |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T00:54:00Z|coyote\_creek|26.666666666666668| |degrees|average\_temperature|1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|2019-08-17T01:00:00Z|coyote\_creek|21.11111111111111 | | ••• | ••• | ••• | ••• | ••• | ••• | ••• | ## Calculate a new column To use values in a row to calculate and add a new column, use `map()`. This example below converts temperature from Fahrenheit to Celsius and maps the Celsius value to a new `celsius` column. The following query: * Uses [`filter()`](/flux/v0/stdlib/universe/filter/) to filter the `average_temperature` measurement. * Uses [`map()`](/flux/v0/stdlib/universe/map/) to create a new column calculated from existing values in each row. ```js from(bucket: "noaa") |> filter(fn: (r) => r._measurement == "average_temperature") |> range(start: -30d) |> map(fn: (r) => ({r with celsius: (r._value - 32.0) * 5.0 / 9.0})) ``` #### Example results | \_start | \_stop |\_field| \_measurement | location | \_time |\_value|celsius| |--------------------|--------------------|-------|--------------------|-------------|--------------------|-------|-------| |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:00:00Z| 82 | 27.78 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:06:00Z| 73 | 22.78 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:12:00Z| 86 | 30.00 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:18:00Z| 89 | 31.67 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:24:00Z| 77 | 25.00 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:30:00Z| 70 | 21.11 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:36:00Z| 84 | 28.89 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:42:00Z| 76 | 24.44 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:48:00Z| 85 | 29.44 | |1920-03-05T22:10:01Z|2020-03-05T22:10:01Z|degrees|average\_temperature|coyote\_creek|2019-08-17T00:54:00Z| 80 | 26.67 | | ••• | ••• | ••• | ••• | ••• | ••• | ••• | ••• | [queries](/influxdb/v2/tags/queries/) | location | | --- | | location | | coyote_creek | | santa_monica | | location | | --- | | location | | 2 | | _field | _measurement | _start | _stop | _time | location | _value | | --- | --- | --- | --- | --- | --- | --- | | _field | _measurement | _start | _stop | _time | location | _value | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:00:00Z | coyote_creek | 27.77777777777778 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:06:00Z | coyote_creek | 22.77777777777778 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:12:00Z | coyote_creek | 30 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:18:00Z | coyote_creek | 31.666666666666668 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:24:00Z | coyote_creek | 25 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:30:00Z | coyote_creek | 21.11111111111111 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:36:00Z | coyote_creek | 28.88888888888889 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:42:00Z | coyote_creek | 24.444444444444443 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:48:00Z | coyote_creek | 29.444444444444443 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:54:00Z | coyote_creek | 26.666666666666668 | | degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T01:00:00Z | coyote_creek | 21.11111111111111 | | ••• | ••• | ••• | ••• | ••• | ••• | ••• | | _start | _stop | _field | _measurement | location | _time | _value | celsius | | --- | --- | --- | --- | --- | --- | --- | --- | | _start | _stop | _field | _measurement | location | _time | _value | celsius | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:00:00Z | 82 | 27.78 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:06:00Z | 73 | 22.78 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:12:00Z | 86 | 30.00 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:18:00Z | 89 | 31.67 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:24:00Z | 77 | 25.00 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:30:00Z | 70 | 21.11 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:36:00Z | 84 | 28.89 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:42:00Z | 76 | 24.44 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:48:00Z | 85 | 29.44 | | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:54:00Z | 80 | 26.67 | | ••• | ••• | ••• | ••• | ••• | ••• | ••• | ••• | --- # Execute queries Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). There are multiple ways to execute queries with InfluxDB. Choose from the following options: ### [Query in Data Explorer](/influxdb/v2/query-data/execute-queries/data-explorer/) Query InfluxDB using the InfluxDB user interface (UI) Data Explorer. Discover how to query data in InfluxDB 2.1 using the InfluxDB UI. ### [Query with the InfluxDB API](/influxdb/v2/query-data/execute-queries/influx-api/) Query InfluxDB with the InfluxDB API. Discover how to query data in InfluxDB 2.1 using the InfluxDB API. ### [Query in the Flux REPL](/influxdb/v2/query-data/execute-queries/flux-repl/) Query InfluxDB using the Flux REPL. Discover how to query data in InfluxDB 2.5 using the Flux REPL. ### [Use the influx query command](/influxdb/v2/query-data/execute-queries/influx-query/) Query InfluxDB using the influx CLI. Discover how to query data in InfluxDB 2.1 using `influx query`. ### [Query sample data](/influxdb/v2/query-data/execute-queries/query-sample-data/) Explore InfluxDB OSS with our sample data buckets. [query](/influxdb/v2/tags/query/) --- # Query in Data Explorer Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/data-explorer/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Build, execute, and visualize your queries in InfluxDB UI’s **Data Explorer**. ![Data Explorer with Flux](/img/influxdb/2-0-data-explorer.png) Move seamlessly between using the Flux builder or templates and manually editing the query. Choose between [visualization types](/influxdb/v2/visualize-data/visualization-types/) for your query. ## Query data with Flux and the Data Explorer Flux is a functional data scripting language designed for querying, analyzing, and acting on time series data. See [Get started with Flux](/influxdb/v2/query-data/get-started) to learn more about Flux. 1. In the navigation menu on the left, click **Data Explorer**. Data Explorer 2. Use the Flux builder in the bottom panel to create a Flux query: * Select a bucket to define your data source or select `+ Create Bucket` to add a new bucket. * Edit your time range with the [time range option](#select-time-range) in the dropdown menu. * Add filters to narrow your data by selecting attributes or columns in the dropdown menu. * Select **Group** from the **Filter** dropdown menu to group data into tables. For more about how grouping data in Flux works, see [Group data](/influxdb/v2/query-data/flux/group-data/). 3. Alternatively, click **Script Editor** to manually edit the query. To switch back to the query builder, click **Query Builder**. Note that your updates from the Script Editor will not be saved. 4. Use the **Functions** list to review the available Flux functions. Click a function from the list to add it to your query. 5. Click **Submit** (or press `Control+Enter`) to run your query. You can then preview your graph in the above pane. To cancel your query while it’s running, click **Cancel**. 6. To work on multiple queries at once, click the to add another tab. * Click the eye icon on a tab to hide or show a query’s visualization. * Click the name of the query in the tab to rename it. ## Visualize your query * Select an available [visualization types](/influxdb/v2/visualize-data/visualization-types/) from the dropdown menu in the upper-left: ## Control your dashboard cell To open the cell editor overlay, click the gear icon in the upper right of a cell and select **Configure**. The cell editor overlay opens. ### View raw data Toggle the **View Raw Data** option to see your data in table format instead of a graph. Scroll through raw data using arrows, or click page numbers to find specific tables. [Group keys](/influxdb/cloud/reference/glossary/#group-key) and [data types](/influxdb/cloud/reference/glossary/#data-type) are easily identifiable at the top of each column underneath the headings. Use this option when data can’t be visualized using a visualization type. View raw data ### Save as CSV Click the CSV icon to save the cells contents as a CSV file. ### Manually refresh dashboard Click the refresh button () to manually refresh the dashboard’s data. ### Select time range 1. Select from the time range options in the dropdown menu. Select time range 2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. The default time range is 5m. > > > The custom time range uses the selected timezone (local time or UTC). > > ### Query Builder or Script Editor Click **Query Builder** to use the builder to create a Flux query. Click **Script Editor** to manually edit the query. #### Keyboard shortcuts In **Script Editor** mode, the following keyboard shortcuts are available: | Key | Description | |------------------------------|-------------------------------------------| |`Control + /` (`⌘ + /` on Mac)|Comment/uncomment current or selected lines| | `Control + Enter` | Submit query | ## Save your query as a dashboard cell or task * Click **Save as** in the upper right, and then: * To add your query to a dashboard, click **Dashboard Cell**. * To save your query as a task, click **Task**. * To save your query as a variable, click **Variable**. [query](/influxdb/v2/tags/query/) | Key | Description | | --- | --- | | Key | Description | | Control + / ( ⌘ + / on Mac) | Comment/uncomment current or selected lines | | Control + Enter | Submit query | --- # Query in the Flux REPL Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/flux-repl/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The [Flux REPL](/influxdb/v2/tools/flux-repl/) starts an interactive Read-Eval-Print Loop (REPL) where you can write and execute Flux queries. ```sh ./flux repl ``` For more information, see [Use the Flux REPL](/influxdb/v2/tools/flux-repl/). [query](/influxdb/v2/tags/query/) --- # Query with the InfluxDB API Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/influx-api/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The [InfluxDB v2 API](/influxdb/v2/reference/api) provides a programmatic interface for all interactions with InfluxDB. To query InfluxDB 2.10, do one of the following: * [Send a Flux query request](#send-a-flux-query-request) * [Send an InfluxQL query request](#send-an-influxql-query-request) ## Send a Flux query request Send a Flux query request to the following endpoint: ``` POST /api/v2/query ``` In your request, set the following: * Your organization via the `org` or `orgID` URL parameters * Headers: * `Authorization: Token ` * `Accept: application/csv` * `Content-type: application/vnd.flux` * Your Flux query text in the request body > [!Note] > #### Use gzip to compress a large query response > > To compress the query response, set the `Accept-Encoding` header to `gzip`. > This saves network bandwidth, but increases server-side load. > > We recommend only using gzip compression on responses that are larger than 1.4 KB. > If the response is smaller than 1.4 KB, gzip encoding will always return a 1.4 KB > response, despite the uncompressed response size. > 1500 bytes (\~1.4 KB) is the maximum transmission unit (MTU) size for the public > network and is the largest packet size allowed at the network layer. #### Flux - Example query request The following example shows how to use cURL to send a Flux query to InfluxDB 2.10: [Without compression](#without-compression)[With compression](#with-compression) ```bash curl \ --request POST \ http://localhost:8086/api/v2/query?orgID=ORG_ID \ --header 'Authorization: Token API_TOKEN' \ --header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --data 'from(bucket:"BUCKET_NAME") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1h, fn: mean)' ``` ```bash curl \ --request POST \ http://localhost:8086/api/v2/query?orgID=ORG_ID \ --header 'Authorization: Token API_TOKEN' \ --header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --header 'Accept-Encoding: gzip' \ --data 'from(bucket:"BUCKET_NAME") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1h, fn: mean)' ``` Replace the following with your values: * `ORG_ID` - the ID of the [organization](/influxdb/v2/admin/organizations/) that owns the bucket. * `API_TOKEN` - your [token](/influxdb/v2/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/v2/admin/buckets/) to query. ## Send an InfluxQL query request To query InfluxDB 2.10 using the [InfluxQL query language](/influxdb/v2/reference/syntax/influxql/), send a request to the v1-compatible API endpoint: ``` GET /query ``` ``` POST /query ``` In your request, set the following: * [1.x-compatible or 2.x authentication](/influxdb/v2/api-guide/influxdb-1x/#authentication) credentials * Headers: * `Accept: application/csv` or `Accept: application/json` * `Content-type: application/vnd.influxql` * The database and retention policy mapped to the bucket you want to query * Your InfluxQL query text > [!Note] > If you have an existing bucket that doesn’t follow the **database/retention-policy** naming convention, > you **must** [manually create a database and retention policy mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings)to query that bucket with the `/query` compatibility API. > Use the `db` and `rp` query parameters to specify the database and retention policy > for the bucket you want to query. #### InfluxQL - Example query request The following example shows how to use cURL to send an InfluxQL query to InfluxDB 2.10 using v1-compatible authentication: [HTTP POST](#http-post)[HTTP GET](#http-get) ```bash # 1.x compatible POST request using Basic authentication and InfluxQL curl --request POST \ "http://localhost:8086/query?db=BUCKET_NAME&p=API_TOKEN&u=ignored" \ --header "Content-type: application/vnd.influxql" \ --data "SELECT * FROM home WHERE time > now() - 1h" ``` ```bash # 1.x compatible GET request using Basic authentication and InfluxQL curl --get "http://localhost:8086/query" \ --header "Accept: application/json" \ --data-urlencode "q=SELECT * FROM home WHERE time > now() - 1h" \ --data-urlencode "db=BUCKET_NAME" \ --data-urlencode "u=ignored" \ --data-urlencode "p=API_TOKEN" ``` Replace the following with your values: * `API_TOKEN` - your [token](/influxdb/v2/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/v2/admin/buckets/) to query. [Without compression](#without-compression-2)[With compression](#with-compression-2) ```bash curl --get "http://localhost:8086/query" \ --header 'Accept: application/csv' \ --header 'Content-type: application/json' \ --data-urlencode "db=BUCKET_NAME" \ --data-urlencode "p=API_TOKEN" \ --data-urlencode "u=ignored" \ --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" ``` ```bash curl --get "http://localhost:8086/query" \ --header 'Accept: application/csv' \ --header 'Content-type: application/json' \ --header 'Accept-Encoding: gzip' \ --data-urlencode "db=BUCKET_NAME" \ --data-urlencode "p=API_TOKEN" \ --data-urlencode "u=ignored" \ --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" ``` Replace the following with your values: * `API_TOKEN` - your [token](/influxdb/v2/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/v2/admin/buckets/) to query. InfluxDB returns the query results in [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/). [query](/influxdb/v2/tags/query/) --- # Use the influx query command Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/influx-query/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`influx query` command](/influxdb/v2/reference/cli/influx/query) to query data in InfluxDB using Flux. Pass Flux queries to the command as either a file or via stdin. ###### Run a query from a file ```bash influx query --file /path/to/query.flux ``` ###### Pass raw Flux via stdin pipe ```bash influx query - # Return to open the pipe data = from(bucket: "example-bucket") |> range(start: -10m) # ... # Linux & macOS: to close the pipe and submit the command # Windows: , then , then to close the pipe and submit the command ``` > [!Note] > #### Remove unnecessary columns in large datasets > > When using the `influx query` command to query and download large datasets, > drop columns such as `_start` and `_stop` to optimize the download file size. > > ``` > // ... > |> drop(columns: ["_start", "_stop"]) > ``` #### Related * [influx query](/influxdb/v2/reference/cli/influx/query/) [query](/influxdb/v2/tags/query/) --- # Query sample data Source: https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/query-sample-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use **InfluxDB OSS** sample datasets to quickly access data that lets you explore and familiarize yourself with InfluxDB Cloud without requiring you to have or write your own data. * [Choose sample data](#choose-sample-data) * [Explore sample data](#explore-sample-data) * [Create sample data dashboards](#create-sample-data-dashboards) > [!Note] > #### Network bandwidth > > Each execution of `sample.data()` downloads the specified dataset from **Amazon S3**. > If using [InfluxDB Cloud](/influxdb/cloud/) or a hosted InfluxDB OSS instance, > you may see additional network bandwidth costs when using this function. > Approximate sample dataset sizes are listed for each [sample dataset](/influxdb/v2/reference/sample-data/#sample-datasets) and in the output of [`sample.list()`](/flux/v0/stdlib/influxdata/influxdb/sample/list/). ## Choose sample data 1. Choose from the following sample datasets: * **Air sensor sample data**: Explore, visualize, and monitor humidity, temperature, and carbon monoxide levels in the air. * **Bird migration sample data**: Explore, visualize, and monitor the latitude and longitude of bird migration patterns. * **NOAA NDBC sample data**: Explore, visualize, and monitor NDBC’s observations from their buoys. This data observes air temperature, wind speed, and more from specific locations. * **NOAA water sample data**: Explore, visualize, and monitor temperature, water level, pH, and quality from specific locations. * **USGS Earthquake data**: Explore, visualize, and monitor earthquake monitoring data. This data includes alerts, cdi, quarry blast, magnitide, and more. 2. Do one of the following to download sample data: * [Add sample data with community template](#add-sample-data-with-community-templates) * [Add sample data using the InfluxDB UI](#add-sample-data) ### Add sample data with community template 1. Visit the **InfluxDB templates page** in the InfluxDB OSS UI. Click **Settings** \> **Templates** in the navigation menu on the left. Settings 2. Paste the Sample Data community temple URL in **resource manifest file** field: ``` https://github.com/influxdata/community-templates/blob/master/sample-data/sample-data.yml ``` ## Explore sample data Use the [Data Explorer](/influxdb/cloud/visualize-data/explore-metrics/)to query and visualize data in sample data buckets. In the navigation menu on the left, click **Data Explorer**. Data Explorer ### Add sample data 1. In the navigation menu on the left, click **Data (Load Data)** \> **Buckets**. Load Data 2. Click **Create bucket**, and then name your bucket. The bucket will appear in your list of buckets. 3. View the [sample datasets document](/influxdb/cloud/reference/sample-data/#sample-datasets) and choose a sample data to query. 4. Copy the `sample.data()` function listed underneath. 5. Click **Explore** on the left navigation of InfluxDB Cloud and click your bucket, and then click **Script Editor**. 6. Paste the `sample.data()` function. 7. Click **Submit** to run the query. For more information about querying in the Script Editor, see how to [Query data with Flux and the Data Explorer](/influxdb/cloud/query-data/execute-queries/data-explorer/#query-data-with-flux-and-the-data-explorer). ## Create sample data dashboards After adding a sample data bucket, create a dashboard specific to the sample dataset: 1. Click **Boards (Dashboards)** in the navigation menu on the left. Dashboards 2. Click **Create Dashboard \> New Dashboard**, and name the dashboard after your bucket. 3. Click **Add Cell**, and select your sample data bucket. 4. Click **Script Editor**. 5. Copy and paste the `sample.data()` function into the script editor. 6. Click **Submit** to run the query. 7. Define the variables of your sample data. --- # Query data with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following guides walk through both common and complex queries and use cases for Flux. > [!Note] > #### Example data variable > > Many of the examples provided in the following guides use a `data` variable, > which represents a basic query that filters data by measurement and field.`data` is defined as: > > ``` > data = from(bucket: "example-bucket") > |> range(start: -1h) > |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field") > ``` ## Flux query guides * [Query fields and tags](#query-fields-and-tags) * [Group](#group) * [Sort and limit](#sort-and-limit) * [Window & aggregate](#window-amp-aggregate) * [Explore your schema](#explore-your-schema) * [Transform data with math](#transform-data-with-math) * [Calculate percentages](#calculate-percentages) * [Increase](#increase) * [Moving Average](#moving-average) * [Rate](#rate) * [Histograms](#histograms) * [Fill](#fill) * [Median](#median) * [Percentile & quantile](#percentile-amp-quantile) * [Join](#join) * [Cumulative sum](#cumulative-sum) * [First and last](#first-and-last) * [Exists](#exists) * [Custom functions](#custom-functions) * [Extract scalar values](#extract-scalar-values) * [Monitor states](#monitor-states) * [Operate on timestamps](#operate-on-timestamps) * [Query SQL data](#query-sql-data) * [Conditional logic](#conditional-logic) * [Regular expressions](#regular-expressions) * [Geo-temporal data](#geo-temporal-data) * [Query the Flux version](#query-the-flux-version) ### [Query fields and tags](/influxdb/v2/query-data/flux/query-fields/) Use `filter()` to query data based on fields, tags, or any other column value. `filter()` performs operations similar to the `SELECT` statement and the `WHERE` clause in InfluxQL and other SQL-like query languages. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement" and r.tag == "example-tag") |> filter(fn: (r) => r._field == "example-field") ``` [Read more ](/influxdb/v2/query-data/flux/query-fields/) ### [Group](/influxdb/v2/query-data/flux/group-data/) Use `group()` to group data with common values in specific columns. ```js data |> group(columns: ["host"], mode: "by") ``` ###### Input: | \_time |host |\_value| |--------------------|-----|-------| |2020-01-01T00:01:00Z|host1| 1.0 | |2020-01-01T00:01:00Z|host2| 2.0 | |2020-01-01T00:02:00Z|host1| 1.0 | |2020-01-01T00:02:00Z|host2| 3.0 | ###### Output: | \_time |host |\_value| |--------------------|-----|-------| |2020-01-01T00:01:00Z|host1| 1.0 | |2020-01-01T00:02:00Z|host1| 1.0 | | \_time |host |\_value| |--------------------|-----|-------| |2020-01-01T00:01:00Z|host2| 2.0 | |2020-01-01T00:02:00Z|host2| 3.0 | [Read more ](/influxdb/v2/query-data/flux/group-data/) ### [Sort and limit](/influxdb/v2/query-data/flux/sort-limit/) Use `sort()` to order records within each table by specific columns and `limit()` to limit the number of records in output tables to a fixed number, `n`. ```js data |> sort(columns: ["host", "_value"]) |> limit(n: 4) ``` ###### Input: | \_time |host|\_value| |--------------------|----|-------| |2020-01-01T00:01:00Z| A | 1.0 | |2020-01-01T00:02:00Z| B | 1.2 | |2020-01-01T00:03:00Z| A | 1.8 | |2020-01-01T00:04:00Z| B | 0.9 | |2020-01-01T00:05:00Z| B | 1.4 | |2020-01-01T00:06:00Z| B | 2.0 | ###### Output: | \_time |host|\_value| |--------------------|----|-------| |2020-01-01T00:03:00Z| A | 1.8 | |2020-01-01T00:01:00Z| A | 1.0 | |2020-01-01T00:06:00Z| B | 2.0 | |2020-01-01T00:05:00Z| B | 1.4 | [Read more ](/influxdb/v2/query-data/flux/sort-limit/) ### [Window & aggregate](/influxdb/v2/query-data/flux/window-aggregate/) This guide walks through windowing and aggregating data with Flux and outlines how it shapes your data in the process. ```js data |> aggregateWindow(every: 20m, fn: mean) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:20:00Z| 195 | |2020-01-01T00:40:00Z| 200 | |2020-01-01T01:00:00Z| 290 | |2020-01-01T01:20:00Z| 340 | [Read more ](/influxdb/v2/query-data/flux/window-aggregate/) ### [Explore your schema](/influxdb/v2/query-data/flux/explore-schema/) Flux provides functions that let you explore the structure and schema of your data stored in InfluxDB. ```js import "influxdata/influxdb/schema" // List buckets buckets() // List measurements schema.measurements(bucket: "example-bucket") // List field keys schema.fieldKeys(bucket: "example-bucket") // List tag keys schema.tagKeys(bucket: "example-bucket") // List tag values schema.tagValues(bucket: "example-bucket", tag: "example-tag") ``` [Read more ](/influxdb/v2/query-data/flux/explore-schema/) ### [Transform data with math](/influxdb/v2/query-data/flux/mathematic-operations/) Use `map()` to remap column values and apply mathematic operations. ```js data |> map(fn: (r) => ({ r with _value: r._value * r._value })) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 2 | |2020-01-01T00:02:00Z| 4 | |2020-01-01T00:03:00Z| 3 | |2020-01-01T00:04:00Z| 5 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 4 | |2020-01-01T00:02:00Z| 16 | |2020-01-01T00:03:00Z| 9 | |2020-01-01T00:04:00Z| 25 | [Read more ](/influxdb/v2/query-data/flux/mathematic-operations/) ### [Calculate percentages](/influxdb/v2/query-data/flux/calculate-percentages/) Use [`pivot()` or `join()`](/influxdb/v2/query-data/flux/mathematic-operations/#pivot-vs-join) and the `map()` function to align operand values into rows and calculate a percentage. ```js data |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") |> map( fn: (r) => ({ _time: r._time, _field: "used_percent", _value: float(v: r.used) / float(v: r.total) * 100.0, }), ) ``` ###### Input: | \_time |\_field|\_value| |--------------------|-------|-------| |2020-01-01T00:00:00Z| used | 2.5 | |2020-01-01T00:00:10Z| used | 3.1 | |2020-01-01T00:00:20Z| used | 4.2 | | \_time |\_field|\_value| |--------------------|-------|-------| |2020-01-01T00:00:00Z| total | 8.0 | |2020-01-01T00:00:10Z| total | 8.0 | |2020-01-01T00:00:20Z| total | 8.0 | ###### Output: | \_time | \_field |\_value| |--------------------|-------------|-------| |2020-01-01T00:00:00Z|used\_percent| 31.25 | |2020-01-01T00:00:10Z|used\_percent| 38.75 | |2020-01-01T00:00:20Z|used\_percent| 52.50 | [Read more ](/influxdb/v2/query-data/flux/calculate-percentages/) ### [Increase](/influxdb/v2/query-data/flux/increase/) Use `increase()` to track increases across multiple columns in a table. This function is especially useful when tracking changes in counter values that wrap over time or periodically reset. ```js data |> increase() ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1 | |2020-01-01T00:02:00Z| 2 | |2020-01-01T00:03:00Z| 8 | |2020-01-01T00:04:00Z| 10 | |2020-01-01T00:05:00Z| 0 | |2020-01-01T00:06:00Z| 4 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:02:00Z| 1 | |2020-01-01T00:03:00Z| 7 | |2020-01-01T00:04:00Z| 9 | |2020-01-01T00:05:00Z| 9 | |2020-01-01T00:06:00Z| 13 | [Read more ](/influxdb/v2/query-data/flux/increase/) ### [Moving Average](/influxdb/v2/query-data/flux/moving-average/) Use `movingAverage()` or `timedMovingAverage()` to return the moving average of data. ```js data |> movingAverage(n: 3) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.2 | |2020-01-01T00:03:00Z| 1.8 | |2020-01-01T00:04:00Z| 0.9 | |2020-01-01T00:05:00Z| 1.4 | |2020-01-01T00:06:00Z| 2.0 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:03:00Z| 1.33 | |2020-01-01T00:04:00Z| 1.30 | |2020-01-01T00:05:00Z| 1.36 | |2020-01-01T00:06:00Z| 1.43 | ```js data |> timedMovingAverage(every: 2m, period: 4m) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.2 | |2020-01-01T00:03:00Z| 1.8 | |2020-01-01T00:04:00Z| 0.9 | |2020-01-01T00:05:00Z| 1.4 | |2020-01-01T00:06:00Z| 2.0 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:02:00Z| 1.000 | |2020-01-01T00:04:00Z| 1.333 | |2020-01-01T00:06:00Z| 1.325 | |2020-01-01T00:06:00Z| 1.150 | [Read more ](/influxdb/v2/query-data/flux/moving-average/) ### [Rate](/influxdb/v2/query-data/flux/rate/) Use `derivative()` to calculate the rate of change between subsequent values or `aggregate.rate()` to calculate the average rate of change per window of time. If time between points varies, these functions normalize points to a common time interval making values easily comparable. ```js data |> derivative(unit: 1m, nonNegative: true) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:04:00Z| | |2020-01-01T00:12:00Z| | |2020-01-01T00:19:00Z| 10.0 | |2020-01-01T00:32:00Z| | |2020-01-01T00:51:00Z| 4.74 | |2020-01-01T01:00:00Z| 5.56 | ```js import "experimental/aggregate" data |> aggregate.rate(every: 20m, unit: 1m) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:20:00Z| | |2020-01-01T00:40:00Z| 10.0 | |2020-01-01T01:00:00Z| 4.74 | |2020-01-01T01:20:00Z| 5.56 | [Read more ](/influxdb/v2/query-data/flux/rate/) ### [Histograms](/influxdb/v2/query-data/flux/histograms/) Use `histogram()` to create cumulative histograms with Flux. ```js data |> histogram( column: "_value", upperBoundColumn: "le", countColumn: "_value", bins: [100.0, 200.0, 300.0, 400.0], ) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250.0 | |2020-01-01T00:01:00Z| 160.0 | |2020-01-01T00:02:00Z| 150.0 | |2020-01-01T00:03:00Z| 220.0 | |2020-01-01T00:04:00Z| 200.0 | |2020-01-01T00:05:00Z| 290.0 | |2020-01-01T01:00:00Z| 340.0 | ###### Output: | le |\_value| |-----|-------| |100.0| 0.0 | |200.0| 3.0 | |300.0| 6.0 | |400.0| 7.0 | [Read more ](/influxdb/v2/query-data/flux/histograms/) ### [Fill](/influxdb/v2/query-data/flux/fill/) Use `fill()` function to replace *null* values. ```js data |> fill(usePrevious: true) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| null | |2020-01-01T00:04:00Z| null | |2020-01-01T00:05:00Z| 1.4 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| 0.8 | |2020-01-01T00:04:00Z| 0.8 | |2020-01-01T00:05:00Z| 1.4 | ```js data |> fill(value: 0.0) ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| null | |2020-01-01T00:04:00Z| null | |2020-01-01T00:05:00Z| 1.4 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 0.0 | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| 0.0 | |2020-01-01T00:04:00Z| 0.0 | |2020-01-01T00:05:00Z| 1.4 | [Read more ](/influxdb/v2/query-data/flux/fill/) ### [Median](/influxdb/v2/query-data/flux/median/) Use `median()` to return a value representing the `0.5` quantile (50th percentile) or median of input data. ```js data |> median() ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | ###### Output: |\_value| |-------| | 1.5 | [Read more ](/influxdb/v2/query-data/flux/median/) ### [Percentile & quantile](/influxdb/v2/query-data/flux/percentile-quantile/) Use the `quantile()` function to return all values within the `q` quantile or percentile of input data. ```js data |> quantile(q: 0.99, method: "estimate_tdigest") ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | ###### Output: |\_value| |-------| | 3.0 | [Read more ](/influxdb/v2/query-data/flux/percentile-quantile/) ### [Join](/influxdb/v2/query-data/flux/join/) This guide walks through joining data with Flux and outlines how it shapes your data in the process. ```js import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-m") |> filter(fn: (r) => r._field == "example-f") |> drop(columns: ["_measurement", "_field"]) right = sql.from( driverName: "postgres", dataSourceName: "postgresql://username:password@localhost:5432", query: "SELECT * FROM example_table", ) join.inner( left: left |> group(), right: right, on: (l, r) => l.sensorID == r.ID, as: (l, r) => ({l with expired: r.expired}), ) |> group(columns: ["_time", "_value"], mode: "except") ``` ###### Input: ###### left | \_time |sensorID|\_value| |--------------------|--------|-------| |2020-01-01T00:01:00Z| 1234 | 1 | |2020-01-01T00:02:00Z| 1234 | 2 | |2020-01-01T00:03:00Z| 1234 | 1 | |2020-01-01T00:04:00Z| 1234 | 3 | | \_time |sensorID|\_value| |--------------------|--------|-------| |2020-01-01T00:01:00Z| 5678 | 2 | |2020-01-01T00:02:00Z| 5678 | 5 | |2020-01-01T00:03:00Z| 5678 | 1 | |2020-01-01T00:04:00Z| 5678 | 8 | ###### right | ID |expired| serviced | |----|-------|----------| |1234| false |2022-01-01| |5678| true |2022-01-01| ###### Output: | \_time |sensorID|\_value|expired| |--------------------|--------|-------|-------| |2020-01-01T00:01:00Z| 1234 | 1 | false | |2020-01-01T00:02:00Z| 1234 | 2 | false | |2020-01-01T00:03:00Z| 1234 | 1 | false | |2020-01-01T00:04:00Z| 1234 | 3 | false | | \_time |sensorID|\_value|expired| |--------------------|--------|-------|-------| |2020-01-01T00:01:00Z| 5678 | 2 | true | |2020-01-01T00:02:00Z| 5678 | 5 | true | |2020-01-01T00:03:00Z| 5678 | 1 | true | |2020-01-01T00:04:00Z| 5678 | 8 | true | [Read more ](/influxdb/v2/query-data/flux/join/) ### [Cumulative sum](/influxdb/v2/query-data/flux/cumulativesum/) Use the `cumulativeSum()` function to calculate a running total of values. ```js data |> cumulativeSum() ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1 | |2020-01-01T00:02:00Z| 2 | |2020-01-01T00:03:00Z| 1 | |2020-01-01T00:04:00Z| 3 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1 | |2020-01-01T00:02:00Z| 3 | |2020-01-01T00:03:00Z| 4 | |2020-01-01T00:04:00Z| 7 | [Read more ](/influxdb/v2/query-data/flux/cumulativesum/) ### [First and last](/influxdb/v2/query-data/flux/first-last/) Use `first()` or `last()` to return the first or last point in an input table. ```js data |> first() ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | ```js data |> last() ``` ###### Input: | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | ###### Output: | \_time |\_value| |--------------------|-------| |2020-01-01T00:04:00Z| 3.0 | [Read more ](/influxdb/v2/query-data/flux/first-last/) ### [Exists](/influxdb/v2/query-data/flux/exists/) Use the Flux `exists` operator to check if a row record contains a column or if that column’s value is `null`. ##### Filter null values ```js data |> filter(fn: (r) => exists r._value) ``` [Read more ](/influxdb/v2/query-data/flux/exists/) ### [Custom functions](/influxdb/v2/query-data/flux/custom-functions/) Create your own custom Flux functions to transform and operate on data. ```js multByX = (tables=<-, x) => tables |> map(fn: (r) => ({r with _value: r._value * x})) data |> multByX(x: 2.0) ``` [Read more ](/influxdb/v2/query-data/flux/custom-functions/) ### [Extract scalar values](/influxdb/v2/query-data/flux/scalar-values/) Use Flux dynamic query functions to extract scalar values from Flux query output. This lets you, for example, dynamically set variables using query results. ```js scalarValue = (tables=<-) => { _record = tables |> findRecord(fn: (key) => true, idx: 0) return _record._value } ``` [Read more ](/influxdb/v2/query-data/flux/scalar-values/) ### [Monitor states](/influxdb/v2/query-data/flux/monitor-states/) Flux provides several functions to help monitor states and state changes in your data. ### [Operate on timestamps](/influxdb/v2/query-data/flux/operate-on-timestamps/) Use Flux to process and operate on timestamps. ### [Query SQL data](/influxdb/v2/query-data/flux/sql/) The Flux `sql` package provides functions for working with SQL data sources. Use `sql.from()` to query SQL databases like PostgreSQL, MySQL, Snowflake, SQLite, Microsoft SQL Server, Amazon Athena, and Google BigQuery. ```js import "sql" sql.from( driverName: "postgres", dataSourceName: "postgresql://user:password@localhost", query: "SELECT * FROM example_table", ) ``` [Read more ](/influxdb/v2/query-data/flux/sql/) ### [Conditional logic](/influxdb/v2/query-data/flux/conditional-logic/) This guide describes how to use Flux conditional expressions, such as `if`, `else`, and `then`, to query and transform data. **Flux evaluates statements from left to right and stops evaluating once a condition matches.** ```js if color == "green" then "008000" else "ffffff" ``` [Read more ](/influxdb/v2/query-data/flux/conditional-logic/) ### [Regular expressions](/influxdb/v2/query-data/flux/regular-expressions/) This guide walks through using regular expressions in evaluation logic in Flux functions. ```js data |> filter(fn: (r) => r.tag =~ /^foo[1-3]/) ``` ###### Input: | \_time |tag |\_value| |--------------------|----|-------| |2020-01-01T00:01:00Z|foo1| 1.0 | |2020-01-01T00:02:00Z|foo5| 1.2 | |2020-01-01T00:03:00Z|bar3| 1.8 | |2020-01-01T00:04:00Z|foo3| 0.9 | |2020-01-01T00:05:00Z|foo2| 1.4 | |2020-01-01T00:06:00Z|bar1| 2.0 | ###### Output: | \_time |tag |\_value| |--------------------|----|-------| |2020-01-01T00:01:00Z|foo1| 1.0 | |2020-01-01T00:04:00Z|foo3| 0.9 | |2020-01-01T00:05:00Z|foo2| 1.4 | [Read more ](/influxdb/v2/query-data/flux/regular-expressions/) ### [Geo-temporal data](/influxdb/v2/query-data/flux/geo/) Use the Flux Geo package to filter geo-temporal data and group by geographic location or track. ```js import "experimental/geo" sampleGeoData |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) |> geo.groupByArea(newColumn: "geoArea", level: 5) ``` [Read more ](/influxdb/v2/query-data/flux/geo/) ### [Query the Flux version](/influxdb/v2/query-data/flux/flux-version/) Use `runtime.version()` to return the version of Flux installed in InfluxDB. ```js import "array" import "runtime" array.from(rows: [{version: runtime.version()}]) ``` [Read more ](/influxdb/v2/query-data/flux/flux-version/) [flux](/influxdb/v2/tags/flux/)[query](/influxdb/v2/tags/query/) | _time | host | _value | | --- | --- | --- | | _time | host | _value | | 2020-01-01T00:01:00Z | host1 | 1.0 | | 2020-01-01T00:01:00Z | host2 | 2.0 | | 2020-01-01T00:02:00Z | host1 | 1.0 | | 2020-01-01T00:02:00Z | host2 | 3.0 | | _time | host | _value | | --- | --- | --- | | _time | host | _value | | 2020-01-01T00:01:00Z | host1 | 1.0 | | 2020-01-01T00:02:00Z | host1 | 1.0 | | _time | host | _value | | --- | --- | --- | | _time | host | _value | | 2020-01-01T00:01:00Z | host2 | 2.0 | | 2020-01-01T00:02:00Z | host2 | 3.0 | | _time | host | _value | | --- | --- | --- | | _time | host | _value | | 2020-01-01T00:01:00Z | A | 1.0 | | 2020-01-01T00:02:00Z | B | 1.2 | | 2020-01-01T00:03:00Z | A | 1.8 | | 2020-01-01T00:04:00Z | B | 0.9 | | 2020-01-01T00:05:00Z | B | 1.4 | | 2020-01-01T00:06:00Z | B | 2.0 | | _time | host | _value | | --- | --- | --- | | _time | host | _value | | 2020-01-01T00:03:00Z | A | 1.8 | | 2020-01-01T00:01:00Z | A | 1.0 | | 2020-01-01T00:06:00Z | B | 2.0 | | 2020-01-01T00:05:00Z | B | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:20:00Z | 195 | | 2020-01-01T00:40:00Z | 200 | | 2020-01-01T01:00:00Z | 290 | | 2020-01-01T01:20:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 2 | | 2020-01-01T00:02:00Z | 4 | | 2020-01-01T00:03:00Z | 3 | | 2020-01-01T00:04:00Z | 5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 4 | | 2020-01-01T00:02:00Z | 16 | | 2020-01-01T00:03:00Z | 9 | | 2020-01-01T00:04:00Z | 25 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:00:00Z | used | 2.5 | | 2020-01-01T00:00:10Z | used | 3.1 | | 2020-01-01T00:00:20Z | used | 4.2 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:00:00Z | total | 8.0 | | 2020-01-01T00:00:10Z | total | 8.0 | | 2020-01-01T00:00:20Z | total | 8.0 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:00:00Z | used_percent | 31.25 | | 2020-01-01T00:00:10Z | used_percent | 38.75 | | 2020-01-01T00:00:20Z | used_percent | 52.50 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1 | | 2020-01-01T00:02:00Z | 2 | | 2020-01-01T00:03:00Z | 8 | | 2020-01-01T00:04:00Z | 10 | | 2020-01-01T00:05:00Z | 0 | | 2020-01-01T00:06:00Z | 4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:02:00Z | 1 | | 2020-01-01T00:03:00Z | 7 | | 2020-01-01T00:04:00Z | 9 | | 2020-01-01T00:05:00Z | 9 | | 2020-01-01T00:06:00Z | 13 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.2 | | 2020-01-01T00:03:00Z | 1.8 | | 2020-01-01T00:04:00Z | 0.9 | | 2020-01-01T00:05:00Z | 1.4 | | 2020-01-01T00:06:00Z | 2.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:03:00Z | 1.33 | | 2020-01-01T00:04:00Z | 1.30 | | 2020-01-01T00:05:00Z | 1.36 | | 2020-01-01T00:06:00Z | 1.43 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.2 | | 2020-01-01T00:03:00Z | 1.8 | | 2020-01-01T00:04:00Z | 0.9 | | 2020-01-01T00:05:00Z | 1.4 | | 2020-01-01T00:06:00Z | 2.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:02:00Z | 1.000 | | 2020-01-01T00:04:00Z | 1.333 | | 2020-01-01T00:06:00Z | 1.325 | | 2020-01-01T00:06:00Z | 1.150 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:04:00Z | | | 2020-01-01T00:12:00Z | | | 2020-01-01T00:19:00Z | 10.0 | | 2020-01-01T00:32:00Z | | | 2020-01-01T00:51:00Z | 4.74 | | 2020-01-01T01:00:00Z | 5.56 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:20:00Z | | | 2020-01-01T00:40:00Z | 10.0 | | 2020-01-01T01:00:00Z | 4.74 | | 2020-01-01T01:20:00Z | 5.56 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250.0 | | 2020-01-01T00:01:00Z | 160.0 | | 2020-01-01T00:02:00Z | 150.0 | | 2020-01-01T00:03:00Z | 220.0 | | 2020-01-01T00:04:00Z | 200.0 | | 2020-01-01T00:05:00Z | 290.0 | | 2020-01-01T01:00:00Z | 340.0 | | le | _value | | --- | --- | | le | _value | | 100.0 | 0.0 | | 200.0 | 3.0 | | 300.0 | 6.0 | | 400.0 | 7.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | null | | 2020-01-01T00:04:00Z | null | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | 0.8 | | 2020-01-01T00:04:00Z | 0.8 | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | null | | 2020-01-01T00:04:00Z | null | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 0.0 | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | 0.0 | | 2020-01-01T00:04:00Z | 0.0 | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 1.5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 3.0 | | _time | sensorID | _value | | --- | --- | --- | | _time | sensorID | _value | | 2020-01-01T00:01:00Z | 1234 | 1 | | 2020-01-01T00:02:00Z | 1234 | 2 | | 2020-01-01T00:03:00Z | 1234 | 1 | | 2020-01-01T00:04:00Z | 1234 | 3 | | _time | sensorID | _value | | --- | --- | --- | | _time | sensorID | _value | | 2020-01-01T00:01:00Z | 5678 | 2 | | 2020-01-01T00:02:00Z | 5678 | 5 | | 2020-01-01T00:03:00Z | 5678 | 1 | | 2020-01-01T00:04:00Z | 5678 | 8 | | ID | expired | serviced | | --- | --- | --- | | ID | expired | serviced | | 1234 | false | 2022-01-01 | | 5678 | true | 2022-01-01 | | _time | sensorID | _value | expired | | --- | --- | --- | --- | | _time | sensorID | _value | expired | | 2020-01-01T00:01:00Z | 1234 | 1 | false | | 2020-01-01T00:02:00Z | 1234 | 2 | false | | 2020-01-01T00:03:00Z | 1234 | 1 | false | | 2020-01-01T00:04:00Z | 1234 | 3 | false | | _time | sensorID | _value | expired | | --- | --- | --- | --- | | _time | sensorID | _value | expired | | 2020-01-01T00:01:00Z | 5678 | 2 | true | | 2020-01-01T00:02:00Z | 5678 | 5 | true | | 2020-01-01T00:03:00Z | 5678 | 1 | true | | 2020-01-01T00:04:00Z | 5678 | 8 | true | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1 | | 2020-01-01T00:02:00Z | 2 | | 2020-01-01T00:03:00Z | 1 | | 2020-01-01T00:04:00Z | 3 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1 | | 2020-01-01T00:02:00Z | 3 | | 2020-01-01T00:03:00Z | 4 | | 2020-01-01T00:04:00Z | 7 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:04:00Z | 3.0 | | _time | tag | _value | | --- | --- | --- | | _time | tag | _value | | 2020-01-01T00:01:00Z | foo1 | 1.0 | | 2020-01-01T00:02:00Z | foo5 | 1.2 | | 2020-01-01T00:03:00Z | bar3 | 1.8 | | 2020-01-01T00:04:00Z | foo3 | 0.9 | | 2020-01-01T00:05:00Z | foo2 | 1.4 | | 2020-01-01T00:06:00Z | bar1 | 2.0 | | _time | tag | _value | | --- | --- | --- | | _time | tag | _value | | 2020-01-01T00:01:00Z | foo1 | 1.0 | | 2020-01-01T00:04:00Z | foo3 | 0.9 | | 2020-01-01T00:05:00Z | foo2 | 1.4 | --- # Calculate percentages with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/calculate-percentages/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Calculating percentages from queried data is a common use case for time series data. To calculate a percentage in Flux, operands must be in each row. Use `map()` to re-map values in the row and calculate a percentage. **To calculate percentages** 1. Use [`from()`](/flux/v0/stdlib/influxdata/influxdb/from/),[`range()`](/flux/v0/stdlib/universe/range/) and[`filter()`](/flux/v0/stdlib/universe/filter/) to query operands. 2. Use [`pivot()` or `join()`](/influxdb/v2/query-data/flux/mathematic-operations/#pivot-vs-join)to align operand values into rows. 3. Use [`map()`](/flux/v0/stdlib/universe/map/)to divide the numerator operand value by the denominator operand value and multiply by 100. > [!Note] > The following examples use `pivot()` to align operands into rows because`pivot()` works in most cases and is more performant than `join()`.*See [Pivot vs join](/influxdb/v2/query-data/flux/mathematic-operations/#pivot-vs-join).* ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "m1" and r._field =~ /field[1-2]/ ) |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") |> map(fn: (r) => ({ r with _value: r.field1 / r.field2 * 100.0 })) ``` ## GPU monitoring example The following example queries data from the gpu-monitor bucket and calculates the percentage of GPU memory used over time. Data includes the following: * **`gpu` measurement** * **`mem_used` field**: used GPU memory in bytes * **`mem_total` field**: total GPU memory in bytes ### Query mem\_used and mem\_total fields ```js from(bucket: "gpu-monitor") |> range(start: 2020-01-01T00:00:00Z) |> filter(fn: (r) => r._measurement == "gpu" and r._field =~ /mem_/) ``` ###### Returns the following stream of tables: | \_time |\_measurement| \_field | \_value | |--------------------|-------------|---------|----------| |2020-01-01T00:00:00Z| gpu |mem\_used|2517924577| |2020-01-01T00:00:10Z| gpu |mem\_used|2695091978| |2020-01-01T00:00:20Z| gpu |mem\_used|2576980377| |2020-01-01T00:00:30Z| gpu |mem\_used|3006477107| |2020-01-01T00:00:40Z| gpu |mem\_used|3543348019| |2020-01-01T00:00:50Z| gpu |mem\_used|4402341478| | \_time |\_measurement| \_field | \_value | |--------------------|-------------|----------|----------| |2020-01-01T00:00:00Z| gpu |mem\_total|8589934592| |2020-01-01T00:00:10Z| gpu |mem\_total|8589934592| |2020-01-01T00:00:20Z| gpu |mem\_total|8589934592| |2020-01-01T00:00:30Z| gpu |mem\_total|8589934592| |2020-01-01T00:00:40Z| gpu |mem\_total|8589934592| |2020-01-01T00:00:50Z| gpu |mem\_total|8589934592| ### Pivot fields into columns Use `pivot()` to pivot the `mem_used` and `mem_total` fields into columns. Output includes `mem_used` and `mem_total` columns with values for each corresponding `_time`. ```js // ... |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") ``` ###### Returns the following: | \_time |\_measurement|mem\_used |mem\_total| |--------------------|-------------|----------|----------| |2020-01-01T00:00:00Z| gpu |2517924577|8589934592| |2020-01-01T00:00:10Z| gpu |2695091978|8589934592| |2020-01-01T00:00:20Z| gpu |2576980377|8589934592| |2020-01-01T00:00:30Z| gpu |3006477107|8589934592| |2020-01-01T00:00:40Z| gpu |3543348019|8589934592| |2020-01-01T00:00:50Z| gpu |4402341478|8589934592| ### Map new values Each row now contains the values necessary to calculate a percentage. Use `map()` to re-map values in each row. Divide `mem_used` by `mem_total` and multiply by 100 to return the percentage. > [!Note] > To return a precise float percentage value that includes decimal points, the example > below casts integer field values to floats and multiplies by a float value (`100.0`). ```js // ... |> map( fn: (r) => ({ _time: r._time, _measurement: r._measurement, _field: "mem_used_percent", _value: float(v: r.mem_used) / float(v: r.mem_total) * 100.0 }), ) ``` ##### Query results: | \_time |\_measurement| \_field |\_value| |--------------------|-------------|------------------|-------| |2020-01-01T00:00:00Z| gpu |mem\_used\_percent| 29.31 | |2020-01-01T00:00:10Z| gpu |mem\_used\_percent| 31.37 | |2020-01-01T00:00:20Z| gpu |mem\_used\_percent| 30.00 | |2020-01-01T00:00:30Z| gpu |mem\_used\_percent| 35.00 | |2020-01-01T00:00:40Z| gpu |mem\_used\_percent| 41.25 | |2020-01-01T00:00:50Z| gpu |mem\_used\_percent| 51.25 | ### Full query ```js from(bucket: "gpu-monitor") |> range(start: 2020-01-01T00:00:00Z) |> filter(fn: (r) => r._measurement == "gpu" and r._field =~ /mem_/ ) |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") |> map( fn: (r) => ({ _time: r._time, _measurement: r._measurement, _field: "mem_used_percent", _value: float(v: r.mem_used) / float(v: r.mem_total) * 100.0 }), ) ``` ## Examples #### Calculate percentages using multiple fields ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "used_system" or r._field == "used_user" or r._field == "total") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> map( fn: (r) => ({ r with _value: float(v: r.used_system + r.used_user) / float(v: r.total) * 100.0 }), ) ``` #### Calculate percentages using multiple measurements 1. Ensure measurements are in the same [bucket](/influxdb/v2/reference/glossary/#bucket). 2. Use `filter()` to include data from both measurements. 3. Use `group()` to ungroup data and return a single table. 4. Use `pivot()` to pivot fields into columns. 5. Use `map()` to re-map rows and perform the percentage calculation. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == "m1" or r._measurement == "m2") and (r._field == "field1" or r._field == "field2")) |> group() |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> map(fn: (r) => ({r with _value: r.field1 / r.field2 * 100.0})) ``` #### Calculate percentages using multiple data sources ```js import "sql" import "influxdata/influxdb/secrets" pgUser = secrets.get(key: "POSTGRES_USER") pgPass = secrets.get(key: "POSTGRES_PASSWORD") pgHost = secrets.get(key: "POSTGRES_HOST") t1 = sql.from( driverName: "postgres", dataSourceName: "postgresql://${pgUser}:${pgPass}@${pgHost}", query: "SELECT id, name, available FROM example_table", ) t2 = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field") join(tables: {t1: t1, t2: t2}, on: ["id"]) |> map(fn: (r) => ({r with _value: r._value_t2 / r.available_t1 * 100.0})) ``` #### Related * [Transform data with mathematic operations](/influxdb/v2/query-data/flux/mathematic-operations/) * [map() function](/flux/v0/stdlib/universe/map/) * [pivot() function](/flux/v0/stdlib/universe/pivot/) * [join() function](/flux/v0/stdlib/universe/join/) | _time | _measurement | _field | _value | | --- | --- | --- | --- | | _time | _measurement | _field | _value | | 2020-01-01T00:00:00Z | gpu | mem_used | 2517924577 | | 2020-01-01T00:00:10Z | gpu | mem_used | 2695091978 | | 2020-01-01T00:00:20Z | gpu | mem_used | 2576980377 | | 2020-01-01T00:00:30Z | gpu | mem_used | 3006477107 | | 2020-01-01T00:00:40Z | gpu | mem_used | 3543348019 | | 2020-01-01T00:00:50Z | gpu | mem_used | 4402341478 | | _time | _measurement | _field | _value | | --- | --- | --- | --- | | _time | _measurement | _field | _value | | 2020-01-01T00:00:00Z | gpu | mem_total | 8589934592 | | 2020-01-01T00:00:10Z | gpu | mem_total | 8589934592 | | 2020-01-01T00:00:20Z | gpu | mem_total | 8589934592 | | 2020-01-01T00:00:30Z | gpu | mem_total | 8589934592 | | 2020-01-01T00:00:40Z | gpu | mem_total | 8589934592 | | 2020-01-01T00:00:50Z | gpu | mem_total | 8589934592 | | _time | _measurement | mem_used | mem_total | | --- | --- | --- | --- | | _time | _measurement | mem_used | mem_total | | 2020-01-01T00:00:00Z | gpu | 2517924577 | 8589934592 | | 2020-01-01T00:00:10Z | gpu | 2695091978 | 8589934592 | | 2020-01-01T00:00:20Z | gpu | 2576980377 | 8589934592 | | 2020-01-01T00:00:30Z | gpu | 3006477107 | 8589934592 | | 2020-01-01T00:00:40Z | gpu | 3543348019 | 8589934592 | | 2020-01-01T00:00:50Z | gpu | 4402341478 | 8589934592 | | _time | _measurement | _field | _value | | --- | --- | --- | --- | | _time | _measurement | _field | _value | | 2020-01-01T00:00:00Z | gpu | mem_used_percent | 29.31 | | 2020-01-01T00:00:10Z | gpu | mem_used_percent | 31.37 | | 2020-01-01T00:00:20Z | gpu | mem_used_percent | 30.00 | | 2020-01-01T00:00:30Z | gpu | mem_used_percent | 35.00 | | 2020-01-01T00:00:40Z | gpu | mem_used_percent | 41.25 | | 2020-01-01T00:00:50Z | gpu | mem_used_percent | 51.25 | --- # Query using conditional logic Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/conditional-logic/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux provides `if`, `then`, and `else` conditional expressions that allow for powerful and flexible Flux queries. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ##### Conditional expression syntax ```js // Pattern if then else // Example if color == "green" then "008000" else "ffffff" ``` Conditional expressions are most useful in the following contexts: * When defining variables. * When using functions that operate on a single row at a time ([`filter()`](/flux/v0/stdlib/universe/filter/),[`map()`](/flux/v0/stdlib/universe/map/),[`reduce()`](/flux/v0/stdlib/universe/reduce) ). ## Evaluating conditional expressions Flux evaluates statements in order and stops evaluating once a condition matches. For example, given the following statement: ```js if r._value > 95.0000001 and r._value <= 100.0 then "critical" else if r._value > 85.0000001 and r._value <= 95.0 then "warning" else if r._value > 70.0000001 and r._value <= 85.0 then "high" else "normal" ``` When `r._value` is 96, the output is “critical” and the remaining conditions are not evaluated. ## Examples * [Conditionally set the value of a variable](#conditionally-set-the-value-of-a-variable) * [Create conditional filters](#create-conditional-filters) * [Conditionally transform column values with map()](#conditionally-transform-column-values-with-map) * [Conditionally increment a count with reduce()](#conditionally-increment-a-count-with-reduce) ### Conditionally set the value of a variable The following example sets the `overdue` variable based on the`dueDate` variable’s relation to `now()`. ```js dueDate = 2019-05-01 overdue = if dueDate < now() then true else false ``` ### Create conditional filters The following example uses an example `metric` [dashboard variable](/influxdb/v2/visualize-data/variables/)to change how the query filters data.`metric` has three possible values: * Memory * CPU * Disk ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter( fn: (r) => if v.metric == "Memory" then r._measurement == "mem" and r._field == "used_percent" else if v.metric == "CPU" then r._measurement == "cpu" and r._field == "usage_user" else if v.metric == "Disk" then r._measurement == "disk" and r._field == "used_percent" else r._measurement != "", ) ``` ### Conditionally transform column values with map() The following example uses the [`map()` function](/flux/v0/stdlib/universe/map/)to conditionally transform column values. It sets the `level` column to a specific string based on `_value` column. [No Comments](#no-comments)[Comments](#comments) ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> map( fn: (r) => ({r with level: if r._value >= 95.0000001 and r._value <= 100.0 then "critical" else if r._value >= 85.0000001 and r._value <= 95.0 then "warning" else if r._value >= 70.0000001 and r._value <= 85.0 then "high" else "normal", }), ) ``` ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> map( fn: (r) => ({ // Retain all existing columns in the mapped row r with // Set the level column value based on the _value column level: if r._value >= 95.0000001 and r._value <= 100.0 then "critical" else if r._value >= 85.0000001 and r._value <= 95.0 then "warning" else if r._value >= 70.0000001 and r._value <= 85.0 then "high" else "normal", }), ) ``` ### Conditionally increment a count with reduce() The following example uses the [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)and [`reduce()`](/flux/v0/stdlib/universe/reduce/)functions to count the number of records in every five minute window that exceed a defined threshold. [No Comments](#no-comments-2)[Comments](#comments-2) ```js threshold = 65.0 data = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> aggregateWindow( every: 5m, fn: (column, tables=<-) => tables |> reduce( identity: {above_threshold_count: 0.0}, fn: (r, accumulator) => ({ above_threshold_count: if r._value >= threshold then accumulator.above_threshold_count + 1.0 else accumulator.above_threshold_count + 0.0, }), ), ) ``` ```js threshold = 65.0 from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") // Aggregate data into 5 minute windows using a custom reduce() function |> aggregateWindow( every: 5m, // Use a custom function in the fn parameter. // The aggregateWindow fn parameter requires 'column' and 'tables' parameters. fn: (column, tables=<-) => tables |> reduce( identity: {above_threshold_count: 0.0}, fn: (r, accumulator) => ({ // Conditionally increment above_threshold_count if // r.value exceeds the threshold above_threshold_count: if r._value >= threshold then accumulator.above_threshold_count + 1.0 else accumulator.above_threshold_count + 0.0, }), ), ) ``` #### Related * [Query fields and tags](/influxdb/v2/query-data/flux/query-fields/) * [filter() function](/flux/v0/stdlib/universe/filter/) * [map() function](/flux/v0/stdlib/universe/map/) * [reduce() function](/flux/v0/stdlib/universe/reduce/) [conditionals](/influxdb/v2/tags/conditionals/)[flux](/influxdb/v2/tags/flux/) --- # Query cumulative sum Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/cumulativesum/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`cumulativeSum()` function](/flux/v0/stdlib/universe/cumulativesum/)to calculate a running total of values.`cumulativeSum` sums the values of subsequent records and returns each row updated with the summed total. **Given the following input table:** |\_time|\_value| |------|-------| | 0001 | 1 | | 0002 | 2 | | 0003 | 1 | | 0004 | 3 | **`cumulativeSum()` returns:** |\_time|\_value| |------|-------| | 0001 | 1 | | 0002 | 3 | | 0003 | 4 | | 0004 | 7 | > [!Note] > The examples below use the [example data variable](/influxdb/v2/query-data/flux/#example-data-variable). ##### Calculate the running total of values ```js data |> cumulativeSum() ``` ## Use cumulativeSum() with aggregateWindow() [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)segments data into windows of time, aggregates data in each window into a single point, then removes the time-based segmentation. It is primarily used to [downsample data](/influxdb/v2/process-data/common-tasks/downsample-data/). `aggregateWindow()` expects an aggregate function that returns a single row for each time window. To use `cumulativeSum()` with `aggregateWindow`, use `sum` in `aggregateWindow()`, then calculate the running total of the aggregate values with `cumulativeSum()`. ```js data |> aggregateWindow(every: 5m, fn: sum) |> cumulativeSum() ``` #### Related * [cumulativeSum() function](/flux/v0/stdlib/universe/cumulativesum/) [query](/influxdb/v2/tags/query/)[cumulative sum](/influxdb/v2/tags/cumulative-sum/) | _time | _value | | --- | --- | | _time | _value | | 0001 | 1 | | 0002 | 2 | | 0003 | 1 | | 0004 | 3 | | _time | _value | | --- | --- | | _time | _value | | 0001 | 1 | | 0002 | 3 | | 0003 | 4 | | 0004 | 7 | --- # Create custom Flux functions Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/custom-functions/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux’s functional syntax lets you create custom functions. This guide walks through the basics of creating your own function. * [Function definition syntax](#function-definition-syntax) * [Use piped-forward data in a custom function](#use-piped-forward-data-in-a-custom-function) * [Define parameter defaults](#define-parameter-defaults) * [Define functions with scoped variables](#define-functions-with-scoped-variables) ## Function definition syntax The basic syntax for defining functions in Flux is as follows: ```js // Basic function definition syntax functionName = (functionParameters) => functionOperations ``` ##### functionName The name used to call the function in your Flux script. ##### functionParameters A comma-separated list of parameters passed into the function and used in its operations.[Parameter defaults](#define-parameter-defaults) can be defined for each. ##### functionOperations Operations and functions that manipulate the input into the desired output. #### Basic function examples ###### Example square function ```js // Function definition square = (n) => n * n // Function usage > square(n:3) 9 ``` ###### Example multiply function ```js // Function definition multiply = (x, y) => x * y // Function usage > multiply(x: 2, y: 15) 30 ``` ## Use piped-forward data in a custom function Most Flux functions process piped-forward data. To process piped-forward data, one of the function parameters must capture the input tables using the `<-` pipe-receive expression. In the example below, the `tables` parameter is assigned to the `<-` expression, which represents all data piped-forward into the function.`tables` is then piped-forward into other operations in the function definition. ```js functionName = (tables=<-) => tables |> functionOperations ``` #### Pipe-forwardable function example ###### Multiply row values by x The example below defines a `multByX` function that multiplies the `_value` column of each row in the input table by the `x` parameter. It uses the [`map()` function](/flux/v0/stdlib/universe/map)to modify each `_value`. ```js // Function definition multByX = (tables=<-, x) => tables |> map(fn: (r) => ({r with _value: r._value * x})) // Function usage from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> multByX(x: 2.0) ``` ## Define parameter defaults Use the `=` assignment operator to assign a default value to function parameters in your function definition: ```js functionName = (param1=defaultValue1, param2=defaultValue2) => functionOperation ``` Defaults are overridden by explicitly defining the parameter in the function call. ### Example functions with defaults #### Get a list of leaders The example below defines a `leaderBoard` function that returns a limited number of records sorted by values in specified columns. It uses the [`sort()` function](/flux/v0/stdlib/universe/sort)to sort records in either descending or ascending order. It then uses the [`limit()` function](/flux/v0/stdlib/universe/limit)to return a specified number of records from the sorted table. ```js // Function definition leaderBoard = (tables=<-, limit=4, columns=["_value"], desc=true) => tables |> sort(columns: columns, desc: desc) |> limit(n: limit) // Function usage // Get the 4 highest scoring players from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._measurement == "player-stats" and r._field == "total-points") |> leaderBoard() // Get the 10 shortest race times from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._measurement == "race-times" and r._field == "elapsed-time") |> leaderBoard(limit: 10, desc: false) ``` ## Define functions with scoped variables To create custom functions with variables scoped to the function, place your function operations and variables inside of a [block (`{}`)](/influxdb/v2/reference/flux/language/blocks/)and use a `return` statement to return a specific variable. ``` functionName = (functionParameters) => { exampleVar = "foo" return exampleVar } ``` ### Example functions with scoped variables * [Return an alert level based on a value](#return-an-alert-level-based-on-a-value) * [Convert a HEX color code to a name](#convert-a-hex-color-code-to-a-name) #### Return an alert level based on a value The following function uses conditional logic to return an alert level based on a numeric input value: ``` alertLevel = (v) => { level = if float(v: v) >= 90.0 then "crit" else if float(v: v) >= 80.0 then "warn" else if float(v: v) >= 65.0 then "info" else "ok" return level } alertLevel(v: 87.3) // Returns "warn" ``` #### Convert a HEX color code to a name The following function converts a hexadecimal (HEX) color code to the equivalent HTML color name. The functions uses the [Flux dictionary package](/flux/v0/stdlib/dict/)to create a dictionary of HEX codes and their corresponding names. ``` import "dict" hexName = (hex) => { hexNames = dict.fromList( pairs: [ {key: "#00ffff", value: "Aqua"}, {key: "#000000", value: "Black"}, {key: "#0000ff", value: "Blue"}, {key: "#ff00ff", value: "Fuchsia"}, {key: "#808080", value: "Gray"}, {key: "#008000", value: "Green"}, {key: "#00ff00", value: "Lime"}, {key: "#800000", value: "Maroon"}, {key: "#000080", value: "Navy"}, {key: "#808000", value: "Olive"}, {key: "#800080", value: "Purple"}, {key: "#ff0000", value: "Red"}, {key: "#c0c0c0", value: "Silver"}, {key: "#008080", value: "Teal"}, {key: "#ffffff", value: "White"}, {key: "#ffff00", value: "Yellow"}, ], ) name = dict.get(dict: hexNames, key: hex, default: "No known name") return name } hexName(hex: "#000000") // Returns "Black" hexName(hex: "#8b8b8b") // Returns "No known name" ``` [functions](/influxdb/v2/tags/functions/)[custom](/influxdb/v2/tags/custom/)[flux](/influxdb/v2/tags/flux/) --- # Create custom aggregate functions Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/custom-functions/custom-aggregate/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To aggregate your data, use the Flux[aggregate functions](/flux/v0/function-types#aggregates)or create custom aggregate functions using the[`reduce()`function](/flux/v0/stdlib/universe/reduce/). ## Aggregate function characteristics Aggregate functions all have the same basic characteristics: * They operate on individual input tables and transform all records into a single record. * The output table has the same [group key](/flux/v0/get-started/data-model/#group-key) as the input table. ## How reduce() works The `reduce()` function operates on one row at a time using the function defined in the [`fn` parameter](/flux/v0/stdlib/universe/reduce/#fn). The `fn` function maps keys to specific values using two [records](/flux/v0/data-types/composite/record/)specified by the following parameters: | Parameter | Description | |-------------|-----------------------------------------------------------------------| | `r` | A record that represents the row or record. | |`accumulator`|A record that contains values used in each row’s aggregate calculation.| > [!Note] > The `reduce()` function’s [`identity` parameter](/flux/v0/stdlib/universe/reduce/#identity)defines the initial `accumulator` record. ### Example reduce() function The following example `reduce()` function produces a sum and product of all values in an input table. ```js |> reduce( fn: (r, accumulator) => ({ sum: r._value + accumulator.sum, product: r._value * accumulator.product }), identity: {sum: 0.0, product: 1.0}, ) ``` To illustrate how this function works, take this simplified table for example: | \_time |\_value| |--------------------|-------| |2019-04-23T16:10:49Z| 1.6 | |2019-04-23T16:10:59Z| 2.3 | |2019-04-23T16:11:09Z| 0.7 | |2019-04-23T16:11:19Z| 1.2 | |2019-04-23T16:11:29Z| 3.8 | ###### Input records The `fn` function uses the data in the first row to define the `r` record. It defines the `accumulator` record using the `identity` parameter. ```js r = { _time: 2019-04-23T16:10:49.00Z, _value: 1.6 } accumulator = { sum : 0.0, product : 1.0 } ``` ###### Key mappings It then uses the `r` and `accumulator` records to populate values in the key mappings: ```js // sum: r._value + accumulator.sum sum: 1.6 + 0.0 // product: r._value * accumulator.product product: 1.6 * 1.0 ``` ###### Output record This produces an output record with the following key value pairs: ```js { sum: 1.6, product: 1.6 } ``` The function then processes the next row using this **output record** as the `accumulator`. > [!Note] > Because `reduce()` uses the output record as the `accumulator` when processing the next row, > keys mapped in the `fn` function must match keys in the `identity` and `accumulator` records. ###### Processing the next row ```js // Input records for the second row r = { _time: 2019-04-23T16:10:59.00Z, _value: 2.3 } accumulator = { sum : 1.6, product : 1.6 } // Key mappings for the second row sum: 2.3 + 1.6 product: 2.3 * 1.6 // Output record of the second row { sum: 3.9, product: 3.68 } ``` It then uses the new output record as the `accumulator` for the next row. This cycle continues until all rows in the table are processed. ##### Final output record and table After all records in the table are processed, `reduce()` uses the final output record to create a transformed table with one row and columns for each mapped key. ###### Final output record ```js { sum: 9.6, product: 11.74656 } ``` ###### Output table |sum|product | |---|--------| |9.6|11.74656| > [!Note] > #### What happened to the \_time column? > > The `reduce()` function only keeps columns that are: > > 1. Are part of the input table’s [group key](/flux/v0/get-started/data-model/#group-key). > 2. Explicitly mapped in the `fn` function. > > It drops all other columns. > Because `_time` is not part of the group key and is not mapped in the `fn` function, > it isn’t included in the output table. ## Custom aggregate function examples To create custom aggregate functions, use principles outlined in[Creating custom functions](/influxdb/v2/query-data/flux/custom-functions)and the `reduce()` function to aggregate rows in each input table. ### Create a custom average function This example illustrates how to create a function that averages values in a table.*This is meant for demonstration purposes only. The built-in [`mean()` function](/flux/v0/stdlib/universe/mean/)does the same thing and is much more performant.* [Comments](#comments)[No Comments](#no-comments) ```js average = (tables=<-, outputField="average") => tables |> reduce( // Define the initial accumulator record identity: {count: 0.0, sum: 0.0, avg: 0.0}, fn: (r, accumulator) => ({ // Increment the counter on each reduce loop count: accumulator.count + 1.0, // Add the _value to the existing sum sum: accumulator.sum + r._value, // Divide the existing sum by the existing count for a new average avg: (accumulator.sum + r._value) / (accumulator.count + 1.0), }), ) // Drop the sum and the count columns since they are no longer needed |> drop(columns: ["sum", "count"]) // Set the _field column of the output table to to the value // provided in the outputField parameter |> set(key: "_field", value: outputField) // Rename avg column to _value |> rename(columns: {avg: "_value"}) ``` ```js average = (tables=<-, outputField="average") => tables |> reduce( identity: {count: 0.0, sum: 0.0, avg: 0.0}, fn: (r, accumulator) => ({ count: accumulator.count + 1.0, sum: accumulator.sum + r._value, avg: (accumulator.sum + r._value) / (accumulator.count + 1.0), }), ) |> drop(columns: ["sum", "count"]) |> set(key: "_field", value: outputField) |> rename(columns: {avg: "_value"}) ``` ### Aggregate multiple columns Built-in aggregate functions only operate on one column. Use `reduce()` to create a custom aggregate function that aggregates multiple columns. The following function expects input tables to have `c1_value` and `c2_value`columns and generates an average for each. ```js multiAvg = (tables=<-) => tables |> reduce( identity: { count: 1.0, c1_sum: 0.0, c1_avg: 0.0, c2_sum: 0.0, c2_avg: 0.0, }, fn: (r, accumulator) => ({ count: accumulator.count + 1.0, c1_sum: accumulator.c1_sum + r.c1_value, c1_avg: accumulator.c1_sum / accumulator.count, c2_sum: accumulator.c2_sum + r.c2_value, c2_avg: accumulator.c2_sum / accumulator.count, }), ) ``` ### Aggregate gross and net profit Use `reduce()` to create a function that aggregates gross and net profit. This example expects `profit` and `expenses` columns in the input tables. ```js profitSummary = (tables=<-) => tables |> reduce( identity: {gross: 0.0, net: 0.0}, fn: (r, accumulator) => ({ gross: accumulator.gross + r.profit, net: accumulator.net + r.profit - r.expenses } ) ) ``` #### Related [functions](/influxdb/v2/tags/functions/)[custom](/influxdb/v2/tags/custom/)[flux](/influxdb/v2/tags/flux/)[aggregates](/influxdb/v2/tags/aggregates/) | Parameter | Description | | --- | --- | | Parameter | Description | | r | A record that represents the row or record. | | accumulator | A record that contains values used in each row’s aggregate calculation. | | _time | _value | | --- | --- | | _time | _value | | 2019-04-23T16:10:49Z | 1.6 | | 2019-04-23T16:10:59Z | 2.3 | | 2019-04-23T16:11:09Z | 0.7 | | 2019-04-23T16:11:19Z | 1.2 | | 2019-04-23T16:11:29Z | 3.8 | | sum | product | | --- | --- | | sum | product | | 9.6 | 11.74656 | --- # Check if a value exists Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/exists/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `exists` operator to check if a row record contains a column or if a column’s value is *null*. ```js (r) => exists r.column ``` If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. Use `exists` with row functions ([`filter()`](/flux/v0/stdlib/universe/filter/),[`map()`](/flux/v0/stdlib/universe/map/),[`reduce()`](/flux/v0/stdlib/universe/reduce/)) to check if a row includes a column or if the value for that column is *null*. #### Filter null values ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => exists r._value) ``` #### Map values based on existence ```js from(bucket: "default") |> range(start: -30s) |> map( fn: (r) => ({r with human_readable: if exists r._value then "${r._field} is ${string(v: r._value)}." else "${r._field} has no value.", }), ) ``` #### Ignore null values in a custom aggregate function ```js customSumProduct = (tables=<-) => tables |> reduce( identity: {sum: 0.0, product: 1.0}, fn: (r, accumulator) => ({r with sum: if exists r._value then r._value + accumulator.sum else accumulator.sum, product: if exists r._value then r.value * accumulator.product else accumulator.product, }), ) ``` #### Check if a statically defined record contains a key When you use the [record literal syntax](/flux/v0/data-types/composite/record/#record-syntax)to statically define a record, Flux knows the record type and what keys to expect. * If the key exists in the static record, `exists` returns `true`. * If the key exists in the static record, but has a *null* value, `exists` returns `false`. * If the key does not exist in the static record, because the record type is statically known, `exists` returns an error. ``` import "internal/debug" p = { firstName: "John", lastName: "Doe", age: 42, height: debug.null(type: "int"), } exists p.firstName // Returns true exists p.height // Returns false exists p.hairColor // Returns "error: record is missing label hairColor" ``` #### Related * [Query fields and tags](/influxdb/v2/query-data/flux/query-fields/) * [filter() function](/flux/v0/stdlib/universe/filter/) [exists](/influxdb/v2/tags/exists/) --- # Explore your data schema with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/explore-schema/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux provides functions that let you explore the structure and schema of your data stored in InfluxDB. * [List buckets](#list-buckets) * [List measurements](#list-measurements) * [List field keys](#list-field-keys) * [List tag keys](#list-tag-keys) * [List tag values](#list-tag-values) Functions in the `schema` package are not supported in the [Flux REPL](/influxdb/v2/tools/repl/). ## List buckets Use [`buckets()`](/flux/v0/stdlib/universe/buckets/)to list **buckets in your organization**. ```js buckets() ``` [](#view-example-buckets-output) View example `buckets()` output `buckets()` returns a single table with the following columns: * **organizationID**: Organization ID * **name**: Bucket name * **id**: Bucket ID * **retentionPolicy**: Retention policy associated with the bucket * **retentionPeriod**: Retention period in nanoseconds |organizationID| name | id |retentionPolicy|retentionPeriod| |--------------|----------------|-------|---------------|---------------| | XooX0x0 | \_monitoring |XooX0x1| |604800000000000| | XooX0x0 | \_tasks |XooX0x2| |259200000000000| | XooX0x0 |example-bucket-1|XooX0x3| | 0 | | XooX0x0 |example-bucket-2|XooX0x4| | 0 | | XooX0x0 |example-bucket-3|XooX0x5| |172800000000000| ## List measurements Use [`schema.measurements()`](/flux/v0/stdlib/influxdata/influxdb/schema/measurements)to list **measurements in a bucket**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.measurements(bucket: "example-bucket") ``` [](#view-example-schemameasurements-output) View example `schema.measurements()` output `schema.measurements()` returns a single table with a `_value` column. Each row contains the name of a measurement. |\_value| |-------| | m1 | | m2 | | m3 | | m4 | | m5 | ## List field keys Use [`schema.fieldKeys`](/flux/v0/stdlib/influxdata/influxdb/schema/fieldkeys)to list **field keys in a bucket**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.fieldKeys(bucket: "example-bucket") ``` [](#view-example-schemafieldkeys-output) View example `schema.fieldKeys()` output `schema.fieldKeys()` returns a single table with a `_value` column. Each row contains a unique field key from the specified bucket. |\_value| |-------| |field1 | |field2 | |field3 | |field4 | |field5 | ### List fields in a measurement Use [`schema.measurementFieldKeys`](/flux/v0/stdlib/influxdata/influxdb/schema/measurementfieldkeys)to list **field keys in a measurement**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.measurementFieldKeys( bucket: "example-bucket", measurement: "example-measurement", ) ``` [](#view-example-schemameasurementfieldkeys-output) View example `schema.measurementFieldKeys()` output `schema.measurementFieldKeys()` returns a single table with a `_value` column. Each row contains the name of a unique field key in the specified bucket and measurement. |\_value| |-------| |field1 | |field2 | |field3 | |field4 | |field5 | ## List tag keys Use [`schema.tagKeys()`](/flux/v0/stdlib/influxdata/influxdb/schema/tagkeys)to list **tag keys in a bucket**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.tagKeys(bucket: "example-bucket") ``` [](#view-example-schematagkeys-output) View example `schema.tagKeys()` output `schema.tagKeys()` returns a single table with a `_value` column. Each row contains the a unique tag key from the specified bucket. |\_value| |-------| | tag1 | | tag2 | | tag3 | | tag4 | | tag5 | ### List tag keys in a measurement Use [`schema.measurementTagKeys`](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagkeys)to list **tag keys in a measurement**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.measurementTagKeys( bucket: "example-bucket", measurement: "example-measurement", ) ``` [](#view-example-schemameasurementtagkeys-output) View example `schema.measurementTagKeys()` output `schema.measurementTagKeys()` returns a single table with a `_value` column. Each row contains a unique tag key from the specified bucket and measurement. |\_value| |-------| | tag1 | | tag2 | | tag3 | | tag4 | | tag5 | ## List tag values Use [`schema.tagValues()`](/flux/v0/stdlib/influxdata/influxdb/schema/tagvalues)to list **tag values for a given tag in a bucket**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.tagValues(bucket: "example-bucket", tag: "example-tag") ``` [](#view-example-schematagvalues-output) View example `schema.tagValues()` output `schema.tagValues()` returns a single table with a `_value` column. Each row contains a unique tag value from the specified bucket and tag key. | \_value | |---------| |tagValue1| |tagValue2| |tagValue3| |tagValue4| |tagValue5| ### List tag values in a measurement Use [`schema.measurementTagValues`](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues)to list **tag values for a given tag in a measurement**.*By default, this function returns results from the last 30 days.* ```js import "influxdata/influxdb/schema" schema.measurementTagValues( bucket: "example-bucket", tag: "example-tag", measurement: "example-measurement", ) ``` [](#view-example-schemameasurementtagvalues-output) View example `schema.measurementTagValues()` output `schema.measurementTagValues()` returns a single table with a `_value` column. Each row contains a unique tag value from the specified bucket, measurement, and tag key. | \_value | |---------| |tagValue1| |tagValue2| |tagValue3| |tagValue4| |tagValue5| #### Related [schema](/influxdb/v2/tags/schema/) | organizationID | name | id | retentionPolicy | retentionPeriod | | --- | --- | --- | --- | --- | | organizationID | name | id | retentionPolicy | retentionPeriod | | XooX0x0 | _monitoring | XooX0x1 | | 604800000000000 | | XooX0x0 | _tasks | XooX0x2 | | 259200000000000 | | XooX0x0 | example-bucket-1 | XooX0x3 | | 0 | | XooX0x0 | example-bucket-2 | XooX0x4 | | 0 | | XooX0x0 | example-bucket-3 | XooX0x5 | | 172800000000000 | | _value | | --- | | _value | | m1 | | m2 | | m3 | | m4 | | m5 | | _value | | --- | | _value | | field1 | | field2 | | field3 | | field4 | | field5 | | _value | | --- | | _value | | field1 | | field2 | | field3 | | field4 | | field5 | | _value | | --- | | _value | | tag1 | | tag2 | | tag3 | | tag4 | | tag5 | | _value | | --- | | _value | | tag1 | | tag2 | | tag3 | | tag4 | | tag5 | | _value | | --- | | _value | | tagValue1 | | tagValue2 | | tagValue3 | | tagValue4 | | tagValue5 | | _value | | --- | | _value | | tagValue1 | | tagValue2 | | tagValue3 | | tagValue4 | | tagValue5 | --- # Fill null values in data Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/fill/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`fill()`](/flux/v0/stdlib/universe/fill/)to replace *null* values with: * [the previous non-null value](#fill-with-the-previous-value) * [a specified value](#fill-with-a-specified-value) ```js data |> fill(usePrevious: true) // OR data |> fill(value: 0.0) ``` > [!Note] > #### Fill empty windows of time > > The `fill()` function **does not** fill empty windows of time. > It only replaces *null* values in existing data. > Filling empty windows of time requires time interpolation*(see [influxdata/flux#2428](https://github.com/influxdata/flux/issues/2428))*. ## Fill with the previous value To fill *null* values with the previous **non-null** value, set the `usePrevious` parameter to `true`. > [!Note] > Values remain *null* if there is no previous non-null value in the table. ```js data |> fill(usePrevious: true) ``` **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| null | |2020-01-01T00:04:00Z| null | |2020-01-01T00:05:00Z| 1.4 | **`fill(usePrevious: true)` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| 0.8 | |2020-01-01T00:04:00Z| 0.8 | |2020-01-01T00:05:00Z| 1.4 | ## Fill with a specified value To fill *null* values with a specified value, use the `value` parameter to specify the fill value.*The fill value must match the [data type](/flux/v0/spec/types/#basic-types)of the [column](/flux/v0/stdlib/universe/fill/#column).* ```js data |> fill(value: 0.0) ``` **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| null | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| null | |2020-01-01T00:04:00Z| null | |2020-01-01T00:05:00Z| 1.4 | **`fill(value: 0.0)` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 0.0 | |2020-01-01T00:02:00Z| 0.8 | |2020-01-01T00:03:00Z| 0.0 | |2020-01-01T00:04:00Z| 0.0 | |2020-01-01T00:05:00Z| 1.4 | #### Related * [fill() function](/flux/v0/stdlib/universe/fill/) [query](/influxdb/v2/tags/query/)[fill](/influxdb/v2/tags/fill/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | null | | 2020-01-01T00:04:00Z | null | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | 0.8 | | 2020-01-01T00:04:00Z | 0.8 | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | null | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | null | | 2020-01-01T00:04:00Z | null | | 2020-01-01T00:05:00Z | 1.4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 0.0 | | 2020-01-01T00:02:00Z | 0.8 | | 2020-01-01T00:03:00Z | 0.0 | | 2020-01-01T00:04:00Z | 0.0 | | 2020-01-01T00:05:00Z | 1.4 | --- # Query first and last values Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/first-last/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`first()`](/flux/v0/stdlib/universe/first/) or[`last()`](/flux/v0/stdlib/universe/last/) to return the first or last record in an input table. ```js data |> first() // OR data |> last() ``` > [!Note] > By default, InfluxDB returns results sorted by time, however you can use the[`sort()` function](/flux/v0/stdlib/universe/sort/)to change how results are sorted.`first()` and `last()` respect the sort order of input data and return records > based on the order they are received in. ### first `first()` returns the first non-null record in an input table. **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **The following function returns:** ```js |> first() ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | ### last `last()` returns the last non-null record in an input table. **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **The following function returns:** ```js |> last() ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:04:00Z| 3.0 | ## Use first() or last() with aggregateWindow() Use `first()` and `last()` with [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)to select the first or last records in time-based groups.`aggregateWindow()` segments data into windows of time, aggregates data in each window into a single point using aggregate or selector functions, and then removes the time-based segmentation. **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 10 | |2020-01-01T00:00:15Z| 12 | |2020-01-01T00:00:45Z| 9 | |2020-01-01T00:01:05Z| 9 | |2020-01-01T00:01:10Z| 15 | |2020-01-01T00:02:30Z| 11 | **The following function returns:** [first](#first-2)[last](#last-2) ```js |> aggregateWindow(every: 1h, fn: first) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:59Z| 10 | |2020-01-01T00:01:59Z| 9 | |2020-01-01T00:02:59Z| 11 | ```js |> aggregateWindow(every: 1h, fn: last) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:59Z| 9 | |2020-01-01T00:01:59Z| 15 | |2020-01-01T00:02:59Z| 11 | #### Related * [first() function](/flux/v0/stdlib/universe/first/) * [last() function](/flux/v0/stdlib/universe/last/) [query](/influxdb/v2/tags/query/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 10 | | 2020-01-01T00:00:15Z | 12 | | 2020-01-01T00:00:45Z | 9 | | 2020-01-01T00:01:05Z | 9 | | 2020-01-01T00:01:10Z | 15 | | 2020-01-01T00:02:30Z | 11 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:59Z | 10 | | 2020-01-01T00:01:59Z | 9 | | 2020-01-01T00:02:59Z | 11 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:59Z | 9 | | 2020-01-01T00:01:59Z | 15 | | 2020-01-01T00:02:59Z | 11 | --- # Query the Flux version Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/flux-version/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB 2.10 includes specific version of Flux that may or may not support documented Flux functionality. It’s important to know what version of Flux you’re currently using and what functions are supported in that specific version. To query the version of Flux installed with InfluxDB, use `array.from()` to create an ad hoc stream of tables and `runtime.version()` to populate a column with the Flux version. > [!Note] > Because the InfluxDB `/api/v2/query` endpoint can only return a stream of tables > and not single scalar values, you must use `array.from()` to create a stream of tables. Run the following query in the **InfluxDB user interface**, with the **`influx` CLI**, or **InfluxDB API**: ```js import "array" import "runtime" array.from(rows: [{version: runtime.version()}]) ``` [InfluxDB UI](#influxdb-ui)[influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) To return the version of Flux installed with InfluxDB using the InfluxDB UI: 1. Click **Data Explorer** in the left navigation bar. Data Explorer 1. Click **Script Editor** to manually create and edit a Flux query. 2. Enable the **View Raw Data** toggle or select one of the following visualization types: * [Single Stat](/influxdb/v2/visualize-data/visualization-types/single-stat/) * [Table](/influxdb/v2/visualize-data/visualization-types/table/) 3. Enter and run the following query: ``` import "array" import "runtime" array.from(rows: [{version: runtime.version()}]) ``` To return the version of Flux installed with InfluxDB using the `influx` CLI, use the `influx query` command. Provide the following: * InfluxDB **host**, **organization**, and **API token** *(the example below assumes that a[CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials)is set up and active)* * Query to execute ```sh $ influx query \ 'import "array" import "runtime" array.from(rows: [{version: runtime.version()}])' # Output Result: _result Table: keys: [] version:string ---------------------- v0.161.0 ``` To return the version of Flux installed with InfluxDB using the InfluxDB API, use the [`/api/v2/query` endpoint](/influxdb/v2/api/query-data/). ``` POST http://localhost:8086/api/v2/query ``` Provide the following: * InfluxDB host * InfluxDB organization name or ID as a query parameter * `Authorization` header with the `Token` scheme and your API token * `Accept: application/csv` header * `Content-type: application/vnd.flux` header * Query to execute as the request body ```sh curl --request POST \ http://localhost:8086/api/v2/query?orgID=INFLUX_ORG_ID \ --header 'Authorization: Token INFLUX_TOKEN' \ --header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --data 'import "array" import "runtime" array.from(rows: [{version: runtime.version()}])' # Output ,result,table,version ,_result,0,v0.161.0 ``` #### Flux version in the Flux REPL When you run `runtime.version()` in the [Flux REPL](/influxdb/v2/tools/flux-repl/), the function returns the version of Flux the REPL was built with, not the version of Flux installed in the instance of InfluxDB you’re querying. #### Related * [runtime.version() function](/flux/v0/stdlib/runtime/version/) [query](/influxdb/v2/tags/query/) --- # Work with geo-temporal data Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/geo/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [Flux Geo package](/flux/v0/stdlib/experimental/geo) to filter geo-temporal data and group by geographic location or track. The Geo package is experimental and subject to change at any time. By using it, you agree to the [risks of experimental functions](/flux/v0/stdlib/experimental/to/#experimental-functions-are-subject-to-change). **To work with geo-temporal data:** 1. Import the `experimental/geo` package. ``` import "experimental/geo" ``` 2. Load geo-temporal data. *See below for [sample geo-temporal data](#sample-data).* 3. Do one or more of the following: * [Shape data to work with the Geo package](#shape-data-to-work-with-the-geo-package) * [Filter data by region](#filter-geo-temporal-data-by-region) (using strict or non-strict filters) * [Group data by area or by track](#group-geo-temporal-data) ### [Shape data to work with the Geo package](/influxdb/v2/query-data/flux/geo/shape-geo-data/) Functions in the Flux Geo package require **lat** and **lon** fields and an **s2\_cell\_id** tag. Rename latitude and longitude fields and generate S2 cell ID tokens. ```js import "experimental/geo" sampleGeoData |> geo.shapeData(latField: "latitude", lonField: "longitude", level: 10) ``` ### [Filter geo-temporal data by region](/influxdb/v2/query-data/flux/geo/filter-by-region/) Use the `geo.filterRows` function to filter geo-temporal data by box-shaped, circular, or polygonal geographic regions. ```js import "experimental/geo" sampleGeoData |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}, strict: true) ``` ### [Group geo-temporal data](/influxdb/v2/query-data/flux/geo/group-geo-data/) Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()` to group data into tracks or routes. ```js import "experimental/geo" sampleGeoData |> geo.groupByArea(newColumn: "geoArea", level: 5) |> geo.asTracks(groupBy: ["id"],sortBy: ["_time"]) ``` ## Sample data Many of the examples in this section use a `sampleGeoData` variable that represents a sample set of geo-temporal data. The [Bird Migration Sample Data](/influxdb/v2/reference/sample-data/#bird-migration-sample-data)provides sample geo-temporal data that meets the[requirements of the Flux Geo package](/flux/v0/stdlib/experimental/geo/#geo-schema-requirements). ### Load bird migration sample data Use the [`sample.data()` function](/flux/v0/stdlib/influxdata/influxdb/sample/data/)to load the sample bird migration data: ```js import "influxdata/influxdb/sample" sampleGeoData = sample.data(set: "birdMigration") ``` > [!Note] > `sample.data()` downloads sample data each time you execute the query **(\~1.3 MB)**. > If bandwidth is a concern, use the [`to()` function](/flux/v0/stdlib/influxdata/influxdb/to/)to write the data to a bucket, and then query the bucket with [`from()`](/flux/v0/stdlib/influxdata/influxdb/from/). --- # Filter geo-temporal data by region Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/geo/filter-by-region/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`geo.filterRows` function](/flux/v0/stdlib/experimental/geo/filterrows/)to filter geo-temporal data by geographic region: 1. [Define a geographic region](#define-a-geographic-region) 2. [Use strict or non-strict filtering](#strict-and-non-strict-filtering) The following example uses the [sample bird migration data](/influxdb/v2/query-data/flux/geo/#sample-data)and queries data points **within 200km of Cairo, Egypt**: ```js import "experimental/geo" sampleGeoData |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}, strict: true) ``` ## Define a geographic region Many functions in the Geo package filter data based on geographic region. Define a geographic region using one of the the following shapes: * [box](#box) * [circle](#circle) * [polygon](#polygon) ### box Define a box-shaped region by specifying a record containing the following properties: * **minLat:** minimum latitude in decimal degrees (WGS 84) *(Float)* * **maxLat:** maximum latitude in decimal degrees (WGS 84) *(Float)* * **minLon:** minimum longitude in decimal degrees (WGS 84) *(Float)* * **maxLon:** maximum longitude in decimal degrees (WGS 84) *(Float)* ##### Example box-shaped region ```js { minLat: 40.51757813, maxLat: 40.86914063, minLon: -73.65234375, maxLon: -72.94921875, } ``` ### circle Define a circular region by specifying a record containing the following properties: * **lat**: latitude of the circle center in decimal degrees (WGS 84) *(Float)* * **lon**: longitude of the circle center in decimal degrees (WGS 84) *(Float)* * **radius**: radius of the circle in kilometers (km) *(Float)* ##### Example circular region ```js { lat: 40.69335938, lon: -73.30078125, radius: 20.0, } ``` ### polygon Define a polygonal region with a record containing the latitude and longitude for each point in the polygon: * **points**: points that define the custom polygon *(Array of records)* Define each point with a record containing the following properties: ``` - **lat**: latitude in decimal degrees (WGS 84) _(Float)_ - **lon**: longitude in decimal degrees (WGS 84) _(Float)_ ``` ##### Example polygonal region ```js { points: [ {lat: 40.671659, lon: -73.936631}, {lat: 40.706543, lon: -73.749177}, {lat: 40.791333, lon: -73.880327}, ] } ``` ## Strict and non-strict filtering In most cases, the specified geographic region does not perfectly align with S2 grid cells. * **Non-strict filtering** returns points that may be outside of the specified region but inside S2 grid cells partially covered by the region. * **Strict filtering** returns only points inside the specified region. *Strict filtering is less performant, but more accurate than non-strict filtering.* S2 grid cell Filter region Returned point **Strict filtering** **Non-strict filtering** #### Related * [geo package](/flux/v0/stdlib/experimental/geo/) * [geo.filterRows() function](/flux/v0/stdlib/experimental/geo/filterrows/) --- # Group geo-temporal data Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/geo/group-geo-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()`to group data into tracks or routes. * [Group data by area](#group-data-by-area) * [Group data into tracks or routes](#group-data-by-track-or-route) > [!Note] > For example results, use the [bird migration sample data](/influxdb/v2/reference/sample-data/#bird-migration-sample-data)to populate the `sampleGeoData` variable in the queries below. ### Group data by area Use the [`geo.groupByArea()` function](/flux/v0/stdlib/experimental/geo/groupbyarea/)to group geo-temporal data points by geographic area. Areas are determined by [S2 grid cells](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering) * Specify a new column to store the unique area identifier for each point with the `newColumn` parameter. * Specify the [S2 cell level](https://s2geometry.io/resources/s2cell_statistics)to use when calculating geographic areas with the `level` parameter. The following example uses the [sample bird migration data](/influxdb/v2/query-data/flux/geo/#sample-data)to query data points within 200km of Cairo, Egypt and group them by geographic area: ```js import "experimental/geo" sampleGeoData |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) |> geo.groupByArea(newColumn: "geoArea", level: 5) ``` ### Group data by track or route Use [`geo.asTracks()` function](/flux/v0/stdlib/experimental/geo/astracks/)to group data points into tracks or routes and order them by time or other columns. Data must contain a unique identifier for each track. For example: `id` or `tid`. * Specify columns that uniquely identify each track or route with the `groupBy` parameter. * Specify which columns to sort by with the `sortBy` parameter. Default is `["_time"]`. The following example uses the [sample bird migration data](/influxdb/v2/query-data/flux/geo/#sample-data)to query data points within 200km of Cairo, Egypt and group them into routes unique to each bird: ```js import "experimental/geo" sampleGeoData |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) |> geo.asTracks(groupBy: ["id"], orderBy: ["_time"]) ``` #### Related * [geo package](/flux/v0/stdlib/experimental/geo/) * [geo.groupByArea() function](/flux/v0/stdlib/experimental/geo/groupbyarea/) * [geo.asTracks() function](/flux/v0/stdlib/experimental/geo/astracks/) --- # Shape data to work with the Geo package Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/geo/shape-geo-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Functions in the Geo package require the following data schema: * an **s2\_cell\_id** tag containing the [S2 Cell ID](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering)**as a token** * a **`lat` field** field containing the **latitude in decimal degrees** (WGS 84) * a **`lon` field** field containing the **longitude in decimal degrees** (WGS 84) ## Shape geo-temporal data If your data already contains latitude and longitude fields, use the[`geo.shapeData()`function](/flux/v0/stdlib/experimental/geo/shapedata/)to rename the fields to match the requirements of the Geo package, pivot the data into row-wise sets, and generate S2 cell ID tokens for each point. ```js import "experimental/geo" from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement") |> geo.shapeData(latField: "latitude", lonField: "longitude", level: 10) ``` ## Generate S2 cell ID tokens The Geo package uses the [S2 Geometry Library](https://s2geometry.io/) to represent geographic coordinates on a three-dimensional sphere. The sphere is divided into [cells](https://s2geometry.io/devguide/s2cell_hierarchy), each with a unique 64-bit identifier (S2 cell ID). Grid and S2 cell ID accuracy are defined by a [level](https://s2geometry.io/resources/s2cell_statistics). > [!Note] > To filter more quickly, use higher S2 Cell ID levels, > but know that that higher levels increase [series cardinality](/influxdb/v2/reference/glossary/#series-cardinality). The Geo package requires S2 cell IDs as tokens. To generate add S2 cell IDs tokens to your data, use one of the following options: * [Generate S2 cell ID tokens with Telegraf](#generate-s2-cell-id-tokens-with-telegraf) * [Generate S2 cell ID tokens language-specific libraries](#generate-s2-cell-id-tokens-language-specific-libraries) * [Generate S2 cell ID tokens with Flux](#generate-s2-cell-id-tokens-with-flux) ### Generate S2 cell ID tokens with Telegraf Enable the [Telegraf S2 Geo (`s2geo`) processor](https://github.com/influxdata/telegraf/tree/master/plugins/processors/s2geo)to generate S2 cell ID tokens at a specified `cell_level` using `lat` and `lon` field values. Add the `processors.s2geo` configuration to your Telegraf configuration file (`telegraf.conf`): ```toml [[processors.s2geo]] ## The name of the lat and lon fields containing WGS-84 latitude and ## longitude in decimal degrees. lat_field = "lat" lon_field = "lon" ## New tag to create tag_key = "s2_cell_id" ## Cell level (see https://s2geometry.io/resources/s2cell_statistics.html) cell_level = 9 ``` Telegraf stores the S2 cell ID token in the `s2_cell_id` tag. ### Generate S2 cell ID tokens language-specific libraries Many programming languages offer S2 Libraries with methods for generating S2 cell ID tokens. Use latitude and longitude with the `s2.CellID.ToToken` endpoint of the S2 Geometry Library to generate `s2_cell_id` tags. For example: * **Go:** [s2.CellID.ToToken()](https://godoc.org/github.com/golang/geo/s2#CellID.ToToken) * **Python:** [s2sphere.CellId.to\_token()](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId) * **Crystal:** [cell.to\_token(level)](https://github.com/spider-gazelle/s2_cells#usage) * **JavaScript:** [s2.cellid.toToken()](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string) ### Generate S2 cell ID tokens with Flux Use the [`geo.s2CellIDToken()` function](/flux/v0/stdlib/experimental/geo/s2cellidtoken/)with existing longitude (`lon`) and latitude (`lat`) field values to generate and add the S2 cell ID token. First, use the [`geo.toRows()` function](/flux/v0/stdlib/experimental/geo/torows/)to pivot **lat** and **lon** fields into row-wise sets: ```js import "experimental/geo" from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement") |> geo.toRows() |> map( fn: (r) => ({ r with s2_cell_id: geo.s2CellIDToken(point: {lon: r.lon, lat: r.lat}, level: 10) }) ) ``` > [!Note] > The [`geo.shapeData()`function](/flux/v0/stdlib/experimental/geo/shapedata/)generates S2 cell ID tokens as well. #### Related * [geo package](/flux/v0/stdlib/experimental/geo/) * [geo.shapeData() function](/flux/v0/stdlib/experimental/geo/shapedata/) --- # Group data in InfluxDB with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/group-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). With Flux, you can group data by any column in your queried data set. “Grouping” partitions data into tables in which each row shares a common value for specified columns. This guide walks through grouping data in Flux and provides examples of how data is shaped in the process. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Group keys Every table has a **group key** – a list of columns for which every row in the table has the same value. ###### Example group key ```js [_start, _stop, _field, _measurement, host] ``` Grouping data in Flux is essentially defining the group key of output tables. Understanding how modifying group keys shapes output data is key to successfully grouping and transforming data into your desired output. ## group() Function Flux’s [`group()` function](/flux/v0/stdlib/universe/group) defines the group key for output tables, i.e. grouping records based on values for specific columns. ###### group() example ```js dataStream |> group(columns: ["cpu", "host"]) ``` ###### Resulting group key ```js [cpu, host] ``` The `group()` function has the following parameters: ### columns The list of columns to include or exclude (depending on the [mode](#mode)) in the grouping operation. ### mode The method used to define the group and resulting group key. Possible values include `by` and `except`. ## Example grouping operations To illustrate how grouping works, define a `dataSet` variable that queries System CPU usage from the `example-bucket` bucket. Filter the `cpu` tag so it only returns results for each numbered CPU core. ### Data set CPU used by system operations for all numbered CPU cores. It uses a regular expression to filter only numbered cores. ```js dataSet = from(bucket: "example-bucket") |> range(start: -2m) |> filter(fn: (r) => r._field == "usage_system" and r.cpu =~ /cpu[0-9*]/) |> drop(columns: ["host"]) ``` > [!Note] > This example drops the `host` column from the returned data since the CPU data > is only tracked for a single host and it simplifies the output tables. > Don’t drop the `host` column if monitoring multiple hosts. ``` Table: keys: [_start, _stop, _field, _measurement, cpu] _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:00.000000000Z 7.892107892107892 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:10.000000000Z 7.2 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:20.000000000Z 7.4 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:30.000000000Z 5.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:40.000000000Z 7.4 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:50.000000000Z 7.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:00.000000000Z 10.3 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:10.000000000Z 9.2 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:20.000000000Z 8.4 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:30.000000000Z 8.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:40.000000000Z 8.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:50.000000000Z 10.2 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:36:00.000000000Z 10.6 Table: keys: [_start, _stop, _field, _measurement, cpu] _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:00.000000000Z 0.7992007992007992 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:10.000000000Z 0.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:20.000000000Z 0.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:30.000000000Z 0.4 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:40.000000000Z 0.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:50.000000000Z 0.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:00.000000000Z 1.4 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:10.000000000Z 1.2 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:20.000000000Z 0.8 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:30.000000000Z 0.8991008991008991 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:40.000000000Z 0.8008008008008008 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:50.000000000Z 0.999000999000999 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:36:00.000000000Z 1.1022044088176353 Table: keys: [_start, _stop, _field, _measurement, cpu] _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:00.000000000Z 4.1 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:10.000000000Z 3.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:20.000000000Z 3.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:30.000000000Z 2.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:40.000000000Z 4.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:50.000000000Z 4.895104895104895 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:00.000000000Z 6.906906906906907 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:10.000000000Z 5.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:20.000000000Z 5.1 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:30.000000000Z 4.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:40.000000000Z 5.1 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:50.000000000Z 5.9 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:36:00.000000000Z 6.4935064935064934 Table: keys: [_start, _stop, _field, _measurement, cpu] _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:00.000000000Z 0.5005005005005005 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:10.000000000Z 0.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:20.000000000Z 0.5 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:30.000000000Z 0.3 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:40.000000000Z 0.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:50.000000000Z 0.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:00.000000000Z 1.3986013986013985 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:10.000000000Z 0.9 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:20.000000000Z 0.5005005005005005 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:30.000000000Z 0.7 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:40.000000000Z 0.6 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:50.000000000Z 0.8 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:36:00.000000000Z 0.9 ``` [](#) **Note that the group key is output with each table: `Table: keys: `.** ![Group example data set](/img/flux/grouping-data-set.png) ### Group by CPU Group the `dataSet` stream by the `cpu` column. ```js dataSet |> group(columns: ["cpu"]) ``` This won’t actually change the structure of the data since it already has `cpu`in the group key and is therefore grouped by `cpu`. However, notice that it does change the group key: ###### Group by CPU output tables ``` Table: keys: [cpu] cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time ---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 7.892107892107892 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 7.2 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 5.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 7.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 10.3 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 9.2 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 8.4 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 8.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 8.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 10.2 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [cpu] cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time ---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 0.7992007992007992 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 0.4 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 1.4 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 1.2 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 0.8991008991008991 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 0.8008008008008008 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 0.999000999000999 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [cpu] cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time ---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 4.1 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 3.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 3.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 2.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 4.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 4.895104895104895 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 6.906906906906907 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 5.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 4.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 5.9 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [cpu] cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time ---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 0.3 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 1.3986013986013985 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z ``` [](#) The visualization remains the same. ![Group by CPU](/img/flux/grouping-data-set.png) ### Group by time Grouping data by the `_time` column is a good illustration of how grouping changes the structure of your data. ```js dataSet |> group(columns: ["_time"]) ``` When grouping by `_time`, all records that share a common `_time` value are grouped into individual tables. So each output table represents a single point in time. ###### Group by time output tables ``` Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.892107892107892 usage_system cpu cpu0 2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7992007992007992 usage_system cpu cpu1 2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.1 usage_system cpu cpu2 2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.2 usage_system cpu cpu0 2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 3.6 usage_system cpu cpu2 2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu cpu0 2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 3.5 usage_system cpu cpu2 2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.5 usage_system cpu cpu0 2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.4 usage_system cpu cpu1 2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 2.6 usage_system cpu cpu2 2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.3 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu cpu0 2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.5 usage_system cpu cpu2 2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.5 usage_system cpu cpu0 2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.895104895104895 usage_system cpu cpu2 2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.3 usage_system cpu cpu0 2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.4 usage_system cpu cpu1 2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.906906906906907 usage_system cpu cpu2 2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.3986013986013985 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 9.2 usage_system cpu cpu0 2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.2 usage_system cpu cpu1 2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.7 usage_system cpu cpu2 2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.4 usage_system cpu cpu0 2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu cpu1 2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu cpu2 2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.5 usage_system cpu cpu0 2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8991008991008991 usage_system cpu cpu1 2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.7 usage_system cpu cpu2 2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.6 usage_system cpu cpu0 2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8008008008008008 usage_system cpu cpu1 2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu cpu2 2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.2 usage_system cpu cpu0 2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.999000999000999 usage_system cpu cpu1 2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.9 usage_system cpu cpu2 2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu cpu3 Table: keys: [_time] _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string ------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu cpu3 ``` [](#) Because each timestamp is structured as a separate table, when visualized, all points that share the same timestamp appear connected. ![Group by time](/img/flux/grouping-by-time.png) > [!Note] > With some further processing, you could calculate the average CPU usage across all CPUs per point > of time and group them into a single table, but we won’t cover that in this example. > If you’re interested in running and visualizing this yourself, here’s what the query would look like: > > ``` > dataSet > |> group(columns: ["_time"]) > |> mean() > |> group(columns: ["_value", "_time"], mode: "except") > ``` ## Group by CPU and time Group by the `cpu` and `_time` columns. ```js dataSet |> group(columns: ["cpu", "_time"]) ``` This outputs a table for every unique `cpu` and `_time` combination: ###### Group by CPU and time output tables ``` Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.892107892107892 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7992007992007992 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.1 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:10.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.2 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:10.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:10.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 3.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:10.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:20.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:20.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:20.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 3.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:20.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:30.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 5.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:30.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.4 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:30.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:30.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.3 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:40.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:40.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:40.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:40.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:50.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:50.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:50.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.895104895104895 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:34:50.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.3 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.4 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 6.906906906906907 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 1.3986013986013985 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:10.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 9.2 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:10.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.2 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:10.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:10.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:20.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.4 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:20.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:20.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:20.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:30.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.5 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:30.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8991008991008991 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:30.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:30.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:40.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:40.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8008008008008008 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:40.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:40.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:50.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.2 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:50.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.999000999000999 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:50.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.9 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:35:50.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:36:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:36:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:36:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu 2018-11-05T21:34:00.000000000Z Table: keys: [_time, cpu] _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time ------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ 2018-11-05T21:36:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z ``` [](#) When visualized, tables appear as individual, unconnected points. ![Group by CPU and time](/img/flux/grouping-by-cpu-time.png) Grouping by `cpu` and `_time` is a good illustration of how grouping works. ## In conclusion Grouping is a powerful way to shape your data into your desired output format. It modifies the group keys of output tables, grouping records into tables that all share common values within specified columns. #### Related * [group() function](/flux/v0/stdlib/universe/group/) * [experimental.group() function](/flux/v0/stdlib/experimental/group/) [group](/influxdb/v2/tags/group/) --- # Create histograms with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/histograms/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Histograms provide valuable insight into the distribution of your data. This guide walks through using Flux’s `histogram()` function to transform your data into a **cumulative histogram**. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## histogram() function The [`histogram()` function](/flux/v0/stdlib/universe/histogram) approximates the cumulative distribution of a dataset by counting data frequencies for a list of “bins.” A **bin** is simply a range in which a data point falls. All data points that are less than or equal to the bound are counted in the bin. In the histogram output, a column is added (`le`) that represents the upper bounds of of each bin. Bin counts are cumulative. ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> histogram(bins: [0.0, 10.0, 20.0, 30.0]) ``` > [!Note] > Values output by the `histogram` function represent points of data aggregated over time. > Since values do not represent single points in time, there is no `_time` column in the output table. ## Bin helper functions Flux provides two helper functions for generating histogram bins. Each generates an array of floats designed to be used in the `histogram()` function’s `bins` parameter. ### linearBins() The [`linearBins()` function](/flux/v0/stdlib/universe/linearbins) generates a list of linearly separated floats. ``` linearBins(start: 0.0, width: 10.0, count: 10) // Generated list: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, +Inf] ``` ### logarithmicBins() The [`logarithmicBins()` function](/flux/v0/stdlib/universe/logarithmicbins) generates a list of exponentially separated floats. ``` logarithmicBins(start: 1.0, factor: 2.0, count: 10, infinity: true) // Generated list: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, +Inf] ``` ## Histogram visualization The [Histogram visualization type](/influxdb/v2/visualize-data/visualization-types/histogram/)automatically converts query results into a binned and segmented histogram. Histogram visualization Use the [Histogram visualization controls](/influxdb/v2/visualize-data/visualization-types/histogram/#histogram-controls)to specify the number of bins and define groups in bins. ### Histogram visualization data structure Because the Histogram visualization uses visualization controls to creates bins and groups,**do not** structure query results as histogram data. > [!Note] > Output of the [`histogram()` function](#histogram-function) is **not** compatible > with the Histogram visualization type. > View the example [below](#visualize-errors-by-severity). ## Examples ### Generate a histogram with linear bins ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> histogram(bins: linearBins(start: 65.5, width: 0.5, count: 20, infinity: false)) ``` ###### Output table ``` Table: keys: [_start, _stop, _field, _measurement, host] _start:time _stop:time _field:string _measurement:string host:string le:float _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ---------------------------- ---------------------------- 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 65.5 5 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 66 6 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 66.5 8 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 67 9 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 67.5 9 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 68 10 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 68.5 12 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 69 12 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 69.5 15 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 70 23 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 70.5 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 71 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 71.5 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 72 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 72.5 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 73 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 73.5 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 74 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 74.5 30 2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 75 30 ``` ### Generate a histogram with logarithmic bins ```js from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> histogram(bins: logarithmicBins(start: 0.5, factor: 2.0, count: 10, infinity: false)) ``` ###### Output table ``` Table: keys: [_start, _stop, _field, _measurement, host] _start:time _stop:time _field:string _measurement:string host:string le:float _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ---------------------------- ---------------------------- 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 0.5 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 1 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 2 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 4 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 8 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 16 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 32 0 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 64 2 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 128 30 2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 256 30 ``` ### Visualize errors by severity Use the [Telegraf Syslog plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/syslog)to collect error information from your system. Query the `severity_code` field in the `syslog` measurement: ```js from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "syslog" and r._field == "severity_code") ``` In the Histogram visualization options, select `_time` as the **X Column**and `severity` as the **Group By** option: Logs by severity histogram ### Use Prometheus histograms in Flux *For information about working with Prometheus histograms in Flux, see[Work with Prometheus histograms](/flux/v0/prometheus/metric-types/histogram/).* #### Related * [histogram() function](/flux/v0/stdlib/universe/histogram/) * [Work with Prometheus histograms in Flux](/flux/v0/prometheus/metric-types/histogram/) [histogram](/influxdb/v2/tags/histogram/) --- # Calculate the increase Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/increase/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`increase()`](/flux/v0/stdlib/universe/increase/)to track increases across multiple columns in a table. This function is especially useful when tracking changes in counter values that wrap over time or periodically reset. ```js data |> increase() ``` `increase()` returns a cumulative sum of **non-negative** differences between rows in a table. For example: **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1 | |2020-01-01T00:02:00Z| 2 | |2020-01-01T00:03:00Z| 8 | |2020-01-01T00:04:00Z| 10 | |2020-01-01T00:05:00Z| 0 | |2020-01-01T00:06:00Z| 4 | **`increase()` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:02:00Z| 1 | |2020-01-01T00:03:00Z| 7 | |2020-01-01T00:04:00Z| 9 | |2020-01-01T00:05:00Z| 9 | |2020-01-01T00:06:00Z| 13 | #### Related * [increase() function](/flux/v0/stdlib/universe/increase/) [query](/influxdb/v2/tags/query/)[increase](/influxdb/v2/tags/increase/)[counters](/influxdb/v2/tags/counters/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1 | | 2020-01-01T00:02:00Z | 2 | | 2020-01-01T00:03:00Z | 8 | | 2020-01-01T00:04:00Z | 10 | | 2020-01-01T00:05:00Z | 0 | | 2020-01-01T00:06:00Z | 4 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:02:00Z | 1 | | 2020-01-01T00:03:00Z | 7 | | 2020-01-01T00:04:00Z | 9 | | 2020-01-01T00:05:00Z | 9 | | 2020-01-01T00:06:00Z | 13 | --- # Join data with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/join/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the Flux [`join` package](/flux/v0/stdlib/join/) to join two data sets based on common values using the following join methods: **Inner join** **Left outer join** **Right outer join** **Full outer join** The join package lets you join data from different data sources such as[InfluxDB](/flux/v0/query-data/influxdb/), [SQL database](/flux/v0/query-data/sql/),[CSV](/flux/v0/query-data/csv/), and [others](/flux/v0/query-data/). ## Use join functions to join your data [Inner join](#inner-join)[Left join](#left-join)[Right join](#right-join)[Full outer join](#full-outer-join)[Join on time](#join-on-time) 1. Import the `join` package. 2. Define the **left** and **right** data streams to join: * Each stream must have one or more columns with common values. Column labels do not need to match, but column values do. * Each stream should have identical [group keys](/flux/v0/get-started/data-model/#group-key). *For more information, see [join data requirements](/flux/v0/join-data/#data-requirements).* 3. Use [`join.inner()`](/flux/v0/stdlib/join/inner/) to join the two streams together. Provide the following required parameters: * `left`: Stream of data representing the left side of the join. * `right`: Stream of data representing the right side of the join. * `on`: [Join predicate](/flux/v0/join-data/#join-predicate-function-on). For example: `(l, r) => l.column == r.column`. * `as`: [Join output function](/flux/v0/join-data/#join-output-function-as)that returns a record with values from each input stream. For example: `(l, r) => ({l with column1: r.column1, column2: r.column2})`. ```js import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field") right = sql.from( driverName: "postgres", dataSourceName: "postgresql://username:password@localhost:5432", query: "SELECT * FROM example_table", ) join.inner( left: left, right: right, on: (l, r) => l.column == r.column, as: (l, r) => ({l with name: r.name, location: r.location}), ) ``` For more information and detailed examples, see [Perform an inner join](/flux/v0/join-data/inner/)in the Flux documentation. 1. Import the `join` package. 2. Define the **left** and **right** data streams to join: * Each stream must have one or more columns with common values. Column labels do not need to match, but column values do. * Each stream should have identical [group keys](/flux/v0/get-started/data-model/#group-key). *For more information, see [join data requirements](/flux/v0/join-data/#data-requirements).* 3. Use [`join.left()`](/flux/v0/stdlib/join/left/) to join the two streams together. Provide the following required parameters: * `left`: Stream of data representing the left side of the join. * `right`: Stream of data representing the right side of the join. * `on`: [Join predicate](/flux/v0/join-data/#join-predicate-function-on). For example: `(l, r) => l.column == r.column`. * `as`: [Join output function](/flux/v0/join-data/#join-output-function-as)that returns a record with values from each input stream. For example: `(l, r) => ({l with column1: r.column1, column2: r.column2})`. ```js import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field") right = sql.from( driverName: "postgres", dataSourceName: "postgresql://username:password@localhost:5432", query: "SELECT * FROM example_table", ) join.left( left: left, right: right, on: (l, r) => l.column == r.column, as: (l, r) => ({l with name: r.name, location: r.location}), ) ``` For more information and detailed examples, see [Perform a left outer join](/flux/v0/join-data/left-outer/)in the Flux documentation. 1. Import the `join` package. 2. Define the **left** and **right** data streams to join: * Each stream must have one or more columns with common values. Column labels do not need to match, but column values do. * Each stream should have identical [group keys](/flux/v0/get-started/data-model/#group-key). *For more information, see [join data requirements](/flux/v0/join-data/#data-requirements).* 3. Use [`join.right()`](/flux/v0/stdlib/join/right/) to join the two streams together. Provide the following required parameters: * `left`: Stream of data representing the left side of the join. * `right`: Stream of data representing the right side of the join. * `on`: [Join predicate](/flux/v0/join-data/#join-predicate-function-on). For example: `(l, r) => l.column == r.column`. * `as`: [Join output function](/flux/v0/join-data/#join-output-function-as)that returns a record with values from each input stream. For example: `(l, r) => ({l with column1: r.column1, column2: r.column2})`. ```js import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field") right = sql.from( driverName: "postgres", dataSourceName: "postgresql://username:password@localhost:5432", query: "SELECT * FROM example_table", ) join.right( left: left, right: right, on: (l, r) => l.column == r.column, as: (l, r) => ({l with name: r.name, location: r.location}), ) ``` For more information and detailed examples, see [Perform a right outer join](/flux/v0/join-data/right-outer/)in the Flux documentation. 1. Import the `join` package. 2. Define the **left** and **right** data streams to join: * Each stream must have one or more columns with common values. Column labels do not need to match, but column values do. * Each stream should have identical [group keys](/flux/v0/get-started/data-model/#group-key). *For more information, see [join data requirements](/flux/v0/join-data/#data-requirements).* 3. Use [`join.full()`](/flux/v0/stdlib/join/full/) to join the two streams together. Provide the following required parameters: * `left`: Stream of data representing the left side of the join. * `right`: Stream of data representing the right side of the join. * `on`: [Join predicate](/flux/v0/join-data/#join-predicate-function-on). For example: `(l, r) => l.column == r.column`. * `as`: [Join output function](/flux/v0/join-data/#join-output-function-as)that returns a record with values from each input stream. For example: `(l, r) => ({l with column1: r.column1, column2: r.column2})`. > [!Note] > Full outer joins must account for non-group-key columns in both `l` and `r`records being null. Use conditional logic to check which record contains non-null > values for columns not in the group key. > For more information, see [Account for missing, non-group-key values](/flux/v0/join-data/full-outer/#account-for-missing-non-group-key-values). ``` import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "example-field") right = sql.from( driverName: "postgres", dataSourceName: "postgresql://username:password@localhost:5432", query: "SELECT * FROM example_table", ) join.full( left: left, right: right, on: (l, r) => l.id== r.id, as: (l, r) => { id = if exists l.id then l.id else r.id return {name: l.name, location: r.location, id: id} }, ) ``` For more information and detailed examples, see [Perform a full outer join](/flux/v0/join-data/full-outer/)in the Flux documentation. 1. Import the `join` package. 2. Define the **left** and **right** data streams to join: * Each stream must also have a `_time` column. * Each stream must have one or more columns with common values. Column labels do not need to match, but column values do. * Each stream should have identical [group keys](/flux/v0/get-started/data-model/#group-key). *For more information, see [join data requirements](/flux/v0/join-data/#data-requirements).* 3. Use [`join.time()`](/flux/v0/stdlib/join/time/) to join the two streams together based on time values. Provide the following parameters: * `left`: (Required) Stream of data representing the left side of the join. * `right`: (Required) Stream of data representing the right side of the join. * `as`: (Required) [Join output function](/flux/v0/join-data/#join-output-function-as)that returns a record with values from each input stream. For example: `(l, r) => ({r with column1: l.column1, column2: l.column2})`. * `method`: Join method to use. Default is `inner`. ```js import "join" import "sql" left = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-m1") |> filter(fn: (r) => r._field == "example-f1") right = from(bucket: "example-bucket-2") |> range(start: "-1h") |> filter(fn: (r) => r._measurement == "example-m2") |> filter(fn: (r) => r._field == "example-f2") join.time(method: "left", left: left, right: right, as: (l, r) => ({l with f2: r._value})) ``` For more information and detailed examples, see [Join on time](/flux/v0/join-data/time/)in the Flux documentation. ## When to use union and pivot instead of join functions We recommend using the `join` package to join streams that have mostly different schemas or that come from two separate data sources. If you’re joining two datasets queried from InfluxDB, using[`union()`](/flux/v0/stdlib/universe/union/) and [`pivot()`](/flux/v0/stdlib/universe/pivot/)to combine the data will likely be more performant. For example, if you need to query fields from different InfluxDB buckets and align field values in each row based on time: ```js f1 = from(bucket: "example-bucket-1") |> range(start: "-1h") |> filter(fn: (r) => r._field == "f1") |> drop(columns: "_measurement") f2 = from(bucket: "example-bucket-2") |> range(start: "-1h") |> filter(fn: (r) => r._field == "f2") |> drop(columns: "_measurement") union(tables: [f1, f2]) |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") ``` [](#view-example-input-and-output-data) View example input and output data #### Input ##### f1 | \_time |\_field|\_value| |--------------------|-------|-------| |2020-01-01T00:01:00Z| f1 | 1 | |2020-01-01T00:02:00Z| f1 | 2 | |2020-01-01T00:03:00Z| f1 | 1 | |2020-01-01T00:04:00Z| f1 | 3 | ##### f2 | \_time |\_field|\_value| |--------------------|-------|-------| |2020-01-01T00:01:00Z| f2 | 5 | |2020-01-01T00:02:00Z| f2 | 12 | |2020-01-01T00:03:00Z| f2 | 8 | |2020-01-01T00:04:00Z| f2 | 6 | #### Output | \_time |f1 |f2 | |--------------------|---|---| |2020-01-01T00:01:00Z| 1 | 5 | |2020-01-01T00:02:00Z| 2 |12 | |2020-01-01T00:03:00Z| 1 | 8 | |2020-01-01T00:04:00Z| 3 | 6 | #### Related * [Join data](/flux/v0/join-data/) * [Perform an inner join](/flux/v0/join-data/inner/) * [Perform a left outer join](/flux/v0/join-data/left-outer/) * [Perform a right outer join](/flux/v0/join-data/right-outer/) * [Perform a full outer join](/flux/v0/join-data/full-outer/) * [Join on time](/flux/v0/join-data/time/) * [join package](/flux/v0/stdlib/join/) [join](/influxdb/v2/tags/join/)[flux](/influxdb/v2/tags/flux/) | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:01:00Z | f1 | 1 | | 2020-01-01T00:02:00Z | f1 | 2 | | 2020-01-01T00:03:00Z | f1 | 1 | | 2020-01-01T00:04:00Z | f1 | 3 | | _time | _field | _value | | --- | --- | --- | | _time | _field | _value | | 2020-01-01T00:01:00Z | f2 | 5 | | 2020-01-01T00:02:00Z | f2 | 12 | | 2020-01-01T00:03:00Z | f2 | 8 | | 2020-01-01T00:04:00Z | f2 | 6 | | _time | f1 | f2 | | --- | --- | --- | | _time | f1 | f2 | | 2020-01-01T00:01:00Z | 1 | 5 | | 2020-01-01T00:02:00Z | 2 | 12 | | 2020-01-01T00:03:00Z | 1 | 8 | | 2020-01-01T00:04:00Z | 3 | 6 | --- # Transform data with mathematic operations Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/mathematic-operations/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Flux](/flux/v0/), InfluxData’s data scripting and query language, supports mathematic expressions in data transformations. This article describes how to use [Flux arithmetic operators](/flux/v0/spec/operators/#arithmetic-operators)to “map” over data and transform values using mathematic operations. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ##### Basic mathematic operations ```js // Examples executed using the Flux REPL > 9 + 9 18 > 22 - 14 8 > 6 * 5 30 > 21 / 7 3 ``` See [Flux Read-Eval-Print Loop (REPL)](/influxdb/v2/tools/flux-repl/). > [!Note] > #### Operands must be the same type > > Operands in Flux mathematic operations must be the same data type. > For example, integers cannot be used in operations with floats. > Otherwise, you will get an error similar to: > > ``` > Error: type error: float != int > ``` > > To convert operands to the same type, use [type-conversion functions](/flux/v0/stdlib/universe/)or manually format operands. > The operand data type determines the output data type. > For example: > > ``` > 100 // Parsed as an integer > 100.0 // Parsed as a float > > // Example evaluations > > 20 / 8 > 2 > > > 20.0 / 8.0 > 2.5 > ``` ## Custom mathematic functions Flux lets you [create custom functions](/influxdb/v2/query-data/flux/custom-functions) that use mathematic operations. View the examples below. ###### Custom multiplication function ``` multiply = (x, y) => x * y multiply(x: 10, y: 12) // Returns 120 ``` ###### Custom percentage function ``` percent = (sample, total) => (sample / total) * 100.0 percent(sample: 20.0, total: 80.0) // Returns 25.0 ``` ### Transform values in a data stream To transform multiple values in an input stream, your function needs to: * [Handle piped-forward data](/influxdb/v2/query-data/flux/custom-functions/#use-piped-forward-data-in-a-custom-function). * Each operand necessary for the calculation exists in each row *(see [Pivot vs join](#pivot-vs-join) below)*. * Use the [`map()` function](/flux/v0/stdlib/universe/map) to iterate over each row. The example `multiplyByX()` function below includes: * A `tables` parameter that represents the input data stream (`<-`). * An `x` parameter which is the number by which values in the `_value` column are multiplied. * A `map()` function that iterates over each row in the input stream. It uses the `with` operator to preserve existing columns in each row. It also multiples the `_value` column by `x`. ```js multiplyByX = (x, tables=<-) => tables |> map(fn: (r) => ({r with _value: r._value * x})) data |> multiplyByX(x: 10) ``` ## Examples ### Convert bytes to gigabytes To convert active memory from bytes to gigabytes (GB), divide the `active` field in the `mem` measurement by 1,073,741,824. The `map()` function iterates over each row in the piped-forward data and defines a new `_value` by dividing the original `_value` by 1073741824. ```js from(bucket: "example-bucket") |> range(start: -10m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "active") |> map(fn: (r) => ({r with _value: r._value / 1073741824})) ``` You could turn that same calculation into a function: ```js bytesToGB = (tables=<-) => tables |> map(fn: (r) => ({r with _value: r._value / 1073741824})) data |> bytesToGB() ``` #### Include partial gigabytes Because the original metric (bytes) is an integer, the output of the operation is an integer and does not include partial GBs. To calculate partial GBs, convert the `_value` column and its values to floats using the[`float()` function](/flux/v0/stdlib/universe/float)and format the denominator in the division operation as a float. ```js bytesToGB = (tables=<-) => tables |> map(fn: (r) => ({r with _value: float(v: r._value) / 1073741824.0})) ``` ### Calculate a percentage To calculate a percentage, use simple division, then multiply the result by 100. ```js > 1.0 / 4.0 * 100.0 25.0 ``` *For an in-depth look at calculating percentages, see [Calculate percentages](/influxdb/v2/query-data/flux/calculate-percentages).* ## Pivot vs join To query and use values in mathematical operations in Flux, operand values must exists in a single row. Both `pivot()` and `join()` will do this, but there are important differences between the two: #### Pivot is more performant `pivot()` reads and operates on a single stream of data.`join()` requires two streams of data and the overhead of reading and combining both streams can be significant, especially for larger data sets. #### Use join for multiple data sources Use `join()` when querying data from different buckets or data sources. ##### Pivot fields into columns for mathematic calculations ```js data |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> map(fn: (r) => ({r with _value: (r.field1 + r.field2) / r.field3 * 100.0})) ``` ##### Join multiple data sources for mathematic calculations ```js import "sql" import "influxdata/influxdb/secrets" pgUser = secrets.get(key: "POSTGRES_USER") pgPass = secrets.get(key: "POSTGRES_PASSWORD") pgHost = secrets.get(key: "POSTGRES_HOST") t1 = sql.from( driverName: "postgres", dataSourceName: "postgresql://${pgUser}:${pgPass}@${pgHost}", query: "SELECT id, name, available FROM example_table", ) t2 = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field") join(tables: {t1: t1, t2: t2}, on: ["id"]) |> map(fn: (r) => ({r with _value: r._value_t2 / r.available_t1 * 100.0})) ``` #### Related * [map() function](/flux/v0/stdlib/universe/map/) * [reduce() function](/flux/v0/stdlib/universe/reduce/) * [Flux type-conversion functions](/flux/v0/function-types/#type-conversions) * [Calculate percentages with Flux](/influxdb/v2/query-data/flux/calculate-percentages/) [math](/influxdb/v2/tags/math/)[flux](/influxdb/v2/tags/flux/) --- # Find median values Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/median/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`median()` function](/flux/v0/stdlib/universe/median/)to return a value representing the `0.5` quantile (50th percentile) or median of input data. ## Select a method for calculating the median Select one of the following methods to calculate the median: * [estimate\_tdigest](#estimate_tdigest) * [exact\_mean](#exact_mean) * [exact\_selector](#exact_selector) ### estimate\_tdigest **(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest)to compute an accurate `0.5` quantile estimate on large data sources. Output tables consist of a single row containing the calculated median. **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`estimate_tdigest` returns:** |\_value| |-------| | 1.5 | ### exact\_mean An aggregate method that takes the average of the two points closest to the `0.5` quantile value. Output tables consist of a single row containing the calculated median. **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`exact_mean` returns:** |\_value| |-------| | 1.5 | ### exact\_selector A selector method that returns the data point for which at least 50% of points are less than. Output tables consist of a single row containing the calculated median. **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`exact_selector` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:02:00Z| 1.0 | > [!Note] > The examples below use the [example data variable](/influxdb/v2/query-data/flux/#example-data-variable). ## Find the value that represents the median Use the default method, `"estimate_tdigest"`, to return all rows in a table that contain values in the 50th percentile of data in the table. ```js data |> median() ``` ## Find the average of values closest to the median Use the `exact_mean` method to return a single row per input table containing the average of the two values closest to the mathematical median of data in the table. ```js data |> median(method: "exact_mean") ``` ## Find the point with the median value Use the `exact_selector` method to return a single row per input table containing the value that 50% of values in the table are less than. ```js data |> median(method: "exact_selector") ``` ## Use median() with aggregateWindow() [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)segments data into windows of time, aggregates data in each window into a single point, and then removes the time-based segmentation. It is primarily used to [downsample data](/influxdb/v2/process-data/common-tasks/downsample-data/). To specify the [median calculation method](#select-a-method-for-calculating-the-median) in `aggregateWindow()`, use the[full function syntax](/flux/v0/stdlib/universe/aggregatewindow/#specify-parameters-of-the-aggregate-function): ```js data |> aggregateWindow( every: 5m, fn: (tables=<-, column) => tables |> median(method: "exact_selector"), ) ``` #### Related * [Find percentile and quantile values](/influxdb/v2/query-data/flux/percentile-quantile/) * [median() function](/flux/v0/stdlib/universe/median/) * [quantile() function](/flux/v0/stdlib/universe/quantile/) [query](/influxdb/v2/tags/query/)[median](/influxdb/v2/tags/median/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 1.5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 1.5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:02:00Z | 1.0 | --- # Monitor states Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/monitor-states/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux helps you monitor states in your metrics and events: * [Find how long a state persists](#find-how-long-a-state-persists) * [Count the number of consecutive states](#count-the-number-of-consecutive-states) If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Find how long a state persists Use [`stateDuration()`](/flux/v0/stdlib/universe/stateduration/)to calculate the duration of consecutive rows with a specified state. For each consecutive point that matches the specified state, `stateDuration()`increments and stores the duration (in the specified unit) in a user-defined column. Include the following information: * **Column to search:** any tag key, tag value, field key, field value, or measurement. * **Value:** the value (or state) to search for in the specified column. * **State duration column:** a new column to store the state duration─the length of time that the specified value persists. * **Unit:** the unit of time (`1s` (by default), `1m`, `1h`) used to increment the state duration. ```js data |> stateDuration(fn: (r) => r.column_to_search == "value_to_search_for", column: "state_duration", unit: 1s) ``` * For the first point that evaluates `true`, the state duration is set to `0`. For each consecutive point that evaluates `true`, the state duration increases by the time interval between each consecutive point (in specified units). * If the state is `false`, the state duration is reset to `-1`. ### Example query with stateDuration() The following query searches the `doors` bucket over the past 5 minutes to find how many seconds a door has been `closed`. ```js from(bucket: "doors") |> range(start: -5m) |> stateDuration(fn: (r) => r._value == "closed", column: "door_closed", unit: 1s) ``` In this example, `door_closed` is the **State duration** column. If you write data to the `doors` bucket every minute, the state duration increases by `60s` for each consecutive point where `_value` is `closed`. If `_value` is not `closed`, the state duration is reset to `0`. #### Query results Results for the example query above may look like this (for simplicity, we’ve omitted the measurement, tag, and field columns): | \_time |\_value|door\_closed| |--------------------|-------|------------| |2019-10-26T17:39:16Z|closed | 0 | |2019-10-26T17:40:16Z|closed | 60 | |2019-10-26T17:41:16Z|closed | 120 | |2019-10-26T17:42:16Z| open | \-1 | |2019-10-26T17:43:16Z|closed | 0 | |2019-10-26T17:44:27Z|closed | 60 | ## Count the number of consecutive states Use the [`stateCount()` function](/flux/v0/stdlib/universe/statecount/)and include the following information: * **Column to search:** any tag key, tag value, field key, field value, or measurement. * **Value:** to search for in the specified column. * **State count column:** a new column to store the state count─the number of consecutive records in which the specified value exists. ```js |> stateCount( fn: (r) => r.column_to_search == "value_to_search_for", column: "state_count", ) ``` * For the first point that evaluates `true`, the state count is set to `1`. For each consecutive point that evaluates `true`, the state count increases by 1. * If the state is `false`, the state count is reset to `-1`. ### Example query with stateCount() The following query searches the `doors` bucket over the past 5 minutes and calculates how many points have `closed` as their `_value`. ```js from(bucket: "doors") |> range(start: -5m) |> stateCount(fn: (r) => r._value == "closed", column: "door_closed") ``` This example stores the **state count** in the `door_closed` column. If you write data to the `doors` bucket every minute, the state count increases by `1` for each consecutive point where `_value` is `closed`. If `_value` is not `closed`, the state count is reset to `-1`. #### Query results Results for the example query above may look like this (for simplicity, we’ve omitted the measurement, tag, and field columns): | \_time |\_value|door\_closed| |--------------------|-------|------------| |2019-10-26T17:39:16Z|closed | 1 | |2019-10-26T17:40:16Z|closed | 2 | |2019-10-26T17:41:16Z|closed | 3 | |2019-10-26T17:42:16Z| open | \-1 | |2019-10-26T17:43:16Z|closed | 1 | |2019-10-26T17:44:27Z|closed | 2 | #### Example query to count machine state The following query checks the machine state every minute (idle, assigned, or busy). InfluxDB searches the `servers` bucket over the past hour and counts records with a machine state of `idle`, `assigned` or `busy`. ```js from(bucket: "servers") |> range(start: -1h) |> filter(fn: (r) => r.machine_state == "idle" or r.machine_state == "assigned" or r.machine_state == "busy") |> stateCount(fn: (r) => r.machine_state == "busy", column: "_count") |> stateCount(fn: (r) => r.machine_state == "assigned", column: "_count") |> stateCount(fn: (r) => r.machine_state == "idle", column: "_count") ``` #### Related * [stateDuration() function](/flux/v0/stdlib/universe/stateduration/) * [stateCount() function](/flux/v0/stdlib/universe/statecount/) [states](/influxdb/v2/tags/states/)[monitor](/influxdb/v2/tags/monitor/)[flux](/influxdb/v2/tags/flux/) | _time | _value | door_closed | | --- | --- | --- | | _time | _value | door_closed | | 2019-10-26T17:39:16Z | closed | 0 | | 2019-10-26T17:40:16Z | closed | 60 | | 2019-10-26T17:41:16Z | closed | 120 | | 2019-10-26T17:42:16Z | open | -1 | | 2019-10-26T17:43:16Z | closed | 0 | | 2019-10-26T17:44:27Z | closed | 60 | | _time | _value | door_closed | | --- | --- | --- | | _time | _value | door_closed | | 2019-10-26T17:39:16Z | closed | 1 | | 2019-10-26T17:40:16Z | closed | 2 | | 2019-10-26T17:41:16Z | closed | 3 | | 2019-10-26T17:42:16Z | open | -1 | | 2019-10-26T17:43:16Z | closed | 1 | | 2019-10-26T17:44:27Z | closed | 2 | --- # Calculate the moving average Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/moving-average/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`movingAverage()`](/flux/v0/stdlib/universe/movingaverage/)or [`timedMovingAverage()`](/flux/v0/stdlib/universe/timedmovingaverage/)to return the moving average of data. ```js data |> movingAverage(n: 5) // OR data |> timedMovingAverage(every: 5m, period: 10m) ``` ### movingAverage() For each row in a table, `movingAverage()` returns the average of the current value and**previous** values where `n` is the total number of values used to calculate the average. If `n = 3`: |Row #| Calculation | |-----|-----------------------------| | 1 |*Insufficient number of rows*| | 2 |*Insufficient number of rows*| | 3 | (Row1 + Row2 + Row3) / 3 | | 4 | (Row2 + Row3 + Row4) / 3 | | 5 | (Row3 + Row4 + Row5) / 3 | **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.2 | |2020-01-01T00:03:00Z| 1.8 | |2020-01-01T00:04:00Z| 0.9 | |2020-01-01T00:05:00Z| 1.4 | |2020-01-01T00:06:00Z| 2.0 | **The following would return:** ```js |> movingAverage(n: 3) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:03:00Z| 1.33 | |2020-01-01T00:04:00Z| 1.30 | |2020-01-01T00:05:00Z| 1.36 | |2020-01-01T00:06:00Z| 1.43 | ### timedMovingAverage() For each row in a table, `timedMovingAverage()` returns the average of the current value and all row values in the **previous** `period` (duration). It returns moving averages at a frequency defined by the `every` parameter. Each color in the diagram below represents a period of time used to calculate an average and the time a point representing the average is returned. If `every = 30m` and `period = 1h`: 0:000:301:001:302:002:303:003:002:302:001:301:000:30 **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 1.0 | |2020-01-01T00:30:00Z| 1.2 | |2020-01-01T01:00:00Z| 1.8 | |2020-01-01T01:30:00Z| 0.9 | |2020-01-01T02:00:00Z| 1.4 | |2020-01-01T02:30:00Z| 2.0 | |2020-01-01T03:00:00Z| 1.9 | **The following would return:** ```js |> timedMovingAverage(every: 30m, period: 1h) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:30:00Z| 1.0 | |2020-01-01T01:00:00Z| 1.1 | |2020-01-01T01:30:00Z| 1.5 | |2020-01-01T02:00:00Z| 1.35 | |2020-01-01T02:30:00Z| 1.15 | |2020-01-01T03:00:00Z| 1.7 | |2020-01-01T03:00:00Z| 2 | #### Related * [movingAverage() function](/flux/v0/stdlib/universe/movingaverage/) * [timedMovingAverage() function](/flux/v0/stdlib/universe/timedmovingaverage/) [query](/influxdb/v2/tags/query/)[moving average](/influxdb/v2/tags/moving-average/) | Row # | Calculation | | --- | --- | | Row # | Calculation | | 1 | Insufficient number of rows | | 2 | Insufficient number of rows | | 3 | (Row1 + Row2 + Row3) / 3 | | 4 | (Row2 + Row3 + Row4) / 3 | | 5 | (Row3 + Row4 + Row5) / 3 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.2 | | 2020-01-01T00:03:00Z | 1.8 | | 2020-01-01T00:04:00Z | 0.9 | | 2020-01-01T00:05:00Z | 1.4 | | 2020-01-01T00:06:00Z | 2.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:03:00Z | 1.33 | | 2020-01-01T00:04:00Z | 1.30 | | 2020-01-01T00:05:00Z | 1.36 | | 2020-01-01T00:06:00Z | 1.43 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 1.0 | | 2020-01-01T00:30:00Z | 1.2 | | 2020-01-01T01:00:00Z | 1.8 | | 2020-01-01T01:30:00Z | 0.9 | | 2020-01-01T02:00:00Z | 1.4 | | 2020-01-01T02:30:00Z | 2.0 | | 2020-01-01T03:00:00Z | 1.9 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:30:00Z | 1.0 | | 2020-01-01T01:00:00Z | 1.1 | | 2020-01-01T01:30:00Z | 1.5 | | 2020-01-01T02:00:00Z | 1.35 | | 2020-01-01T02:30:00Z | 1.15 | | 2020-01-01T03:00:00Z | 1.7 | | 2020-01-01T03:00:00Z | 2 | --- # Operate on timestamps with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/operate-on-timestamps/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Every point stored in InfluxDB has an associated timestamp. Use Flux to process and operate on timestamps to suit your needs. * [Convert timestamp format](#convert-timestamp-format) * [Calculate the duration between two timestamps](#calculate-the-duration-between-two-timestamps) * [Retrieve the current time](#retrieve-the-current-time) * [Normalize irregular timestamps](#normalize-irregular-timestamps) * [Use timestamps and durations together](#use-timestamps-and-durations-together) > [!Note] > If you’re just getting started with Flux queries, check out the following: > > * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. > * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Convert timestamp format * [Unix nanosecond to RFC3339](#unix-nanosecond-to-rfc3339) * [RFC3339 to Unix nanosecond](#rfc3339-to-unix-nanosecond) ### Unix nanosecond to RFC3339 Use the [`time()` function](/flux/v0/stdlib/universe/time/)to convert a [Unix **nanosecond** timestamp](/influxdb/v2/reference/glossary/#unix-timestamp)to an [RFC3339 timestamp](/influxdb/v2/reference/glossary/#rfc3339-timestamp). ``` time(v: 1568808000000000000) // Returns 2019-09-18T12:00:00.000000000Z ``` ### RFC3339 to Unix nanosecond Use the [`uint()` function](/flux/v0/stdlib/universe/uint/)to convert an RFC3339 timestamp to a Unix nanosecond timestamp. ``` uint(v: 2019-09-18T12:00:00.000000000Z) // Returns 1568808000000000000 ``` ## Calculate the duration between two timestamps Flux doesn’t support mathematical operations using [time type](/flux/v0/spec/types/#time-types) values. To calculate the duration between two timestamps: 1. Use the `uint()` function to convert each timestamp to a Unix nanosecond timestamp. 2. Subtract one Unix nanosecond timestamp from the other. 3. Use the `duration()` function to convert the result into a duration. ``` time1 = uint(v: 2019-09-17T21:12:05Z) time2 = uint(v: 2019-09-18T22:16:35Z) duration(v: time2 - time1) // Returns 25h4m30s ``` > [!Note] > Flux doesn’t support duration column types. > To store a duration in a column, use the [`string()` function](/flux/v0/stdlib/universe/string/)to convert the duration to a string. ## Retrieve the current time * [Current UTC time](#current-utc-time) * [Current system time](#current-system-time) ### Current UTC time Use the [`now()` function](/flux/v0/stdlib/universe/now/) to return the current UTC time in RFC3339 format. ```js now() ``` > [!Note] > `now()` is cached at runtime, so all instances of `now()` in a Flux script > return the same value. ### Current system time Import the `system` package and use the [`system.time()` function](/flux/v0/stdlib/system/time/)to return the current system time of the host machine in RFC3339 format. ```js import "system" system.time() ``` > [!Note] > `system.time()` returns the time it is executed, so each instance of `system.time()`in a Flux script returns a unique value. ## Normalize irregular timestamps To normalize irregular timestamps, truncate all `_time` values to a specified unit with the [`truncateTimeColumn()` function](/flux/v0/stdlib/universe/truncatetimecolumn/). This is useful in [`join()`](/flux/v0/stdlib/universe/join/)and [`pivot()`](/flux/v0/stdlib/universe/pivot/)operations where points should align by time, but timestamps vary slightly. ```js data |> truncateTimeColumn(unit: 1m) ``` **Input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:49Z| 2.0 | |2020-01-01T00:01:01Z| 1.9 | |2020-01-01T00:03:22Z| 1.8 | |2020-01-01T00:04:04Z| 1.9 | |2020-01-01T00:05:38Z| 2.1 | **Output:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 2.0 | |2020-01-01T00:01:00Z| 1.9 | |2020-01-01T00:03:00Z| 1.8 | |2020-01-01T00:04:00Z| 1.9 | |2020-01-01T00:05:00Z| 2.1 | ## Use timestamps and durations together * [Add a duration to a timestamp](#add-a-duration-to-a-timestamp) * [Subtract a duration from a timestamp](#subtract-a-duration-from-a-timestamp) ### Add a duration to a timestamp [`date.add()`](/flux/v0/stdlib/date/add/)adds a duration to a specified time and returns the resulting time. ``` import "date" date.add(d: 6h, to: 2019-09-16T12:00:00Z) // Returns 2019-09-16T18:00:00.000000000Z ``` ### Subtract a duration from a timestamp [`date.sub()`](/flux/v0/stdlib/date/sub/)subtracts a duration from a specified time and returns the resulting time. ``` import "date" date.sub(d: 6h, from: 2019-09-16T12:00:00Z) // Returns 2019-09-16T06:00:00.000000000Z ``` ### Shift a timestamp forward or backward The [timeShift()](/flux/v0/stdlib/universe/timeshift/) function adds the specified duration of time to each value in time columns (`_start`, `_stop`, `_time`). Shift forward in time: ```js from(bucket: "example-bucket") |> range(start: -5m) |> timeShift(duration: 12h) ``` Shift backward in time: ```js from(bucket: "example-bucket") |> range(start: -5m) |> timeShift(duration: -12h) ``` #### Related * [now() function](/flux/v0/stdlib/universe/now/) * [system.time() function](/flux/v0/stdlib/system/time/) * [time() function](/flux/v0/stdlib/universe/time/) * [uint() function](/flux/v0/stdlib/universe/uint/) * [int() function](/flux/v0/stdlib/universe/int/) * [truncateTimeColumn() function](/flux/v0/stdlib/universe/truncatetimecolumn/) * [date.truncate() function](/flux/v0/stdlib/date/truncate/) * [date.add() function](/flux/v0/stdlib/date/add/) * [date.sub() function](/flux/v0/stdlib/date/sub/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:49Z | 2.0 | | 2020-01-01T00:01:01Z | 1.9 | | 2020-01-01T00:03:22Z | 1.8 | | 2020-01-01T00:04:04Z | 1.9 | | 2020-01-01T00:05:38Z | 2.1 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 2.0 | | 2020-01-01T00:01:00Z | 1.9 | | 2020-01-01T00:03:00Z | 1.8 | | 2020-01-01T00:04:00Z | 1.9 | | 2020-01-01T00:05:00Z | 2.1 | --- # Find percentile and quantile values Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/percentile-quantile/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`quantile()` function](/flux/v0/stdlib/universe/quantile/)to return a value representing the `q` quantile or percentile of input data. ## Percentile versus quantile Percentiles and quantiles are very similar, differing only in the number used to calculate return values. A percentile is calculated using numbers between `0` and `100`. A quantile is calculated using numbers between `0.0` and `1.0`. For example, the **`0.5` quantile** is the same as the **50th percentile**. ## Select a method for calculating the quantile Select one of the following methods to calculate the quantile: * [estimate\_tdigest](#estimate_tdigest) * [exact\_mean](#exact_mean) * [exact\_selector](#exact_selector) ### estimate\_tdigest **(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest)to compute a quantile estimate on large data sources. Output tables consist of a single row containing the calculated quantile. If calculating the `0.5` quantile or 50th percentile: **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`estimate_tdigest` returns:** |\_value| |-------| | 1.5 | ### exact\_mean An aggregate method that takes the average of the two points closest to the quantile value. Output tables consist of a single row containing the calculated quantile. If calculating the `0.5` quantile or 50th percentile: **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`exact_mean` returns:** |\_value| |-------| | 1.5 | ### exact\_selector A selector method that returns the data point for which at least `q` points are less than. Output tables consist of a single row containing the calculated quantile. If calculating the `0.5` quantile or 50th percentile: **Given the following input table:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:01:00Z| 1.0 | |2020-01-01T00:02:00Z| 1.0 | |2020-01-01T00:03:00Z| 2.0 | |2020-01-01T00:04:00Z| 3.0 | **`exact_selector` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:02:00Z| 1.0 | > [!Note] > The examples below use the [example data variable](/influxdb/v2/query-data/flux/#example-data-variable). ## Find the value representing the 99th percentile Use the default method, `"estimate_tdigest"`, to return all rows in a table that contain values in the 99th percentile of data in the table. ```js data |> quantile(q: 0.99) ``` ## Find the average of values closest to the quantile Use the `exact_mean` method to return a single row per input table containing the average of the two values closest to the mathematical quantile of data in the table. For example, to calculate the `0.99` quantile: ```js data |> quantile(q: 0.99, method: "exact_mean") ``` ## Find the point with the quantile value Use the `exact_selector` method to return a single row per input table containing the value that `q * 100`% of values in the table are less than. For example, to calculate the `0.99` quantile: ```js data |> quantile(q: 0.99, method: "exact_selector") ``` ## Use quantile() with aggregateWindow() [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)segments data into windows of time, aggregates data in each window into a single point, and then removes the time-based segmentation. It is primarily used to [downsample data](/influxdb/v2/process-data/common-tasks/downsample-data/). To specify the [quantile calculation method](#select-a-method-for-calculating-the-quantile) in`aggregateWindow()`, use the [full function syntax](/flux/v0/stdlib/universe/aggregatewindow/#specify-parameters-of-the-aggregate-function): ```js data |> aggregateWindow( every: 5m, fn: (tables=<-, column) => tables |> quantile(q: 0.99, method: "exact_selector"), ) ``` #### Related * [quantile() function](/flux/v0/stdlib/universe/quantile/) [query](/influxdb/v2/tags/query/)[percentile](/influxdb/v2/tags/percentile/)[quantile](/influxdb/v2/tags/quantile/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 1.5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _value | | --- | | _value | | 1.5 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:01:00Z | 1.0 | | 2020-01-01T00:02:00Z | 1.0 | | 2020-01-01T00:03:00Z | 2.0 | | 2020-01-01T00:04:00Z | 3.0 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:02:00Z | 1.0 | --- # Query fields and tags Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/query-fields/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`filter()`](/flux/v0/stdlib/universe/filter/)to query data based on fields, tags, or any other column value.`filter()` performs operations similar to the `SELECT` statement and the `WHERE`clause in InfluxQL and other SQL-like query languages. ## The filter() function `filter()` has an `fn` parameter that expects a [predicate function](/influxdb/v2/reference/glossary/#predicate-function), an anonymous function comprised of one or more [predicate expressions](/influxdb/v2/reference/glossary/#predicate-expression). The predicate function evaluates each input row. Rows that evaluate to `true` are **included** in the output data. Rows that evaluate to `false` are **excluded** from the output data. ```js // ... |> filter(fn: (r) => r._measurement == "example-measurement-name" ) ``` The `fn` predicate function requires an `r` argument, which represents each row as `filter()` iterates over input data. Key-value pairs in the row record represent columns and their values. Use [dot notation or bracket notation](/flux/v0/data-types/composite/record/#reference-values-in-a-record)to reference specific column values in the predicate function. Use [logical operators](/flux/v0/spec/operators/#logical-operators)to chain multiple predicate expressions together. ```js // Row record r = {foo: "bar", baz: "quz"} // Example predicate function (r) => r.foo == "bar" and r["baz"] == "quz" // Evaluation results (r) => true and true ``` ## Filter by fields and tags The combination of [`from()`](/flux/v0/stdlib/influxdata/influxdb/from),[`range()`](/flux/v0/stdlib/universe/range), and `filter()` represent the most basic Flux query: 1. Use `from()` to define your [bucket](/influxdb/v2/reference/glossary/#bucket). 2. Use `range()` to limit query results by time. 3. Use `filter()` to identify what rows of data to output. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement-name" and r.mytagname == "example-tag-value") |> filter(fn: (r) => r._field == "example-field-name") ``` #### Related * [filter() function](/flux/v0/stdlib/universe/filter/) * [Query using conditional logic](/influxdb/v2/query-data/flux/conditional-logic/) * [Use regular expressions in Flux](/influxdb/v2/query-data/flux/regular-expressions/) [query](/influxdb/v2/tags/query/)[select](/influxdb/v2/tags/select/)[where](/influxdb/v2/tags/where/) --- # Calculate the rate of change Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/rate/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`derivative()`](/flux/v0/stdlib/universe/derivative/)to calculate the rate of change between subsequent values or[`aggregate.rate()`](/flux/v0/stdlib/experimental/aggregate/rate/)to calculate the average rate of change per window of time. If time between points varies, these functions normalize points to a common time interval making values easily comparable. * [Rate of change between subsequent values](#rate-of-change-between-subsequent-values) * [Average rate of change per window of time](#average-rate-of-change-per-window-of-time) ## Rate of change between subsequent values Use the [`derivative()` function](/flux/v0/stdlib/universe/derivative/)to calculate the rate of change per unit of time between subsequent *non-null* values. ```js data |> derivative(unit: 1s) ``` By default, `derivative()` returns only positive derivative values and replaces negative values with *null*. Calculated values are returned as [floats](/flux/v0/spec/types/#numeric-types). **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | **`derivative(unit: 1m)` returns:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:04:00Z| | |2020-01-01T00:12:00Z| | |2020-01-01T00:19:00Z| 10.0 | |2020-01-01T00:32:00Z| | |2020-01-01T00:51:00Z| 4.74 | |2020-01-01T01:00:00Z| 5.56 | Results represent the rate of change **per minute** between subsequent values with negative values set to *null*. ### Return negative derivative values To return negative derivative values, set the `nonNegative` parameter to `false`, **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | **The following returns:** ```js |> derivative(unit: 1m, nonNegative: false) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:04:00Z|\-22.5 | |2020-01-01T00:12:00Z|\-1.25 | |2020-01-01T00:19:00Z| 10.0 | |2020-01-01T00:32:00Z|\-1.54 | |2020-01-01T00:51:00Z| 4.74 | |2020-01-01T01:00:00Z| 5.56 | Results represent the rate of change **per minute** between subsequent values and include negative values. ## Average rate of change per window of time Use the [`aggregate.rate()` function](/flux/v0/stdlib/experimental/aggregate/rate/)to calculate the average rate of change per window of time. ```js import "experimental/aggregate" data |> aggregate.rate( every: 1m, unit: 1s, groupColumns: ["tag1", "tag2"], ) ``` `aggregate.rate()` returns the average rate of change (as a [float](/flux/v0/spec/types/#numeric-types)) per `unit` for time intervals defined by `every`. Negative values are replaced with *null*. > [!Note] > `aggregate.rate()` does not support `nonNegative: false`. **Given the following input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 250 | |2020-01-01T00:04:00Z| 160 | |2020-01-01T00:12:00Z| 150 | |2020-01-01T00:19:00Z| 220 | |2020-01-01T00:32:00Z| 200 | |2020-01-01T00:51:00Z| 290 | |2020-01-01T01:00:00Z| 340 | **The following returns:** ```js |> aggregate.rate( every: 20m, unit: 1m, ) ``` | \_time |\_value| |--------------------|-------| |2020-01-01T00:20:00Z| 10.00 | |2020-01-01T00:40:00Z| | |2020-01-01T01:00:00Z| 4.74 | |2020-01-01T01:20:00Z| 5.56 | Results represent the **average change rate per minute** of every **20 minute interval**with negative values set to *null*. Timestamps represent the right bound of the time window used to average values. #### Related * [derivative() function](/flux/v0/stdlib/universe/derivative/) * [aggregate.rate() function](/flux/v0/stdlib/experimental/aggregate/rate/) [query](/influxdb/v2/tags/query/)[rate](/influxdb/v2/tags/rate/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:04:00Z | | | 2020-01-01T00:12:00Z | | | 2020-01-01T00:19:00Z | 10.0 | | 2020-01-01T00:32:00Z | | | 2020-01-01T00:51:00Z | 4.74 | | 2020-01-01T01:00:00Z | 5.56 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:04:00Z | -22.5 | | 2020-01-01T00:12:00Z | -1.25 | | 2020-01-01T00:19:00Z | 10.0 | | 2020-01-01T00:32:00Z | -1.54 | | 2020-01-01T00:51:00Z | 4.74 | | 2020-01-01T01:00:00Z | 5.56 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 250 | | 2020-01-01T00:04:00Z | 160 | | 2020-01-01T00:12:00Z | 150 | | 2020-01-01T00:19:00Z | 220 | | 2020-01-01T00:32:00Z | 200 | | 2020-01-01T00:51:00Z | 290 | | 2020-01-01T01:00:00Z | 340 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:20:00Z | 10.00 | | 2020-01-01T00:40:00Z | | | 2020-01-01T01:00:00Z | 4.74 | | 2020-01-01T01:20:00Z | 5.56 | --- # Use regular expressions in Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/regular-expressions/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Regular expressions (regexes) are incredibly powerful when matching patterns in large collections of data. With Flux, regular expressions are primarily used for evaluation logic in predicate functions for things such as filtering rows, dropping and keeping columns, state detection, etc. This guide shows how to use regular expressions in your Flux scripts. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Go regular expression syntax Flux uses Go’s [regexp package](https://golang.org/pkg/regexp/) for regular expression search. The links [below](#helpful-links) provide information about Go’s regular expression syntax. ## Regular expression operators Flux provides two comparison operators for use with regular expressions. #### `=~` When the expression on the left **MATCHES** the regular expression on the right, this evaluates to `true`. #### `!~` When the expression on the left **DOES NOT MATCH** the regular expression on the right, this evaluates to `true`. ## Regular expressions in Flux When using regex matching in your Flux scripts, enclose your regular expressions with `/`. The following is the basic regex comparison syntax: ###### Basic regex comparison syntax ```js expression =~ /regex/ expression !~ /regex/ ``` ## Examples ### Use a regex to filter by tag value The following example filters records by the `cpu` tag. It only keeps records for which the `cpu` is either `cpu0`, `cpu1`, or `cpu2`. ```js from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "cpu" and r.cpu =~ /cpu[0-2]$/) ``` ### Use a regex to filter by field key The following example excludes records that do not have `_percent` in a field key. ```js from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "mem" and r._field =~ /_percent/) ``` ### Drop columns matching a regex The following example drops columns whose names do not begin with `_`. ```js from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "mem") |> drop(fn: (column) => column !~ /^_.*/) ``` ## Helpful links ##### Syntax documentation [regexp Syntax GoDoc](https://godoc.org/regexp/syntax) [RE2 Syntax Overview](https://github.com/google/re2/wiki/Syntax) ##### Go regex testers [Regex Tester - Golang](https://regex-golang.appspot.com/assets/html/index.html) [Regex101](https://regex101.com/) #### Related * [Query fields and tags](/influxdb/v2/query-data/flux/query-fields/) * [regexp package](/flux/v0/stdlib/regexp/) [regex](/influxdb/v2/tags/regex/) --- # Extract scalar values in Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/scalar-values/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use Flux [dynamic query functions](/flux/v0/function-types/#dynamic-queries)to extract scalar values from Flux query output. This lets you, for example, dynamically set variables using query results. **To extract scalar values from output:** 1. [Extract a column from the input stream](#extract-a-column)***or*** [extract a row from the input stream](#extract-a-row). 2. Use the returned array or record to reference scalar values. *The samples on this page use the [sample data provided below](#sample-data).* > [!Note] > #### Output scalar values > > The InfluxDB `/api/v2/query` HTTP API endpoint and all clients that use it > (InfluxDB UI, `influx` CLI, etc.) only support queries that return a stream of tables. > This endpoint does not support raw scalar output. > > To output a scalar value as part of a stream of tables: > > 1. Import the [`array` package](/flux/v0/stdlib/array/from/). > 2. Use [`array.from()`](/flux/v0/stdlib/array/from/) and[`display()`](/flux/v0/stdlib/universe/display/) to wrap the > literal representation of a scalar value in a stream of tables and return it > as output. > > [](#view-example) > > View example > > ``` > import "array" > > SFOTemps = > sampleData > |> findColumn( > fn: (key) => key._field == "temp" and key.location == "sfo", > column: "_value", > ) > > array.from(rows: [{ output: display(v: SFOTemps) }]) > ``` > > ##### Returns > > | output | > |--------------------------| > |[ 65.1, 66.2, 66.3, 66.8 ]| ## Table extraction Flux formats query results as a stream of tables. Both [`findColumn()`](/flux/v0/stdlib/universe/findcolumn/)and [`findRecord()`](/flux/v0/stdlib/universe/findrecord/)extract the first table in a stream of tables whose [group key](/flux/v0/get-started/data-model/#group-key)values match the `fn` [predicate function](/flux/v0/get-started/syntax-basics/#predicate-functions). > [!Note] > #### Extract the correct table > > Flux functions do not guarantee table order.`findColumn()` and `findRecord()` extract only the **first** table that matches the `fn` predicate. > To extract the correct table, use the `fn` predicate function to specifically identify the table to extract or > filter and transform your data to minimize the number of tables piped-forward into the functions. ## Extract a column Use the [`findColumn()` function](/flux/v0/stdlib/universe/findcolumn/)to output an array of values from a specific column in the extracted table. *See [Sample data](#sample-data) below.* ``` sampleData |> findColumn( fn: (key) => key._field == "temp" and key.location == "sfo", column: "_value", ) // Returns [65.1, 66.2, 66.3, 66.8] ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ### Use extracted column values Use a variable to store the array of values. In the example below, `SFOTemps` represents the array of values. Reference a specific index (integer starting from `0`) in the array to return the value at that index. *See [Sample data](#sample-data) below.* ``` SFOTemps = sampleData |> findColumn( fn: (key) => key._field == "temp" and key.location == "sfo", column: "_value", ) SFOTemps // Returns [65.1, 66.2, 66.3, 66.8] SFOTemps[0] // Returns 65.1 SFOTemps[2] // Returns 66.3 ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ## Extract a row Use the [`findRecord()` function](/flux/v0/stdlib/universe/findrecord/)to output data from a single row in the extracted table. Specify the index of the row to output using the `idx` parameter. The function outputs a record with key-value pairs for each column. ``` sampleData |> findRecord( fn: (key) => key._field == "temp" and key.location == "sfo", idx: 0, ) // Returns { // _time:2019-11-11T12:00:00Z, // _field:"temp", // location:"sfo", // _value: 65.1 // } ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ### Use an extracted row record Use a variable to store the extracted row record. In the example below, `tempInfo` represents the extracted row. Use [dot or bracket notation](/flux/v0/data-types/composite/record/#dot-notation)to reference keys in the record. ``` tempInfo = sampleData |> findRecord( fn: (key) => key._field == "temp" and key.location == "sfo", idx: 0, ) tempInfo // Returns { // _time:2019-11-11T12:00:00Z, // _field:"temp", // location:"sfo", // _value: 65.1 // } tempInfo._time // Returns 2019-11-11T12:00:00Z tempInfo.location // Returns sfo ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ## Example helper functions Create custom helper functions to extract scalar values from query output. ##### Extract a scalar field value ``` // Define a helper function to extract field values getFieldValue = (tables=<-, field) => { extract = tables |> findColumn(fn: (key) => key._field == field, column: "_value") return extract[0] } // Use the helper function to define a variable lastJFKTemp = sampleData |> filter(fn: (r) => r.location == "kjfk") |> last() |> getFieldValue(field: "temp") lastJFKTemp // Returns 71.2 ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ##### Extract scalar row data ``` // Define a helper function to extract a row as a record getRow = (tables=<-, field, idx=0) => { extract = tables |> findRecord(fn: (key) => true, idx: idx) return extract } // Use the helper function to define a variable lastReported = sampleData |> last() |> getRow(field: "temp") "The last location to report was ${lastReported.location}. The temperature was ${string(v: lastReported._value)}°F." // Returns: // The last location to report was kord. // The temperature was 38.9°F. ``` To return this value from the InfluxDB query API, InfluxDB UI, or influx CLI see[Output scalar values](#output-scalar-values). ## Sample data The following sample data set represents fictional temperature metrics collected from three locations. It’s formatted as an array of Flux [records](/flux/v0/data-types/composite/record/)and structured as a stream of stables using [`array.from()` function](/flux/v0/stdlib/array/from/). Place the following at the beginning of your query to use the sample data: ```js import "array" sampleData = array.from( rows: [ {_time: 2019-11-01T12:00:00Z, location: "sfo", _field: "temp", _value: 65.1}, {_time: 2019-11-01T13:00:00Z, location: "sfo", _field: "temp", _value: 66.2}, {_time: 2019-11-01T14:00:00Z, location: "sfo", _field: "temp", _value: 66.3}, {_time: 2019-11-01T15:00:00Z, location: "sfo", _field: "temp", _value: 66.8}, {_time: 2019-11-01T12:00:00Z, location: "kjfk", _field: "temp", _value: 69.4}, {_time: 2019-11-01T13:00:00Z, location: "kjfk", _field: "temp", _value: 69.9}, {_time: 2019-11-01T14:00:00Z, location: "kjfk", _field: "temp", _value: 71.0}, {_time: 2019-11-01T15:00:00Z, location: "kjfk", _field: "temp", _value: 71.2}, {_time: 2019-11-01T12:00:00Z, location: "kord", _field: "temp", _value: 46.4}, {_time: 2019-11-01T13:00:00Z, location: "kord", _field: "temp", _value: 46.3}, {_time: 2019-11-01T14:00:00Z, location: "kord", _field: "temp", _value: 42.7}, {_time: 2019-11-01T15:00:00Z, location: "kord", _field: "temp", _value: 38.9}, ], ) |> group(columns: ["location", "_field"]) ``` #### Related * [Flux dynamic query functions](/flux/v0/function-types/#dynamic-queries) [scalar](/influxdb/v2/tags/scalar/) | output | | --- | | output | | [ 65.1, 66.2, 66.3, 66.8 ] | --- # Sort and limit data with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/sort-limit/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [`sort()`](/flux/v0/stdlib/universe/sort)to order records within each table by specific columns and[`limit()`](/flux/v0/stdlib/universe/limit)to limit the number of records in output tables to a fixed number, `n`. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ##### Example sorting system uptime The following example orders system uptime first by region, then host, then value. ```js from(bucket: "example-bucket") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime") |> sort(columns: ["region", "host", "_value"]) ``` The [`limit()` function](/flux/v0/stdlib/universe/limit)limits the number of records in output tables to a fixed number, `n`. The following example shows up to 10 records from the past hour. ```js from(bucket:"example-bucket") |> range(start:-1h) |> limit(n:10) ``` You can use `sort()` and `limit()` together to show the top N records. The example below returns the 10 top system uptime values sorted first by region, then host, then value. ```js from(bucket: "example-bucket") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime") |> sort(columns: ["region", "host", "_value"]) |> limit(n: 10) ``` You now have created a Flux query that sorts and limits data. Flux also provides the [`top()`](/flux/v0/stdlib/universe/top)and [`bottom()`](/flux/v0/stdlib/universe/bottom)functions to perform both of these functions at the same time. #### Related * [sort() function](/flux/v0/stdlib/universe/sort/) * [limit() function](/flux/v0/stdlib/universe/limit/) [sort](/influxdb/v2/tags/sort/)[limit](/influxdb/v2/tags/limit/) --- # Query SQL data sources Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/sql/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The [Flux](/influxdb/v2/reference/flux) `sql` package provides functions for working with SQL data sources.[`sql.from()`](/flux/v0/stdlib/sql/from/) lets you query SQL data sources like [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/),[Snowflake](https://www.snowflake.com/), [SQLite](https://www.sqlite.org/index.html),[Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/default.aspx),[Amazon Athena](https://aws.amazon.com/athena/) and [Google BigQuery](https://cloud.google.com/bigquery)and use the results with InfluxDB dashboards, tasks, and other operations. * [Query a SQL data source](#query-a-sql-data-source) * [Join SQL data with data in InfluxDB](#join-sql-data-with-data-in-influxdb) * [Use SQL results to populate dashboard variables](#use-sql-results-to-populate-dashboard-variables) * [Use secrets to store SQL database credentials](#use-secrets-to-store-sql-database-credentials) * [Sample sensor data](#sample-sensor-data) If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Query a SQL data source To query a SQL data source: 1. Import the `sql` package in your Flux query 2. Use the `sql.from()` function to specify the driver, data source name (DSN), and query used to query data from your SQL data source: [PostgreSQL](#postgresql)[MySQL](#mysql)[Snowflake](#snowflake)[SQLite](#sqlite)[SQL Server](#sql-server)[Athena](#athena)[BigQuery](#bigquery) ```js import "sql" sql.from( driverName: "postgres", dataSourceName: "postgresql://user:password@localhost", query: "SELECT * FROM example_table", ) ``` ```js import "sql" sql.from( driverName: "mysql", dataSourceName: "user:password@tcp(localhost:3306)/db", query: "SELECT * FROM example_table", ) ``` ```js import "sql" sql.from( driverName: "snowflake", dataSourceName: "user:password@account/db/exampleschema?warehouse=wh", query: "SELECT * FROM example_table", ) ``` ```js // NOTE: InfluxDB OSS and InfluxDB Cloud do not have access to // the local filesystem and cannot query SQLite data sources. // Use the Flux REPL to query an SQLite data source. import "sql" sql.from( driverName: "sqlite3", dataSourceName: "file:/path/to/test.db?cache=shared&mode=ro", query: "SELECT * FROM example_table", ) ``` ```js import "sql" sql.from( driverName: "sqlserver", dataSourceName: "sqlserver://user:password@localhost:1234?database=examplebdb", query: "GO SELECT * FROM Example.Table", ) ``` *For information about authenticating with SQL Server using ADO-style parameters, see [SQL Server ADO authentication](/flux/v0/stdlib/sql/from/#sql-server-ado-authentication).* ```js import "sql" sql.from( driverName: "awsathena", dataSourceName: "s3://myorgqueryresults/?accessID=12ab34cd56ef®ion=region-name&secretAccessKey=y0urSup3rs3crEtT0k3n", query: "GO SELECT * FROM Example.Table", ) ``` *For information about parameters to include in the Athena DSN, see [Athena connection string](/flux/v0/stdlib/sql/from/#athena-connection-string).* ```js import "sql" sql.from( driverName: "bigquery", dataSourceName: "bigquery://projectid/?apiKey=mySuP3r5ecR3tAP1K3y", query: "SELECT * FROM exampleTable", ) ``` *For information about authenticating with BigQuery, see[BigQuery authentication parameters](/flux/v0/stdlib/sql/from/#bigquery-authentication-parameters).* *See the [`sql.from()` documentation](/flux/v0/stdlib/sql/from/) for information about required function parameters.* ## Join SQL data with data in InfluxDB One of the primary benefits of querying SQL data sources from InfluxDB is the ability to enrich query results with data stored outside of InfluxDB. Using the [air sensor sample data](#sample-sensor-data) below, the following query joins air sensor metrics stored in InfluxDB with sensor information stored in PostgreSQL. The joined data lets you query and filter results based on sensor information that isn’t stored in InfluxDB. ```js // Import the "sql" package import "sql" // Query data from PostgreSQL sensorInfo = sql.from( driverName: "postgres", dataSourceName: "postgresql://localhost?sslmode=disable", query: "SELECT * FROM sensors", ) // Query data from InfluxDB sensorMetrics = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "airSensors") // Join InfluxDB query results with PostgreSQL query results join(tables: {metric: sensorMetrics, info: sensorInfo}, on: ["sensor_id"]) ``` ## Use SQL results to populate dashboard variables Use `sql.from()` to [create dashboard variables](/influxdb/v2/visualize-data/variables/create-variable/)from SQL query results. The following example uses the [air sensor sample data](#sample-sensor-data) below to create a variable that lets you select the location of a sensor. ```js import "sql" sql.from( driverName: "postgres", dataSourceName: "postgresql://localhost?sslmode=disable", query: "SELECT * FROM sensors", ) |> rename(columns: {location: "_value"}) |> keep(columns: ["_value"]) ``` Use the variable to manipulate queries in your dashboards. Dashboard variable from SQL query results ## Use secrets to store SQL database credentials If your SQL database requires authentication, use [InfluxDB secrets](/influxdb/v2/admin/secrets/)to store and populate connection credentials. By default, InfluxDB base64-encodes and stores secrets in its internal key-value store, BoltDB. For added security, [store secrets in Vault](/influxdb/v2/admin/secrets/use-vault/). ### Store your database credentials as secrets Use the [InfluxDB API](/influxdb/v2/reference/api/) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/secret/)to store your database credentials as secrets. [InfluxDB API](#influxdb-api)[influx CLI](#influx-cli) ```sh curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ --header 'Authorization: Token YOURAUTHTOKEN' \ --header 'Content-type: application/json' \ --data '{ "POSTGRES_HOST": "http://example.com", "POSTGRES_USER": "example-username", "POSTGRES_PASS": "example-password" }' ``` **To store secrets, you need:** * [your organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * [your API token](/influxdb/v2/admin/tokens/view-tokens/) ```sh # Syntax influx secret update -k # Example influx secret update -k POSTGRES_PASS ``` **When prompted, enter your secret value.** You can provide the secret value with the `-v`, `--value` flag, but the **plain text secret may appear in your shell history**. ```sh influx secret update -k -v ``` ### Use secrets in your query Import the `influxdata/influxdb/secrets` package and use [string interpolation](/flux/v0/spec/string-interpolation/)to populate connection credentials with stored secrets in your Flux query. ```js import "sql" import "influxdata/influxdb/secrets" POSTGRES_HOST = secrets.get(key: "POSTGRES_HOST") POSTGRES_USER = secrets.get(key: "POSTGRES_USER") POSTGRES_PASS = secrets.get(key: "POSTGRES_PASS") sql.from( driverName: "postgres", dataSourceName: "postgresql://${POSTGRES_USER}:${POSTGRES_PASS}@${POSTGRES_HOST}", query: "SELECT * FROM sensors", ) ``` ## Sample sensor data The [air sensor sample data](#download-sample-air-sensor-data) and[sample sensor information](#import-the-sample-sensor-information) simulate a group of sensors that measure temperature, humidity, and carbon monoxide in rooms throughout a building. Each collected data point is stored in InfluxDB with a `sensor_id` tag that identifies the specific sensor it came from. Sample sensor information is stored in PostgreSQL. **Sample data includes:** * Simulated data collected from each sensor and stored in the `airSensors` measurement in **InfluxDB**: * temperature * humidity * co * Information about each sensor stored in the `sensors` table in **PostgreSQL**: * sensor\_id * location * model\_number * last\_inspected #### Download sample air sensor data 1. [Create a bucket](/influxdb/v2/admin/buckets/create-bucket/) to store the data. 2. [Create an InfluxDB task](/influxdb/v2/process-data/manage-tasks/create-task/)and use the [`sample.data()` function](/flux/v0/stdlib/influxdata/influxdb/sample/data/)to download sample air sensor data every 15 minutes. Write the downloaded sample data to your new bucket: ``` import "influxdata/influxdb/sample" option task = {name: "Collect sample air sensor data", every: 15m} sample.data(set: "airSensor") |> to(org: "example-org", bucket: "example-bucket") ``` 3. [Query your target bucket](/influxdb/v2/query-data/execute-queries/) after the first task run to ensure the sample data is writing successfully. ``` from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._measurement == "airSensors") ``` #### Import the sample sensor information 1. [Download and install PostgreSQL](https://www.postgresql.org/download/). 2. Download the sample sensor information CSV. [Download sample sensor information](https://influx-testdata.s3.amazonaws.com/sample-sensor-info.csv) 3. Use a PostgreSQL client (`psql` or a GUI) to create the `sensors` table: ``` CREATE TABLE sensors ( sensor_id character varying(50), location character varying(50), model_number character varying(50), last_inspected date ); ``` 4. Import the downloaded CSV sample data.*Update the `FROM` file path to the path of the downloaded CSV sample data.* ``` COPY sensors(sensor_id,location,model_number,last_inspected) FROM '/path/to/sample-sensor-info.csv' DELIMITER ',' CSV HEADER; ``` 5. Query the table to ensure the data was imported correctly: ``` SELECT * FROM sensors; ``` #### Import the sample data dashboard Download and import the Air Sensors dashboard to visualize the generated data: [View Air Sensors dashboard JSON](https://raw.githubusercontent.com/influxdata/influxdb2-sample-data/master/air-sensor-data/air-sensors-dashboard.json) *For information about importing a dashboard, see [Create a dashboard](/influxdb/v2/visualize-data/dashboards/create-dashboard).* #### Related * [sql package](/flux/v0/stdlib/sql/) [query](/influxdb/v2/tags/query/)[flux](/influxdb/v2/tags/flux/)[sql](/influxdb/v2/tags/sql/) --- # Window and aggregate data with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/flux/window-aggregate/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A common operation performed with time series data is grouping data into windows of time, or “windowing” data, then aggregating windowed values into a new value. This guide walks through windowing and aggregating data with Flux and demonstrates how data is shaped in the process. If you’re just getting started with Flux queries, check out the following: * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. > [!Note] > The following example is an in-depth walk-through of the steps required to window and aggregate data. > The [`aggregateWindow()` function](#summing-up) performs these operations for you, but understanding > how data is shaped in the process helps to successfully create your desired output. ## Data set For the purposes of this guide, define a variable that represents your base data set. The following example queries the memory usage of the host machine. ```js dataSet = from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> drop(columns: ["host"]) ``` > [!Note] > This example drops the `host` column from the returned data since the memory data > is only tracked for a single host and it simplifies the output tables. > Dropping the `host` column is optional and not recommended if monitoring memory > on multiple hosts. `dataSet` can now be used to represent your base data, which will look similar to the following: ``` Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:00.000000000Z 71.11611366271973 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:10.000000000Z 67.39630699157715 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:20.000000000Z 64.16666507720947 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:30.000000000Z 64.19951915740967 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:40.000000000Z 64.2122745513916 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:50.000000000Z 64.22209739685059 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 64.6336555480957 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:10.000000000Z 64.16516304016113 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:20.000000000Z 64.18349742889404 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:30.000000000Z 64.20474052429199 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:40.000000000Z 68.65062713623047 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:50.000000000Z 67.20139980316162 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 70.9143877029419 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:10.000000000Z 64.14549350738525 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:20.000000000Z 64.15379047393799 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:30.000000000Z 64.1592264175415 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:40.000000000Z 64.18190002441406 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:50.000000000Z 64.28837776184082 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 64.29731845855713 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:10.000000000Z 64.36963081359863 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:20.000000000Z 64.37397003173828 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:30.000000000Z 64.44413661956787 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:40.000000000Z 64.42906856536865 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:50.000000000Z 64.44573402404785 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.48912620544434 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:10.000000000Z 64.49522972106934 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:20.000000000Z 64.48652744293213 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:30.000000000Z 64.49949741363525 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:40.000000000Z 64.4949197769165 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:50.000000000Z 64.49787616729736 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 ``` [](#) ## Windowing data Use the [`window()` function](/flux/v0/stdlib/universe/window)to group your data based on time bounds. The most common parameter passed with the `window()` is `every` which defines the duration of time between windows. Other parameters are available, but for this example, window the base data set into one minute windows. ```js dataSet |> window(every: 1m) ``` > [!Note] > The `every` parameter supports all [valid duration units](/flux/v0/spec/types/#duration-types), > including **calendar months (`1mo`)** and **years (`1y`)**. Each window of time is output in its own table containing all records that fall within the window. ###### window() output tables ``` Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:00.000000000Z 71.11611366271973 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:10.000000000Z 67.39630699157715 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:20.000000000Z 64.16666507720947 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:30.000000000Z 64.19951915740967 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:40.000000000Z 64.2122745513916 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:50.000000000Z 64.22209739685059 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 64.6336555480957 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:10.000000000Z 64.16516304016113 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:20.000000000Z 64.18349742889404 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:30.000000000Z 64.20474052429199 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:40.000000000Z 68.65062713623047 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:50.000000000Z 67.20139980316162 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 70.9143877029419 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:10.000000000Z 64.14549350738525 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:20.000000000Z 64.15379047393799 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:30.000000000Z 64.1592264175415 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:40.000000000Z 64.18190002441406 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:50.000000000Z 64.28837776184082 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 64.29731845855713 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:10.000000000Z 64.36963081359863 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:20.000000000Z 64.37397003173828 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:30.000000000Z 64.44413661956787 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:40.000000000Z 64.42906856536865 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:50.000000000Z 64.44573402404785 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.48912620544434 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:10.000000000Z 64.49522972106934 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:20.000000000Z 64.48652744293213 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:30.000000000Z 64.49949741363525 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:40.000000000Z 64.4949197769165 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:50.000000000Z 64.49787616729736 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 ``` [](#) When visualized in the InfluxDB UI, each window table is displayed in a different color. ![Windowed data](/img/flux/simple-windowed-data.png) ## Aggregate data [Aggregate functions](/flux/v0/function-types#aggregates) take the values of all rows in a table and use them to perform an aggregate operation. The result is output as a new value in a single-row table. Since windowed data is split into separate tables, aggregate operations run against each table separately and output new tables containing only the aggregated value. For this example, use the [`mean()` function](/flux/v0/stdlib/universe/mean)to output the average of each window: ```js dataSet |> window(every: 1m) |> mean() ``` ###### mean() output tables ``` Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 65.88549613952637 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 65.50651391347249 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 65.30719598134358 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 64.39330975214641 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 64.49386278788249 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- 2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 64.49816226959229 ``` [](#) Because each data point is contained in its own table, when visualized, they appear as single, unconnected points. ![Aggregated windowed data](/img/flux/simple-windowed-aggregate-data.png) ### Recreate the time column **Notice the `_time` column is not in the [aggregated output tables](#mean-output-tables).**Because records in each table are aggregated together, their timestamps no longer apply and the column is removed from the group key and table. Also notice the `_start` and `_stop` columns still exist. These represent the lower and upper bounds of the time window. Many Flux functions rely on the `_time` column. To further process your data after an aggregate function, you need to re-add `_time`. Use the [`duplicate()` function](/flux/v0/stdlib/universe/duplicate) to duplicate either the `_start` or `_stop` column as a new `_time` column. ```js dataSet |> window(every: 1m) |> mean() |> duplicate(column: "_stop", as: "_time") ``` ###### duplicate() output tables ``` Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 65.88549613952637 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 65.50651391347249 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 65.30719598134358 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.39330975214641 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49386278788249 Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 ``` [](#) ## “Unwindow” aggregate tables Keeping aggregate values in separate tables generally isn’t the format in which you want your data. Use the `window()` function to “unwindow” your data into a single infinite (`inf`) window. ```js dataSet |> window(every: 1m) |> mean() |> duplicate(column: "_stop", as: "_time") |> window(every: inf) ``` > [!Note] > Windowing requires a `_time` column which is why it’s necessary to[recreate the `_time` column](#recreate-the-time-column) after an aggregation. ###### Unwindowed output table ``` Table: keys: [_start, _stop, _field, _measurement] _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 65.88549613952637 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 65.50651391347249 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 65.30719598134358 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.39330975214641 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49386278788249 2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 ``` With the aggregate values in a single table, data points in the visualization are connected. ![Unwindowed aggregate data](/img/flux/simple-unwindowed-data.png) ## Summing up You have now created a Flux query that windows and aggregates data. The data transformation process outlined in this guide should be used for all aggregation operations. Flux also provides the [`aggregateWindow()` function](/flux/v0/stdlib/universe/aggregatewindow)which performs all these separate functions for you. The following Flux query will return the same results: ###### aggregateWindow function ```js dataSet |> aggregateWindow(every: 1m, fn: mean) ``` #### Related * [aggregateWindow() function](/flux/v0/stdlib/universe/aggregatewindow/) * [window() function](/flux/v0/stdlib/universe/window/) * [Flux aggregate functions](/flux/v0/function-types/#aggregates) * [Flux selector functions](/flux/v0/function-types/#selectors) [flux](/influxdb/v2/tags/flux/)[aggregates](/influxdb/v2/tags/aggregates/) --- # Get started with Flux and InfluxDB Source: https://docs.influxdata.com/influxdb/v2/query-data/get-started/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux is InfluxData’s functional data scripting language designed for querying, analyzing, and acting on data. These guides walks through important concepts related to Flux and querying time series data from InfluxDB using Flux. ## Tools for working with Flux The [Execute queries](/influxdb/v2/query-data/execute-queries) guide walks through the different tools available for querying InfluxDB with Flux. ## Before you start To get a basic understanding of the Flux data model and syntax, see[Get started with Flux](/flux/v0/get-started/) in the[Flux documentation](/flux/v0/). [Query InfluxDB with Flux](/influxdb/v2/query-data/get-started/query-influxdb/) #### Related * [Get started with Flux](/flux/v0/get-started/) * [Flux documentation](/flux/v0/) * [Flux standard library](/flux/v0/stdlib/) [query](/influxdb/v2/tags/query/)[flux](/influxdb/v2/tags/flux/)[get-started](/influxdb/v2/tags/get-started/) --- # Query InfluxDB with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/get-started/query-influxdb/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). This guide walks through the basics of using Flux to query data from InfluxDB. Every Flux query needs the following: 1. [A data source](#1-define-your-data-source) 2. [A time range](#2-specify-a-time-range) 3. [Data filters](#3-filter-your-data) ## 1. Define your data source Flux’s [`from()`](/flux/v0/stdlib/influxdata/influxdb/from/) function defines an InfluxDB data source. It requires a [`bucket`](/flux/v0/stdlib/influxdata/influxdb/from/#bucket) parameter. The following examples use `example-bucket` as the bucket name. ```js from(bucket:"example-bucket") ``` ## 2. Specify a time range Flux requires a time range when querying time series data. “Unbounded” queries are very resource-intensive and as a protective measure, Flux will not query the database without a specified range. Use the [pipe-forward operator](/flux/v0/get-started/syntax-basics/#pipe-forward-operator)(`|>`) to pipe data from your data source into[`range()`](/flux/v0/stdlib/universe/range), which specifies a time range for your query. It accepts two parameters: `start` and `stop`. Start and stop values can be **relative** using negative [durations](/flux/v0/data-types/basic/duration/)or **absolute** using [timestamps](/flux/v0/data-types/basic/time/). ###### Example relative time ranges ```js // Relative time range with start only. Stop defaults to now. from(bucket:"example-bucket") |> range(start: -1h) // Relative time range with start and stop from(bucket:"example-bucket") |> range(start: -1h, stop: -10m) ``` > [!Note] > Relative ranges are relative to “now.” ###### Example absolute time range ```js from(bucket:"example-bucket") |> range(start: 2021-01-01T00:00:00Z, stop: 2021-01-01T12:00:00Z) ``` #### Use the following: For this guide, use the relative time range, `-15m`, to limit query results to data from the last 15 minutes: ```js from(bucket:"example-bucket") |> range(start: -15m) ``` ## 3. Filter your data Pass your ranged data into `filter()` to narrow results based on data attributes or columns.`filter()` has one parameter, `fn`, which expects a[predicate function](/flux/v0/get-started/syntax-basics/#predicate-functions)evaluates rows by column values. `filter()` iterates over every input row and structures row data as a Flux[record](/flux/v0/data-types/composite/record/). The record is passed into the predicate function as `r` where it is evaluated using[predicate expressions](/flux/v0/get-started/syntax-basics/#predicate-expressions). Rows that evaluate to `false` are dropped from the output data. Rows that evaluate to `true` persist in the output data. ```js // Pattern (r) => (r.recordProperty comparisonOperator comparisonExpression) // Example with single filter (r) => (r._measurement == "cpu") // Example with multiple filters (r) => (r._measurement == "cpu" and r._field != "usage_system") ``` #### Use the following: For this example, filter by the `cpu` measurement, `usage_system` field, and`cpu-total` tag value: ```js from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") ``` ## 4. Yield your queried data [`yield()`](/flux/v0/stdlib/universe/yield/) outputs the result of the query. ```js from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> yield() ``` Flux automatically assumes a `yield()` function at the end of each script to output and visualize the data. Explicitly calling `yield()` is only necessary when including multiple queries in the same Flux query. Each set of returned data needs to be named using the `yield()` function. ## Congratulations! You have now queried data from InfluxDB using Flux. The query shown here is a basic example. Flux queries can be extended in many ways to form powerful scripts. [Get started with Flux and InfluxDB](/influxdb/v2/query-data/get-started/)[Transform data with Flux](/influxdb/v2/query-data/get-started/transform-data/) #### Related * [Flux query basics](/flux/v0/get-started/query-basics/) * [Query data with Flux](/influxdb/v2/query-data/flux/) * [from() function](/flux/v0/stdlib/influxdata/influxdb/from/) * [range() function](/flux/v0/stdlib/universe/range/) * [filter() function](/flux/v0/stdlib/universe/filter/) [query](/influxdb/v2/tags/query/)[flux](/influxdb/v2/tags/flux/) --- # Transform data with Flux Source: https://docs.influxdata.com/influxdb/v2/query-data/get-started/transform-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). When [querying data from InfluxDB](/influxdb/v2/query-data/get-started/query-influxdb), you often need to transform that data in some way. Common examples are aggregating data, downsampling data, etc. This guide demonstrates using [Flux functions](/flux/v0/stdlib/) to transform your data. It walks through creating a Flux script that partitions data into windows of time, averages the `_value`s in each window, and outputs the averages as a new table. > [!Note] > If you’re not familiar with how Flux structures and operates on data, see[Flux data model](/flux/v0/get-started/data-model/). ## Query data Use the query built in the previous [Query data from InfluxDB](/influxdb/v2/query-data/get-started/query-influxdb)guide, but update the range to pull data from the last hour: ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") ``` ## Flux functions Flux provides a number of functions that perform specific operations, transformations, and tasks. You can also [create custom functions](/influxdb/v2/query-data/flux/custom-functions) in your Flux queries.*Functions are covered in detail in the [Flux standard library](/flux/v0/stdlib/) documentation.* A common type of function used when transforming data queried from InfluxDB is an aggregate function. Aggregate functions take a set of `_value`s in a table, aggregate them, and transform them into a new value. This example uses the [`mean()` function](/flux/v0/stdlib/universe/mean)to average values within each time window. > [!Note] > The following example walks through the steps required to window and aggregate data, > but there is a [`aggregateWindow()` helper function](#helper-functions) that does it for you. > It’s just good to understand the steps in the process. ## Window your data Flux’s [`window()` function](/flux/v0/stdlib/universe/window) partitions records based on a time value. Use the `every` parameter to define a duration of each window. > [!Note] > #### Calendar months and years > > `every` supports all [valid duration units](/flux/v0/spec/types/#duration-types), > including **calendar months (`1mo`)** and **years (`1y`)**. For this example, window data in five minute intervals (`5m`). ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> window(every: 5m) ``` As data is gathered into windows of time, each window is output as its own table. When visualized, each table is assigned a unique color. ![Windowed data tables](/img/flux/windowed-data.png) ## Aggregate windowed data Flux aggregate functions take the `_value`s in each table and aggregate them in some way. Use the [`mean()` function](/flux/v0/stdlib/universe/mean) to average the `_value`s of each table. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> window(every: 5m) |> mean() ``` As rows in each window are aggregated, their output table contains only a single row with the aggregate value. Windowed tables are all still separate and, when visualized, will appear as single, unconnected points. ![Windowed aggregate data](/img/flux/windowed-aggregates.png) ## Add times to your aggregates As values are aggregated, the resulting tables do not have a `_time` column because the records used for the aggregation all have different timestamps. Aggregate functions don’t infer what time should be used for the aggregate value. Therefore the `_time` column is dropped. A `_time` column is required in the [next operation](#unwindow-aggregate-tables). To add one, use the [`duplicate()` function](/flux/v0/stdlib/universe/duplicate)to duplicate the `_stop` column as the `_time` column for each windowed table. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> window(every: 5m) |> mean() |> duplicate(column: "_stop", as: "_time") ``` ## Unwindow aggregate tables Use the `window()` function with the `every: inf` parameter to gather all points into a single, infinite window. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> window(every: 5m) |> mean() |> duplicate(column: "_stop", as: "_time") |> window(every: inf) ``` Once ungrouped and combined into a single table, the aggregate data points will appear connected in your visualization. ![Unwindowed aggregate data](/img/flux/windowed-aggregates-ungrouped.png) ## Helper functions This may seem like a lot of coding just to build a query that aggregates data, however going through the process helps to understand how data changes “shape” as it is passed through each function. Flux provides (and allows you to create) “helper” functions that abstract many of these steps. The same operation performed in this guide can be accomplished using[`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow). ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") |> aggregateWindow(every: 5m, fn: mean) ``` ## Congratulations! You have now constructed a Flux query that uses Flux functions to transform your data. There are many more ways to manipulate your data using both Flux’s primitive functions and your own custom functions, but this is a good introduction into the basic syntax and query structure. *For a deeper dive into windowing and aggregating data with example data output for each transformation, view the [Window and aggregate data](/influxdb/v2/query-data/flux/window-aggregate) guide.* [Query InfluxDB with Flux](/influxdb/v2/query-data/get-started/query-influxdb/) #### Related * [aggregateWindow() function](/flux/v0/stdlib/universe/aggregatewindow/) * [window() function](/flux/v0/stdlib/universe/window/) [flux](/influxdb/v2/tags/flux/)[transform](/influxdb/v2/tags/transform/)[query](/influxdb/v2/tags/query/) --- # Query data with InfluxQL Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use InfluxQL (an SQL-like query language) to interact with InfluxDB, and API features analyze your times series data. 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 OSS 2.10, data is stored in [buckets](/influxdb/v2/reference/glossary/#bucket). Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL. **To query data with InfluxQL, complete the following steps:** 1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping). 2. [Create DBRP mappings for unmapped buckets](#create-dbrp-mappings-for-unmapped-buckets). 3. [Query a mapped bucket with InfluxQL](#query-a-mapped-bucket-with-influxql). > [!Note] > #### InfluxQL reference documentation > > For complete InfluxQL reference documentation, see the[InfluxQL specification for InfluxDB 2.x](/influxdb/v2/reference/syntax/influxql/spec/). ## Verify buckets have a mapping 1. To verify the buckets you want to query are mapped to a database and retention policy, use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/).*For examples, see [List DBRP mappings](/influxdb/v2/query-data/influxql/dbrp/#list-dbrp-mappings).* 2. If you **do not find a DBRP mapping for a bucket**, [create a new DBRP mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings) to map the unmapped bucket. ## Create DBRP mappings for unmapped buckets * Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/)to manually create DBRP mappings for unmapped buckets.*For examples, see [Create DBRP mappings](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings).* ## Query a mapped bucket with InfluxQL [InfluxQL shell](#influxql-shell)[InfluxDB API](#influxdb-api) The [`influx` CLI](/influxdb/v2/reference/cli/influx/) provides an [InfluxQL shell](/influxdb/v2/tools/influxql-shell/) where you can execute InfluxQL queries in an interactive Read-Eval-Print-Loop (REPL). 1. If you haven’t already, do the following: * [Download and install the `influx` CLI](/influxdb/v2/tools/influx-cli/#install-the-influx-cli) * [Configure your authentication credentials](/influxdb/v2/tools/influx-cli/#provide-required-authentication-credentials) 2. Use the following command to start an InfluxQL shell: ``` influx v1 shell ``` 3. Execute an InfluxQL query inside the InfluxQL shell. ``` SELECT used_percent FROM "example-db"."example-rp"."example-measurement" WHERE host=host1 ``` For more information, see how to [use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/). For more information about DBRP mappings, see [Manage DBRP mappings](/influxdb/v2/query-data/influxql/dbrp/). The [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) supports all InfluxDB 1.x client libraries and integrations in InfluxDB 2.10. 1. To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/query/), and include the following in your request: * **Request method:** `GET` * **Headers:** * **Authorization:** *See [compatibility API authentication](/influxdb/v2/reference/api/influxdb-1x/#authentication)* * **Query parameters:** * **db**: 1.x database to query * **rp**: 1.x retention policy to query *(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)* * **q**: URL-encoded InfluxQL query > [!Note] > URL-encode query parameters that may contain whitespace or other special characters. ``` curl --get http://localhost:8086/query?db=example-db \ --header "Authorization: Token YourAuthToken" \ --data-urlencode "q=SELECT used_percent FROM \"example-db\".\"example-rp\".\"example-measurement\" WHERE host=host1" ``` By default, the `/query` compatibility endpoint returns results in **JSON**. 2. (Optional) To return results as **CSV**, include the `Accept: application/csv` header. For more information about DBRP mappings, see [Manage DBRP mappings](/influxdb/v2/query-data/influxql/dbrp/). ## InfluxQL support InfluxDB OSS 2.x supports the following InfluxQL statements and clauses. See supported and unsupported queries below. > [!Note] > ##### Supported InfluxQL queries > > * `DELETE`\* > * `DROP MEASUREMENT`\* > * `EXPLAIN ANALYZE` > * `SELECT` *(read-only)* > * `SHOW DATABASES` > * `SHOW SERIES` > * `SHOW MEASUREMENTS` > * `SHOW TAG KEYS` > * `SHOW FIELD KEYS` > * `SHOW SERIES EXACT CARDINALITY` > * `SHOW TAG KEY CARDINALITY` > * `SHOW FIELD KEY CARDINALITY` > > \* These commands delete data. ##### Unsupported InfluxQL queries * `SELECT INTO` * `ALTER` * `CREATE` * `DROP` *(limited support)* * `GRANT` * `KILL` * `REVOKE` * `SHOW SERIES CARDINALITY` #### Related * [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) [influxql](/influxdb/v2/tags/influxql/)[query](/influxdb/v2/tags/query/) --- # Manage DBRP mappings Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/dbrp/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxQL requires a database and retention policy (DBRP) combination in order to query data. In InfluxDB 2.10, databases and retention policies have been combined and replaced by InfluxDB [buckets](/influxdb/v2/reference/glossary/#bucket). To query InfluxDB 2.10 with InfluxQL, the specified DBRP combination must be mapped to a bucket. * [Automatic DBRP mapping](#automatic-dbrp-mapping) * [Virtual DBRP mappings](#virtual-dbrp-mappings) * [Create DBRP mappings](#create-dbrp-mappings) * [List DBRP mappings](#list-dbrp-mappings) * [Update a DBRP mapping](#update-a-dbrp-mapping) * [Delete a DBRP mapping](#delete-a-dbrp-mapping) ## Automatic DBRP mapping InfluxDB 2.10 will automatically create DBRP mappings for you during the following operations: * Writing to the [`/write` v1 compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/write/) * [Upgrading from InfluxDB 1.x to 2.10](/influxdb/v2/upgrade/v1-to-v2/) * Creating a bucket ([virtual DBRPs](#virtual-dbrp-mappings)) For more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/). ## Virtual DBRP mappings InfluxDB 2.10 provides “virtual” DBRP mappings for any bucket that does not have an explicit DBRP mapping associated with it. Virtual DBRP mappings use the bucket name to provide a DBRP mapping that can be used without having to explicitly define a mapping. Virtual DBRP mappings are read-only. To override a virtual DBRP mapping, [create an explicit mapping](#create-dbrp-mappings). For information about how virtual DBRP mappings are created, see[Database and retention policy mapping – When creating a bucket](/influxdb/v2/reference/api/influxdb-1x/dbrp/#when-creating-a-bucket). ## Create DBRP mappings Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the[InfluxDB API](/influxdb/v2/reference/api/) to create DBRP mappings. > [!Note] > #### A DBRP combination can only be mapped to a single bucket > > Each unique DBRP combination can only be mapped to a single bucket. > If you map a DBRP combination that is already mapped to another bucket, > it will overwrite the existing DBRP mapping. [influx CLI](#influx-cli)[InfluxDB API](#influxdb-api) Use the [`influx v1 dbrp create` command](/influxdb/v2/reference/cli/influx/v1/dbrp/create/)to map an unmapped bucket to a database and retention policy. Include the following: \* Required * \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/). * \* **database name** to map * \* **retention policy** name to map * \* [Bucket ID](/influxdb/v2/admin/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to * **Default flag** to set the provided retention policy as the default retention policy for the database ```sh influx v1 dbrp create \ --db example-db \ --rp example-rp \ --bucket-id 00oxo0oXx000x0Xo \ --default ``` Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2/api/dbrps/) to create a new DBRP mapping. ``` POST http://localhost:8086/api/v2/dbrps ``` Include the following: * **Request method:** `POST` * **Headers:** * **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields: \* Required * \* **bucketID:** [bucket ID](/influxdb/v2/admin/buckets/view-buckets/) * \* **database:** database name * **default:** set the provided retention policy as the default retention policy for the database * \* **org** or **orgID:** organization name or [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * \* **retention\_policy:** retention policy name ```sh curl --request POST http://localhost:8086/api/v2/dbrps \ --header "Authorization: Token YourAuthToken" \ --header 'Content-type: application/json' \ --data '{ "bucketID": "00oxo0oXx000x0Xo", "database": "example-db", "default": true, "orgID": "00oxo0oXx000x0Xo", "retention_policy": "example-rp" }' ``` ## List DBRP mappings Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/)to list all DBRP mappings and verify the buckets you want to query are mapped to a database and retention policy. [influx CLI](#influx-cli-2)[InfluxDB API](#influxdb-api-2) Use the [`influx v1 dbrp list` command](/influxdb/v2/reference/cli/influx/v1/dbrp/list/) to list DBRP mappings. > [!Note] > The examples below assume that your organization and API token are > provided by the active [InfluxDB connection configuration](/influxdb/v2/reference/cli/influx/config/) in the `influx` CLI. > If not, include your organization (`--org`) and API token (`--token`) with each command. ##### View all DBRP mappings ```sh influx v1 dbrp list ``` ##### Filter DBRP mappings by database ```sh influx v1 dbrp list --db example-db ``` ##### Filter DBRP mappings by bucket ID ```sh influx v1 dbrp list --bucket-id 00oxo0oXx000x0Xo ``` Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2/api/dbrps/) to list DBRP mappings. ``` GET http://localhost:8086/api/v2/dbrps ``` Include the following: * **Request method:** `GET` * **Headers:** * **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Query parameters:** \* Required * \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **bucketID:** [bucket ID](/influxdb/v2/admin/buckets/view-buckets/) *(to list DBRP mappings for a specific bucket)* * **database:** database name *(to list DBRP mappings with a specific database name)* * **rp:** retention policy name *(to list DBRP mappings with a specific retention policy name)* * **id:** DBRP mapping ID *(to list a specific DBRP mapping)* ##### View all DBRP mappings ```sh curl --request GET \ http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo \ --header "Authorization: Token YourAuthToken" ``` ##### Filter DBRP mappings by database ```sh curl --request GET \ http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo&db=example-db \ --header "Authorization: Token YourAuthToken" ``` ##### Filter DBRP mappings by bucket ID ```sh curl --request GET \ https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&bucketID=00oxo0oXx000x0Xo \ --header "Authorization: Token YourAuthToken" ``` ## Update a DBRP mapping Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the[InfluxDB API](/influxdb/v2/reference/api/) to update a DBRP mapping. > [!Note] > Virtual DBRP mappings cannot be updated. > To override a virtual DBRP mapping, [create an explicit mapping](#create-dbrp-mappings). [influx CLI](#influx-cli-3)[InfluxDB API](#influxdb-api-3) Use the [`influx v1 dbrp update` command](/influxdb/v2/reference/cli/influx/v1/dbrp/update/)to update a DBRP mapping. Include the following: \* Required * \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/). * \* **DBRP mapping ID** to update * **Retention policy** name to update to * **Default flag** to set the retention policy as the default retention policy for the database ##### Update the default retention policy ```sh influx v1 dbrp update \ --id 00oxo0X0xx0XXoX0 --rp example-rp \ --default ``` Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/v2/api/dbrps/) to update DBRP mappings. ``` PATCH http://localhost:8086/api/v2/dbrps/{dbrpID} ``` Include the following: \* Required * **Request method:** `PATCH` * **Headers:** * \* **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Path parameters:** * \* **id:** DBRP mapping ID to update * **Query parameters:** * \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **Request body (JSON):** * **rp:** retention policy name to update to * **default:** set the retention policy as the default retention policy for the database ##### Update the default retention policy ```sh curl --request PATCH \ http://localhost:8086/api/v2/dbrps/00oxo0X0xx0XXoX0?orgID=00oxo0oXx000x0Xo \ --header "Authorization: Token YourAuthToken" --data '{ "rp": "example-rp", "default": true }' ``` ## Delete a DBRP mapping Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the[InfluxDB API](/influxdb/v2/reference/api/) to delete a DBRP mapping. > [!Note] > Virtual DBRP mappings cannot be deleted. [influx CLI](#influx-cli-4)[InfluxDB API](#influxdb-api-4) Use the [`influx v1 dbrp delete` command](/influxdb/v2/reference/cli/influx/v1/dbrp/delete/)to delete a DBRP mapping. Include the following: \* Required * \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/). * \* **DBRP mapping ID** to delete ```sh influx v1 dbrp delete --id 00oxo0X0xx0XXoX0 ``` Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/v2/api/dbrps/) to delete a DBRP mapping. ``` DELETE http://localhost:8086/api/v2/dbrps/{dbrpID} ``` Include the following: \* Required * **Request method:** `PATCH` * **Headers:** * \* **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Path parameters:** * \* **id:** DBRP mapping ID to update * **Query parameters:** * \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) ```sh curl --request DELETE \ http://localhost:8086/api/v2/dbrps/00oxo0X0xx0XXoX0?orgID=00oxo0oXx000x0Xo \ --header "Authorization: Token YourAuthToken" ``` [influxql](/influxdb/v2/tags/influxql/)[dbrp](/influxdb/v2/tags/dbrp/) --- # Explore data using InfluxQL Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To start exploring data with InfluxQL, do the following: 1. Verify your bucket has a database and retention policy (DBRP) mapping by [listing DBRP mappings for your bucket](/influxdb/v2/query-data/influxql/dbrp/#list-dbrp-mappings). If not, [create a new DBRP mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings). 2. [Configure timestamps in the InfluxQL shell](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/). 3. *(Optional)* If you would like to use the data used in the examples below, [download the NOAA sample data](#download-sample-data). 4. Use the InfluxQL `SELECT` statement with other key clauses to explore your data. * [SELECT statement](#select-statement) * [WHERE clause](#where-clause) * [GROUP BY clause](#group-by-clause) * [ORDER BY clause](#order-by-clause) * [LIMIT and SLIMIT clauses](#limit-and-slimit-clauses) * [OFFSET and SOFFSET clauses](#offset-and-soffset-clauses) * [Time and timezone queries](#time-and-timezone-queries) * [Subqueries](#subqueries) * [Regular expressions](#regular-expressions) ### [SELECT statement](/influxdb/v2/query-data/influxql/explore-data/select/) Use the `SELECT` statement to query data from a particular [measurement](/influxdb/v2/reference/glossary/#measurement) or measurements. ```sql SELECT [,,] FROM [,] ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/select/) ### [WHERE clause](/influxdb/v2/query-data/influxql/explore-data/where/) Use the `WHERE` clause to filter data based on [fields](/influxdb/v2/reference/glossary/#field), [tags](/influxdb/v2/reference/glossary/#tag), and/or [timestamps](/influxdb/v2/reference/glossary/#timestamp). ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/where/) ### [GROUP BY clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) Use the `GROUP BY` clause to group query results by one or more specified [tags](/influxdb/v2/reference/glossary/#tag) and/or a specified time interval. ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) ### [OFFSET and SOFFSET clauses](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) Use the `OFFSET` and `SOFFSET` clauses to paginate [points](/influxdb/v2/reference/glossary/#point) and [series](/influxdb/v2/reference/glossary/#series). ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) ### [Time and timezone queries](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/) Explore InfluxQL features used specifically for working with time. Use the `tz` (timezone) clause to return the UTC offset for the specified timezone. ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/) ### [Subqueries](/influxdb/v2/query-data/influxql/explore-data/subqueries/) Use a `subquery` to apply a query as a condition in the enclosing query. ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/subqueries/) ### [Regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) Use `regular expressions` to match patterns in your data. ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` [Read more ](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) ## Download sample data The example InfluxQL queries in this documentation use publicly available [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov/) data. To download a subset of NOAA data used in examples, run the script under [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data) (for example, copy and paste the script into your Data Explorer - Script Editor), and replace “example-org” in the script with the name of your InfluxDB organization. Let’s get acquainted with this subsample of the data in the `h2o_feet` measurement: Output: Name: h2o\_feet | time | level description | location |water\_level| |--------------------|--------------------|-------------|------------| |2019-08-18T00:00:00Z|between 6 and 9 feet|coyote\_creek|8.1200000000| |2019-08-18T00:00:00Z| below 3 feet |santa\_monica|2.0640000000| |2019-08-18T00:06:00Z|between 6 and 9 feet|coyote\_creek|8.0050000000| |2019-08-18T00:06:00Z| below 3 feet |santa\_monica|2.1160000000| |2019-08-18T00:12:00Z|between 6 and 9 feet|coyote\_creek|7.8870000000| |2019-08-18T00:12:00Z| below 3 feet |santa\_monica|2.0280000000| The data in the `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement)occurs at six-minute time intervals. This measurement has one [tag key](/influxdb/v2/reference/glossary/#tag-key)(`location`) which has two [tag values](/influxdb/v2/reference/glossary/#tag-value):`coyote_creek` and `santa_monica`. The measurement also has two [fields](/influxdb/v2/reference/glossary/#field):`level description` stores string [field values](/influxdb/v2/reference/glossary/#field-value)and `water_level` stores float field values. ### Configure timestamps in the InfluxQL shell By default, the [InfluxQL shell](/influxdb/v2/tools/influxql-shell/) returns timestamps in nanosecond UNIX epoch format by default. To return human-readable RFC3339 timestamps instead of Unix nanosecond timestamps, use the [precision helper command](/influxdb/v2/tools/influxql-shell/#precision) ` to configure the timestamp format: ```sql precision rfc3339 ``` The [InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) returns timestamps in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. Specify alternative formats with the [`epoch` query string parameter](/influxdb/v2/reference/api/influxdb-1x/). | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-18T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000 | | 2019-08-18T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | 2019-08-18T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.0050000000 | | 2019-08-18T00:06:00Z | below 3 feet | santa_monica | 2.1160000000 | | 2019-08-18T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.8870000000 | | 2019-08-18T00:12:00Z | below 3 feet | santa_monica | 2.0280000000 | --- # GROUP BY clause Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/group-by/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `GROUP BY` clause to group query results by one or more specified [tags](/influxdb/v2/reference/glossary/#tag) and/or a specified time interval. `GROUP BY` requires an [aggregate](/influxdb/v2/query-data/influxql/functions/aggregates/) or [selector](/influxdb/v2/query-data/influxql/functions/selectors/) function in the `SELECT` statement. `GROUP BY` supports [regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). > [!Note] > **Note:** You cannot use `GROUP BY` to group **fields**. * [GROUP BY tags](#group-by-tags) * [Syntax and examples](#syntax) * [GROUP BY time intervals](#group-by-time-intervals) * [Basic syntax and examples](#basic-group-by-time-syntax) * [Common issues with basic syntax](#common-issues-with-basic-syntax) * [Advanced syntax and examples](#advanced-group-by-time-syntax) * [GROUP BY time intervals and fill()](#group-by-time-intervals-and-fill) * [Syntax and examples](#syntax-2) * [Common issues with fill()](#common-issues-with-fill) ## GROUP BY tags `GROUP BY ` groups query results by one or more specified [tags](/influxdb/v2/reference/glossary/#tag). ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [,]] ``` * `GROUP BY *` - Groups results by all [tags](/influxdb/v2/reference/glossary/#tag) * `GROUP BY ` - Groups results by a specific tag * `GROUP BY ,` - Groups results by more than one tag. The order of the [tag keys](/influxdb/v2/reference/glossary/#tag-key) is irrelevant. * `GROUP BY \regex\` - Groups results by tags that match the regular expression. If the query includes a `WHERE` clause, the `GROUP BY` clause must appear after the `WHERE` clause. ### Examples [](#group-query-results-by-a-single-tag) Group query results by a single tag ```sql SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|5.3591424203| name: h2o\_feet tags: location=santa\_monica | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|3.5307120942| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/)to calculate the average `water_level` for each[tag value](/influxdb/v2/reference/glossary/#tag-value) of `location` in the `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). InfluxDB returns results in two [series](/influxdb/v2/reference/glossary/#series): one for each tag value of `location`. > [!Note] > **Note:** In InfluxDB, [epoch 0](https://en.wikipedia.org/wiki/Unix_time) (`1970-01-01T00:00:00Z`) is often used as a null timestamp equivalent. > If you request a query that has no timestamp to return, such as an [aggregation function](/influxdb/v2/query-data/influxql/functions/aggregates/) with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. [](#group-query-results-by-more-than-one-tag) Group query results by more than one tag ```sql SELECT MEAN("index") FROM "h2o_quality" GROUP BY "location","randtag" ``` Output: name: h2o\_quality tags: location=coyote\_creek, randtag=1 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|50.6903376019| name: h2o\_quality tags: location=coyote\_creek, randtag=2 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.6618675442| name: h2o\_quality tags: location=coyote\_creek, randtag=3 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.3609399076| name: h2o\_quality tags: location=santa\_monica, randtag=1 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.1327124563| name: h2o\_quality tags: location=santa\_monica, randtag=2 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|50.2937984496| name: h2o\_quality tags: location=santa\_monica, randtag=3 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.9991990388| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `index` for each combination of the `location` tag and the `randtag` tag in the`h2o_quality` measurement. Separate multiple tags with a comma in the `GROUP BY` clause. [](#group-query-results-by-all-tags) Group query results by all tags ```sql SELECT MEAN("index") FROM "h2o_quality" GROUP BY * ``` Output: name: h2o\_quality tags: location=coyote\_creek, randtag=1 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|50.6903376019| name: h2o\_quality tags: location=coyote\_creek, randtag=2 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.6618675442| name: h2o\_quality tags: location=coyote\_creek, randtag=3 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.3609399076| name: h2o\_quality tags: location=santa\_monica, randtag=1 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.1327124563| name: h2o\_quality tags: location=santa\_monica, randtag=2 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|50.2937984496| name: h2o\_quality tags: location=santa\_monica, randtag=3 | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|49.9991990388| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `index` for every possible[tag](/influxdb/v2/reference/glossary/#tag) combination in the `h2o_quality`measurement. [](#group-query-results-by-tags-that-start-with-l) Group query results by tags that start with `l` ```sql SELECT MAX("water_level"),location FROM "h2o_feet" GROUP BY /l/ ``` This query uses a regular expression to group by tags that start with `l`. With the sample NOAA water dataset, results are grouped by the `location` tag. ## GROUP BY time intervals `GROUP BY time()` group query results by a user-specified time interval. When using aggregate or selector functions in the `SELECT` clause, the operation is applied to each interval. ### Basic GROUP BY time() syntax #### Syntax ```sql SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] ``` Basic `GROUP BY time()` queries require an InfluxQL [function](/influxdb/v2/query-data/influxql/functions)in the `SELECT` clause and a time range in the `WHERE` clause. Note that the `GROUP BY` clause must come **after** the `WHERE` clause. ##### `time(time_interval)` The `time_interval` in the `GROUP BY time()` clause is a[duration literal](/influxdb/v2/reference/glossary/#duration). It determines how InfluxDB groups query results over time. For example, a `time_interval` of `5m` groups query results into five-minute time groups across the time range specified in the `WHERE` clause. ##### `fill()` `fill()` is optional. It changes the value reported for time intervals with no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill)for more information. **Coverage:** Basic `GROUP BY time()` queries rely on the `time_interval` and InfluxDB’s preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. ### Examples of basic syntax The examples below use the following subsample of the sample data: ```sql SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` Output: Name: h2o\_feet | time |water\_level| location | |--------------------|------------|-------------| |2019-08-18T00:00:00Z|8.5040000000|coyote\_creek| |2019-08-18T00:00:00Z|2.3520000000|santa\_monica| |2019-08-18T00:06:00Z|8.4190000000|coyote\_creek| |2019-08-18T00:06:00Z|2.3790000000|santa\_monica| |2019-08-18T00:12:00Z|8.3200000000|coyote\_creek| |2019-08-18T00:12:00Z|2.3430000000|santa\_monica| |2019-08-18T00:18:00Z|8.2250000000|coyote\_creek| |2019-08-18T00:18:00Z|2.3290000000|santa\_monica| |2019-08-18T00:24:00Z|8.1300000000|coyote\_creek| |2019-08-18T00:24:00Z|2.2640000000|santa\_monica| |2019-08-18T00:30:00Z|8.0120000000|coyote\_creek| |2019-08-18T00:30:00Z|2.2670000000|santa\_monica| [](#group-query-results-into-12-minute-intervals) Group query results into 12 minute intervals ```sql SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` Output: Name: h2o\_feet | time | count | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| The query uses the InfluxQL [COUNT() function](/influxdb/v2/query-data/influxql/functions/aggregates/#count) to count the number of `water_level` points per location, per 12-minute interval. Each output row represents a single 12 minute interval. The count for the first timestamp covers the raw data between `2019-08-18T00:00:00Z`and up to, but not including, `2019-08-18T00:12:00Z`. The count for the second timestamp covers the raw data between `2019-08-18T00:12:00Z`and up to, but not including, `2019-08-18T00:24:00Z.` [](#group-query-results-into-12-minute-intervals-and-by-a-tag-key) Group query results into 12 minute intervals and by a tag key ```sql SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | count | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| name: h2o\_feet tags: location=santa\_monica | time | count | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| The query uses the InfluxQL [COUNT() function](/influxdb/v2/query-data/influxql/functions/aggregates/#count)to count the number of `water_level` points per location, per 12 minute interval. Note that the time interval and the tag key are separated by a comma in the`GROUP BY` clause. The query returns two [series](/influxdb/v2/reference/glossary/#series) of results: one for each[tag value](/influxdb/v2/reference/glossary/#tag-value) of the `location` tag. The result for each timestamp represents a single 12 minute interval. Each output row represents a single 12 minute interval. and up to, but not including, `2019-08-18T00:12:00Z`. The count for the second timestamp covers the raw data between `2019-08-18T00:12:00Z`and up to, but not including, `2019-08-18T00:24:00Z.` ### Common issues with basic syntax ##### Unexpected timestamps and values in query results With the basic syntax, InfluxDB relies on the `GROUP BY time()` interval and on the system’s preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. In some cases, this can lead to unexpected results. **Example** Raw data: ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:18:00Z' ``` Output: name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|8.5040000000| |2019-08-18T00:06:00Z|8.4190000000| |2019-08-18T00:12:00Z|8.3200000000| |2019-08-18T00:18:00Z|8.2250000000| Query and results: The following example queries a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: ```sql SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m) ``` Output: name: h2o\_feet | time | count | |--------------------|------------| |2019-08-18T00:00:00Z|1.0000000000| |2019-08-18T00:12:00Z|1.0000000000| > [!Note] > **Note:** The timestamp in the first row of data occurs before the start of the queried time range. Explanation: InfluxDB uses preset round-number time boundaries for `GROUP BY` intervals that are independent of any time conditions in the `WHERE` clause. When it calculates the results, all returned data must occur within the query’s explicit time range but the `GROUP BY` intervals will be based on the preset time boundaries. The table below shows the preset time boundary, the relevant `GROUP BY time()` interval, the points included, and the returned timestamp for each `GROUP BY time()`interval in the results. |Time Interval Number| Preset Time Boundary | `GROUP BY time()` Interval |Points Included| Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------------------------------------------|---------------|----------------------| | 1 |`time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z`|`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z`| `8.005` |`2019-08-18T00:00:00Z`| | 2 |`time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z`|`time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z`| `7.887` |`2019-08-18T00:12:00Z`| The first preset 12-minute time boundary begins at `00:00` and ends just before`00:12`. Only one raw point (`8.005`) falls both within the query’s first `GROUP BY time()` interval and in that first time boundary. Note that while the returned timestamp occurs before the start of the queried time range, the query result excludes data that occur before the queried time range. The second preset 12-minute time boundary begins at `00:12` and ends just before`00:24`. Only one raw point (`7.887`) falls both within the query’s second `GROUP BY time()` interval and in that second time boundary. The [advanced `GROUP BY time()` syntax](#advanced-group-by-time-syntax) allows users to shift the start time of the InfluxDB database’s preset time boundaries. It shifts forward the preset time boundaries by six minutes such that InfluxDB returns: Output: name: h2o\_feet | time |count| |--------------------|-----| |2019-08-18T00:06:00Z| 2 | ### Advanced GROUP BY time() syntax #### Syntax ```sql SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] ``` Advanced `GROUP BY time()` queries require an InfluxQL [function](/influxdb/v2/query-data/influxql/functions/)in the `SELECT` clause and a time range in the`WHERE` clause). Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval,offset_interval)` See the [Basic GROUP BY time() Syntax](#basic-group-by-time-syntax)for details on the `time_interval`. The `offset_interval` is a [duration literal](/influxdb/v2/reference/glossary/#duration). It shifts forward or back the InfluxDB database’s preset time boundaries. The `offset_interval` can be positive or negative. ##### `fill()` `fill()` is optional. It changes the value reported for time intervals with no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill)for more information. **Coverage:** Advanced `GROUP BY time()` queries rely on the `time_interval`, the `offset_interval`, and on the InfluxDB database’s preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. ### Examples of advanced syntax The examples below use the following subsample of the sample data: ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|8.5040000000| |2019-08-18T00:06:00Z|8.4190000000| |2019-08-18T00:12:00Z|8.3200000000| |2019-08-18T00:18:00Z|8.2250000000| |2019-08-18T00:24:00Z|8.1300000000| |2019-08-18T00:30:00Z|8.0120000000| |2019-08-18T00:36:00Z|7.8940000000| |2019-08-18T00:42:00Z|7.7720000000| |2019-08-18T00:48:00Z|7.6380000000| |2019-08-18T00:54:00Z|7.5100000000| [](#group-query-results-into-18-minute-intervals-and-shift-the-preset-time-boundaries-forward) Group query results into 18 minute intervals and shift the preset time boundaries forward ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m,6m) ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:06:00Z|8.3213333333| |2019-08-18T00:24:00Z|8.0120000000| |2019-08-18T00:42:00Z|7.6400000000| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean)to calculate the average `water_level`, grouping results into 18 minute time intervals, and offsetting the preset time boundaries by 6 minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to the InfluxDB database’s preset time boundaries. Let’s first examine the results without the offset: ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m) ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.3695000000| |2019-08-18T00:18:00Z|8.1223333333| |2019-08-18T00:36:00Z|7.7680000000| |2019-08-18T00:54:00Z|7.5100000000| The time boundaries and returned timestamps for the query **without** the`offset_interval` adhere to the InfluxDB database’s preset time boundaries: |Time Interval Number| Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------------------------------------------|----------------------|----------------------| | 1 |`time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z`|`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z`| `8.005`,`7.887` |`2019-08-18T00:00:00Z`| | 2 |`time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z`| \<— same |`7.762`,`7.635`,`7.5` |`2019-08-18T00:18:00Z`| | 3 |`time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z`| \<— same |`7.372`,`7.234`,`7.11`|`2019-08-18T00:36:00Z`| | 4 |`time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z`| `time = 2019-08-18T00:54:00Z` | `6.982` |`2019-08-18T00:54:00Z`| The first preset 18-minute time boundary begins at `00:00` and ends just before`00:18`. Two raw points (`8.005` and `7.887`) fall both within the first `GROUP BY time()` interval and in that first time boundary. While the returned timestamp occurs before the start of the queried time range, the query result excludes data that occur before the queried time range. The second preset 18-minute time boundary begins at `00:18` and ends just before`00:36`. Three raw points (`7.762` and `7.635` and `7.5`) fall both within the second `GROUP BY time()` interval and in that second time boundary. In this case, the boundary time range and the interval’s time range are the same. The fourth preset 18-minute time boundary begins at `00:54` and ends just before`1:12:00`. One raw point (`6.982`) falls both within the fourth `GROUP BY time()` interval and in that fourth time boundary. The time boundaries and returned timestamps for the query **with** the `offset_interval` adhere to the offset time boundaries: |Time Interval Number| Offset Time Boundary |`GROUP BY time()` Interval| Points Included | Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------|-----------------------|----------------------| | 1 |`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z`| \<— same |`8.005`,`7.887`,`7.762`|`2019-08-18T00:06:00Z`| | 2 |`time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z`| \<— same | `7.635`,`7.5`,`7.372` |`2019-08-18T00:24:00Z`| | 3 |`time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z`| \<— same |`7.234`,`7.11`,`6.982` |`2019-08-18T00:42:00Z`| | 4 |`time >= 2019-08-18T01:00:00Z AND time < 2019-08-18T01:18:00Z`| NA | NA | NA | The six-minute offset interval shifts forward the preset boundary’s time range such that the boundary time ranges and the relevant `GROUP BY time()` interval time ranges are always the same. With the offset, each interval performs the calculation on three points, and the timestamp returned matches both the start of the boundary time range and the start of the `GROUP BY time()` interval time range. Note that `offset_interval` forces the fourth time boundary to be outside the queried time range so the query returns no results for that last interval. [](#group-query-results-into-12-minute-intervals-and-shift-the-preset-time-boundaries-back) Group query results into 12 minute intervals and shift the preset time boundaries back ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m,-12m) ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:06:00Z|8.3213333333| |2019-08-18T00:24:00Z|8.0120000000| |2019-08-18T00:42:00Z|7.6400000000| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level`, grouping results into 18 minute time intervals, and offsetting the preset time boundaries by -12 minutes. > [!Note] > **Note:** The query in Example 2 returns the same results as the query in Example 1, but > the query in Example 2 uses a negative `offset_interval` instead of a positive`offset_interval`. > There are no performance differences between the two queries; feel free to choose the most > intuitive option when deciding between a positive and negative `offset_interval`. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database’s preset time boundaries. Let’s first examine the results without the offset: ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m) ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.3695000000| |2019-08-18T00:18:00Z|8.1223333333| |2019-08-18T00:36:00Z|7.7680000000| |2019-08-18T00:54:00Z|7.5100000000| The time boundaries and returned timestamps for the query **without** the`offset_interval` adhere to the InfluxDB database’s preset time boundaries: |Time Interval Number| Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------------------------------------------|----------------------|----------------------| | 1 |`time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z`|`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z`| `8.005`,`7.887` |`2019-08-18T00:00:00Z`| | 2 |`time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z`| \<— same |`7.762`,`7.635`,`7.5` |`2019-08-18T00:18:00Z`| | 3 |`time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z`| \<— same |`7.372`,`7.234`,`7.11`|`2019-08-18T00:36:00Z`| | 4 |`time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z`| `time = 2019-08-18T00:54:00Z` | `6.982` |`2019-08-18T00:54:00Z`| The first preset 18-minute time boundary begins at `00:00` and ends just before`00:18`. Two raw points (`8.005` and `7.887`) fall both within the first `GROUP BY time()` interval and in that first time boundary. Note that while the returned timestamp occurs before the start of the queried time range, the query result excludes data that occur before the queried time range. The second preset 18-minute time boundary begins at `00:18` and ends just before`00:36`. Three raw points (`7.762` and `7.635` and `7.5`) fall both within the second `GROUP BY time()` interval and in that second time boundary. In this case, the boundary time range and the interval’s time range are the same. The fourth preset 18-minute time boundary begins at `00:54` and ends just before`1:12:00`. One raw point (`6.982`) falls both within the fourth `GROUP BY time()` interval and in that fourth time boundary. The time boundaries and returned timestamps for the query **with** the`offset_interval` adhere to the offset time boundaries: |Time Interval Number| Offset Time Boundary |`GROUP BY time()` Interval| Points Included | Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------|-----------------------|----------------------| | 1 |`time >= 2019-08-17T23:48:00Z AND time < 2019-08-18T00:06:00Z`| NA | NA | NA | | 2 |`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z`| \<— same |`8.005`,`7.887`,`7.762`|`2019-08-18T00:06:00Z`| | 3 |`time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z`| \<— same | `7.635`,`7.5`,`7.372` |`2019-08-18T00:24:00Z`| | 4 |`time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z`| \<— same |`7.234`,`7.11`,`6.982` |`2019-08-18T00:42:00Z`| The negative 12-minute offset interval shifts back the preset boundary’s time range such that the boundary time ranges and the relevant `GROUP BY time()` interval time ranges are always the same. With the offset, each interval performs the calculation on three points, and the timestamp returned matches both the start of the boundary time range and the start of the `GROUP BY time()` interval time range. Note that `offset_interval` forces the first time boundary to be outside the queried time range so the query returns no results for that first interval. [](#group-query-results-into-12-minute-intervals-and-shift-the-preset-time-boundaries-forward) Group query results into 12 minute intervals and shift the preset time boundaries forward This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). ```sql SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m,6m) ``` Output: Name: h2o\_feet | time | count | |--------------------|------------| |2019-08-18T00:06:00Z|2.0000000000| The query uses the InfluxQL [COUNT() function](/influxdb/v2/query-data/influxql/functions/aggregates/#count) to count the number of `water_level` points per location, per 12-minute interval, and offset the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database’s preset time boundaries. Let’s first examine the results without the offset: ```sql SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m) ``` Output: Name: h2o\_feet | time | count | |--------------------|------------| |2019-08-18T00:00:00Z|1.0000000000| |2019-08-18T00:12:00Z|1.0000000000| The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database’s preset time boundaries: |Time Interval Number| Preset Time Boundary | `GROUP BY time()` Interval |Points Included| Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------------------------------------------|---------------|----------------------| | 1 |`time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z`|`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z`| `8.005` |`2019-08-18T00:00:00Z`| | 2 |`time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z`|`time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z`| `7.887` |`2019-08-18T00:12:00Z`| The first preset 12-minute time boundary begins at `00:00` and ends just before`00:12`. Only one raw point (`8.005`) falls both within the query’s first `GROUP BY time()` interval and in that first time boundary. Note that while the returned timestamp occurs before the start of the queried time range, the query result excludes data that occur before the queried time range. The second preset 12-minute time boundary begins at `00:12` and ends just before`00:24`. Only one raw point (`7.887`) falls both within the query’s second `GROUP BY time()` interval and in that second time boundary. The time boundaries and returned timestamps for the query **with** the`offset_interval` adhere to the offset time boundaries: |Time Interval Number| Offset Time Boundary |`GROUP BY time()` Interval|Points Included| Returned Timestamp | |--------------------|--------------------------------------------------------------|--------------------------|---------------|----------------------| | 1 |`time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z`| \<— same |`8.005`,`7.887`|`2019-08-18T00:06:00Z`| | 2 |`time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:30:00Z`| NA | NA | NA | The six-minute offset interval shifts forward the preset boundary’s time range such that the preset boundary time range and the relevant `GROUP BY time()` interval time range are the same. With the offset, the query returns a single result, and the timestamp returned matches both the start of the boundary time range and the start of the `GROUP BY time()` interval time range. Note that `offset_interval` forces the second time boundary to be outside the queried time range so the query returns no results for that second interval. ## `GROUP BY` time intervals and `fill()` `fill()` changes the value reported for time intervals with no data. #### Syntax ```sql SELECT () FROM_clause WHERE GROUP BY time(time_interval,[])[,tag_key] [fill()] ``` By default, a `GROUP BY time()` interval with no data reports `null` as its value in the output column.`fill()` changes the value reported for time intervals with no data. Note that `fill()` must go at the end of the `GROUP BY` clause if you’re`GROUP(ing) BY` several things (for example, both [tags](/influxdb/v2/reference/glossary/#tag) and a time interval). ##### fill\_option * Any numerical value - Reports the given numerical value for time intervals with no data. * `linear` - Reports the results of [linear interpolation](https://en.wikipedia.org/wiki/Linear_interpolation) for time intervals with no data. * `none` - Reports no timestamp and no value for time intervals with no data. * `null` - Reports null for time intervals with no data but returns a timestamp. This is the same as the default behavior. * `previous` - Reports the value from the previous time interval for time intervals with no data. ### Examples [fill(100)](#fill100)[fill(linear)](#filllinear)[fill(none)](#fillnone)[fill(null)](#fillnull)[fill(previous)](#fillprevious) Without `fill(100)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |2019-08-19T08:45:00Z|29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z| | |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z| | |2019-08-19T09:30:00Z|6.0000000000 | With `fill(100)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(100) ``` Output: Name: h2o\_quality | time | mean | |--------------------|--------------| |2019-08-19T08:40:00Z|68.0000000000 | |2019-08-19T08:45:00Z|29.0000000000 | |2019-08-19T08:50:00Z|47.0000000000 | |2019-08-19T08:55:00Z|100.0000000000| |2019-08-19T09:00:00Z|84.0000000000 | |2019-08-19T09:05:00Z| 0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000 | |2019-08-19T09:15:00Z|13.0000000000 | |2019-08-19T09:20:00Z| 9.0000000000 | |2019-08-19T09:25:00Z|100.0000000000| |2019-08-19T09:30:00Z| 6.0000000000 | `fill(100)` changes the value reported for the time interval with no data to `100`. Without `fill(linear)`: ```sql SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:00:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) ``` Output: Name: pond | time |mean| |--------------------|----| |2019-11-11T21:00:00Z| 1 | |2019-11-11T21:12:00Z| | |2019-11-11T21:24:00Z| 3 | |2019-11-11T21:36:00Z| | |2019-11-11T21:48:00Z| | |2019-11-11T22:00:00Z| 6 | With `fill(linear)`: ```sql SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:00:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) ``` Output: Name: pond | time |mean| |--------------------|----| |2019-11-11T21:00:00Z| 1 | |2019-11-11T21:12:00Z| 2 | |2019-11-11T21:24:00Z| 3 | |2019-11-11T21:36:00Z| 4 | |2019-11-11T21:48:00Z| 5 | |2019-11-11T22:00:00Z| 6 | `fill(linear)` changes the value reported for the time interval with no data to the results of [linear interpolation](https://en.wikipedia.org/wiki/Linear_interpolation). > [!Note] > **Note:** The data in this example is not in the `noaa` database. Without `fill(none)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |019-08-19T08:45:00Z |29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z| | |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z| | |2019-08-19T09:30:00Z|6.0000000000 | With `fill(none)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(none) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |2019-08-19T08:45:00Z|29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:30:00Z|6.0000000000 | ``` `fill(none)` reports no value and no timestamp for the time interval with no data. ``` Without `fill(null)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |019-08-19T08:45:00Z |29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z| | |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z| | |2019-08-19T09:30:00Z|6.0000000000 | With `fill(null)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(null) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |019-08-19T08:45:00Z |29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z| null | |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z| null | |2019-08-19T09:30:00Z|6.0000000000 | `fill(null)` reports `null` as the value for the time interval with no data. That result matches the result of the query without `fill(null)`. Without `fill(previous)`: ``` SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |019-08-19T08:45:00Z |29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z| | |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z| | With `fill(previous)`: ```sql SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(previous) ``` Output: Name: h2o\_quality | time | mean | |--------------------|-------------| |2019-08-19T08:40:00Z|68.0000000000| |019-08-19T08:45:00Z |29.0000000000| |2019-08-19T08:50:00Z|47.0000000000| |2019-08-19T08:55:00Z|47.0000000000| |2019-08-19T09:00:00Z|84.0000000000| |2019-08-19T09:05:00Z|0.0000000000 | |2019-08-19T09:10:00Z|41.0000000000| |2019-08-19T09:15:00Z|13.0000000000| |2019-08-19T09:20:00Z|9.0000000000 | |2019-08-19T09:25:00Z|9.0000000000 | `fill(previous)` changes the value reported for the time interval with no data to `3.235`, the value from the previous time interval. ### Common issues with `fill()` ##### Queries with no data in the queried time range Currently, queries ignore `fill()` if no data exists in the queried time range. This is the expected behavior. An open[feature request](https://github.com/influxdata/influxdb/issues/6967) on GitHub proposes that `fill()` should force a return of values even if the queried time range covers no data. **Example** The following query returns no data because `water_level` has no points within the queried time range. Note that `fill(800)` has no effect on the query results. ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2019-09-18T22:00:00Z' AND time <= '2019-09-18T22:18:00Z' GROUP BY time(12m) fill(800) > no results ``` ##### Queries with `fill(previous)` when the previous result is outside the queried time range `fill(previous)` doesn’t fill the result for a time interval if the previous value is outside the query’s time range. **Example** The following example queries the time range between `2019-09-18T16:24:00Z` and `2019-09-18T16:54:00Z`. Note that `fill(previous)` fills the result for `2019-09-18T16:36:00Z` with the result from `2019-09-18T16:24:00Z`. ```sql SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2019-09-18T16:24:00Z' AND time <= '2019-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) ``` Output: Name: h2o\_feet | time | max | |--------------------|-----| |2019-09-18T16:24:00Z|3.235| |2019-09-18T16:36:00Z|3.235| |2019-09-18T16:48:00Z| 4 | The next example queries the time range between `2019-09-18T16:36:00Z` and `2019-09-18T16:54:00Z`. Note that `fill(previous)` doesn’t fill the result for `2019-09-18T16:36:00Z` with the result from `2019-09-18T16:24:00Z`; the result for `2019-09-18T16:24:00Z` is outside the query’s shorter time range. ```sql SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2019-09-18T16:36:00Z' AND time <= '2019-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) ``` Output: Name: h2o\_feet | time |max| |--------------------|---| |2019-09-18T16:36:00Z| | |2019-09-18T16:48:00Z| 4 | ##### `fill(linear)` when the previous or following result is outside the queried time range `fill(linear)` doesn’t fill the result for a time interval with no data if the previous result or the following result is outside the queried time range. **Example** The following example queries the time range between `2019-11-11T21:24:00Z` and`2019-11-11T22:06:00Z`. Note that `fill(linear)` fills the results for the`2019-11-11T21:36:00Z` time interval and the `2019-11-11T21:48:00Z` time interval using the values from the `2019-11-11T21:24:00Z` time interval and the`2019-11-11T22:00:00Z` time interval. ```sql SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2019-11-11T21:24:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) ``` Output: Name: pond | time |mean| |--------------------|----| |2019-11-11T21:24:00Z| 3 | |2019-11-11T21:36:00Z| 4 | |2019-11-11T21:48:00Z| 5 | |2019-11-11T22:00:00Z| 6 | The next query shortens the time range in the previous query. It now covers the time between `2019-11-11T21:36:00Z` and `2019-11-11T22:06:00Z`. Note that `fill()` previous doesn’t fill the results for the `2019-11-11T21:36:00Z`time interval and the `2019-11-11T21:48:00Z` time interval; the result for`2019-11-11T21:24:00Z` is outside the query’s shorter time range and InfluxDB cannot perform the linear interpolation. ```sql SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:36:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) ``` Output: Name: pond | time |mean| |--------------------|----| |2019-11-11T21:36:00Z| | |2019-11-11T21:48:00Z| | |2019-11-11T22:00:00Z| 6 | > [!Note] > **Note:** The data in Issue 3 are not in `NOAA` database. We had to create a dataset with less regular data to work with `fill(linear)`. | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 5.3591424203 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 3.5307120942 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 50.6903376019 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.6618675442 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.3609399076 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.1327124563 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 50.2937984496 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.9991990388 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 50.6903376019 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.6618675442 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.3609399076 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.1327124563 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 50.2937984496 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 49.9991990388 | | time | water_level | location | | --- | --- | --- | | time | water_level | location | | 2019-08-18T00:00:00Z | 8.5040000000 | coyote_creek | | 2019-08-18T00:00:00Z | 2.3520000000 | santa_monica | | 2019-08-18T00:06:00Z | 8.4190000000 | coyote_creek | | 2019-08-18T00:06:00Z | 2.3790000000 | santa_monica | | 2019-08-18T00:12:00Z | 8.3200000000 | coyote_creek | | 2019-08-18T00:12:00Z | 2.3430000000 | santa_monica | | 2019-08-18T00:18:00Z | 8.2250000000 | coyote_creek | | 2019-08-18T00:18:00Z | 2.3290000000 | santa_monica | | 2019-08-18T00:24:00Z | 8.1300000000 | coyote_creek | | 2019-08-18T00:24:00Z | 2.2640000000 | santa_monica | | 2019-08-18T00:30:00Z | 8.0120000000 | coyote_creek | | 2019-08-18T00:30:00Z | 2.2670000000 | santa_monica | | time | count | | --- | --- | | time | count | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | time | count | | --- | --- | | time | count | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | time | count | | --- | --- | | time | count | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 8.5040000000 | | 2019-08-18T00:06:00Z | 8.4190000000 | | 2019-08-18T00:12:00Z | 8.3200000000 | | 2019-08-18T00:18:00Z | 8.2250000000 | | time | count | | --- | --- | | time | count | | 2019-08-18T00:00:00Z | 1.0000000000 | | 2019-08-18T00:12:00Z | 1.0000000000 | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z | 8.005 | 2019-08-18T00:00:00Z | | 2 | time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z | time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z | 7.887 | 2019-08-18T00:12:00Z | | time | count | | --- | --- | | time | count | | 2019-08-18T00:06:00Z | 2 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 8.5040000000 | | 2019-08-18T00:06:00Z | 8.4190000000 | | 2019-08-18T00:12:00Z | 8.3200000000 | | 2019-08-18T00:18:00Z | 8.2250000000 | | 2019-08-18T00:24:00Z | 8.1300000000 | | 2019-08-18T00:30:00Z | 8.0120000000 | | 2019-08-18T00:36:00Z | 7.8940000000 | | 2019-08-18T00:42:00Z | 7.7720000000 | | 2019-08-18T00:48:00Z | 7.6380000000 | | 2019-08-18T00:54:00Z | 7.5100000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:06:00Z | 8.3213333333 | | 2019-08-18T00:24:00Z | 8.0120000000 | | 2019-08-18T00:42:00Z | 7.6400000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.3695000000 | | 2019-08-18T00:18:00Z | 8.1223333333 | | 2019-08-18T00:36:00Z | 7.7680000000 | | 2019-08-18T00:54:00Z | 7.5100000000 | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z | 8.005 , 7.887 | 2019-08-18T00:00:00Z | | 2 | time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z | <— same | 7.762 , 7.635 , 7.5 | 2019-08-18T00:18:00Z | | 3 | time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z | <— same | 7.372 , 7.234 , 7.11 | 2019-08-18T00:36:00Z | | 4 | time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z | time = 2019-08-18T00:54:00Z | 6.982 | 2019-08-18T00:54:00Z | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z | <— same | 8.005 , 7.887 , 7.762 | 2019-08-18T00:06:00Z | | 2 | time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z | <— same | 7.635 , 7.5 , 7.372 | 2019-08-18T00:24:00Z | | 3 | time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z | <— same | 7.234 , 7.11 , 6.982 | 2019-08-18T00:42:00Z | | 4 | time >= 2019-08-18T01:00:00Z AND time < 2019-08-18T01:18:00Z | NA | NA | NA | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:06:00Z | 8.3213333333 | | 2019-08-18T00:24:00Z | 8.0120000000 | | 2019-08-18T00:42:00Z | 7.6400000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.3695000000 | | 2019-08-18T00:18:00Z | 8.1223333333 | | 2019-08-18T00:36:00Z | 7.7680000000 | | 2019-08-18T00:54:00Z | 7.5100000000 | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z | 8.005 , 7.887 | 2019-08-18T00:00:00Z | | 2 | time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z | <— same | 7.762 , 7.635 , 7.5 | 2019-08-18T00:18:00Z | | 3 | time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z | <— same | 7.372 , 7.234 , 7.11 | 2019-08-18T00:36:00Z | | 4 | time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z | time = 2019-08-18T00:54:00Z | 6.982 | 2019-08-18T00:54:00Z | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-17T23:48:00Z AND time < 2019-08-18T00:06:00Z | NA | NA | NA | | 2 | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z | <— same | 8.005 , 7.887 , 7.762 | 2019-08-18T00:06:00Z | | 3 | time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z | <— same | 7.635 , 7.5 , 7.372 | 2019-08-18T00:24:00Z | | 4 | time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z | <— same | 7.234 , 7.11 , 6.982 | 2019-08-18T00:42:00Z | | time | count | | --- | --- | | time | count | | 2019-08-18T00:06:00Z | 2.0000000000 | | time | count | | --- | --- | | time | count | | 2019-08-18T00:00:00Z | 1.0000000000 | | 2019-08-18T00:12:00Z | 1.0000000000 | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Preset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z | 8.005 | 2019-08-18T00:00:00Z | | 2 | time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z | time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z | 7.887 | 2019-08-18T00:12:00Z | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | --- | --- | --- | --- | --- | | Time Interval Number | Offset Time Boundary | GROUP BY time() Interval | Points Included | Returned Timestamp | | 1 | time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z | <— same | 8.005 , 7.887 | 2019-08-18T00:06:00Z | | 2 | time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:30:00Z | NA | NA | NA | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 2019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 2019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | 100.0000000000 | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | 100.0000000000 | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-11-11T21:00:00Z | 1 | | 2019-11-11T21:12:00Z | | | 2019-11-11T21:24:00Z | 3 | | 2019-11-11T21:36:00Z | | | 2019-11-11T21:48:00Z | | | 2019-11-11T22:00:00Z | 6 | | time | mean | | --- | --- | | time | mean | | 2019-11-11T21:00:00Z | 1 | | 2019-11-11T21:12:00Z | 2 | | 2019-11-11T21:24:00Z | 3 | | 2019-11-11T21:36:00Z | 4 | | 2019-11-11T21:48:00Z | 5 | | 2019-11-11T22:00:00Z | 6 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 2019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | null | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | null | | 2019-08-19T09:30:00Z | 6.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | | | time | mean | | --- | --- | | time | mean | | 2019-08-19T08:40:00Z | 68.0000000000 | | 019-08-19T08:45:00Z | 29.0000000000 | | 2019-08-19T08:50:00Z | 47.0000000000 | | 2019-08-19T08:55:00Z | 47.0000000000 | | 2019-08-19T09:00:00Z | 84.0000000000 | | 2019-08-19T09:05:00Z | 0.0000000000 | | 2019-08-19T09:10:00Z | 41.0000000000 | | 2019-08-19T09:15:00Z | 13.0000000000 | | 2019-08-19T09:20:00Z | 9.0000000000 | | 2019-08-19T09:25:00Z | 9.0000000000 | | time | max | | --- | --- | | time | max | | 2019-09-18T16:24:00Z | 3.235 | | 2019-09-18T16:36:00Z | 3.235 | | 2019-09-18T16:48:00Z | 4 | | time | max | | --- | --- | | time | max | | 2019-09-18T16:36:00Z | | | 2019-09-18T16:48:00Z | 4 | | time | mean | | --- | --- | | time | mean | | 2019-11-11T21:24:00Z | 3 | | 2019-11-11T21:36:00Z | 4 | | 2019-11-11T21:48:00Z | 5 | | 2019-11-11T22:00:00Z | 6 | | time | mean | | --- | --- | | time | mean | | 2019-11-11T21:36:00Z | | | 2019-11-11T21:48:00Z | | | 2019-11-11T22:00:00Z | 6 | --- # LIMIT and SLIMIT clauses Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use `LIMIT` and `SLIMIT` to limit the number of [points](/influxdb/v2/reference/glossary/#point) and [series](/influxdb/v2/reference/glossary/#series) returned per query. * [LIMIT clause](#limit-clause) * [Syntax](#syntax) * [Examples](#examples) * [SLIMIT clause](#slimit-clause) * [Syntax](#syntax-1) * [Examples](#examples-2) * [Use LIMIT and SLIMIT together](#use-limit-and-slimit-together) ## LIMIT clause `LIMIT ` returns the first `N` points from the specified [measurement](/influxdb/v2/reference/glossary/#measurement). ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` `N` specifies the number of points to return from the specified measurement . If `N` is greater than the number of points in a measurement, InfluxDB returns all points from the measurement. > [!Note] > **IMPORTANT:** The `LIMIT` clause must appear in the order outlined in the syntax above. ### Examples [](#limit-the-number-of-points-returned) Limit the number of points returned ```sql SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 ``` Output: Name: h2o\_feet | time |water\_level| location | |--------------------|------------|-------------| |2019-08-17T00:00:00Z|8.1200000000|coyote\_creek| |2019-08-17T00:00:00Z|2.0640000000|santa\_monica| |2019-08-17T00:06:00Z|8.0050000000|coyote\_creek| The query returns the three oldest points, determined by timestamp, from the `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). [](#limit-the-number-of-points-returned-and-include-a-group-by-clause) Limit the number of points returned and include a `GROUP BY` clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.4615000000| |2019-08-18T00:12:00Z|8.2725000000| name: h2o\_feet tags: location=santa\_monica | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|2.3655000000| |2019-08-18T00:12:00Z|2.3360000000| This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) and a `GROUP BY` clause to calculate the average `water_level` for each [tag](/influxdb/v2/reference/glossary/#tag) and for each 12-minute interval in the queried time range. `LIMIT 2` requests the two oldest 12-minute averages (determined by timestamp). Note that without `LIMIT 2`, the query would return four points per series; one for each 12-minute interval in the queried time range. ## SLIMIT clause `SLIMIT ` returns every [point](/influxdb/v2/reference/glossary/#point) from `N` [series](//influxdb/v2/reference/glossary/#series) in the specified [measurement](/influxdb/v2/reference/glossary/#measurement). ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT ``` `N` specifies the number of series to return from the specified measurement. If `N` is greater than the number of series in a measurement, InfluxDB returns all series from that measurement. `SLIMIT` queries must include `GROUP BY *`. Note that the `SLIMIT` clause must appear in the order outlined in the syntax above. ### Examples [](#limit-the-number-of-series-returned) Limit the number of series returned ```sql SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 ``` Output: name: h2o\_feet tags: location=coyote\_creek | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|8.1200000000| |2019-08-17T00:06:00Z|8.0050000000| |2019-08-17T00:12:00Z|7.8870000000| |2019-08-17T00:18:00Z|7.7620000000| |2019-08-17T00:24:00Z|7.6350000000| |2019-08-17T00:30:00Z|7.5000000000| |2019-08-17T00:36:00Z|7.3720000000| The results above include only the first few rows, as the data set is quite large. The query returns all `water_level` [points](/influxdb/v2/reference/glossary/#point) from one of the [series](/influxdb/v2/reference/glossary/#series) associated with the `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). [](#limit-the-number-of-series-returned-and-include-a-group-by-time-clause) Limit the number of series returned and include a `GROUP BY time()` clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.4615000000| |2019-08-18T00:12:00Z|8.2725000000| |2019-08-18T00:24:00Z|8.0710000000| |2019-08-18T00:36:00Z|7.8330000000| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean)and a time interval in the [GROUP BY clause](/influxdb/v2/query-data/influxql/explore-data/group-by/)to calculate the average `water_level` for each 12-minute interval in the queried time range. `SLIMIT 1` requests a single series associated with the `h2o_feet` measurement. Note that without `SLIMIT 1`, the query would return results for the two series associated with the `h2o_feet` measurement: `location=coyote_creek` and`location=santa_monica`. ## Use LIMIT and SLIMIT together `LIMIT ` followed by `SLIMIT <2>` returns the first `N1` [points](/influxdb/v2/reference/glossary/#point) from `N2` series in the specified measurement. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT ``` `N1` specifies the number of points to return per measurement. If `N1` is greater than the number of points in a measurement, InfluxDB returns all points from that measurement. `N2` specifies the number of series to return from the specified measurement. If `N2` is greater than the number of series in a measurement, InfluxDB returns all series from that measurement. `SLIMIT` queries must include `GROUP BY *`. Note that the `SLIMIT` clause must appear in the order outlined in the syntax above. ### Examples [](#limit-the-number-of-points-and-series-returned) Limit the number of points and series returned ```sql SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 ``` Output: Name: h2o\_feet Tags: location=coyote\_creek | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|8.1200000000| |2019-08-17T00:06:00Z|8.0050000000| |2019-08-17T00:12:00Z|7.8870000000| The query returns the three oldest points, determined by timestamp, from one of the series associated with the measurement `h2o_feet`. [](#limit-the-number-of-points-and-series-returned-and-include-a-group-by-time-clause) Limit the number of points and series returned and include a `GROUP BY time()` clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 ``` Output: Name: h2o\_feet Tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.4615000000| |2019-08-18T00:12:00Z|8.2725000000| The query uses the InfluxQL function MEAN() and a time interval in the GROUP BY clause to calculate the average `water_level` for each 12-minute interval in the queried time range. `LIMIT 2` requests the two oldest 12-minute averages (determined by timestamp) and `SLIMIT 1` requests a single series associated with the `h2o_feet` measurement. Note that without `LIMIT 2 SLIMIT 1`, the query would return four points for each of the two series associated with the `h2o_feet` measurement. | time | water_level | location | | --- | --- | --- | | time | water_level | location | | 2019-08-17T00:00:00Z | 8.1200000000 | coyote_creek | | 2019-08-17T00:00:00Z | 2.0640000000 | santa_monica | | 2019-08-17T00:06:00Z | 8.0050000000 | coyote_creek | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.4615000000 | | 2019-08-18T00:12:00Z | 8.2725000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 2.3655000000 | | 2019-08-18T00:12:00Z | 2.3360000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.1200000000 | | 2019-08-17T00:06:00Z | 8.0050000000 | | 2019-08-17T00:12:00Z | 7.8870000000 | | 2019-08-17T00:18:00Z | 7.7620000000 | | 2019-08-17T00:24:00Z | 7.6350000000 | | 2019-08-17T00:30:00Z | 7.5000000000 | | 2019-08-17T00:36:00Z | 7.3720000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.4615000000 | | 2019-08-18T00:12:00Z | 8.2725000000 | | 2019-08-18T00:24:00Z | 8.0710000000 | | 2019-08-18T00:36:00Z | 7.8330000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.1200000000 | | 2019-08-17T00:06:00Z | 8.0050000000 | | 2019-08-17T00:12:00Z | 7.8870000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.4615000000 | | 2019-08-18T00:12:00Z | 8.2725000000 | --- # OFFSET and SOFFSET clauses Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use `OFFSET` and `SOFFSET` to paginate [points](/influxdb/v2/reference/glossary/#point) and [series](/influxdb/v2/reference/glossary/#series) returned. * [OFFSET clause](#offset-clause) * [Syntax](#syntax) * [Examples](#examples) * [The SOFFSET clause](#soffset-clause) * [Syntax](#syntax-1) * [Examples](#examples-1) ## `OFFSET` clause `OFFSET ` paginates `N` [points](/influxdb/v2/reference/glossary/#point) in the query results. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` `N` specifies the number of points to paginate. The `OFFSET` clause requires a [`LIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/#limit-clause). > [!Note] > **Note:** InfluxDB returns no results if the `WHERE clause` includes a time range and the `OFFSET clause` would cause InfluxDB to return points with timestamps outside of that time range. ### Examples [](#paginate-points) Paginate points ```sql SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 ``` Output: Name: h2o\_feet | time |water\_level| location | |--------------------|------------|-------------| |2019-08-17T00:06:00Z|2.1160000000|santa\_monica| |2019-08-17T00:12:00Z|7.8870000000|coyote\_creek| |2019-08-17T00:12:00Z|2.0280000000|santa\_monica| The query returns the fourth, fifth, and sixth points from the `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). If the query did not include `OFFSET 3`, it would return the first, second, and third points from that measurement. [](#paginate-points-and-include-several-clauses) Paginate points and include several clauses ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:12:00Z|8.2725000000| |2019-08-18T00:00:00Z|8.4615000000| In this example: * The [`SELECT clause`](/influxdb/v2/query-data/influxql/explore-data/select/) specifies the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean). * The [`FROM clause`] (/influxdb/v2/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. * The [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/) specifies the time range for the query. * The [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. * The [`ORDER BY time DESC` clause](/influxdb/v2/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. * The [`LIMIT 2` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) limits the number of points returned to two. * The `OFFSET 2` clause excludes the first two averages from the query results. * The [`SLIMIT 1` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) limits the number of series returned to one. Without `OFFSET 2`, the query would return the first two averages of the query results: Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:36:00Z|7.8330000000| |2019-08-18T00:24:00Z|8.0710000000| ## `SOFFSET` clause `SOFFSET ` paginates `N` [series](/influxdb/v2/reference/glossary/#series) in the query results. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET ``` `N` specifies the number of [series](/influxdb/v2/reference/glossary/#series) to paginate. The `SOFFSET` clause requires an [`SLIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/. Using the `SOFFSET` clause without an `SLIMIT` clause can cause [inconsistent query results](https://github.com/influxdata/influxdb/issues/7578).`SLIMIT` queries must include `GROUP BY *`. > [!Note] > **Note:** InfluxDB returns no results if the `SOFFSET` clause paginates through more than the total number of series. ### Examples [](#paginate-series) Paginate series #### Paginate series ```sql SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 ``` Output: name: h2o\_feet tags: location=santa\_monica | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|2.1260000000| |2019-08-17T00:24:00Z|2.0410000000| |2019-08-17T00:30:00Z|2.0510000000| |2019-08-17T00:36:00Z|2.0670000000| |2019-08-17T00:42:00Z|2.0570000000| The results above are partial, as the data set is quite large. The query returns data for the series associated with the `h2o_feet`measurement and the `location = santa_monica` tag. Without `SOFFSET 1`, the query returns data for the series associated with the `h2o_feet` measurement and the `location = coyote_creek` tag. [](#paginate-points-and-include-several-clauses) Paginate points and include several clauses #### Paginate series and include all clauses ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 ``` Output: name: h2o\_feet tags: location=santa\_monica | time | mean | |--------------------|------------| |2019-08-18T00:12:00Z|2.3360000000| |2019-08-18T00:00:00Z|2.3655000000| In this example: * The [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/) specifies an InfluxQL [function](/influxdb/v2/query-data/influxql/functions/). * The [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. * The [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/) specifies the time range for the query. * The [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. * The [`ORDER BY time DESC` clause](/influxdb/v2/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. * The [`LIMIT 2` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) limits the number of points returned to two. * The [`OFFSET 2` clause](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) excludes the first two averages from the query results. * The [`SLIMIT 1` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) limits the number of series returned to one. * The [`SOFFSET 1`](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) clause paginates the series returned. Without `SOFFSET 1`, the query would return the results for a different series: Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:12:00Z|8.2725000000| |2019-08-18T00:00:00Z|8.4615000000| | time | water_level | location | | --- | --- | --- | | time | water_level | location | | 2019-08-17T00:06:00Z | 2.1160000000 | santa_monica | | 2019-08-17T00:12:00Z | 7.8870000000 | coyote_creek | | 2019-08-17T00:12:00Z | 2.0280000000 | santa_monica | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:12:00Z | 8.2725000000 | | 2019-08-18T00:00:00Z | 8.4615000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:36:00Z | 7.8330000000 | | 2019-08-18T00:24:00Z | 8.0710000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | 2019-08-17T00:24:00Z | 2.0410000000 | | 2019-08-17T00:30:00Z | 2.0510000000 | | 2019-08-17T00:36:00Z | 2.0670000000 | | 2019-08-17T00:42:00Z | 2.0570000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:12:00Z | 2.3360000000 | | 2019-08-18T00:00:00Z | 2.3655000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:12:00Z | 8.2725000000 | | 2019-08-18T00:00:00Z | 8.4615000000 | --- # ORDER BY clause Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/order-by/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `ORDER BY` clause to sort data. * [Syntax](#syntax) * [Examples](#examples) ## ORDER BY time DESC By default, InfluxDB returns results in ascending time order; the first [point](/influxdb/v2/reference/glossary/#point)returned has the oldest [timestamp](/influxdb/v2/reference/glossary/#timestamp) and the last point returned has the most recent timestamp.`ORDER BY time DESC` reverses that order such that InfluxDB returns the points with the most recent timestamps first. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC ``` If the query includes a `GROUP BY` clause, `ORDER by time DESC` must appear **after** the `GROUP BY` clause. If the query includes a `WHERE` clause and no `GROUP BY` clause, `ORDER by time DESC` must appear **after** the `WHERE` clause. ### Examples [](#return-the-newest-points-first) Return the newest points first ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-09-17T21:42:00Z|4.9380000000| |2019-09-17T21:36:00Z|5.0660000000| |2019-09-17T21:30:00Z|5.0100000000| |2019-09-17T21:24:00Z|5.0130000000| |2019-09-17T21:18:00Z|5.0720000000| The query returns the points with the most recent timestamps from the`h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement) first. Without `ORDER by time DESC`, the query would return the following output: Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|2.1260000000| [](#return-the-newest-points-first-and-include-a-group-by-time-clause) Return the newest points first and include a `GROUP BY time()` clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:36:00Z|4.9712860355| |2019-08-18T00:24:00Z|5.1682500000| |2019-08-18T00:12:00Z|5.3042500000| |2019-08-18T00:00:00Z|5.4135000000| The query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean)and a time interval in the [GROUP BY clause](/influxdb/v2/query-data/influxql/explore-data/group-by/)to calculate the average `water_level` for each 12-minute interval in the queried time range.[`ORDER BY time DESC`](/influxdb/v2/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns the most recent 12-minute time intervals first. Without `ORDER BY time DESC`, the query would return the following output: Output: Name: h2o\_feet | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|5.4135000000| |2019-08-18T00:12:00Z|5.3042500000| |2019-08-18T00:24:00Z|5.1682500000| |2019-08-18T00:36:00Z|4.9712860355| | time | water_level | | --- | --- | | time | water_level | | 2019-09-17T21:42:00Z | 4.9380000000 | | 2019-09-17T21:36:00Z | 5.0660000000 | | 2019-09-17T21:30:00Z | 5.0100000000 | | 2019-09-17T21:24:00Z | 5.0130000000 | | 2019-09-17T21:18:00Z | 5.0720000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:36:00Z | 4.9712860355 | | 2019-08-18T00:24:00Z | 5.1682500000 | | 2019-08-18T00:12:00Z | 5.3042500000 | | 2019-08-18T00:00:00Z | 5.4135000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 5.4135000000 | | 2019-08-18T00:12:00Z | 5.3042500000 | | 2019-08-18T00:24:00Z | 5.1682500000 | | 2019-08-18T00:36:00Z | 4.9712860355 | --- # Regular expressions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/regular-expressions/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxQL supports using regular expressions when specifying: * [field keys](/influxdb/v2/reference/glossary/#field-key) and [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/). * [measurements](/influxdb/v2/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause). * [tag values](/influxdb/v2/reference/glossary/#tag-value) and string [field values](/influxdb/v2/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/). * [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) Regular expressions in InfluxQL only support string comparisons and can only evaluate [fields](/influxdb/v2/reference/glossary/#field) with string values. > [!Note] > **Note:** Regular expression comparisons are more computationally intensive than exact > string comparisons. Queries with regular expressions are not as performant > as those without. * [Syntax](#syntax) * [Examples](#examples) ## Syntax ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` Regular expressions are surrounded by `/` characters and use the[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). ## Supported operators `=~`: matches against`!~`: doesn’t match against ### Examples [](#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 /l/ FROM "h2o_feet" LIMIT 1 ``` Output: Name: h2o\_feet | time |level description| location |water\_level| |--------------------|-----------------|-------------|------------| |2019-08-17T00:00:00Z| below 3 feet |santa\_monica|2.0640000000| The query selects all field keys and tag keys that include an `l`. Note that the regular expression in the `SELECT` clause must match at least one field key in order to return results for a tag key that matches the regular expression. Currently, there is no syntax to distinguish between regular expressions for field keys and regular expressions for tag keys in the `SELECT` clause. The syntax `//::[field | tag]` is not supported. [](#use-a-regular-expression-to-specify-field-keys-and-tag-keys-in-function-arguments) Use a regular expression to specify field keys and tag keys in function arguments ```sql SELECT MAX(/_level/) FROM "h2o_feet" LIMIT 1 ``` Output: Name: h2o\_feet | time |max\_water\_level| |--------------------|-----------------| |2019-08-28T07:24:00Z| 9.964 | This query uses the InfluxQL [`MAX()` selector function](/influxdb/v2/query-data/influxql/functions/selectors/#max)to find the greatest field value out of all field keys that match the regular expression. [](#use-a-regular-expression-to-specify-measurements-in-the-from-clause) Use a regular expression to specify measurements in the FROM clause ```sql SELECT MEAN("degrees") FROM /temperature/ ``` Output: Name: average\_temperature | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|79.9847293223| Name: h2o\_feet | time | mean | |--------------------|-------------| |1970-01-01T00:00:00Z|64.9980273540| This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `degrees` for every [measurement](/influxdb/v2/reference/glossary/#measurement) in the [NOAA sample data] that contains the word `temperature`. [](#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 MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4710766395| This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level` where the [tag value](/influxdb/v2/reference/glossary/#measurement) of `location` includes an `m` and `water_level` is greater than three. [](#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 "h2o_feet" WHERE "location" !~ /./ > ``` The query selects all data from the `h2o_feet` measurement where the `location`[tag](/influxdb/v2/reference/glossary/#tag) has no value. Every data [point](/influxdb/v2/reference/glossary/#point) in the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data) has a tag value for `location`. It’s possible to perform this same query without a regular expression. See the [Frequently Asked Questions](/influxdb/v2/reference/faq/#how-do-i-query-data-by-a-tag-with-a-null-value)document for more information. [](#use-a-regular-expression-to-specify-a-tag-with-a-value-in-the-where-clause) Use a regular expression to specify a tag with a value in the WHERE clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4418434585| This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level` across all data with a tag value for `location`. [](#use-a-regular-expression-to-specify-a-field-value-in-the-where-clause) Use a regular expression to specify a field value in the WHERE clause ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4713666916| This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean)to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. [](#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 FIRST("index") FROM "h2o_quality" GROUP BY /l/ ``` Output: name: h2o\_quality tags: location=coyote\_creek | time | mean | |--------------------|-------------| |2019-08-17T00:00:00Z|41.0000000000| name: h2o\_quality tags: location=santa\_monica | time | mean | |--------------------|-------------| |2019-08-17T00:00:00Z|99.0000000000| This query uses the InfluxQL [FIRST() function](/influxdb/v2/query-data/influxql/functions/selectors/#first) to select the first value of `index` for every tag that includes the letter `l`in its tag key. | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | time | max_water_level | | --- | --- | | time | max_water_level | | 2019-08-28T07:24:00Z | 9.964 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 79.9847293223 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 64.9980273540 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4710766395 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4418434585 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4713666916 | | time | mean | | --- | --- | | time | mean | | 2019-08-17T00:00:00Z | 41.0000000000 | | time | mean | | --- | --- | | time | mean | | 2019-08-17T00:00:00Z | 99.0000000000 | --- # SELECT statement Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/select/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `SELECT` statement to query data from a particular [measurement](/influxdb/v2/reference/glossary/#measurement) or measurements. * [Syntax](#syntax) * [Examples](#examples) * [Common issues](#common-issues-with-the-select-statement) * [Regular expressions](#regular-expressions) * [Data types and cast operations](#data-types-and-cast-operations) * [Merge behavior](#merge-behavior) * [Multiple statements](#multiple-statements) ## Syntax ```sql SELECT [,,] FROM [,] ``` > [!Note] > **Note:** The `SELECT` statement **requires** a `SELECT` clause and a `FROM` clause. ### `SELECT` clause The `SELECT` clause supports several formats for specifying data: * `SELECT *` - Returns all [fields](/influxdb/v2/reference/glossary/#field) and [tags](/influxdb/v2/reference/glossary/#tag). * `SELECT ""` - Returns a specific field. * `SELECT "",""` - Returns more than one field. * `SELECT "",""` - Returns a specific field and tag. The `SELECT` clause must specify at least one field when it includes a tag. * `SELECT ""::field,""::tag` - Returns a specific field and tag. The `::[field | tag]` syntax specifies the [identifier’s](/influxdb/v2/reference/syntax/influxql/spec/#identifiers) type. Use this syntax to differentiate between field keys and tag keys with the same name. Other supported features include: * [Functions](/influxdb/v2/query-data/influxql/functions/) * [Basic cast operations](#data-types-and-cast-operations) * [Regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) > [!Note] > **Note:** The SELECT statement cannot include an aggregate function **and** a non-aggregate function, field key, or tag key. 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). ### `FROM` clause The `SELECT` clause specifies the measurement to query. This clause supports several formats for specifying a [measurement](/influxdb/v2/reference/glossary/#measurement): * `FROM ` - Returns data from a measurement. * `FROM ,` - Returns data from more than one measurement. * `FROM ..` - Returns data from a fully qualified measurement. * `FROM ..` - Returns data from a measurement. #### Quoting [Identifiers](/influxdb/v2/reference/syntax/influxql/spec/#identifiers) **must** be double quoted if they contain characters other than `[A-z,0-9,_]`, begin with a digit, or are an [InfluxQL keyword](https://github.com/influxdata/influxql/blob/master/README.md#keywords). While not always necessary, we recommend that you double quote identifiers. > [!Note] > **Note:** InfluxQL quoting guidelines differ from [line protocol quoting guidelines](/influxdb/v2/reference/syntax/line-protocol/#quotes). > Please review the [rules for single and double-quoting](/influxdb/v2/reference/syntax/line-protocol/#quotes) in queries. ### Examples [](#select-all-fields-and-tags-from-a-measurement) Select all fields and tags from a measurement ```sql SELECT * FROM "h2o_feet" ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |---------------------|--------------------|-------------|------------| |2019-08-17T00:00:00Z | below 3 feet |santa\_monica|2.0640000000| |2019-08-17T00:00:00Z |between 6 and 9 feet|coyote\_creek|8.1200000000| |2019-08-17T00:06:00Z | below 3 feet |santa\_monica|2.1160000000| |2019- 08-17T00:06:00Z|between 6 and 9 feet|coyote\_creek|8.0050000000| |2019-08-17T00:12:00Z | below 3 feet |santa\_monica|2.0280000000| |2019-08-17T00:12:00Z |between 6 and 9 feet|coyote\_creek|7.8870000000| |2019-08-17T00:18:00Z | below 3 feet |santa\_monica|2.1260000000| The data above is a partial listing of the query output, as the result set is quite large. The query selects all [fields](/influxdb/v2/reference/glossary/#field) and[tags](/influxdb/v2/reference/glossary/#tag) from the `h2o_feet`[measurement](/influxdb/v2/reference/glossary/#measurement). [](#select-specific-tags-and-fields-from-a-measurement) Select specific tags and fields from a measurement ```sql SELECT "level description","location","water_level" FROM "h2o_feet" ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |--------------------|--------------------|-------------|------------| |2019-08-17T00:00:00Z| below 3 feet |santa\_monica|2.0640000000| |2019-08-17T00:00:00Z|between 6 and 9 feet|coyote\_creek|8.1200000000| The query selects the `level description` field, the `location` tag, and the`water_level` field. > [!Note] > **Note:** The `SELECT` clause must specify at least one field when it includes > a tag. [](#select-specific-tags-and-fields-from-a-measurement-and-provide-their-identifier-type) Select specific tags and fields from a measurement and provide their identifier type ```sql SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |--------------------|--------------------|-------------|------------| |2019-08-17T00:24:00Z|between 6 and 9 feet|coyote\_creek|7.6350000000| |2019-08-17T00:30:00Z| below 3 feet |santa\_monica|2.0510000000| |2019-08-17T00:30:00Z|between 6 and 9 feet|coyote\_creek|7.5000000000| |2019-08-17T00:36:00Z| below 3 feet |santa\_monica|2.0670000000| |2019-08-17T00:36:00Z|between 6 and 9 feet|coyote\_creek|7.3720000000| |2019-08-17T00:42:00Z| below 3 feet |santa\_monica|2.0570000000| The query selects the `level description` field, the `location` tag, and the`water_level` field from the `h2o_feet` measurement. The `::[field | tag]` syntax specifies if the[identifier](/influxdb/v2/reference/syntax/influxql/spec/#identifiers) is a field or tag. Use `::[field | tag]` to differentiate between [an identical field key and tag key ](/v2.4/reference/faq/#how-do-i-query-data-with-an-identical-tag-key-and-field-key). That syntax is not required for most use cases. [](#select-all-fields-from-a-measurement) Select all fields from a measurement ```sql SELECT *::field FROM "h2o_feet" ``` Output: Name: h2o\_feet | time | level description |water\_level| |--------------------|--------------------|------------| |2019-08-17T00:00:00Z| below 3 feet |2.0640000000| |2019-08-17T00:00:00Z|between 6 and 9 feet|8.1200000000| |2019-08-17T00:06:00Z| below 3 feet |2.1160000000| |2019-08-17T00:06:00Z|between 6 and 9 feet|8.0050000000| |2019-08-17T00:12:00Z| below 3 feet |2.0280000000| |2019-08-17T00:12:00Z|between 6 and 9 feet|7.8870000000| The query selects all fields from the `h2o_feet` measurement. The `SELECT` clause supports combining the `*` syntax with the `::` syntax. [](#select-a-specific-field-from-a-measurement-and-perform-basic-arithmetic) Select a specific field from a measurement and perform basic arithmetic ```sql SELECT ("water_level" * 2) + 4 FROM "h2o_feet" ``` Output: Name: h2o\_feet | time |water\_level | |--------------------|-------------| |2019-08-17T00:00:00Z|20.2400000000| |2019-08-17T00:00:00Z|8.1280000000 | |2019-08-17T00:06:00Z|20.0100000000| |2019-08-17T00:06:00Z|8.2320000000 | |2019-08-17T00:12:00Z|19.7740000000| |2019-08-17T00:12:00Z|8.0560000000 | The query multiplies `water_level`’s field values by two and adds four to those values. > [!Note] > **Note:** InfluxDB follows the standard order of operations. > See [InfluxQL mathematical operators](/influxdb/v2/query-data/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 "h2o_feet","h2o_pH" ``` Output: Name: h2o\_feet | time | level description | location |pH |water\_level| |--------------------|--------------------|-------------|---|------------| |2019-08-17T00:00:00Z| below 3 feet |santa\_monica| |2.0640000000| |2019-08-17T00:00:00Z|between 6 and 9 feet|coyote\_creek| |8.1200000000| |2019-08-17T00:06:00Z| below 3 feet |santa\_monica| |2.1160000000| |2019-08-17T00:06:00Z|between 6 and 9 feet|coyote\_creek| |8.0050000000| |2019-08-17T00:12:00Z| below 3 feet |santa\_monica| |2.0280000000| |2019-08-17T00:12:00Z|between 6 and 9 feet|coyote\_creek| |7.8870000000| |2019-08-17T00:18:00Z| below 3 feet |santa\_monica| |2.1260000000| |2019-08-17T00:18:00Z|between 6 and 9 feet|coyote\_creek| |7.7620000000| Name: h2o\_pH | time |level description| location | pH |water\_level| |--------------------|-----------------|-------------|----|------------| |2019-08-17T00:00:00Z| |coyote\_creek|7.00| | |2019-08-17T00:06:00Z| |coyote\_creek|8.00| | |2019-08-17T00:06:00Z| |santa\_monica|6.00| | |2019-08-17T00:12:00Z| |coyote\_creek|8.00| | The query selects all fields and tags from two measurements: `h2o_feet` and`h2o_pH`. Separate multiple measurements with a comma (`,`). [](#select-all-data-from-a-measurement-in-a-particular-database) Select all data from a measurement in a particular database ```sql SELECT * FROM noaa.."h2o_feet" ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |---------------------|--------------------|-------------|------------| |2019-08-17T00:00:00Z | below 3 feet |santa\_monica|2.0640000000| |2019-08-17T00:00:00Z |between 6 and 9 feet|coyote\_creek|8.1200000000| |2019-08-17T00:06:00Z | below 3 feet |santa\_monica|2.1160000000| |2019- 08-17T00:06:00Z|between 6 and 9 feet|coyote\_creek|8.0050000000| |2019-08-17T00:12:00Z | below 3 feet |santa\_monica|2.0280000000| |2019-08-17T00:12:00Z |between 6 and 9 feet|coyote\_creek|7.8870000000| The query selects data from the `h2o_feet` measurement in the `noaa` database. The `..` indicates the `DEFAULT` retention policy for the specified database. ## Common issues with the SELECT statement ### Selecting tag keys in the SELECT statement A query requires at least one [field key](/influxdb/v2/reference/glossary/#field-key)in the `SELECT` clause to return data. If the `SELECT` clause only includes a single [tag key](/influxdb/v2/reference/glossary/#tag-key) or several tag keys, the query returns an empty response. #### Example The following query returns no data because it specifies a single tag key (`location`) in the `SELECT` clause: ```sql SELECT "location" FROM "h2o_feet" > No results ``` To return any data associated with the `location` tag key, the query’s `SELECT`clause must include at least one field key (`water_level`): ```sql SELECT "water_level","location" FROM "h2o_feet" ``` Output: Name: h2o\_feet | time |water\_level| location | |---------------------|------------|-------------| |2019-08-17T00:00:00Z |8.1200000000|coyote\_creek| |2019-08-17T00:00:00Z |2.0640000000|santa\_monica| |2019-08-17T 00:06:00Z|8.0050000000|coyote\_creek| |2019-08-17T00:06:00Z |2.1160000000|santa\_monica| |2019-08-17T00:12:00Z |7.8870000000|coyote\_creek| |2019-08-17T00:12:00Z |2.0280000000|santa\_monica| |2019-08-17T00:18:00Z |7.7620000000|coyote\_creek| |2019-08-17T00:18:00Z |2.1260000000|santa\_monica| ## Regular expressions InfluxQL supports using [regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) when specifying: * [field keys](/influxdb/v2/reference/glossary/#field-key) and [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/) * [measurements](/influxdb/v2/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause) * [tag values](/influxdb/v2/reference/glossary/#tag-value) and string [field values](/influxdb/v2/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/). * [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) ## Syntax ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` See [regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) for more information. ## Data types and cast operations The [`SELECT` clause](#select-clause) supports specifying a [field’s](/influxdb/v2/reference/glossary/#field) type and basic cast operations with the `::` syntax. * [Data types](#data-types) * [Cast operations](#cast-operations) ### Data types [Field values](/influxdb/v2/reference/glossary/#field-value) can be floats, integers, strings, or booleans. The `::` syntax allows users to specify the field’s type in a query. > [!Note] > **Note:** Generally, it is not necessary to specify the field value type in the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/). In most cases, InfluxDB rejects any writes that attempt to write a [field value](/influxdb/v2/reference/glossary/#field-value) to a field that previously accepted field values of a different type. It is possible for field value types to differ across [shard groups](/influxdb/v2/reference/glossary/#shard-group). In these cases, it may be necessary to specify the field value type in the`SELECT` clause. Please see the[Frequently Asked Questions](/influxdb/v2/reference/faq/#how-does-influxdb-handle-field-type-discrepancies-across-shards)document for more information on how InfluxDB handles field value type discrepancies. ### Syntax ```sql SELECT_clause :: FROM_clause ``` `type` can be `float`, `integer`, `string`, or `boolean`. In most cases, InfluxDB returns no data if the `field_key` does not store data of the specified`type`. See [Cast Operations](#cast-operations) for more information. ### Example ```sql SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|8.1200000000| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|8.0050000000| |2019-08-17T00:06:00Z|2.1160000000| The query returns values of the `water_level` field key that are floats. ## Cast operations The `::` syntax allows users to perform basic cast operations in queries. Currently, InfluxDB supports casting [field values](/influxdb/v2/reference/glossary/#field-value) from integers to floats or from floats to integers. ### Syntax ```sql SELECT_clause :: FROM_clause ``` `type` can be `float` or `integer`. InfluxDB returns no data if the query attempts to cast an integer or float to a string or boolean. ### Examples [](#cast-float-field-values-to-integers) Cast float field values to integers ```sql SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|8.0000000000| |2019-08-17T00:00:00Z|2.0000000000| |2019-08-17T00:06:00Z|8.0000000000| |2019-08-17T00:06:00Z|2.0000000000| The query returns the integer form of `water_level`’s float [field values](/influxdb/v2/reference/glossary/#field-value). [](#cast-float-field-values-to-strings-this-functionality-is-not-supported) Cast float field values to strings (this functionality is not supported) ```sql SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 > No results ``` The query returns no data as casting a float field value to a string is not yet supported. ## Merge behavior InfluxQL merges [series](/influxdb/v2/reference/glossary/#series) automatically. ### Example [](#merge-behavior) Merge behavior The `h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement) in the `noaa` is part of two [series](/influxdb/v2/reference/glossary/#series). The first series is made up of the `h2o_feet` measurement and the `location = coyote_creek` [tag](/influxdb/v2/reference/glossary/#tag). The second series is made of up the `h2o_feet` measurement and the `location = santa_monica` tag. The following query automatically merges those two series when it calculates the average `water_level` using the [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean): ```sql SELECT MEAN("water_level") FROM "h2o_feet" ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4419314021| If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/): ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|5.3591424203| If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/): ```sql SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|5.3591424203| name: h2o\_feet tags: location=santa\_monica | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|3.5307120942| ## Multiple statements Separate multiple `SELECT` statements in a query with a semicolon (`;`). ### Examples [InfluxQL shell](#influxql-shell)[InfluxDB API](#influxdb-api) In the [InfluxQL shell](/influxdb/v2/tools/influxql-shell/): ```sql SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 ``` Output: Name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4419314021| Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z| 8.12 | |2015-08-18T00:00:00Z| 2.064 | With the [InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/): ```json { "results": [ { "statement_id": 0, "series": [ { "name": "h2o_feet", "columns": [ "time", "mean" ], "values": [ [ "1970-01-01T00:00:00Z", 4.442107025822522 ] ] } ] }, { "statement_id": 1, "series": [ { "name": "h2o_feet", "columns": [ "time", "water_level" ], "values": [ [ "2015-08-18T00:00:00Z", 8.12 ], [ "2015-08-18T00:00:00Z", 2.064 ] ] } ] } ] } ``` | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000 | | 2019-08-17T00:06:00Z | below 3 feet | santa_monica | 2.1160000000 | | 2019- 08-17T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.0050000000 | | 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000 | | 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.8870000000 | | 2019-08-17T00:18:00Z | below 3 feet | santa_monica | 2.1260000000 | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000 | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:24:00Z | between 6 and 9 feet | coyote_creek | 7.6350000000 | | 2019-08-17T00:30:00Z | below 3 feet | santa_monica | 2.0510000000 | | 2019-08-17T00:30:00Z | between 6 and 9 feet | coyote_creek | 7.5000000000 | | 2019-08-17T00:36:00Z | below 3 feet | santa_monica | 2.0670000000 | | 2019-08-17T00:36:00Z | between 6 and 9 feet | coyote_creek | 7.3720000000 | | 2019-08-17T00:42:00Z | below 3 feet | santa_monica | 2.0570000000 | | time | level description | water_level | | --- | --- | --- | | time | level description | water_level | | 2019-08-17T00:00:00Z | below 3 feet | 2.0640000000 | | 2019-08-17T00:00:00Z | between 6 and 9 feet | 8.1200000000 | | 2019-08-17T00:06:00Z | below 3 feet | 2.1160000000 | | 2019-08-17T00:06:00Z | between 6 and 9 feet | 8.0050000000 | | 2019-08-17T00:12:00Z | below 3 feet | 2.0280000000 | | 2019-08-17T00:12:00Z | between 6 and 9 feet | 7.8870000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 20.2400000000 | | 2019-08-17T00:00:00Z | 8.1280000000 | | 2019-08-17T00:06:00Z | 20.0100000000 | | 2019-08-17T00:06:00Z | 8.2320000000 | | 2019-08-17T00:12:00Z | 19.7740000000 | | 2019-08-17T00:12:00Z | 8.0560000000 | | time | level description | location | pH | water_level | | --- | --- | --- | --- | --- | | time | level description | location | pH | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | | 2.0640000000 | | 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | | 8.1200000000 | | 2019-08-17T00:06:00Z | below 3 feet | santa_monica | | 2.1160000000 | | 2019-08-17T00:06:00Z | between 6 and 9 feet | coyote_creek | | 8.0050000000 | | 2019-08-17T00:12:00Z | below 3 feet | santa_monica | | 2.0280000000 | | 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | | 7.8870000000 | | 2019-08-17T00:18:00Z | below 3 feet | santa_monica | | 2.1260000000 | | 2019-08-17T00:18:00Z | between 6 and 9 feet | coyote_creek | | 7.7620000000 | | time | level description | location | pH | water_level | | --- | --- | --- | --- | --- | | time | level description | location | pH | water_level | | 2019-08-17T00:00:00Z | | coyote_creek | 7.00 | | | 2019-08-17T00:06:00Z | | coyote_creek | 8.00 | | | 2019-08-17T00:06:00Z | | santa_monica | 6.00 | | | 2019-08-17T00:12:00Z | | coyote_creek | 8.00 | | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000 | | 2019-08-17T00:06:00Z | below 3 feet | santa_monica | 2.1160000000 | | 2019- 08-17T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.0050000000 | | 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000 | | 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.8870000000 | | time | water_level | location | | --- | --- | --- | | time | water_level | location | | 2019-08-17T00:00:00Z | 8.1200000000 | coyote_creek | | 2019-08-17T00:00:00Z | 2.0640000000 | santa_monica | | 2019-08-17T 00:06:00Z | 8.0050000000 | coyote_creek | | 2019-08-17T00:06:00Z | 2.1160000000 | santa_monica | | 2019-08-17T00:12:00Z | 7.8870000000 | coyote_creek | | 2019-08-17T00:12:00Z | 2.0280000000 | santa_monica | | 2019-08-17T00:18:00Z | 7.7620000000 | coyote_creek | | 2019-08-17T00:18:00Z | 2.1260000000 | santa_monica | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.1200000000 | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 8.0050000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.0000000000 | | 2019-08-17T00:00:00Z | 2.0000000000 | | 2019-08-17T00:06:00Z | 8.0000000000 | | 2019-08-17T00:06:00Z | 2.0000000000 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4419314021 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 5.3591424203 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 5.3591424203 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 3.5307120942 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4419314021 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.12 | | 2015-08-18T00:00:00Z | 2.064 | --- # Subqueries Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/subqueries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A subquery is a query that is nested in the `FROM` clause of another query. Use a subquery to apply a query as a condition in the enclosing query. Subqueries offer functionality similar to nested functions and the SQL [`HAVING` clause](https://en.wikipedia.org/wiki/Having_%28SQL%29). > [!Note] > **Note:** InfluxQL does not support a `HAVING` clause. * [Syntax](#syntax) * [Examples](#examples) * [Common Issues](#common-issues-with-subqueries) ### Syntax ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` InfluxDB **performs the subquery first** and the main query second. The main query surrounds the subquery and requires at least the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/) and the [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause). The main query supports all clauses listed in InfluxQL 2.x documentation. The subquery appears in the main query’s `FROM` clause, and it requires surrounding parentheses. The subquery also supports all clauses listed in InfluxQL 2.x documentation. InfluxQL supports multiple nested subqueries per main query. Sample syntax for multiple subqueries: ```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` > [!Note] > **Note:** #### Improve performance of time-bound subqueries > To improve the performance of InfluxQL queries with time-bound subqueries, > apply the `WHERE time` clause to the outer query instead of the inner query. > For example, the following queries return the same results, but **the query with > time bounds on the outer query is more performant than the query with time > bounds on the inner query**: > > ##### Time bounds on the outer query (recommended) > > ``` > SELECT inner_value AS value FROM (SELECT raw_value as inner_value) > WHERE time >= '2022-07-19T21:00:00Z' > AND time <= '2022-07-20T22:00:00Z' > ``` > > ##### Time bounds on the inner query > > ``` > SELECT inner_value AS value FROM ( > SELECT raw_value as inner_value > WHERE time >= '2022-07-19T21:00:00Z' > AND time <= '2022-07-20T22:00:00Z' > ) > ``` ### Examples [](#calculate-the-sum-of-several-max-values) Calculate the SUM() of several MAX() values ```sql SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") ``` Output: Name: h2o\_feet | time | sum | |--------------------|------| |1970-01-01T00:00:00Z|17.169| The query returns the sum of the maximum `water_level` values across every tag value of `location`. InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: ```sql SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time | max | |--------------------|------------| |2015-08-29T07:24:00Z|9.9640000000| name: h2o\_feet tags: location=santa\_monica | time | max | |--------------------|------------| |2015-08-29T03:54:00Z|7.2050000000| Next, InfluxDB performs the main query and calculates the sum of those maximum values: `9.9640000000` + `7.2050000000` = `17.169`. Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. [](#calculate-the-mean-difference-between-two-fields) Calculate the MEAN() difference between two fields ```sql SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") ``` Output: Name: pet\_daycare | time |max | |--------------------|----| |1970-01-01T00:00:00Z|1.75| The query returns the average of the differences between the number of `cats` and `dogs` in the `pet_daycare` measurement. InfluxDB first performs the subquery. The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, and it names the output column `difference`: ```sql SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" ``` Output: Name: pet\_daycare | time |difference| |--------------------|----------| |2017-01-20T00:55:56Z| \-1 | |2017-01-21T00:55:56Z| \-49 | |2017-01-22T00:55:56Z| 66 | |2017-01-23T00:55:56Z| \-9 | Next, InfluxDB performs the main query and calculates the average of those differences. Notice that the main query specifies `difference` as the field key in the [`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) function. [](#calculate-several-mean-values-and-place-a-condition-on-those-mean-values) Calculate several MEAN() values and place a condition on those mean values ```sql SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 ``` Output: Name: h2o\_feet | time |all\_the\_means| |--------------------|---------------| |2019-08-18T00:00:00Z| 5.4135000000 | |2019-08-18T00:12:00Z| 5.3042500000 | |2019-08-18T00:24:00Z| 5.1682500000 | The query returns all mean values of the `water_level` field that are greater than five. InfluxDB first performs the subquery. The subquery calculates `MEAN()` values of `water_level` from `2019-08-18T00:00:00Z` through `2019-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: ```sql SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` Output: Name: h2o\_feet | time |all\_the\_means| |--------------------|---------------| |2019-08-18T00:00:00Z| 5.4135000000 | |2019-08-18T00:12:00Z| 5.3042500000 | |2019-08-18T00:24:00Z| 5.1682500000 | Next, InfluxDB performs the main query and returns only those mean values that are greater than five. Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. [](#calculate-the-sum-of-several-derivative-values) Calculate the SUM() of several DERIVATIVE() values ```sql SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time |sum\_derivative| |--------------------|---------------| |1970-01-01T00:00:00Z|\-0.5315000000 | name: h2o\_feet tags: location=santa\_monica | time |sum\_derivative| |--------------------|---------------| |1970-01-01T00:00:00Z|\-0.2375000000 | The query returns the sum of the derivative of average `water_level` values for each tag value of `location`. InfluxDB first performs the subquery. The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: ```sql SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location" ``` Output: name: h2o\_feet tags: location=coyote\_creek | time |water\_level\_derivative| |--------------------|------------------------| |2019-08-18T00:00:00Z| \-0.1410000000 | |2019-08-18T00:12:00Z| \-0.1890000000 | |2019-08-18T00:24:00Z| \-0.2015000000 | name: h2o\_feet tags: location=santa\_monica | time |water\_level\_derivative| |--------------------|------------------------| |2019-08-18T00:00:00Z| \-0.1375000000 | |2019-08-18T00:12:00Z| \-0.0295000000 | |2019-08-18T00:24:00Z| \-0.0705000000 | Next, InfluxDB performs the main query and calculates the sum of the `water_level_derivative` values for each tag value of `location`. Notice that the main query specifies `water_level_derivative`, not `water_level` or `derivative`, as the field key in the [`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum) function. ### Common issues with subqueries #### Multiple statements in a subquery InfluxQL supports multiple nested subqueries per main query: ```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` InfluxQL does not support multiple [`SELECT` statements](/influxdb/v2/query-data/influxql/explore-data/select/) per subquery: ```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` The system returns a parsing error if a subquery includes multiple `SELECT` statements. | time | sum | | --- | --- | | time | sum | | 1970-01-01T00:00:00Z | 17.169 | | time | max | | --- | --- | | time | max | | 2015-08-29T07:24:00Z | 9.9640000000 | | time | max | | --- | --- | | time | max | | 2015-08-29T03:54:00Z | 7.2050000000 | | time | max | | --- | --- | | time | max | | 1970-01-01T00:00:00Z | 1.75 | | time | difference | | --- | --- | | time | difference | | 2017-01-20T00:55:56Z | -1 | | 2017-01-21T00:55:56Z | -49 | | 2017-01-22T00:55:56Z | 66 | | 2017-01-23T00:55:56Z | -9 | | time | all_the_means | | --- | --- | | time | all_the_means | | 2019-08-18T00:00:00Z | 5.4135000000 | | 2019-08-18T00:12:00Z | 5.3042500000 | | 2019-08-18T00:24:00Z | 5.1682500000 | | time | all_the_means | | --- | --- | | time | all_the_means | | 2019-08-18T00:00:00Z | 5.4135000000 | | 2019-08-18T00:12:00Z | 5.3042500000 | | 2019-08-18T00:24:00Z | 5.1682500000 | | time | sum_derivative | | --- | --- | | time | sum_derivative | | 1970-01-01T00:00:00Z | -0.5315000000 | | time | sum_derivative | | --- | --- | | time | sum_derivative | | 1970-01-01T00:00:00Z | -0.2375000000 | | time | water_level_derivative | | --- | --- | | time | water_level_derivative | | 2019-08-18T00:00:00Z | -0.1410000000 | | 2019-08-18T00:12:00Z | -0.1890000000 | | 2019-08-18T00:24:00Z | -0.2015000000 | | time | water_level_derivative | | --- | --- | | time | water_level_derivative | | 2019-08-18T00:00:00Z | -0.1375000000 | | 2019-08-18T00:12:00Z | -0.0295000000 | | 2019-08-18T00:24:00Z | -0.0705000000 | --- # Time and timezone queries Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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: * [Configuring returned timestamps](#configuring-returned-timestamps) * [Time syntax](#time-syntax) * [Absolute time](#absolute-time) * [Relative time](#relative-time) * [The Time Zone clause](#the-time-zone-clause) * [Common issues with time syntax](#common-issues-with-time-syntax) ## Configuring returned timestamps The [InfluxQL shell](/influxdb/v2/tools/influxql-shell/) returns timestamps in nanosecond UNIX epoch format by default. Specify alternative formats with the[`precision ` command](/influxdb/v2/tools/influxql-shell/#precision). If you are using the [InfluxQL shell](/influxdb/v2/tools/influxql-shell/), use the precision helper command `precision rfc3339` to view results in human readable format. The [InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) returns timestamps in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. Specify alternative formats with the[`epoch` query string parameter](/influxdb/v2/reference/api/influxdb-1x/). ## Time syntax For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/), the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2/reference/glossary/#now). The following sections detail how to specify alternative time ranges in the `SELECT`statement’s [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/). Other supported features include: [Absolute time](#absolute-time) [Relative time](#relative-time) ## Absolute time Specify absolute time with date-time strings and epoch time. ### Syntax ```sql SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] ``` #### Supported 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 | Currently, InfluxDB does not support using `OR` with absolute time in the `WHERE`clause. See the [Frequently Asked Questions](/influxdb/v2/reference/faq/#why-is-my-query-with-a-where-or-time-clause-returning-empty-results)document and the [GitHub Issue](https://github.com/influxdata/influxdb/issues/7530)for more information. #### `rfc3339_date_time_string` ```sql 'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' ``` `.nnnnnnnnn` is optional and is set to `.000000000` if not included. The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires single quotes. #### `rfc3339_like_date_time_string` ```sql 'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' ``` `HH:MM:SS.nnnnnnnnn.nnnnnnnnn` is optional and is set to `00:00:00.000000000` if not included. The RFC3339-like date-time string requires single quotes. #### `epoch_time` Epoch time is the amount of time that has elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. By default, InfluxDB assumes that all epoch timestamps are in **nanoseconds**. Include a [duration literal](/influxdb/v2/reference/glossary/#duration) at the end of the epoch timestamp to indicate a precision other than nanoseconds. #### Basic arithmetic All timestamp formats support basic arithmetic. Add (`+`) or subtract (`-`) a time from a timestamp with a [duration literal](/influxdb/v2/reference/glossary/#duration). Note that InfluxQL requires a whitespace between the `+` or `-` and the duration literal. ### Examples [](#specify-a-time-range-with-rfc3339-date-time-strings) Specify a time range with RFC3339 date-time strings ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00.000000000Z' AND time <= '2019-08-18T00:12:00Z' ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| The query returns data with timestamps between August 18, 2019 at 00:00:00.000000000 and August 18, 2019 at 00:12:00. Note that the single quotes around the RFC3339 date-time strings are required. [](#specify-a-time-range-with-rfc3339-like-date-time-strings) Specify a time range with RFC3339-like date-time strings ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18' AND time <= '2019-08-18 00:12:00' ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| The query returns data with timestamps between August 18, 2019 at 00:00:00 and August 18, 2019 at 00:12:00. The first date-time string does not include a time; InfluxDB assumes the time is 00:00:00. Note that the single quotes around the RFC3339-like date-time strings are required. [](#specify-a-time-range-with-epoch-timestamps) Specify a time range with epoch timestamps ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1564635600000000000 AND time <= 1566190800000000000 ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|2.1260000000| |2019-08-17T00:24:00Z|2.0410000000| |2019-08-17T00:30:00Z|2.0510000000| |2019-08-17T00:36:00Z|2.0670000000| |2019-08-17T00:42:00Z|2.0570000000| |2019-08-17T00:48:00Z|1.9910000000| |2019-08-17T00:54:00Z|2.0540000000| |2019-08-17T01:00:00Z|2.0180000000| |2019-08-17T01:06:00Z|2.0960000000| |2019-08-17T01:12:00Z|2.1000000000| |2019-08-17T01:18:00Z|2.1060000000| |2019-08-17T01:24:00Z|2.1261441460| The query returns data with timestamps that occur between August 1, 2019 at 00:00:00 and August 19, 2019 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. [](#specify-a-time-range-with-second-precision-epoch-timestamps) Specify a time range with second-precision epoch timestamps ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1566190800s AND time <= 1566191520s ``` Output: | time |water\_level| |--------------------|------------| |2019-08-19T05:00:00Z|3.2320000000| |2019-08-19T05:06:00Z|3.2320000000| |2019-08-19T05:12:00Z|3.2910000000| The query returns data with timestamps that occur between August 19, 2019 at 00:00:00 and August 19, 2019 at 00:12:00. The `s` duration literal at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. [](#perform-basic-arithmetic-on-an-rfc3339-like-date-time-string) Perform basic arithmetic on an RFC3339-like date-time string ```sql SELECT "water_level" FROM "h2o_feet" WHERE time > '2019-09-17T21:24:00Z' + 6m ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-09-17T21:36:00Z|5.0660000000| |2019-09-17T21:42:00Z|4.9380000000| The query returns data with timestamps that occur at least six minutes after September 17, 2019 at 21:24:00. Note that the whitespace between the `+` and `6m` is required. [](#perform-basic-arithmetic-on-an-epoch-timestamp) Perform basic arithmetic on an epoch timestamp ```sql SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|8.1200000000| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|8.0050000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|7.8870000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|7.7620000000| |2019-08-17T00:18:00Z|2.1260000000| The query returns data with timestamps that occur at least six minutes before September 18, 2019 at 21:24:00. Note that the whitespace between the `-` and `6m` is required. Note that the results above are partial as the dataset is large. ## Relative time Use [`now()`](/influxdb/v2/reference/glossary/#now) to query data with [timestamps](/influxdb/v2/reference/glossary/#timestamp) relative to the server’s current timestamp. ### Syntax ```sql SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] ``` `now()` is the Unix time of the server at the time the query is executed on that server. The whitespace between `-` or `+` and the [duration literal](/influxdb/v2/reference/glossary/#duration) is required. #### Supported 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 | #### `duration_literal` * microseconds: `u` or `µ` * milliseconds: `ms` * seconds`s` * minutes`m` * hours:`h` * days:`d` * weeks:`w` ### Examples [](#specify-a-time-range-with-relative-time) Specify a time range with relative time ```sql SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h ``` The query returns data with timestamps that occur within the past hour. The whitespace between `-` and `1h` is required. [](#specify-a-time-range-with-absolute-time-and-relative-time) Specify a time range with absolute time and relative time #### Specify a time range with absolute time and relative time ```sql SELECT "level description" FROM "h2o_feet" WHERE time > '2019-09-17T21:18:00Z' AND time < now() + 1000d ``` Output: Name: h2o\_feet | time | level description | |--------------------|--------------------| |2019-09-17T21:24:00Z|between 3 and 6 feet| |2019-09-17T21:30:00Z|between 3 and 6 feet| |2019-09-17T21:36:00Z|between 3 and 6 feet| |2019-09-17T21:42:00Z|between 3 and 6 feet| The query returns data with timestamps that occur between September 17, 2019 at 21:18:00 and 1000 days from `now()`. The whitespace between `+` and `1000d` is required. ## The Time Zone clause Use the `tz()` clause to return the UTC offset for the specified timezone. ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` By default, InfluxDB stores and returns timestamps in UTC. The `tz()` clause includes the UTC offset or, if applicable, the UTC Daylight Savings Time (DST) offset to the query’s returned timestamps. The returned timestamps must be in `RFC3339` format for the UTC offset or UTC DST to appear. The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) and it requires single quotes. ### Examples [](#return-the-utc-offset-for-chicagos-time-zone) Return the UTC offset for Chicago’s time zone ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:18:00Z' tz('America/Chicago') ``` Output: Name: h2o\_feet | time |water\_level| |-------------------------|------------| |2019-08-17T19:00:00-05:00|2.3520000000| |2019-08-17T19:06:00-05:00|2.3790000000| |2019-08-17T19:12:00-05:00|2.3430000000| |2019-08-17T19:18:00-05:00|2.3290000000| The query results include the UTC offset (`-05:00`) for the `America/Chicago` time zone in the timestamps. ## Common issues with time syntax ### Using `OR` to select time multiple time intervals InfluxDB does not support using the `OR` operator in the `WHERE` clause to specify multiple time intervals. For more information, see [Frequently asked questions](/influxdb/v2/reference/faq/#why-is-my-query-with-a-where-or-time-clause-returning-empty-results). ### Querying data that occur after `now()` with a `GROUP BY time()` clause Most `SELECT` statements have a default time range between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals), the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2/reference/glossary/#now). To query data with timestamps that occur after `now()`, `SELECT` statements with a `GROUP BY time()` clause must provide an alternative upper bound in the`WHERE` clause. | 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 | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | 2019-08-17T00:24:00Z | 2.0410000000 | | 2019-08-17T00:30:00Z | 2.0510000000 | | 2019-08-17T00:36:00Z | 2.0670000000 | | 2019-08-17T00:42:00Z | 2.0570000000 | | 2019-08-17T00:48:00Z | 1.9910000000 | | 2019-08-17T00:54:00Z | 2.0540000000 | | 2019-08-17T01:00:00Z | 2.0180000000 | | 2019-08-17T01:06:00Z | 2.0960000000 | | 2019-08-17T01:12:00Z | 2.1000000000 | | 2019-08-17T01:18:00Z | 2.1060000000 | | 2019-08-17T01:24:00Z | 2.1261441460 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-19T05:00:00Z | 3.2320000000 | | 2019-08-19T05:06:00Z | 3.2320000000 | | 2019-08-19T05:12:00Z | 3.2910000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-09-17T21:36:00Z | 5.0660000000 | | 2019-09-17T21:42:00Z | 4.9380000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 8.1200000000 | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 8.0050000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 7.8870000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 7.7620000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | 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 | level description | | --- | --- | | time | level description | | 2019-09-17T21:24:00Z | between 3 and 6 feet | | 2019-09-17T21:30:00Z | between 3 and 6 feet | | 2019-09-17T21:36:00Z | between 3 and 6 feet | | 2019-09-17T21:42:00Z | between 3 and 6 feet | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T19:00:00-05:00 | 2.3520000000 | | 2019-08-17T19:06:00-05:00 | 2.3790000000 | | 2019-08-17T19:12:00-05:00 | 2.3430000000 | | 2019-08-17T19:18:00-05:00 | 2.3290000000 | --- # The WHERE clause Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-data/where/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `WHERE` clause to filter data based on[fields](/influxdb/v2/reference/glossary/#field),[tags](/influxdb/v2/reference/glossary/#tag), and/or[timestamps](/influxdb/v2/reference/glossary/#timestamp). * [Syntax](#syntax) * [Examples](#examples) * [Common issues](#common-issues-with-the-where-clause) ### Syntax ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` The `WHERE` clause supports `conditional_expressions` on fields, tags, and timestamps. > [!Note] > **Note:** InfluxDB does not support using OR in the WHERE clause to specify multiple time ranges. For example, InfluxDB returns an empty response for the following query: > > ``` > SELECT * FROM "mydb" WHERE time = '2020-07-31T20:07:00Z' OR time = '2020-07-31T23:07:17Z'` > ``` #### Fields ``` field_key ['string' | boolean | float | integer] ``` The `WHERE` clause supports comparisons against string, boolean, float, and integer [field values](/influxdb/v2/reference/glossary/#field-value). Single quote string field values in the `WHERE` clause. Queries with unquoted string field values or double quoted string field values will not return any data and, in most cases,[will not return an error](#common-issues-with-the-where-clause). #### Supported 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 | InfluxQL also supports [Regular Expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). #### Tags ```sql tag_key ['tag_value'] ``` Single quote [tag values](/influxdb/v2/reference/glossary/#tag-value) in the `WHERE` clause. Queries with unquoted tag values or double quoted tag values will not return any data and, in most cases,[will not return an error](#common-issues-with-the-where-clause). #### Supported operators |Operator| Meaning | |--------|------------| | `=` | equal to | | `<>` |not equal to| | `!=` |not equal to| #### Timestamps For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2/reference/faq/#what-are-the-minimum-and-maximum-integers-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/), the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2/reference/glossary/#now). See [Time Syntax](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax) for information on how to specify alternative time ranges in the `WHERE` clause. ### Examples [](#select-data-with-specific-field-key-values) Select data with specific field key-values ```sql SELECT * FROM "h2o_feet" WHERE "water_level" > 9 ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |--------------------|-------------------------|-------------|------------| |2019-08-25T04:00:00Z|at or greater than 9 feet|coyote\_creek|9.0320000000| |2019-08-25T04:06:00Z|at or greater than 9 feet|coyote\_creek|9.0780000000| |2019-08-25T04:12:00Z|at or greater than 9 feet|coyote\_creek|9.1110000000| |2019-08-25T04:18:00Z|at or greater than 9 feet|coyote\_creek|9.1500000000| |2019-08-25T04:24:00Z|at or greater than 9 feet|coyote\_creek|9.1800000000| The query returns data from the `h2o_feet` measurement with field values of `water_level` that are greater than nine. This is a partial data set. [](#select-data-with-a-specific-string-field-key-value) Select data with a specific string field key-value ```sql SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' ``` Output: Name: h2o\_feet | time |level description| location |water\_level| |--------------------|-----------------|-------------|------------| |2019-08-17T00:00:00Z| below 3 feet |santa\_monica|2.0640000000| |2019-08-17T00:06:00Z| below 3 feet |santa\_monica|2.1160000000| |2019-08-17T00:12:00Z| below 3 feet |santa\_monica|2.0280000000| |2019-08-17T00:18:00Z| below 3 feet |santa\_monica|2.1260000000| |2019-08-17T00:24:00Z| below 3 feet |santa\_monica|2.0410000000| |2019-08-17T00:30:00Z| below 3 feet |santa\_monica|2.0510000000| The query returns data from the `h2o_feet` measurement with field values of `level description` that equal the `below 3 feet` string. InfluxQL requires single quotes around string field values in the `WHERE` clause. [](#select-data-with-a-specific-field-key-value-and-perform-basic-arithmetic) Select data with a specific field key-value and perform basic arithmetic ```sql SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 ``` Output: Name: h2o\_feet | time | level description | location |water\_level| |--------------------|-------------------------|-------------|------------| |2019-08-28T07:06:00Z|at or greater than 9 feet|coyote\_creek|9.9020000000| |2019-08-28T07:12:00Z|at or greater than 9 feet|coyote\_creek|9.9380000000| |2019-08-28T07:18:00Z|at or greater than 9 feet|coyote\_creek|9.9570000000| |2019-08-28T07:24:00Z|at or greater than 9 feet|coyote\_creek|9.9640000000| |2019-08-28T07:30:00Z|at or greater than 9 feet|coyote\_creek|9.9540000000| |2019-08-28T07:36:00Z|at or greater than 9 feet|coyote\_creek|9.9410000000| |2019-08-28T07:42:00Z|at or greater than 9 feet|coyote\_creek|9.9250000000| |2019-08-28T07:48:00Z|at or greater than 9 feet|coyote\_creek|9.9020000000| |2019-09-01T23:30:00Z|at or greater than 9 feet|coyote\_creek|9.9020000000| The query returns data from the `h2o_feet` measurement with field values of`water_level` plus two that are greater than 11.9. Note that InfluxDB follows the standard order of operations. See [Mathematical operators](/influxdb/v2/query-data/influxql/math-operators/)for more on supported operators. [](#select-data-with-a-specific-tag-key-value) Select data with a specific tag key-value ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|2.1260000000| |2019-08-17T00:24:00Z|2.0410000000| The query returns data from the `h2o_feet` measurement where the[tag key](/influxdb/v2/reference/glossary/#tag-key) `location` is set to `santa_monica`. InfluxQL requires single quotes around tag values in the `WHERE` clause. [](#select-data-with-specific-field-key-values-and-tag-key-values) Select data with specific field key-values and tag key-values ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) ``` Output: Name: h2o\_feet | time | water\_level | |--------------------|--------------| |2019-08-28T07:18:00Z| 9.9570000000 | |2019-08-28T07:24:00Z| 9.9640000000 | |2019-08-28T07:30:00Z| 9.9540000000 | |2019-08-28T14:30:00Z|\-0.6100000000| |2019-08-28T14:36:00Z|\-0.5910000000| |2019-08-29T15:18:00Z|\-0.5940000000| The query returns data from the `h2o_feet` measurement where the tag key`location` is not set to `santa_monica` and where the field values of`water_level` are either less than -0.59 or greater than 9.95. The `WHERE` clause supports the operators `AND` and `OR`, and supports separating logic with parentheses. ```sql SELECT * FROM "h2o_feet" WHERE time > now() - 7d ``` The query returns data from the `h2o_feet` measurement with [timestamps](/influxdb/v2/reference/glossary/#timestamp)within the past seven days. See [Time Syntax](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax) for more in-depth information on supported time syntax in the `WHERE` clause. ### Common issues with the `WHERE` clause #### A `WHERE` clause query unexpectedly returns no data In most cases, this issue is the result of missing single quotes around tag values or string field values. Queries with unquoted or double quoted tag values or string field values will not return any data and, in most cases, will not return an error. The first two queries in the code block below attempt to specify the tag value`santa_monica` without any quotes and with double quotes. Those queries return no results. The third query single quotes `santa_monica` (this is the supported syntax) and returns the expected results. ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica No results SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" No results SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ``` Output: Name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-17T00:00:00Z|2.0640000000| |2019-08-17T00:06:00Z|2.1160000000| |2019-08-17T00:12:00Z|2.0280000000| |2019-08-17T00:18:00Z|2.1260000000| |2019-08-17T00:24:00Z|2.0410000000| |2019-08-17T00:30:00Z|2.0510000000| The first two queries in the code block below attempt to specify the string field value `at or greater than 9 feet` without any quotes and with double quotes. The first query returns an error because the string field value includes white spaces. The second query returns no results. The third query single quotes `at or greater than 9 feet` (this is the supported syntax) and returns the expected results. ```sql SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet ERR: 400 Bad Request: failed to parse query: found than, expected ; at line 1, char 86 SELECT "level description" FROM "h2o_feet" WHERE "level description" = "at or greater than 9 feet" No results SELECT "level description" FROM "h2o_feet" WHERE "level description" = 'at or greater than 9 feet' ``` Output: Name: h2o\_feet | time | level\_description | |--------------------|-------------------------| |2019-08-25T04:00:00Z|at or greater than 9 feet| |2019-08-25T04:06:00Z|at or greater than 9 feet| |019-08-25T04:12:00Z |at or greater than 9 feet| |2019-08-25T04:18:00Z|at or greater than 9 feet| |2019-08-25T04:24:00Z|at or greater than 9 feet| | 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 | | Operator | Meaning | | --- | --- | | Operator | Meaning | | = | equal to | | <> | not equal to | | != | not equal to | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-25T04:00:00Z | at or greater than 9 feet | coyote_creek | 9.0320000000 | | 2019-08-25T04:06:00Z | at or greater than 9 feet | coyote_creek | 9.0780000000 | | 2019-08-25T04:12:00Z | at or greater than 9 feet | coyote_creek | 9.1110000000 | | 2019-08-25T04:18:00Z | at or greater than 9 feet | coyote_creek | 9.1500000000 | | 2019-08-25T04:24:00Z | at or greater than 9 feet | coyote_creek | 9.1800000000 | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | | 2019-08-17T00:06:00Z | below 3 feet | santa_monica | 2.1160000000 | | 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000 | | 2019-08-17T00:18:00Z | below 3 feet | santa_monica | 2.1260000000 | | 2019-08-17T00:24:00Z | below 3 feet | santa_monica | 2.0410000000 | | 2019-08-17T00:30:00Z | below 3 feet | santa_monica | 2.0510000000 | | time | level description | location | water_level | | --- | --- | --- | --- | | time | level description | location | water_level | | 2019-08-28T07:06:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000 | | 2019-08-28T07:12:00Z | at or greater than 9 feet | coyote_creek | 9.9380000000 | | 2019-08-28T07:18:00Z | at or greater than 9 feet | coyote_creek | 9.9570000000 | | 2019-08-28T07:24:00Z | at or greater than 9 feet | coyote_creek | 9.9640000000 | | 2019-08-28T07:30:00Z | at or greater than 9 feet | coyote_creek | 9.9540000000 | | 2019-08-28T07:36:00Z | at or greater than 9 feet | coyote_creek | 9.9410000000 | | 2019-08-28T07:42:00Z | at or greater than 9 feet | coyote_creek | 9.9250000000 | | 2019-08-28T07:48:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000 | | 2019-09-01T23:30:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | 2019-08-17T00:24:00Z | 2.0410000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-28T07:18:00Z | 9.9570000000 | | 2019-08-28T07:24:00Z | 9.9640000000 | | 2019-08-28T07:30:00Z | 9.9540000000 | | 2019-08-28T14:30:00Z | -0.6100000000 | | 2019-08-28T14:36:00Z | -0.5910000000 | | 2019-08-29T15:18:00Z | -0.5940000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-17T00:00:00Z | 2.0640000000 | | 2019-08-17T00:06:00Z | 2.1160000000 | | 2019-08-17T00:12:00Z | 2.0280000000 | | 2019-08-17T00:18:00Z | 2.1260000000 | | 2019-08-17T00:24:00Z | 2.0410000000 | | 2019-08-17T00:30:00Z | 2.0510000000 | | time | level_description | | --- | --- | | time | level_description | | 2019-08-25T04:00:00Z | at or greater than 9 feet | | 2019-08-25T04:06:00Z | at or greater than 9 feet | | 019-08-25T04:12:00Z | at or greater than 9 feet | | 2019-08-25T04:18:00Z | at or greater than 9 feet | | 2019-08-25T04:24:00Z | at or greater than 9 feet | --- # Explore your schema using InfluxQL Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/explore-schema/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use InfluxQL to explore the schema of your time series data. Use the following InfluxQL commands to explore your schema: * [SHOW SERIES](#show-series) * [SHOW MEASUREMENTS](#show-measurements) * [SHOW TAG KEYS](#show-tag-keys) * [SHOW TAG VALUES](#show-tag-values) * [SHOW FIELD KEYS](#show-field-keys) * [SHOW FIELD KEY CARDINALITY](#show-field-key-cardinality) * [SHOW TAG KEY CARDINALITY](#show-tag-key-cardinality) > [!Note] > Command examples use the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). ## SHOW SERIES Return a list of [series](/influxdb/v2/reference/glossary/#series) for the specified [database](/influxdb/v2/reference/glossary/#database). ### Syntax ```sql SHOW SERIES [ON ] [FROM_clause] [WHERE [ '' | ]] [LIMIT_clause] [OFFSET_clause] ``` * `ON ` is optional. If the query does not include `ON `, you must specify the database with the `db` query string parameter in the[InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) request. * `FROM`, `WHERE`, `LIMIT`, and `OFFSET` clauses are optional. * The `WHERE` clause in `SHOW SERIES` supports tag comparisons but not field comparisons. **Supported operators in the `WHERE` clause**: * `=`: equal to * `<>`: not equal to * `!=`: not equal to * `=~`: matches against * `!~`: doesn’t match against See [Explore data using InfluxQL](/influxdb/v2/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). ### Examples #### Run SHOW SERIES with the ON clause ```sql SHOW SERIES ON noaa ``` **Output:** The query returns all series in the `noaa` database. The query’s output is similar to the [line protocol](/influxdb/v2/reference/syntax/line-protocol/) format. Everything before the first comma is the [measurement](/influxdb/v2/reference/glossary/#measurement) name. Everything after the first comma is either a [tag key](/influxdb/v2/reference/glossary/#tag-key) or a [tag value](/influxdb/v2/reference/glossary/#tag-value). The `noaa` database has 5 different measurements and 13 different series. | key | |---------------------------------------------| | average\_temperature,location=coyote\_creek | | average\_temperature,location=santa\_monica | | h2o\_feet,location=coyote\_creek | | h2o\_feet,location=santa\_monica | | h2o\_pH,location=coyote\_creek | | h2o\_pH,location=santa\_monica | |h2o\_quality,location=coyote\_creek,randtag=1| |h2o\_quality,location=coyote\_creek,randtag=2| |h2o\_quality,location=coyote\_creek,randtag=3| |h2o\_quality,location=santa\_monica,randtag=1| |h2o\_quality,location=santa\_monica,randtag=2| |h2o\_quality,location=santa\_monica,randtag=3| | h2o\_temperature,location=coyote\_creek | #### Run SHOW SERIES with several clauses ```sql SHOW SERIES ON noaa FROM "h2o_quality" WHERE "location" = 'coyote_creek' LIMIT 2 ``` **Output:** The query returns all series in the `noaa` database that are associated with the `h2o_quality` measurement and the tag `location = coyote_creek`. The `LIMIT` clause limits the number of series returned to two. | key | |---------------------------------------------| |h2o\_quality,location=coyote\_creek,randtag=1| |h2o\_quality,location=coyote\_creek,randtag=2| ## SHOW MEASUREMENTS Returns a list of [measurements](/influxdb/v2/reference/glossary/#measurement)for the specified [database](/influxdb/v2/reference/glossary/#database). ### Syntax ```sql SHOW MEASUREMENTS [ON ] [WITH MEASUREMENT ['' | ]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] ``` * `ON ` is optional. If the query does not include `ON `, you must specify the database with the `db` query string parameter in the[InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) request. * The `WITH`, `WHERE`, `LIMIT` and `OFFSET` clauses are optional. * The `WHERE` in `SHOW MEASUREMENTS` supports tag comparisons, but not field comparisons. **Supported operators in the `WHERE` clause:** * `=` : equal to * `<>`: not equal to * `!=`: not equal to * `=~`: matches against * `!~`: doesn’t match against See [Explore data using InfluxQL](/influxdb/v2/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). ### Examples #### Run SHOW MEASUREMENTS with the ON clause ```sql SHOW MEASUREMENTS ON noaa ``` **Output:** The query returns the list of measurements in the `noaa` database. The database has five measurements: `average_temperature`, `h2o_feet`, `h2o_pH`,`h2o_quality`, and `h2o_temperature`. | name | |--------------------| |average\_temperature| | h2o\_feet | | h2o\_pH | | h2o\_quality | | h2o\_temperature | #### Run SHOW MEASUREMENTS with several clauses (i) ```sql SHOW MEASUREMENTS ON noaa WITH MEASUREMENT =~ /h2o.*/ LIMIT 2 OFFSET 1 ``` **Output:** The query returns the measurements in the `noaa` database that start with `h2o`. The `LIMIT` and `OFFSET` clauses limit the number of measurement names returned to two and offset the results by one, skipping the `h2o_feet` measurement. | name | |------------| | h2o\_pH | |h2o\_quality| #### Run SHOW MEASUREMENTS with several clauses (ii) ```sql SHOW MEASUREMENTS ON noaa WITH MEASUREMENT =~ /h2o.*/ WHERE "randtag" =~ /\d/ ``` The query returns all measurements in the `noaa` that start with `h2o` and have values for the tag key `randtag` that include an integer. | name | |------------| |h2o\_quality| ## SHOW TAG KEYS Returns a list of [tag keys](/influxdb/v2/reference/glossary/#tag-key)associated with the specified [database](/influxdb/v2/reference/glossary/#database). ### Syntax ```sql SHOW TAG KEYS [ON ] [FROM_clause] WITH KEY [ [ "" | ] | [IN ("","")]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] ``` * `ON ` is optional. If the query does not include `ON `, you must specify the database with `db` query string parameter in the [InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) request. * The `FROM` clause and the `WHERE` clause are optional. * The `WHERE` clause in `SHOW TAG KEYS` supports tag comparisons, but not field comparisons. **Supported operators in the `WHERE` clause:** * `=` : equal to * `<>`: not equal to * `!=`: not equal to * `=~`: matches against * `!~`: doesn’t match against See [Explore data using InfluxQL](/influxdb/v2/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). ### Examples #### Run SHOW TAG KEYS with the ON clause ```sql SHOW TAG KEYS ON noaa ``` **Output:** The query returns the list of tag keys in the `noaa` database. The output groups tag keys by measurement name; it shows that every measurement has the `location` tag key and that the`h2o_quality` measurement has an additional `randtag` tag key. | name | tagKey | |--------------------|--------| |average\_temperature|location| | h2o\_feet |location| | h2o\_pH |location| | h2o\_quality |location| | h2o\_quality |randtag | | h2o\_temperature |location| #### Run SHOW TAG KEYS with several clauses ```sql SHOW TAG KEYS ON noaa FROM "h2o_quality" LIMIT 1 OFFSET 1 ``` **Output:** The query returns tag keys from the `h2o_quality` measurement in the `noaa` database. The `LIMIT` and `OFFSET` clauses limit the number of tag keys returned to one and offsets the results by one. | name |tagKey | |------------|-------| |h2o\_quality|randtag| #### Run SHOW TAG KEYS with a WITH KEY IN clause ```sql SHOW TAG KEYS ON noaa WITH KEY IN ("location") ``` **Output:** | measurement | tagKey | |--------------------|--------| |average\_temperature|location| | h2o\_feet |location| | h2o\_pH |location| | h2o\_quality |location| | h2o\_quality |randtag | | h2o\_temperature |location| ## SHOW TAG VALUES Returns the list of [tag values](/influxdb/v2/reference/glossary/#tag-value)for the specified [tag key(s)](/influxdb/v2/reference/glossary/#tag-key) in the database. ### Syntax ```sql SHOW TAG VALUES [ON ][FROM_clause] WITH KEY [ [ "" | ] | [IN ("","")]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] ``` * `ON ` is optional. If the query does not include `ON `, you must specify the database with the `db` query string parameter in the [InfluxDB API](/influxdb/v2/reference/api/influxdb-1x/) request. * The `WITH` clause is required. It supports specifying a single tag key, a regular expression, and multiple tag keys. * The `FROM`, `WHERE`, `LIMIT`, and `OFFSET` clauses are optional. * The `WHERE` clause in `SHOW TAG KEYS` supports tag comparisons, but not field comparisons. **Supported operators in the `WITH` and `WHERE` clauses:** * `=` : equal to * `<>`: not equal to * `!=`: not equal to * `=~`: matches against * `!~`: doesn’t match against See [Explore data using InfluxQL](/influxdb/v2/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). ### Examples #### Run SHOW TAG VALUES with the ON clause ```sql SHOW TAG VALUES ON noaa WITH KEY = "randtag" ``` **Output:** The query returns all tag values of the `randtag` tag key in the `noaa` database.`SHOW TAG VALUES` groups query results by measurement name. name: h2o\_quality | key |value| |-------|-----| |randtag| 1 | |randtag| 2 | |randtag| 3 | #### Run a `SHOW TAG VALUES` query with several clauses ```sql SHOW TAG VALUES ON noaa WITH KEY IN ("location","randtag") WHERE "randtag" =~ /./ LIMIT 3 ``` **Output:** The query returns the tag values of the tag keys `location` and `randtag` for all measurements in the `noaa` database where `randtag` has tag values. The `LIMIT` clause limits the number of tag values returned to three. name: h2o\_quality | key | value | |--------|-------------| |location|coyote\_creek| |location|santa\_monica| |randtag | 1 | ## SHOW FIELD KEYS Returns the [field keys](/influxdb/v2/reference/glossary/#field-key) and the[data type](/influxdb/v2/reference/glossary/#data-type) of their[field values](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SHOW FIELD KEYS [ON ] [FROM ] ``` * `ON ` is optional. If the query does not include `ON `, you must specify the database with `USE ` when using the [InfluxQL shell](/influxdb/v2/tools/influxql-shell/)or with the `db` query string parameter in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) request. * The `FROM` clause is optional. See the Data Exploration page for documentation on the[`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause). > [!Note] > **Note:** A field’s data type [can differ](/influxdb/v2/reference/faq/#how-does-influxdb-handle-field-type-discrepancies-across-shards) across[shards](/influxdb/v2/reference/glossary/#shard). > If your field has more than one type, `SHOW FIELD KEYS` returns the type that > occurs first in the following list: float, integer, string, boolean. ### Examples #### Run SHOW FIELD KEYS with the ON clause ```sql SHOW FIELD KEYS ON noaa ``` **Output:** The query returns the field keys and field value data types for each measurement in the `noaa` database. | name | fieldKey |fieldType| |--------------------|-----------------|---------| |average\_temperature| degrees | float | | h2o\_feet |level description| string | | h2o\_feet | water\_level | float | | h2o\_pH | pH | float | | h2o\_quality | index | float | | hh2o\_temperature | degrees | float | #### Run SHOW FIELD KEYS with the FROM clause ```sql SHOW FIELD KEYS ON noaa FROM h2o_feet ``` **Output:** The query returns the fields keys and field value data types for the `h2o_feet`measurement in the `noaa` database. | name | fieldKey |fieldType| |---------|-----------------|---------| |h2o\_feet|level description| string | |h2o\_feet| water\_level | float | ### Common Issues with SHOW FIELD KEYS #### SHOW FIELD KEYS and field type discrepancies Field value [data types](/influxdb/v2/reference/glossary/#data-type)cannot differ within a [shard](/influxdb/v2/reference/glossary/#shard) but they can differ across shards.`SHOW FIELD KEYS` returns every data type, across every shard, associated with the field key. ##### Example The `all_the_types` field stores four different data types: ```sql SHOW FIELD KEYS ``` name: mymeas | fieldKey |fieldType| |---------------|---------| |all\_the\_types| integer | |all\_the\_types| float | |all\_the\_types| string | |all\_the\_types| boolean | Note that `SHOW FIELD KEYS` handles field type discrepancies differently from`SELECT` statements. For more information, see the[How does InfluxDB handle field type discrepancies across shards?](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-field-type-discrepancies-across-shards). ## SHOW FIELD KEY CARDINALITY Cardinality is the product of all unique databases, retention policies, measurements, field keys and tag values in your Influx instance. Managing cardinality is important, as high cardinality leads to greater resource usage. ```sql -- show estimated cardinality of the field key set of current database SHOW FIELD KEY CARDINALITY -- show exact cardinality on field key set of specified database SHOW FIELD KEY EXACT CARDINALITY ON noaa ``` ## SHOW TAG KEY CARDINALITY ```sql -- show estimated tag key cardinality SHOW TAG KEY CARDINALITY -- show exact tag key cardinality SHOW TAG KEY EXACT CARDINALITY ``` | key | | --- | | key | | average_temperature,location=coyote_creek | | average_temperature,location=santa_monica | | h2o_feet,location=coyote_creek | | h2o_feet,location=santa_monica | | h2o_pH,location=coyote_creek | | h2o_pH,location=santa_monica | | h2o_quality,location=coyote_creek,randtag=1 | | h2o_quality,location=coyote_creek,randtag=2 | | h2o_quality,location=coyote_creek,randtag=3 | | h2o_quality,location=santa_monica,randtag=1 | | h2o_quality,location=santa_monica,randtag=2 | | h2o_quality,location=santa_monica,randtag=3 | | h2o_temperature,location=coyote_creek | | key | | --- | | key | | h2o_quality,location=coyote_creek,randtag=1 | | h2o_quality,location=coyote_creek,randtag=2 | | name | | --- | | name | | average_temperature | | h2o_feet | | h2o_pH | | h2o_quality | | h2o_temperature | | name | | --- | | name | | h2o_pH | | h2o_quality | | name | | --- | | name | | h2o_quality | | name | tagKey | | --- | --- | | name | tagKey | | average_temperature | location | | h2o_feet | location | | h2o_pH | location | | h2o_quality | location | | h2o_quality | randtag | | h2o_temperature | location | | name | tagKey | | --- | --- | | name | tagKey | | h2o_quality | randtag | | measurement | tagKey | | --- | --- | | measurement | tagKey | | average_temperature | location | | h2o_feet | location | | h2o_pH | location | | h2o_quality | location | | h2o_quality | randtag | | h2o_temperature | location | | key | value | | --- | --- | | key | value | | randtag | 1 | | randtag | 2 | | randtag | 3 | | key | value | | --- | --- | | key | value | | location | coyote_creek | | location | santa_monica | | randtag | 1 | | name | fieldKey | fieldType | | --- | --- | --- | | name | fieldKey | fieldType | | average_temperature | degrees | float | | h2o_feet | level description | string | | h2o_feet | water_level | float | | h2o_pH | pH | float | | h2o_quality | index | float | | hh2o_temperature | degrees | float | | name | fieldKey | fieldType | | --- | --- | --- | | name | fieldKey | fieldType | | h2o_feet | level description | string | | h2o_feet | water_level | float | | fieldKey | fieldType | | --- | --- | | fieldKey | fieldType | | all_the_types | integer | | all_the_types | float | | all_the_types | string | | all_the_types | boolean | --- # View InfluxQL functions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/functions/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. > [!Note] > To query with InfluxQL, the bucket you query must be mapped to a database and retention policy (DBRP). For more information, see how to [Query data with InfluxQL](/influxdb/v2/query-data/influxql/). ## InfluxQL functions (by type) * [Aggregates](/influxdb/v2/query-data/influxql/functions/aggregates/) * [COUNT()](/influxdb/v2/query-data/influxql/functions/aggregates/#count) * [DISTINCT()](/influxdb/v2/query-data/influxql/functions/aggregates/#distinct) * [INTEGRAL()](/influxdb/v2/query-data/influxql/functions/aggregates/#integral) * [MEAN()](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) * [MEDIAN()](/influxdb/v2/query-data/influxql/functions/aggregates/#median) * [MODE()](/influxdb/v2/query-data/influxql/functions/aggregates/#mode) * [SPREAD()](/influxdb/v2/query-data/influxql/functions/aggregates/#spread) * [STDDEV()](/influxdb/v2/query-data/influxql/functions/aggregates/#stddev) * [SUM()](/influxdb/v2/query-data/influxql/functions/aggregates/#sum) * [Selectors](/influxdb/v2/query-data/influxql/functions/selectors/) * [BOTTOM()](/influxdb/v2/query-data/influxql/functions/selectors/#bottom) * [FIRST()](/influxdb/v2/query-data/influxql/functions/selectors/#first) * [LAST()](/influxdb/v2/query-data/influxql/functions/selectors/#last) * [MAX()](/influxdb/v2/query-data/influxql/functions/selectors/#max) * [MIN()](/influxdb/v2/query-data/influxql/functions/selectors/#min) * [PERCENTILE()](/influxdb/v2/query-data/influxql/functions/selectors/#percentile) * [SAMPLE()](/influxdb/v2/query-data/influxql/functions/selectors/#sample) * [TOP()](/influxdb/v2/query-data/influxql/functions/selectors/#top) * [Transformations](/influxdb/v2/query-data/influxql/functions/transformations/) * [ABS()](/influxdb/v2/query-data/influxql/functions/transformations/#abs) * [ACOS()](/influxdb/v2/query-data/influxql/functions/transformations/#acos) * [ASIN()](/influxdb/v2/query-data/influxql/functions/transformations/#asin) * [ATAN()](/influxdb/v2/query-data/influxql/functions/transformations/#atan) * [ATAN2()](/influxdb/v2/query-data/influxql/functions/transformations/#atan2) * [CEIL()](/influxdb/v2/query-data/influxql/functions/transformations/#ceil) * [COS()](/influxdb/v2/query-data/influxql/functions/transformations/#cos) * [CUMULATIVE\_SUM()](/influxdb/v2/query-data/influxql/functions/transformations/#cumulative_sum) * [DERIVATIVE()](/influxdb/v2/query-data/influxql/functions/transformations/#derivative) * [DIFFERENCE()](/influxdb/v2/query-data/influxql/functions/transformations/#difference) * [ELAPSED()](/influxdb/v2/query-data/influxql/functions/transformations/#elapsed) * [EXP()](/influxdb/v2/query-data/influxql/functions/transformations/#exp) * [FLOOR()](/influxdb/v2/query-data/influxql/functions/transformations/#floor) * [HISTOGRAM()](/influxdb/v2/query-data/influxql/functions/transformations/#histogram) * [LN()](/influxdb/v2/query-data/influxql/functions/transformations/#ln) * [LOG()](/influxdb/v2/query-data/influxql/functions/transformations/#log) * [LOG2()](/influxdb/v2/query-data/influxql/functions/transformations/#log2) * [LOG10()](/influxdb/v2/query-data/influxql/functions/transformations/#log10) * [MOVING\_AVERAGE()](/influxdb/v2/query-data/influxql/functions/transformations/#moving_average) * [NON\_NEGATIVE\_DERIVATIVE()](/influxdb/v2/query-data/influxql/functions/transformations/#non_negative_derivative) * [NON\_NEGATIVE\_DIFFERENCE()](/influxdb/v2/query-data/influxql/functions/transformations/#non_negative_difference) * [POW()](/influxdb/v2/query-data/influxql/functions/transformations/#pow) * [ROUND()](/influxdb/v2/query-data/influxql/functions/transformations/#round) * [SIN()](/influxdb/v2/query-data/influxql/functions/transformations/#sin) * [SQRT()](/influxdb/v2/query-data/influxql/functions/transformations/#sqrt) * [TAN()](/influxdb/v2/query-data/influxql/functions/transformations/#tan) * [Technical analysis](/influxdb/v2/query-data/influxql/functions/technical-analysis/) * (Predictive analysis) [HOLT\_WINTERS()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#holt_winters) * [CHANDE\_MOMENTUM\_OSCILLATOR()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#chande_momentum_oscillator) * [EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#exponential_moving_average) * [DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#double_exponential_moving_average) * [KAUFMANS\_EFFICIENCY\_RATIO()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) * [KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) * [TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#triple_exponential_moving_average) * [TRIPLE\_EXPONENTIAL\_DERIVATIVE()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#triple_exponential_derivative) * [RELATIVE\_STRENGTH\_INDEX()](/influxdb/v2/query-data/influxql/functions/technical-analysis/#relative_strength_index) --- # InfluxQL aggregate functions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/functions/aggregates/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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. Each aggregate function below covers **syntax** including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). * [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](/influxdb/v2/reference/glossary/#field-value). Supports all field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT COUNT( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `COUNT(*)` Returns the number of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `COUNT(field_key)` Returns the number of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `COUNT(/regular_expression/)` Returns the number of field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). #### Examples [](#count-values-for-a-field) Count values for a field Return the number of non-null field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT COUNT("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | count | |--------------------|----------------| |1970-01-01T00:00:00Z|61026.0000000000| [](#count-values-for-each-field-in-a-measurement) Count values for each field in a measurement Return the number of non-null field values for each field key associated with the `h2o_feet` measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT COUNT(*) FROM "h2o_feet" ``` name: h2o\_feet | time |count\_level description|count\_water\_level| |--------------------|------------------------|-------------------| |1970-01-01T00:00:00Z| 61026.0000000000 | 61026.0000000000 | [](#count-the-values-that-match-a-regular-expression) Count the values that match a regular expression Return the number of non-null field values for every field key that contains the word `water` in the `h2o_feet` measurement. ```sql SELECT COUNT(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |count\_water\_level| |--------------------|-------------------| |1970-01-01T00:00:00Z| 61026.0000000000 | [](#count-distinct-values-for-a-field) Count distinct values for a field Return the number of unique field values for the `level description` field key and the `h2o_feet` measurement. InfluxQL supports nesting [DISTINCT()](#distinct) in `COUNT()`. ```sql SELECT COUNT(DISTINCT("level description")) FROM "h2o_feet" ``` name: h2o\_feet | time | count | |--------------------|------------| |1970-01-01T00:00:00Z|4.0000000000| ## DISTINCT() Returns the list of unique [field values](/influxdb/v2/reference/glossary/#field-value). Supports all field value [data types](/influxdb/v2/reference/glossary/#data-type). InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count). ### Syntax ```sql SELECT DISTINCT( [ | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `DISTINCT(field_key)` Returns the unique field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). #### Examples [](#list-the-distinct-field-values-associated-with-a-field-key) List the distinct field values associated with a field key Return a tabular list of the unique field values in the `level description`field key in the `h2o_feet` measurement. ```sql SELECT DISTINCT("level description") FROM "h2o_feet" ``` name: h2o\_feet | time | distinct | |--------------------|-------------------------| |1970-01-01T00:00:00Z| between 6 and 9 feet | |1970-01-01T00:00:00Z| below 3 feet | |1970-01-01T00:00:00Z| between 3 and 6 feet | |1970-01-01T00:00:00Z|at or greater than 9 feet| ## INTEGRAL() Returns the area under the curve for subsequent [field values](/influxdb/v2/reference/glossary/#field-value). > [!Note] > `INTEGRAL()` does not support [`fill()`](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill). `INTEGRAL()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT INTEGRAL( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` InfluxDB calculates the area under the curve for subsequent field values and converts those results into the summed area per `unit`. The `unit` argument is an integer followed by an optional [duration literal](/influxdb/v2/reference/syntax/influxql/spec/#literals). If the query does not specify the `unit`, the unit defaults to one second (`1s`). `INTEGRAL(field_key)` Returns the area under the curve for subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `INTEGRAL(/regular_expression/)` Returns the area under the curve for subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `INTEGRAL(*)` Returns the average field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples The following examples use a subset of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data) data: ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-integral-for-the-field-values-associated-with-a-field-key) Calculate the integral for the field values associated with a field key Return the area under the curve (in seconds) for the field values associated with the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT INTEGRAL("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time | integral | |--------------------|---------------| |1970-01-01T00:00:00Z|4184.8200000000| [](#calculate-the-integral-for-the-field-values-associated-with-a-field-key-and-specify-the-unit-option) Calculate the integral for the field values associated with a field key and specify the unit option Return the area under the curve (in minutes) for the field values associated with the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT INTEGRAL("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time | integral | |--------------------|-------------| |1970-01-01T00:00:00Z|69.7470000000| [](#calculate-the-integral-for-the-field-values-associated-with-each-field-key-in-a-measurement-and-specify-the-unit-option) Calculate the integral for the field values associated with each field key in a measurement 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(*,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |integral\_water\_level| |--------------------|----------------------| |1970-01-01T00:00:00Z| 69.7470000000 | [](#calculate-the-integral-for-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression-and-specify-the-unit-option) Calculate the integral for the field values associated with each field key that matches a regular expression 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 includes the word `water` in the `h2o_feet` measurement. ```sql SELECT INTEGRAL(/water/,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |integral\_water\_level| |--------------------|----------------------| |1970-01-01T00:00:00Z| 69.7470000000 | [](#calculate-the-integral-for-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the integral for the field values associated with a field key and include several clauses Return the area under the curve (in minutes) for the field values associated with the `water_level` field key and in the `h2o_feet` measurement in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax) between`2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z`, [grouped](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 12-minute intervals, and[limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of results returned to one. ```sql SELECT INTEGRAL("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) LIMIT 1 ``` name: h2o\_feet | time | integral | |--------------------|-------------| |2019-08-18T00:00:00Z|28.3590000000| ## MEAN() Returns the arithmetic mean (average) of [field values](/influxdb/v2/reference/glossary/#field-value). `MEAN()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT MEAN( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MEAN(field_key)`Returns the average field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MEAN(/regular\_expression/) Returns the average field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `MEAN(*)`Returns the average field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-mean-field-value-associated-with-a-field-key) Calculate the mean field value associated with a field key Return the average field value in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT MEAN("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | mean | |--------------------|------------| |1970-01-01T00:00:00Z|4.4418674882| [](#calculate-the-mean-field-value-associated-with-each-field-key-in-a-measurement) Calculate the mean field value associated with each field key in a measurement Return the average field value for every field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT MEAN(*) FROM "h2o_feet" ``` name: h2o\_feet | time |mean\_water\_level| |--------------------|------------------| |1970-01-01T00:00:00Z| 4.4418674882 | [](#calculate-the-mean-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the mean field value associated with each field key that matches a regular expression Return the average field value for each field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT MEAN(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |mean\_water\_level| |--------------------|------------------| |1970-01-01T00:00:00Z| 4.4418674882 | [](#calculate-the-mean-field-value-associated-with-a-field-key-and-include-several-clauses) Calculate the mean field value associated with a field key and include several clauses Return the average of the values in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01` and[limit](/influxdb/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to seven and one. ```sql SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 7 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time | mean | |--------------------|------------| |2019-08-18T00:00:00Z|8.4615000000| |2019-08-18T00:12:00Z|8.2725000000| |2019-08-18T00:24:00Z|8.0710000000| ## MEDIAN() Returns the middle value from a sorted list of [field values](/influxdb/v2/reference/glossary/#field-value). `MEDIAN()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). > [!Note] > **Note:** `MEDIAN()` is nearly equivalent to [`PERCENTILE(field_key, 50)`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile), except `MEDIAN()` returns the average of the two middle field values if the field contains an even number of values. ### Syntax ```sql SELECT MEDIAN( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MEDIAN(field_key)` Returns the middle field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MEDIAN(/regular_expression/)` Returns the middle field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `MEDIAN(*)` Returns the middle field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-median-field-value-associated-with-a-field-key) Calculate the median field value associated with a field key Return the middle field value in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT MEDIAN("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | median | |--------------------|------------| |1970-01-01T00:00:00Z|4.1240000000| [](#calculate-the-median-field-value-associated-with-each-field-key-in-a-measurement) Calculate the median field value associated with each field key in a measurement Return the middle field value for every field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT MEDIAN(*) FROM "h2o_feet" ``` name: h2o\_feet | time |median\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 4.1240000000 | [](#calculate-the-median-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the median field value associated with each field key that matches a regular expression Return the middle field value for every field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT MEDIAN(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |median\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 4.1240000000 | [](#calculate-the-median-field-value-associated-with-a-field-key-and-include-several-clauses) Calculate the median field value associated with a field key and include several clauses Return the middle field value in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `700 `, [limit](/influxdb/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to seven and one, and [offset](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. ```sql SELECT MEDIAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(700) LIMIT 7 SLIMIT 1 SOFFSET 1 ``` name: h2o\_feet tags: location=santa\_monica | time | median | |--------------------|------------| |2019-08-18T00:00:00Z|2.3655000000| |2019-08-18T00:12:00Z|2.3360000000| |2019-08-18T00:24:00Z|2.2655000000| ## MODE() Returns the most frequent value in a list of [field values](/influxdb/v2/reference/glossary/#field-value). `MODE()` supports all field value [data types](/influxdb/v2/reference/glossary/#data-type). > [!Note] > **Note:** `MODE()` returns the field value with the earliest [timestamp](/influxdb/v2/reference/glossary/#timestamp) if there’s a tie between two or more values for the maximum number of occurrences. ### Syntax ```sql SELECT MODE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MODE(field_key)` Returns the most frequent field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MODE(/regular_expression/)` Returns the most frequent field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `MODE(*)` Returns the most frequent field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-mode-field-value-associated-with-a-field-key) Calculate the mode field value associated with a field key Return the most frequent field value in the `level description` field key and in the `h2o_feet` measurement. ```sql SELECT MODE("level description") FROM "h2o_feet" ``` name: h2o\_feet | time | mode | |--------------------|--------------------| |1970-01-01T00:00:00Z|between 3 and 6 feet| [](#calculate-the-mode-field-value-associated-with-each-field-key-in-a-measurement) Calculate the mode field value associated with each field key in a measurement Return the most frequent field value for every field key in the `h2o_feet` measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT MODE(*) FROM "h2o_feet" ``` name: h2o\_feet | time |mode\_level description|mode\_water\_level| |--------------------|-----------------------|------------------| |1970-01-01T00:00:00Z| between 3 and 6 feet | 2.6900000000 | [](#calculate-the-mode-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the mode field value associated with each field key that matches a regular expression Return the most frequent field value for every field key that includes the word`/water/` in the `h2o_feet` measurement. ```sql SELECT MODE(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |mode\_water\_level| |--------------------|------------------| |1970-01-01T00:00:00Z| 2.6900000000 | [](#calculate-the-mode-field-value-associated-with-a-field-key-and-include-several-clauses) Calculate the mode field value associated with a field key and include several clauses Return the mode of the values associated with the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [limits](/influxdb/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to three and one, and it [offsets](/influxdb/v2/query-data/influxql/explore-data #the-offset-and-soffset-clauses) the series returned by one. ```sql SELECT MODE("level description") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* LIMIT 3 SLIMIT 1 SOFFSET 1 ``` name: h2o\_feet tags: location=santa\_monica | time | mode | |--------------------|------------| |2019-08-18T00:00:00Z|below 3 feet| |2019-08-18T00:12:00Z|below 3 feet| |2019-08-18T00:24:00Z|below 3 feet| ## SPREAD() Returns the difference between the minimum and maximum [field values](/influxdb/v2/reference/glossary/#field-value). `SPREAD()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT SPREAD( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `SPREAD(field_key)` Returns the difference between the minimum and maximum field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `SPREAD(/regular_expression/)` Returns the difference between the minimum and maximum field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `SPREAD(*)` Returns the difference between the minimum and maximum field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-spread-for-the-field-values-associated-with-a-field-key) Calculate the spread for the field values associated with a field key Return the difference between the minimum and maximum field values in the`water_level` field key and in the `h2o_feet` measurement. ```sql SELECT SPREAD("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | spread | |--------------------|-------------| |1970-01-01T00:00:00Z|10.5740000000| [](#calculate-the-spread-for-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the spread for the field values associated with each field key in a measurement Return the difference between the minimum and maximum field values for every field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT SPREAD(*) FROM "h2o_feet" ``` name: h2o\_feet | time |spread\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 10.5740000000 | [](#calculate-the-spread-for-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the spread for the field values associated with each field key that matches a regular expression Return the difference between the minimum and maximum field values for every field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT SPREAD(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |spread\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 10.5740000000 | [](#calculate-the-spread-for-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the spread for the field values associated with a field key and include several clauses Return the difference between the minimum and maximum field values in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `18`, [lim ts](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to three and one, and [offsets](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. ```sql SELECT SPREAD("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18) LIMIT 3 SLIMIT 1 SOFFSET 1 ``` name: h2o\_feet tags: location=santa\_monica | time | spread | |--------------------|------------| |2019-08-18T00:00:00Z|0.0270000000| |2019-08-18T00:12:00Z|0.0140000000| |2019-08-18T00:24:00Z|0.0030000000| ## STDDEV() Returns the standard deviation of [field values](/influxdb/v2/reference/glossary/#field-value). `STDDEV()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT STDDEV( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `STDDEV(field_key)` Returns the standard deviation of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `STDDEV(/regular_expression/)` Returns the standard deviation of field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `STDDEV(*)` Returns the standard deviation of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-standard-deviation-for-the-field-values-associated-with-a-field-key) Calculate the standard deviation for the field values associated with a field key Return the standard deviation of the field values in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT STDDEV("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | stddev | |--------------------|------------| |1970-01-01T00:00:00Z|2.2789744110| [](#calculate-the-standard-deviation-for-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the standard deviation for the field values associated with each field key in a measurement Return the standard deviation of numeric fields in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT STDDEV(*) FROM "h2o_feet" ``` name: h2o\_feet | time |stddev\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 2.2789744110 | [](#calculate-the-standard-deviation-for-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the standard deviation for the field values associated with each field key that matches a regular expression Return the standard deviation of numeric fields with `water` in the field key in the `h2o_feet` measurement. ```sql SELECT STDDEV(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |stddev\_water\_level| |--------------------|--------------------| |1970-01-01T00:00:00Z| 2.2789744110 | [](#calculate-the-standard-deviation-for-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the standard deviation for the field values associated with a field key and include several clauses Return the standard deviation of the field values in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `18000`, [limit](/influxdb/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to two and one, and [offsets](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. ```sql SELECT STDDEV("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18000) LIMIT 2 SLIMIT 1 SOFFSET 1 ``` name: h2o\_feet tags: location=santa\_monica | time | stddev | |--------------------|------------| |2019-08-18T00:00:00Z|0.0190918831| |2019-08-18T00:12:00Z|0.0098994949| ## SUM() Returns the sum of [field values](/influxdb/v2/reference/glossary/#field-value). `SUM()` supports int64 and float64 field value [data types](/influxdb/v2/reference/glossary/#data-type). ### Syntax ```sql SELECT SUM( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `SUM(field_key)` Returns the sum of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `SUM(/regular_expression/)` Returns the sum of field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/#regular-expressions). `SUM(*)` Returns the sums of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). #### Examples [](#calculate-the-sum-of-the-field-values-associated-with-a-field-key) Calculate the sum of the field values associated with a field key Return the summed total of the field values in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT SUM("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | sum | |--------------------|-----------------| |1970-01-01T00:00:00Z|271069.4053333958| [](#calculate-the-sum-of-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the sum of the field values associated with each field key in a measurement Return the summed total of numeric fields in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT SUM(*) FROM "h2o_feet" ``` name: h2o\_feet | time |sum\_water\_level| |--------------------|-----------------| |1970-01-01T00:00:00Z|271069.4053333958| [](#calculate-the-sum-of-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the sum of the field values associated with each field key that matches a regular expression Return the summed total of numeric fields with `water` in the field key in the `h2o_feet` measurement. ```sql SELECT SUM(/water/) FROM "h2o_feet" ``` name: h2o\_feet | time |sum\_water\_level| |--------------------|-----------------| |1970-01-01T00:00:00Z|271069.4053333958| [](#calculate-the-sum-of-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the sum of the field values associated with a field key and include several clauses Return the summed total of the field values in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with 18000, and [limit](/influxdb/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to four and one. ```sql SELECT SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18000) LIMIT 4 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time | sum | |--------------------|-------------| |2019-08-18T00:00:00Z|16.9230000000| |2019-08-18T00:12:00Z|16.5450000000| |2019-08-18T00:24:00Z|16.1420000000| | time | count | | --- | --- | | time | count | | 1970-01-01T00:00:00Z | 61026.0000000000 | | time | count_level description | count_water_level | | --- | --- | --- | | time | count_level description | count_water_level | | 1970-01-01T00:00:00Z | 61026.0000000000 | 61026.0000000000 | | time | count_water_level | | --- | --- | | time | count_water_level | | 1970-01-01T00:00:00Z | 61026.0000000000 | | time | count | | --- | --- | | time | count | | 1970-01-01T00:00:00Z | 4.0000000000 | | time | distinct | | --- | --- | | time | distinct | | 1970-01-01T00:00:00Z | between 6 and 9 feet | | 1970-01-01T00:00:00Z | below 3 feet | | 1970-01-01T00:00:00Z | between 3 and 6 feet | | 1970-01-01T00:00:00Z | at or greater than 9 feet | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | integral | | --- | --- | | time | integral | | 1970-01-01T00:00:00Z | 4184.8200000000 | | time | integral | | --- | --- | | time | integral | | 1970-01-01T00:00:00Z | 69.7470000000 | | time | integral_water_level | | --- | --- | | time | integral_water_level | | 1970-01-01T00:00:00Z | 69.7470000000 | | time | integral_water_level | | --- | --- | | time | integral_water_level | | 1970-01-01T00:00:00Z | 69.7470000000 | | time | integral | | --- | --- | | time | integral | | 2019-08-18T00:00:00Z | 28.3590000000 | | time | mean | | --- | --- | | time | mean | | 1970-01-01T00:00:00Z | 4.4418674882 | | time | mean_water_level | | --- | --- | | time | mean_water_level | | 1970-01-01T00:00:00Z | 4.4418674882 | | time | mean_water_level | | --- | --- | | time | mean_water_level | | 1970-01-01T00:00:00Z | 4.4418674882 | | time | mean | | --- | --- | | time | mean | | 2019-08-18T00:00:00Z | 8.4615000000 | | 2019-08-18T00:12:00Z | 8.2725000000 | | 2019-08-18T00:24:00Z | 8.0710000000 | | time | median | | --- | --- | | time | median | | 1970-01-01T00:00:00Z | 4.1240000000 | | time | median_water_level | | --- | --- | | time | median_water_level | | 1970-01-01T00:00:00Z | 4.1240000000 | | time | median_water_level | | --- | --- | | time | median_water_level | | 1970-01-01T00:00:00Z | 4.1240000000 | | time | median | | --- | --- | | time | median | | 2019-08-18T00:00:00Z | 2.3655000000 | | 2019-08-18T00:12:00Z | 2.3360000000 | | 2019-08-18T00:24:00Z | 2.2655000000 | | time | mode | | --- | --- | | time | mode | | 1970-01-01T00:00:00Z | between 3 and 6 feet | | time | mode_level description | mode_water_level | | --- | --- | --- | | time | mode_level description | mode_water_level | | 1970-01-01T00:00:00Z | between 3 and 6 feet | 2.6900000000 | | time | mode_water_level | | --- | --- | | time | mode_water_level | | 1970-01-01T00:00:00Z | 2.6900000000 | | time | mode | | --- | --- | | time | mode | | 2019-08-18T00:00:00Z | below 3 feet | | 2019-08-18T00:12:00Z | below 3 feet | | 2019-08-18T00:24:00Z | below 3 feet | | time | spread | | --- | --- | | time | spread | | 1970-01-01T00:00:00Z | 10.5740000000 | | time | spread_water_level | | --- | --- | | time | spread_water_level | | 1970-01-01T00:00:00Z | 10.5740000000 | | time | spread_water_level | | --- | --- | | time | spread_water_level | | 1970-01-01T00:00:00Z | 10.5740000000 | | time | spread | | --- | --- | | time | spread | | 2019-08-18T00:00:00Z | 0.0270000000 | | 2019-08-18T00:12:00Z | 0.0140000000 | | 2019-08-18T00:24:00Z | 0.0030000000 | | time | stddev | | --- | --- | | time | stddev | | 1970-01-01T00:00:00Z | 2.2789744110 | | time | stddev_water_level | | --- | --- | | time | stddev_water_level | | 1970-01-01T00:00:00Z | 2.2789744110 | | time | stddev_water_level | | --- | --- | | time | stddev_water_level | | 1970-01-01T00:00:00Z | 2.2789744110 | | time | stddev | | --- | --- | | time | stddev | | 2019-08-18T00:00:00Z | 0.0190918831 | | 2019-08-18T00:12:00Z | 0.0098994949 | | time | sum | | --- | --- | | time | sum | | 1970-01-01T00:00:00Z | 271069.4053333958 | | time | sum_water_level | | --- | --- | | time | sum_water_level | | 1970-01-01T00:00:00Z | 271069.4053333958 | | time | sum_water_level | | --- | --- | | time | sum_water_level | | 1970-01-01T00:00:00Z | 271069.4053333958 | | time | sum | | --- | --- | | time | sum | | 2019-08-18T00:00:00Z | 16.9230000000 | | 2019-08-18T00:12:00Z | 16.5450000000 | | 2019-08-18T00:24:00Z | 16.1420000000 | --- # InfluxQL selector functions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/functions/selectors/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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. Each selector function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). * [BOTTOM()](#bottom) * [FIRST()](#first) * [LAST()](#last) * [MAX()](#max) * [MIN()](#min) * [PERCENTILE()](#percentile) * [SAMPLE()](#sample) * [TOP()](#top) ## BOTTOM() Returns the smallest `N` [field values](/influxdb/v2/reference/glossary/#field-value). `BOTTOM()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). > [!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. ### Syntax ```sql SELECT BOTTOM([,], )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `BOTTOM(field_key,N)` Returns the smallest N field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `BOTTOM(field_key,tag_key,N)` Returns the smallest field value for N tag values of the [tag key](/influxdb/v2/reference/glossary/#tag-key). Add a comma between multiple tag keys: `tag_key,tag_key`. `BOTTOM((field_key,N),tag_key,field_key)` Returns the smallest N field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). Add a comma between multiple tag or field keys: `tag_key,tag_key,field_key,field_key`. #### Examples [](#select-the-bottom-three-field-values-associated-with-a-field-key) Select the bottom three field values associated with a field key Return the smallest three field values in the `water_level` field key and in the`h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). ```sql SELECT BOTTOM("water_level",3) FROM "h2o_feet" ``` name: h2o\_feet | time |bottom | |--------------------|-------| |2019-08-29T14:30:00Z|\-0.610| |2019-08-29T14:36:00Z|\-0.591| |2019-08-30T15:18:00Z|\-0.594| [](#select-the-bottom-field-value-associated-with-a-field-key-for-two-tags) Select the bottom field value associated with a field key for two tags Return the smallest field values in the `water_level` field key for two tag values associated with the `location` tag key. ```sql SELECT BOTTOM("water_level","location",2) FROM "h2o_feet" ``` name: h2o\_feet | time |bottom | location | |--------------------|-------|-------------| |2019-08-29T10:36:00Z|\-0.243|santa\_monica| |2019-08-29T14:30:00Z|\-0.610|coyote\_creek| [](#select-the-bottom-four-field-values-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the bottom four field values associated with a field key and the relevant tags and fields Return the smallest four field values in the `water_level` field key and the relevant values of the `location` tag key and the `level description` field key. ```sql SELECT BOTTOM("water_level",4),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time |bottom | location |level description| |--------------------|-------|-------------|-----------------| |2019-08-29T14:24:00Z|\-0.587|coyote\_creek| below 3 feet | |2019-08-29T14:30:00Z|\-0.610|coyote\_creek| below 3 feet | |2019-08-29T14:36:00Z|\-0.591|coyote\_creek| below 3 feet | |2019-08-30T15:18:00Z|\-0.594|coyote\_creek| below 3 feet | [](#select-the-bottom-three-field-values-associated-with-a-field-key-and-include-several-clauses) Select the bottom three field values associated with a field key and include several clauses Return the smallest three values in the `water_level` field key for each 24-minute[interval](/influxdb/v2/query-data/influxql/explore-data/group-by/#basic-group-by-time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:54:00Z` with results in[descending timestamp](/influxdb/v2/query-data/influxql/explore-data/order-by/) order. ```sql SELECT BOTTOM("water_level",3),"location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) ORDER BY time DESC ``` name: h2o\_feet | time | bottom | location | |--------------------|------------|-------------| |2019-08-18T00:54:00Z| 2.172 |santa\_monica| |2019-08-18T00:54:00Z| 7.510 |coyote\_creek| |2019-08-18T00:48:00Z| 2.087 |santa\_monica| |2019-08-18T00:42:00Z| 2.093 |santa\_monica| |2019-08-18T00:36:00Z|2.1261441420|santa\_monica| |2019-08-18T00:24:00Z| 2.264 |santa\_monica| |2019-08-18T00:18:00Z| 2.329 |santa\_monica| |2019-08-18T00:12:00Z| 2.343 |santa\_monica| |2019-08-18T00:00:00Z| 2.352 |santa\_monica| Notice that the [GROUP BY time() clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals)does not override the points’ original timestamps. See [Issue 1](#bottom-with-a-group-by-time-clause) in the section below for a more detailed explanation of that behavior. ### Common issues with BOTTOM() #### BOTTOM() with a GROUP BY time() clause Queries with `BOTTOM()` and a `GROUP BY time()` clause return the specified number of points per `GROUP BY time()` interval. For [most `GROUP BY time()` queries](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals), the returned timestamps mark the start of the `GROUP BY time()` interval.`GROUP BY time()` queries with the `BOTTOM()` function behave differently; they maintain the timestamp of the original data point. ##### Example The query below returns two points per 18-minute`GROUP BY time()` interval. Notice that the returned timestamps are the points’ original timestamps; they are not forced to match the start of the `GROUP BY time()` intervals. ```sql SELECT BOTTOM("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) ``` name: h2o\_feet | time |bottom| |--------------------|------| |2019-08-18T00:00:00Z|2.064 | |2019-08-18T00:12:00Z|2.028 | |2019-08-18T00:24:00Z|2.041 | |2019-08-18T00:30:00Z|2.051 | *Notice that the first two rows contain the smallest values from the first time interval and the last two rows contains the smallest values for the second time interval.* #### BOTTOM() and a tag key with fewer than N tag values Queries with the syntax `SELECT BOTTOM(,,)` can return fewer points than expected. If the tag key has `X` tag values, the query specifies `N` values, and `X` is smaller than `N`, then the query returns `X` points. ##### Example The query below asks for the smallest field values of `water_level` for three tag values of the `location` tag key. Because the `location` tag key has two tag values (`santa_monica` and `coyote_creek`), the query returns two points instead of three. ```sql SELECT BOTTOM("water_level","location",3) FROM "h2o_feet" ``` name: h2o\_feet | time |bottom | location | |--------------------|-------|-------------| |2019-08-29T10:36:00Z|\-0.243|santa\_monica| |2019-08-29T14:30:00Z|\-0.610|coyote\_creek| ## FIRST() Returns the [field value ](/influxdb/v2/reference/glossary/#field-value)with the oldest timestamp. ### Syntax ```sql SELECT FIRST()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `FIRST(field_key)` Returns the oldest field value (determined by timestamp) associated with the field key. `FIRST(/regular_expression/)` Returns the oldest field value (determined by timestamp) associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `FIRST(*)` Returns the oldest field value (determined by timestamp) associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `FIRST(field_key),tag_key(s),field_key(s)` Returns the oldest field value (determined by timestamp) associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `FIRST()` supports all field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-the-first-field-value-associated-with-a-field-key) Select the first field value associated with a field key Return the oldest field value (determined by timestamp) associated with the`level description` field key and in the `h2o_feet` measurement. ```sql SELECT FIRST("level description") FROM "h2o_feet" ``` name: h2o\_feet | time | first | |--------------------|--------------------| |2019-08-17T00:00:00Z|between 6 and 9 feet| [](#select-the-first-field-value-associated-with-each-field-key-in-a-measurement) Select the first field value associated with each field key in a measurement Return the oldest field value (determined by timestamp) for each field key in the `h2o_feet` measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT FIRST(*) FROM "h2o_feet" ``` name: h2o\_feet | time |first\_level description|first\_water\_level| |--------------------|------------------------|-------------------| |1970-01-01T00:00:00Z| between 6 and 9 feet | 8.120 | [](#select-the-first-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Select the first field value associated with each field key that matches a regular expression Return the oldest field value for each field key that includes the word `level` in the `h2o_feet` measurement. ```sql SELECT FIRST(/level/) FROM "h2o_feet" ``` name: h2o\_feet | time |first\_level description|first\_water\_level| |--------------------|------------------------|-------------------| |1970-01-01T00:00:00Z| between 6 and 9 feet | 8.120 | [](#select-the-first-value-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the first value associated with a field key and the relevant tags and fields Return the oldest field value (determined by timestamp) in the `level description`field key and the relevant values of the `location` tag key and the `water_level` field key. ```sql SELECT FIRST("level description"),"location","water_level" FROM "h2o_feet" ``` name: h2o\_feet | time | first | location |water\_level| |--------------------|--------------------|-------------|------------| |2019-08-17T00:00:00Z|between 6 and 9 feet|coyote\_creek| 8.120 | [](#select-the-first-field-value-associated-with-a-field-key-and-include-several-clauses) Select the first field value associated with a field key and include several clauses Returns the oldest field value (determined by timestamp) in the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and[groups](/influxdb/v2/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to four and one. ```sql SELECT FIRST("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time |first| |--------------------|-----| |2019-08-17T23:48:00Z|8.635| |2019-08-18T00:00:00Z|8.504| |2019-08-18T00:12:00Z|8.320| |2019-08-18T00:24:00Z|8.130| Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. The timestamps in the results indicate the the start of each 12-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. ## LAST() Returns the [field value](/influxdb/v2/reference/glossary/#field-value) with the most recent timestamp. ### Syntax ```sql SELECT LAST()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `LAST(field_key)` Returns the newest field value (determined by timestamp) associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `LAST(/regular_expression/)` Returns the newest field value (determined by timestamp) associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `LAST(*)` Returns the newest field value (determined by timestamp) associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `LAST(field_key),tag_key(s),field_key(s)` Returns the newest field value (determined by timestamp) associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `LAST()` supports all field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-the-last-field-values-associated-with-a-field-key) Select the last field values associated with a field key Return the newest field value (determined by timestamp) associated with the`level description` field key and in the `h2o_feet` measurement. ```sql SELECT LAST("level description") FROM "h2o_feet" ``` name: h2o\_feet | time | last | |--------------------|--------------------| |2019-09-17T21:42:00Z|between 3 and 6 feet| [](#select-the-last-field-values-associated-with-each-field-key-in-a-measurement) Select the last field values associated with each field key in a measurement Return the newest field value (determined by timestamp) for each field key in the `h2o_feet` measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT LAST(*) FROM "h2o_feet" ``` name: h2o\_feet | time |last\_level description|last\_water\_level| |--------------------|-----------------------|------------------| |1970-01-01T00:00:00Z| between 3 and 6 feet | 4.938 | [](#select-the-last-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Select the last field value associated with each field key that matches a regular expression Return the newest field value for each field key that includes the word `level`in the `h2o_feet` measurement. ```sql SELECT LAST(/level/) FROM "h2o_feet" ``` name: h2o\_feet | time |last\_level description|last\_water\_level| |--------------------|-----------------------|------------------| |1970-01-01T00:00:00Z| between 3 and 6 feet | 4.938 | [](#select-the-last-field-value-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the last field value associated with a field key and the relevant tags and fields Return the newest field value (determined by timestamp) in the `level description`field key and the relevant values of the `location` tag key and the `water_level` field key. ```sql SELECT LAST("level description"),"location","water_level" FROM "h2o_feet" ``` name: h2o\_feet | time | last | location |water\_level| |--------------------|--------------------|-------------|------------| |2019-09-17T21:42:00Z|between 3 and 6 feet|santa\_monica| 4.938 | [](#select-the-last-field-value-associated-with-a-field-key-and-include-several-clauses) Select the last field value associated with a field key and include several clauses Return the newest field value (determined by timestamp) in the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and[groups](/influxdb/v2/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to four and one. ```sql SELECT LAST("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time |last | |--------------------|-----| |2019-08-17T23:48:00Z|8.570| |2019-08-18T00:00:00Z|8.419| |2019-08-18T00:12:00Z|8.225| |2019-08-18T00:24:00Z|8.012| Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. The timestamps in the results indicate the the start of each 12-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. ## MAX() Returns the greatest [field value](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SELECT MAX()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MAX(field_key)` Returns the greatest field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MAX(/regular_expression/)` Returns the greatest field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `MAX(*)` Returns the greatest field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `MAX(field_key),tag_key(s),field_key(s)` Returns the greatest field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `MAX()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-the-maximum-field-value-associated-with-a-field-key) Select the maximum field value associated with a field key Return the greatest field value in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT MAX("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | max | |--------------------|-----| |2019-08-28T07:24:00Z|9.964| [](#select-the-maximum-field-value-associated-with-each-field-key-in-a-measurement) Select the maximum field value associated with each field key in a measurement Return the greatest field value for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT MAX(*) FROM "h2o_feet" ``` name: h2o\_feet | time |max\_water\_level| |--------------------|-----------------| |2019-08-28T07:24:00Z| 9.964 | [](#select-the-maximum-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Select the maximum field value associated with each field key that matches a regular expression Return the greatest field value for each field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT MAX(/level/) FROM "h2o_feet" ``` name: h2o\_feet | time |max\_water\_level| |--------------------|-----------------| |2019-08-28T07:24:00Z| 9.964 | [](#select-the-maximum-field-value-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the maximum field value associated with a field key and the relevant tags and fields Return the greatest field value in the `water_level` field key and the relevant values of the `location` tag key and the `level description` field key. ```sql SELECT MAX("water_level"),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time | max | location | level description | |--------------------|-----|-------------|-------------------------| |2019-08-28T07:24:00Z|9.964|coyote\_creek|at or greater than 9 feet| [](#select-the-maximum-field-value-associated-with-a-field-key-and-include-several-clauses) Select the maximum field value associated with a field key and include several clauses Return the greatest field value in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and[groups](/influxdb/v2/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to four and one. ```sql SELECT MAX("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time | max | |--------------------|-----| |2019-08-17T23:48:00Z|8.635| |2019-08-18T00:00:00Z|8.504| |2019-08-18T00:12:00Z|8.320| |2019-08-18T00:24:00Z|8.130| Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. The timestamps in the results indicate the the start of each 12-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. ## MIN() Returns the lowest [field value](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SELECT MIN()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MIN(field_key)` Returns the lowest field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MIN(/regular_expression/)` Returns the lowest field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `MIN(*)` Returns the lowest field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `MIN(field_key),tag_key(s),field_key(s)` Returns the lowest field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `MIN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-the-minimum-field-value-associated-with-a-field-key) Select the minimum field value associated with a field key Return the lowest field value in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT MIN("water_level") FROM "h2o_feet" ``` name: h2o\_feet | time | min | |--------------------|-------| |2019-08-28T14:30:00Z|\-0.610| [](#select-the-minimum-field-value-associated-with-each-field-key-in-a-measurement) Select the minimum field value associated with each field key in a measurement Return the lowest field value for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT MIN(*) FROM "h2o_feet" ``` name: h2o\_feet | time |min\_water\_level| |--------------------|-----------------| |2019-08-28T14:30:00Z| \-0.610 | [](#select-the-minimum-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Select the minimum field value associated with each field key that matches a regular expression Return the lowest field value for each numeric field with `water` in the field key in the `h2o_feet` measurement. ```sql SELECT MIN(/level/) FROM "h2o_feet" ``` name: h2o\_feet | time |min\_water\_level| |--------------------|-----------------| |2019-08-28T14:30:00Z| \-0.610 | [](#select-the-minimum-field-value-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the minimum field value associated with a field key and the relevant tags and fields Return the lowest field value in the `water_level` field key and the relevant values of the `location` tag key and the `level description` field key. ```sql SELECT MIN("water_level"),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time | min | location |level description| |--------------------|-------|-------------|-----------------| |2019-08-28T14:30:00Z|\-0.610|coyote\_creek| below 3 feet | [](#select-the-minimum-field-value-associated-with-a-field-key-and-include-several-clauses) Select the minimum field value associated with a field key and include several clauses Return the lowest field value in the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and[groups](/influxdb/v2/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to four and one. ```sql SELECT MIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 ``` name: h2o\_feet tags: location=coyote\_creek | time | min | |--------------------|-----| |2019-08-17T23:48:00Z|8.570| |2019-08-18T00:00:00Z|8.419| |2019-08-18T00:12:00Z|8.225| |2019-08-18T00:24:00Z|8.012| Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. The timestamps in the results indicate the the start of each 12-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. ## PERCENTILE() Returns the `N`th percentile [field value](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SELECT PERCENTILE(, )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `PERCENTILE(field_key,N)` Returns the Nth percentile field value associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `PERCENTILE(/regular_expression/,N)` Returns the Nth percentile field value associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `PERCENTILE(*,N)` Returns the Nth percentile field value associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `PERCENTILE(field_key,N),tag_key(s),field_key(s)` Returns the Nth percentile field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `N` must be an integer or floating point number between `0` and `100`, inclusive.`PERCENTILE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-the-fifth-percentile-field-value-associated-with-a-field-key) Select the fifth percentile field value associated with a field key Return the field value that is larger than five percent of the field values in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT PERCENTILE("water_level",5) FROM "h2o_feet" ``` name: h2o\_feet | time |percentile| |--------------------|----------| |2019-09-01T17:54:00Z| 1.122 | [](#select-the-fifth-percentile-field-value-associated-with-each-field-key-in-a-measurement) Select the fifth percentile field value associated with each field key in a measurement Return the field value that is larger than five percent of the field values in each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT PERCENTILE(*,5) FROM "h2o_feet" ``` name: h2o\_feet | time |percentile\_water\_level| |--------------------|------------------------| |2019-09-01T17:54:00Z| 1.122 | [](#select-fifth-percentile-field-value-associated-with-each-field-key-that-matches-a-regular-expression) Select fifth percentile field value associated with each field key that matches a regular expression Return the field value that is larger than five percent of the field values in each numeric field with `water` in the field key. ```sql SELECT PERCENTILE(/level/,5) FROM "h2o_feet" ``` name: h2o\_feet | time |percentile\_water\_level| |--------------------|------------------------| |2019-09-01T17:54:00Z| 1.122 | [](#select-the-fifth-percentile-field-values-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the fifth percentile field values associated with a field key and the relevant tags and fields Return the field value that is larger than five percent of the field values in the `water_level` field key and the relevant values of the `location` tag key and the `level description` field key. ```sql SELECT PERCENTILE("water_level",5),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time |percentile| location |level description| |--------------------|----------|-------------|-----------------| |2019-08-24T10:18:00Z| 1.122 |coyote\_creek| below 3 feet | [](#select-the-twentieth-percentile-field-value-associated-with-a-field-key-and-include-several-clauses) Select the twentieth percentile field value associated with a field key and include several clauses Return the field value that is larger than 20 percent of the values in the`water_level` field in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and [group](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 24-minute intervals. Then [fill](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `15` and [limit](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to two. ```sql SELECT PERCENTILE("water_level",20) FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) fill(15) LIMIT 2 ``` name: h2o\_feet | time |percentile| |--------------------|----------| |2019-08-17T23:36:00Z| 2.398 | |2019-08-18T00:00:00Z| 2.343 | Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. The timestamps in the results indicate the the start of each 24-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:36:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:00:00Z` and just before `2019-08-18T00:24:00Z`. ### Common issues with PERCENTILE() #### PERCENTILE() compared to other InfluxQL functions * `PERCENTILE(,100)` is equivalent to [`MAX()`](#max). * `PERCENTILE(, 50)` is nearly equivalent to [`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median), except the `MEDIAN()` function returns the average of the two middle values if the field key contains an even number of field values. * `PERCENTILE(,0)` is not equivalent to [`MIN()`](#min). This is a known [issue](https://github.com/influxdata/influxdb/issues/4418). ## SAMPLE() Returns a random sample of `N` [field values](/influxdb/v2/reference/glossary/#field-value).`SAMPLE()` uses [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling) to generate the random points. ### Syntax ```sql SELECT SAMPLE(, )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `SAMPLE(field_key,N)` Returns N randomly selected field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `SAMPLE(/regular_expression/,N)` Returns N randomly selected field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `SAMPLE(*,N)` Returns N randomly selected field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `SAMPLE(field_key,N),tag_key(s),field_key(s)` Returns N randomly selected field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `N` must be an integer.`SAMPLE()` supports all field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#select-a-sample-of-the-field-values-associated-with-a-field-key) Select a sample of the field values associated with a field key Return two randomly selected points from the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT SAMPLE("water_level",2) FROM "h2o_feet" ``` name: h2o\_feet | time |sample| |--------------------|------| |2019-08-22T03:42:00Z|7.218 | |2019-08-28T20:18:00Z|2.848 | [](#select-a-sample-of-the-field-values-associated-with-each-field-key-in-a-measurement) Select a sample of the field values associated with each field key in a measurement Return two randomly selected points for each field key in the `h2o_feet` measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT SAMPLE(*,2) FROM "h2o_feet" ``` name: h2o\_feet | time |sample\_level description|sample\_water\_level| |--------------------|-------------------------|--------------------| |2019-08-23T17:30:00Z| below 3 feet | | |2019-09-08T19:18:00Z| | 8.379 | |2019-09-09T03:54:00Z| between 6 and 9 feet | | |2019-09-16T04:48:00Z| | 1.437 | [](#select-a-sample-of-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Select a sample of the field values associated with each field key that matches a regular expression Return two randomly selected points for each field key that includes the word`level` in the `h2o_feet` measurement. ```sql SELECT SAMPLE(/level/,2) FROM "h2o_feet" ``` name: h2o\_feet | time |sample\_level description|sample\_water\_level| |--------------------|-------------------------|--------------------| |2019-08-19T20:24:00Z| | 4.951 | |2019-08-26T06:30:00Z| below 3 feet | | |2019-09-10T09:06:00Z| | 1.312 | |2019-09-16T21:00:00Z| between 3 and 6 feet | | [](#select-a-sample-of-the-field-values-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select a sample of the field values associated with a field key and the relevant tags and fields Return two randomly selected points from the `water_level` field key and the relevant values of the `location` tag and the `level description` field. ```sql SELECT SAMPLE("water_level",2),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time |sample| location | level description | |--------------------|------|-------------|--------------------| |2019-08-31T04:30:00Z|4.954 |santa\_monica|between 3 and 6 feet| |2019-09-13T01:24:00Z|3.389 |santa\_monica|between 3 and 6 feet| [](#select-a-sample-of-the-field-values-associated-with-a-field-key-and-include-several-clauses) Select a sample of the field values associated with a field key and include several clauses Return one randomly selected point from the `water_level` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and[group](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals)results into 18-minute intervals. ```sql SELECT SAMPLE("water_level",1) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) ``` name: h2o\_feet | time |sample| |--------------------|------| |2019-08-18T00:12:00Z|2.343 | |2019-08-18T00:24:00Z|2.264 | Notice that the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) does not override the points’ original timestamps. See [Issue 1](#sample-with-a-group-by-time-clause) in the section below for a more detailed explanation of that behavior. ### Common issues with SAMPLE() #### SAMPLE() with a GROUP BY time() clause Queries with `SAMPLE()` and a `GROUP BY time()` clause return the specified number of points (`N`) per `GROUP BY time()` interval. For [most `GROUP BY time()` queries](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals), the returned timestamps mark the start of the `GROUP BY time()` interval.`GROUP BY time()` queries with the `SAMPLE()` function behave differently; they maintain the timestamp of the original data point. ##### Example The query below returns two randomly selected points per 18-minute`GROUP BY time()` interval. Notice that the returned timestamps are the points’ original timestamps; they are not forced to match the start of the `GROUP BY time()` intervals. ```sql SELECT SAMPLE("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) ``` name: h2o\_feet | time |sample| |--------------------|------| |2019-08-18T00:06:00Z|2.116 | |2019-08-18T00:12:00Z|2.028 | |2019-08-18T00:18:00Z|2.126 | |2019-08-18T00:30:00Z|2.051 | Notice that the first two rows are randomly-selected points from the first time interval and the last two rows are randomly-selected points from the second time interval. ## TOP() Returns the greatest `N` [field values](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SELECT TOP( [,], )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `TOP(field_key,N)` Returns the greatest N field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `TOP(field_key,tag_key(s),N)` Returns the greatest field value for N tag values of the [tag key](/influxdb/v2/reference/glossary/#tag-key). `TOP(field_key,N),tag_key(s),field_key(s)` Returns the greatest N field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2/reference/glossary/#tag) and/or [field](/influxdb/v2/reference/glossary/#field). `TOP()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). > [!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. #### Examples [](#select-the-top-three-field-values-associated-with-a-field-key) Select the top three field values associated with a field key Return the greatest three field values in the `water_level` field key and in the`h2o_feet` [measurement](/influxdb/v2/reference/glossary/#measurement). ```sql SELECT TOP("water_level",3) FROM "h2o_feet" ``` name: h2o\_feet | time | top | |--------------------|-----| |2019-08-28T07:18:00Z|9.957| |2019-08-28T07:24:00Z|9.964| |2019-08-28T07:30:00Z|9.954| [](#select-the-top-field-value-associated-with-a-field-key-for-two-tags) Select the top field value associated with a field key for two tags Return the greatest field values in the `water_level` field key for two tag values associated with the `location` tag key. ```sql SELECT TOP("water_level","location",2) FROM "h2o_feet" ``` name: h2o\_feet | time | top | location | |--------------------|-----|-------------| |2019-08-28T03:54:00Z|7.205|santa\_monica| |2019-08-28T07:24:00Z|9.964|coyote\_creek| [](#select-the-top-four-field-values-associated-with-a-field-key-and-the-relevant-tags-and-fields) Select the top four field values associated with a field key and the relevant tags and fields Return the greatest four field values in the `water_level` field key and the relevant values of the `location` tag key and the `level description` field key. ```sql SELECT TOP("water_level",4),"location","level description" FROM "h2o_feet" ``` name: h2o\_feet | time | top | location | level description | |--------------------|-----|-------------|-------------------------| |2019-08-28T07:18:00Z|9.957|coyote\_creek|at or greater than 9 feet| |2019-08-28T07:24:00Z|9.964|coyote\_creek|at or greater than 9 feet| |2019-08-28T07:30:00Z|9.954|coyote\_creek|at or greater than 9 feet| |2019-08-28T07:36:00Z|9.941|coyote\_creek|at or greater than 9 feet| [](#select-the-top-three-field-values-associated-with-a-field-key-and-include-several-clauses) Select the top three field values associated with a field key and include several clauses Return the greatest three values in the `water_level` field key for each 24-minute[interval](/influxdb/v2/query-data/influxql/explore-data/group-by/#basic-group-by-time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:54:00Z` with results in[descending timestamp](/influxdb/v2/query-data/influxql/explore-data/order-by/) order. ```sql SELECT TOP("water_level",3),"location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) ORDER BY time DESC ``` name: h2o\_feet | time | top | location | |--------------------|-----|-------------| |2019-08-18T00:54:00Z|6.982|coyote\_creek| |2019-08-18T00:54:00Z|2.054|santa\_monica| |2019-08-18T00:48:00Z|7.110|coyote\_creek| |2019-08-18T00:36:00Z|7.372|coyote\_creek| |2019-08-18T00:30:00Z|7.500|coyote\_creek| |2019-08-18T00:24:00Z|7.635|coyote\_creek| |2019-08-18T00:12:00Z|7.887|coyote\_creek| |2019-08-18T00:06:00Z|8.005|coyote\_creek| |2019-08-18T00:00:00Z|8.120|coyote\_creek| Notice that the [GROUP BY time() clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) does not override the points’ original timestamps. See [Issue 1](#top-with-a-group-by-time-clause) in the section below for a more detailed explanation of that behavior. ### Common issues with `TOP()` #### `TOP()` with a `GROUP BY time()` clause Queries with `TOP()` and a `GROUP BY time()` clause return the specified number of points per `GROUP BY time()` interval. For [most `GROUP BY time()` queries](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals), the returned timestamps mark the start of the `GROUP BY time()` interval.`GROUP BY time()` queries with the `TOP()` function behave differently; they maintain the timestamp of the original data point. ##### Example The query below returns two points per 18-minute`GROUP BY time()` interval. Notice that the returned timestamps are the points’ original timestamps; they are not forced to match the start of the `GROUP BY time()` intervals. ```sql SELECT TOP("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) ``` name: h2o\_feet | time | top | |--------------------|-----| |2019-08-18T00:00:00Z|2.064| |2019-08-18T00:06:00Z|2.116| |2019-08-18T00:18:00Z|2.126| |2019-08-18T00:30:00Z|2.051| Notice that the first two rows are the greatest points for the first time interval and the last two rows are the greatest points for the second time interval. #### TOP() and a tag key with fewer than N tag values Queries with the syntax `SELECT TOP(,,)` can return fewer points than expected. If the tag key has `X` tag values, the query specifies `N` values, and `X` is smaller than `N`, then the query returns `X` points. ##### Example The query below asks for the greatest field values of `water_level` for three tag values of the `location` tag key. Because the `location` tag key has two tag values (`santa_monica` and `coyote_creek`), the query returns two points instead of three. ```sql SELECT TOP("water_level","location",3) FROM "h2o_feet" ``` name: h2o\_feet | time | top | location | |--------------------|-----|-------------| |2019-08-29T03:54:00Z|7.205|santa\_monica| |2019-08-29T07:24:00Z|9.964|coyote\_creek| | time | bottom | | --- | --- | | time | bottom | | 2019-08-29T14:30:00Z | -0.610 | | 2019-08-29T14:36:00Z | -0.591 | | 2019-08-30T15:18:00Z | -0.594 | | time | bottom | location | | --- | --- | --- | | time | bottom | location | | 2019-08-29T10:36:00Z | -0.243 | santa_monica | | 2019-08-29T14:30:00Z | -0.610 | coyote_creek | | time | bottom | location | level description | | --- | --- | --- | --- | | time | bottom | location | level description | | 2019-08-29T14:24:00Z | -0.587 | coyote_creek | below 3 feet | | 2019-08-29T14:30:00Z | -0.610 | coyote_creek | below 3 feet | | 2019-08-29T14:36:00Z | -0.591 | coyote_creek | below 3 feet | | 2019-08-30T15:18:00Z | -0.594 | coyote_creek | below 3 feet | | time | bottom | location | | --- | --- | --- | | time | bottom | location | | 2019-08-18T00:54:00Z | 2.172 | santa_monica | | 2019-08-18T00:54:00Z | 7.510 | coyote_creek | | 2019-08-18T00:48:00Z | 2.087 | santa_monica | | 2019-08-18T00:42:00Z | 2.093 | santa_monica | | 2019-08-18T00:36:00Z | 2.1261441420 | santa_monica | | 2019-08-18T00:24:00Z | 2.264 | santa_monica | | 2019-08-18T00:18:00Z | 2.329 | santa_monica | | 2019-08-18T00:12:00Z | 2.343 | santa_monica | | 2019-08-18T00:00:00Z | 2.352 | santa_monica | | time | bottom | | --- | --- | | time | bottom | | 2019-08-18T00:00:00Z | 2.064 | | 2019-08-18T00:12:00Z | 2.028 | | 2019-08-18T00:24:00Z | 2.041 | | 2019-08-18T00:30:00Z | 2.051 | | time | bottom | location | | --- | --- | --- | | time | bottom | location | | 2019-08-29T10:36:00Z | -0.243 | santa_monica | | 2019-08-29T14:30:00Z | -0.610 | coyote_creek | | time | first | | --- | --- | | time | first | | 2019-08-17T00:00:00Z | between 6 and 9 feet | | time | first_level description | first_water_level | | --- | --- | --- | | time | first_level description | first_water_level | | 1970-01-01T00:00:00Z | between 6 and 9 feet | 8.120 | | time | first_level description | first_water_level | | --- | --- | --- | | time | first_level description | first_water_level | | 1970-01-01T00:00:00Z | between 6 and 9 feet | 8.120 | | time | first | location | water_level | | --- | --- | --- | --- | | time | first | location | water_level | | 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.120 | | time | first | | --- | --- | | time | first | | 2019-08-17T23:48:00Z | 8.635 | | 2019-08-18T00:00:00Z | 8.504 | | 2019-08-18T00:12:00Z | 8.320 | | 2019-08-18T00:24:00Z | 8.130 | | time | last | | --- | --- | | time | last | | 2019-09-17T21:42:00Z | between 3 and 6 feet | | time | last_level description | last_water_level | | --- | --- | --- | | time | last_level description | last_water_level | | 1970-01-01T00:00:00Z | between 3 and 6 feet | 4.938 | | time | last_level description | last_water_level | | --- | --- | --- | | time | last_level description | last_water_level | | 1970-01-01T00:00:00Z | between 3 and 6 feet | 4.938 | | time | last | location | water_level | | --- | --- | --- | --- | | time | last | location | water_level | | 2019-09-17T21:42:00Z | between 3 and 6 feet | santa_monica | 4.938 | | time | last | | --- | --- | | time | last | | 2019-08-17T23:48:00Z | 8.570 | | 2019-08-18T00:00:00Z | 8.419 | | 2019-08-18T00:12:00Z | 8.225 | | 2019-08-18T00:24:00Z | 8.012 | | time | max | | --- | --- | | time | max | | 2019-08-28T07:24:00Z | 9.964 | | time | max_water_level | | --- | --- | | time | max_water_level | | 2019-08-28T07:24:00Z | 9.964 | | time | max_water_level | | --- | --- | | time | max_water_level | | 2019-08-28T07:24:00Z | 9.964 | | time | max | location | level description | | --- | --- | --- | --- | | time | max | location | level description | | 2019-08-28T07:24:00Z | 9.964 | coyote_creek | at or greater than 9 feet | | time | max | | --- | --- | | time | max | | 2019-08-17T23:48:00Z | 8.635 | | 2019-08-18T00:00:00Z | 8.504 | | 2019-08-18T00:12:00Z | 8.320 | | 2019-08-18T00:24:00Z | 8.130 | | time | min | | --- | --- | | time | min | | 2019-08-28T14:30:00Z | -0.610 | | time | min_water_level | | --- | --- | | time | min_water_level | | 2019-08-28T14:30:00Z | -0.610 | | time | min_water_level | | --- | --- | | time | min_water_level | | 2019-08-28T14:30:00Z | -0.610 | | time | min | location | level description | | --- | --- | --- | --- | | time | min | location | level description | | 2019-08-28T14:30:00Z | -0.610 | coyote_creek | below 3 feet | | time | min | | --- | --- | | time | min | | 2019-08-17T23:48:00Z | 8.570 | | 2019-08-18T00:00:00Z | 8.419 | | 2019-08-18T00:12:00Z | 8.225 | | 2019-08-18T00:24:00Z | 8.012 | | time | percentile | | --- | --- | | time | percentile | | 2019-09-01T17:54:00Z | 1.122 | | time | percentile_water_level | | --- | --- | | time | percentile_water_level | | 2019-09-01T17:54:00Z | 1.122 | | time | percentile_water_level | | --- | --- | | time | percentile_water_level | | 2019-09-01T17:54:00Z | 1.122 | | time | percentile | location | level description | | --- | --- | --- | --- | | time | percentile | location | level description | | 2019-08-24T10:18:00Z | 1.122 | coyote_creek | below 3 feet | | time | percentile | | --- | --- | | time | percentile | | 2019-08-17T23:36:00Z | 2.398 | | 2019-08-18T00:00:00Z | 2.343 | | time | sample | | --- | --- | | time | sample | | 2019-08-22T03:42:00Z | 7.218 | | 2019-08-28T20:18:00Z | 2.848 | | time | sample_level description | sample_water_level | | --- | --- | --- | | time | sample_level description | sample_water_level | | 2019-08-23T17:30:00Z | below 3 feet | | | 2019-09-08T19:18:00Z | | 8.379 | | 2019-09-09T03:54:00Z | between 6 and 9 feet | | | 2019-09-16T04:48:00Z | | 1.437 | | time | sample_level description | sample_water_level | | --- | --- | --- | | time | sample_level description | sample_water_level | | 2019-08-19T20:24:00Z | | 4.951 | | 2019-08-26T06:30:00Z | below 3 feet | | | 2019-09-10T09:06:00Z | | 1.312 | | 2019-09-16T21:00:00Z | between 3 and 6 feet | | | time | sample | location | level description | | --- | --- | --- | --- | | time | sample | location | level description | | 2019-08-31T04:30:00Z | 4.954 | santa_monica | between 3 and 6 feet | | 2019-09-13T01:24:00Z | 3.389 | santa_monica | between 3 and 6 feet | | time | sample | | --- | --- | | time | sample | | 2019-08-18T00:12:00Z | 2.343 | | 2019-08-18T00:24:00Z | 2.264 | | time | sample | | --- | --- | | time | sample | | 2019-08-18T00:06:00Z | 2.116 | | 2019-08-18T00:12:00Z | 2.028 | | 2019-08-18T00:18:00Z | 2.126 | | 2019-08-18T00:30:00Z | 2.051 | | time | top | | --- | --- | | time | top | | 2019-08-28T07:18:00Z | 9.957 | | 2019-08-28T07:24:00Z | 9.964 | | 2019-08-28T07:30:00Z | 9.954 | | time | top | location | | --- | --- | --- | | time | top | location | | 2019-08-28T03:54:00Z | 7.205 | santa_monica | | 2019-08-28T07:24:00Z | 9.964 | coyote_creek | | time | top | location | level description | | --- | --- | --- | --- | | time | top | location | level description | | 2019-08-28T07:18:00Z | 9.957 | coyote_creek | at or greater than 9 feet | | 2019-08-28T07:24:00Z | 9.964 | coyote_creek | at or greater than 9 feet | | 2019-08-28T07:30:00Z | 9.954 | coyote_creek | at or greater than 9 feet | | 2019-08-28T07:36:00Z | 9.941 | coyote_creek | at or greater than 9 feet | | time | top | location | | --- | --- | --- | | time | top | location | | 2019-08-18T00:54:00Z | 6.982 | coyote_creek | | 2019-08-18T00:54:00Z | 2.054 | santa_monica | | 2019-08-18T00:48:00Z | 7.110 | coyote_creek | | 2019-08-18T00:36:00Z | 7.372 | coyote_creek | | 2019-08-18T00:30:00Z | 7.500 | coyote_creek | | 2019-08-18T00:24:00Z | 7.635 | coyote_creek | | 2019-08-18T00:12:00Z | 7.887 | coyote_creek | | 2019-08-18T00:06:00Z | 8.005 | coyote_creek | | 2019-08-18T00:00:00Z | 8.120 | coyote_creek | | time | top | | --- | --- | | time | top | | 2019-08-18T00:00:00Z | 2.064 | | 2019-08-18T00:06:00Z | 2.116 | | 2019-08-18T00:18:00Z | 2.126 | | 2019-08-18T00:30:00Z | 2.051 | | time | top | location | | --- | --- | --- | | time | top | location | | 2019-08-29T03:54:00Z | 7.205 | santa_monica | | 2019-08-29T07:24:00Z | 9.964 | coyote_creek | --- # InfluxQL analysis functions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/functions/technical-analysis/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use technical analysis functions to apply algorithms to your data–often used to analyze financial and investment data. Each analysis function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). * [Predictive analysis](#predictive-analysis): * [HOLT\_WINTERS()](#holt_winters) * [Technical analysis](#technical-analysis-functions): * [CHANDE\_MOMENTUM\_OSCILLATOR()](#chande_momentum_oscillator) * [EXPONENTIAL\_MOVING\_AVERAGE()](#exponential_moving_average) * [DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE()](#double_exponential_moving_average) * [KAUFMANS\_EFFICIENCY\_RATIO()](#kaufmans_efficiency_ratio) * [KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE()](#kaufmans_adaptive_moving_average) * [TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE()](#triple_exponential_moving_average) * [TRIPLE\_EXPONENTIAL\_DERIVATIVE()](#triple_exponential_derivative) * [RELATIVE\_STRENGTH\_INDEX()](#relative_strength_index) ## Predictive analysis Predictive analysis functions are a type of technical analysis algorithms that predict and forecast future values. ### HOLT\_WINTERS() Returns N number of predicted [field values](/influxdb/v2/reference/glossary/#field-value)using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. Supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Works with data that occurs at consistent time intervals. Requires an InfluxQL function and the `GROUP BY time()` clause to ensure that the Holt-Winters function operates on regular data. Use `HOLT_WINTERS()` to: * Predict when data values will cross a given threshold * Compare predicted values with actual values to detect anomalies in your data #### Syntax ``` SELECT HOLT_WINTERS[_WITH-FIT]((),,) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `HOLT_WINTERS(function(field_key),N,S)` returns `N` seasonally adjusted predicted field values for the specified [field key](/influxdb/v2/reference/glossary/#field-key). The `N` predicted values occur at the same interval as the [`GROUP BY time()` interval](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). If your `GROUP BY time()` interval is `6m` and `N` is `3` you’ll receive three predicted values that are each six minutes apart. `S` is the seasonal pattern parameter and delimits the length of a seasonal pattern according to the `GROUP BY time()` interval. If your `GROUP BY time()` interval is `2m` and `S` is `3`, then the seasonal pattern occurs every six minutes, that is, every three data points. If you do not want to seasonally adjust your predicted values, set `S` to `0`or `1.` `HOLT_WINTERS_WITH_FIT(function(field_key),N,S)` returns the fitted values in addition to `N` seasonally adjusted predicted field values for the specified field key. #### Examples [](#predict-field-values-associated-with-a-field-key) Predict field values associated with a field key ##### Sample data The examples use the following subset of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >= '2019-08-17T00:00:00Z' AND time <= '2019-08-22T00:00:00Z' ``` ##### Step 1: Match the trends of the raw data Write a `GROUP BY time()` query that matches the general trends of the raw `water_level` data. Here, we use the [`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first) function: ```sql SELECT FIRST("water_level") FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' and time >= '2019-08-17T00:00:00Z' AND time <= '2019-08-22T00:00:00Z' GROUP BY time(6h,6h) ``` In the `GROUP BY time()` clause, the first argument (`6h`) matches the length of time that occurs between each peak and trough in the `water_level` data. The second argument (`6h`) is the[offset interval](/influxdb/v2/query-data/influxql/explore-data/group-by/#advanced-group-by-time-syntax). The offset interval alters the default `GROUP BY time()` boundaries to match the time range of the raw data. Holt Winters base data ###### Step 2: Determine the seasonal pattern Identify the seasonal pattern in the data using the information from the query in step 1. The pattern in the `water_level` data repeats about every 12 hours. There are two data points per season, so `2` is the seasonal pattern argument. Holt Winters seasonal data ###### Step 3: Apply the HOLT\_WINTERS() function Add the Holt-Winters function to the query. Here, we use `HOLT_WINTERS_WITH_FIT()` to view both the fitted values and the predicted values: ```sql SELECT HOLT_WINTERS_WITH_FIT(FIRST("water_level"),10,2) FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >= '2019-08-17 00:00:00' AND time <= '2019-08-22 00:00:00' GROUP BY time(6h,6h) ``` In the `HOLT_WINTERS_WITH_FIT()` function, the first argument (`10`) requests 10 predicted field values. Each predicted point is `6h` apart, the same interval as the first argument in the `GROUP BY time()` clause. The second argument in the `HOLT_WINTERS_WITH_FIT()` function (`2`) is the seasonal pattern that we determined in the previous step. Holt Winters predicted data #### Common issues with `HOLT_WINTERS()` ##### Receiving fewer than `N` points In some cases, you may receive fewer predicted points than requested by the `N` parameter. That behavior typically occurs when the math becomes unstable and cannot forecast more points. In this case, `HOLT_WINTERS()` may not be suited for the dataset or the seasonal adjustment parameter is invalid. ## Technical analysis functions Technical analysis functions apply widely used algorithms to your data. While they are primarily used in finance and investing, they have application in other industries. For technical analysis functions, consider whether to include the `PERIOD`, `HOLD_PERIOD`, and `WARMUP_TYPE` arguments: #### `PERIOD` **Required, integer, min=1** The sample size for the algorithm, which is the number of historical samples with significant effect on the output of the algorithm. For example, `2` means the current point and the point before it. The algorithm uses an exponential decay rate to determine the weight of a historical point, generally known as the alpha (α). The `PERIOD` controls the decay rate. > [!Note] > **Note:** Older points can still have an impact. #### `HOLD_PERIOD` **integer, min=-1** How many samples the algorithm needs before emitting results. The default of `-1` means the value is based on the algorithm, the `PERIOD`, and the `WARMUP_TYPE`. Verify this value is enough for the algorithm to emit meaningful results. ***Default hold periods:*** For most technical analysis functions, the default `HOLD_PERIOD` is determined by the function and the [`WARMUP_TYPE`](#warmup_type) shown in the following table: | Algorithm \\ Warmup Type | simple |exponential| none | |--------------------------------------------------------------------------|-----------------------|-----------|----------| | [EXPONENTIAL\_MOVING\_AVERAGE](#exponential_moving_average) | PERIOD - 1 |PERIOD - 1 | n/a | |[DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE](#double_exponential_moving_average)| ( PERIOD - 1 ) \* 2 |PERIOD - 1 | n/a | |[TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE](#triple_exponential_moving_average)| ( PERIOD - 1 ) \* 3 |PERIOD - 1 | n/a | | [TRIPLE\_EXPONENTIAL\_DERIVATIVE](#triple_exponential_derivative) |( PERIOD - 1 ) \* 3 + 1| PERIOD | n/a | | [RELATIVE\_STRENGTH\_INDEX](#relative_strength_index) | PERIOD | PERIOD | n/a | | [CHANDE\_MOMENTUM\_OSCILLATOR](#chande_momentum_oscillator) | PERIOD | PERIOD |PERIOD - 1| ***Kaufman algorithm default hold periods:*** | Algorithm |Default Hold Period| |--------------------------------------------------------------------------|-------------------| | [KAUFMANS\_EFFICIENCY\_RATIO()](#kaufmans_efficiency_ratio) | PERIOD | |[KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE()](#kaufmans_adaptive_moving_average)| PERIOD | #### `WARMUP_TYPE` **default=‘exponential’** Controls how the algorithm initializes for the first `PERIOD` samples. It is essentially the duration for which it has an incomplete sample set. ##### simple Simple moving average (SMA) of the first `PERIOD` samples. This is the method used by [ta-lib](https://www.ta-lib.org/). ##### exponential Exponential moving average (EMA) with scaling alpha (α). Uses an EMA with `PERIOD=1` for the first point, `PERIOD=2`for the second point, and so on, until the algorithm has consumed `PERIOD` number of points. As the algorithm immediately starts using an EMA, when this method is used and`HOLD_PERIOD` is unspecified or `-1`, the algorithm may start emitting points after a much smaller sample size than with `simple`. ##### none The algorithm does not perform any smoothing at all. Method used by [ta-lib](https://www.ta-lib.org/). When this method is used and `HOLD_PERIOD` is unspecified, `HOLD_PERIOD`defaults to `PERIOD - 1`. > [!Note] > **Note:** The `none` warmup type is only available with the [`CHANDE_MOMENTUM_OSCILLATOR()`](#chande_momentum_oscillator) function. ## CHANDE\_MOMENTUM\_OSCILLATOR() The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. The CMO indicator is created by calculating the difference between the sum of all recent higher data points and the sum of all recent lower data points, then dividing the result by the sum of all data movement over a given time period. The result is multiplied by 100 to give the -100 to +100 range.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `CHANDE_MOMENTUM_OSCILLATOR()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` CHANDE_MOMENTUM_OSCILLATOR([ * | | /regular_expression/ ], [, , [warmup_type]]) ``` ### Arguments * [period](#period) * (Optional) [hold\_period](#hold_period) * (Optional) [warmup\_type](#warmup_type) `CHANDE_MOMENTUM_OSCILLATOR(field_key, 2)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Chande Momentum Oscillator algorithm with a 2-value period and the default hold period and warmup type. `CHANDE_MOMENTUM_OSCILLATOR(field_key, 10, 9, 'none')` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Chande Momentum Oscillator algorithm with a 10-value period a 9-value hold period, and the `none` warmup type. `CHANDE_MOMENTUM_OSCILLATOR(MEAN(), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Chande Momentum Oscillator algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `CHANDE_MOMENTUM_OSCILLATOR()` function. `CHANDE_MOMENTUM_OSCILLATOR(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Chande Momentum Oscillator algorithm with a 2-value period and the default hold period and warmup type. `CHANDE_MOMENTUM_OSCILLATOR(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Chande Momentum Oscillator algorithm with a 2-value period and the default hold period and warmup type. `CHANDE_MOMENTUM_OSCILLATOR()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). ## EXPONENTIAL\_MOVING\_AVERAGE() An exponential moving average (EMA) (or exponentially weighted moving average) is a type of moving average similar to a [simple moving average](/influxdb/v2/query-data/influxql/functions/transformations/#moving_average), except more weight is given to the latest data. This type of moving average reacts faster to recent data changes than a simple moving average.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ```sql EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `EXPONENTIAL_MOVING_AVERAGE()` function. `EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `EXPONENTIAL_MOVING_AVERAGE(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). ### Arguments * [period](#period) * (Optional) [hold\_period](#hold_period) * (Optional) [warmup\_type](#warmup_type) ## DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE() The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag associated with moving averages by placing more weight on recent values. The name suggests this is achieved by applying a double exponential smoothing which is not the case. The value of an [EMA](#exponential_moving_average) is doubled. To keep the value in line with the actual data and to remove the lag, the value “EMA of EMA” is subtracted from the previously doubled EMA.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` DOUBLE_EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Double Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` function. `DOUBLE_EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Double Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Double Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). ### Arguments * [period](#period) * (Optional) [hold\_period](#hold_period) * (Optional) [warmup\_type](#warmup_type) ## KAUFMANS\_EFFICIENCY\_RATIO() Kaufman’s Efficiency Ration, or simply “Efficiency Ratio” (ER), is calculated by dividing the data change over a period by the absolute sum of the data movements that occurred to achieve that change. The resulting ratio ranges between 0 and 1 with higher values representing a more efficient or trending market. The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). The difference is that the CMO takes market direction into account, but if you take the absolute CMO and divide by 100, you you get the Efficiency Ratio.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `KAUFMANS_EFFICIENCY_RATIO()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` KAUFMANS_EFFICIENCY_RATIO([ * | | /regular_expression/ ], [, ]) ``` `KAUFMANS_EFFICIENCY_RATIO(field_key, 2)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Efficiency Index algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_EFFICIENCY_RATIO(field_key, 10, 10)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Efficiency Index algorithm with a 10-value period and a 10-value hold period. `KAUFMANS_EFFICIENCY_RATIO(MEAN(), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Efficiency Index algorithm with a 2-value period and the default hold period. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `KAUFMANS_EFFICIENCY_RATIO()` function. `KAUFMANS_EFFICIENCY_RATIO(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Efficiency Index algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_EFFICIENCY_RATIO(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Efficiency Index algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_EFFICIENCY_RATIO()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). **Arguments:** * [period](#period) * (Optional) [hold\_period](#hold_period) ## KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE() Kaufman’s Adaptive Moving Average (KAMA) is a moving average designed to account for sample noise or volatility. KAMA will closely follow data points when the data swings are relatively small and noise is low. KAMA will adjust when the data swings widen and follow data from a greater distance. This trend-following indicator can be used to identify the overall trend, time turning points and filter data movements.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` KAUFMANS_ADAPTIVE_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ]) ``` `KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_key, 2)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_key, 10, 10)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Kaufman Adaptive Moving Average algorithm with a 10-value period and a 10-value hold period. `KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period and the default hold period. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` function. `KAUFMANS_ADAPTIVE_MOVING_AVERAGE(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period and the default hold period and warmup type. `KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). **Arguments:** * [period](#period) * (Optional) [hold\_period](#hold_period) ## TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE() The triple exponential moving average (TEMA) filters out volatility from conventional moving averages. While the name implies that it’s a triple exponential smoothing, it’s actually a composite of a [single exponential moving average](#exponential_moving_average), a [double exponential moving average](#double_exponential_moving_average), and a triple exponential moving average.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` TRIPLE_EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Triple Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` function. `TRIPLE_EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Triple Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Triple Exponential Moving Average algorithm with a 2-value period and the default hold period and warmup type. `TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). **Arguments:** * [period](#period) * (Optional) [hold\_period](#hold_period) * (Optional) [warmup\_type](#warmup_type) ## TRIPLE\_EXPONENTIAL\_DERIVATIVE() The triple exponential derivative indicator, commonly referred to as “TRIX,” is an oscillator used to identify oversold and overbought markets, and can also be used as a momentum indicator. TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average)of the [log](/influxdb/v2/query-data/influxql/functions/transformations/#log)of the data input over the period of time. The previous value is subtracted from the previous value. This prevents cycles that are shorter than the defined period from being considered by the indicator. Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, a positive value indicates an overbought market while a negative value indicates an oversold market. When used as a momentum indicator, a positive value suggests momentum is increasing while a negative value suggests momentum is decreasing. Many analysts believe that when the TRIX crosses above the zero line it gives a buy signal, and when it closes below the zero line, it gives a sell signal.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `TRIPLE_EXPONENTIAL_DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` TRIPLE_EXPONENTIAL_DERIVATIVE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Triple Exponential Derivative algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `TRIPLE_EXPONENTIAL_DERIVATIVE()` function. `TRIPLE_EXPONENTIAL_DERIVATIVE(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Triple Exponential Derivative algorithm with a 2-value period and the default hold period and warmup type. `TRIPLE_EXPONENTIAL_DERIVATIVE(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Triple Exponential Derivative algorithm with a 2-value period and the default hold period and warmup type. `TRIPLE_EXPONENTIAL_DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). ## RELATIVE\_STRENGTH\_INDEX() The relative strength index (RSI) is a momentum indicator that compares the magnitude of recent increases and decreases over a specified time period to measure speed and change of data movements.Source Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `RELATIVE_STRENGTH_INDEX()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2/query-data/influxql/functions/transformations/#advanced-syntax). ### Basic syntax ``` RELATIVE_STRENGTH_INDEX([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` Returns the mean of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key)processed using the Relative Strength Index algorithm with a 2-value period and the default hold period and warmup type. > [!Note] > **Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2/query-data/influxql/functions/aggregates/) in your call to the `RELATIVE_STRENGTH_INDEX()` function. `RELATIVE_STRENGTH_INDEX(/regular_expression/, 2)` Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/)processed using the Relative Strength Index algorithm with a 2-value period and the default hold period and warmup type. `RELATIVE_STRENGTH_INDEX(*, 2)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)processed using the Relative Strength Index algorithm with a 2-value period and the default hold period and warmup type. `RELATIVE_STRENGTH_INDEX()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). **Arguments:** * [period](#period) * (Optional) [hold\_period](#hold_period) * (Optional) [warmup\_type](#warmup_type) | Algorithm \ Warmup Type | simple | exponential | none | | --- | --- | --- | --- | | Algorithm \ Warmup Type | simple | exponential | none | | EXPONENTIAL_MOVING_AVERAGE | PERIOD - 1 | PERIOD - 1 | n/a | | DOUBLE_EXPONENTIAL_MOVING_AVERAGE | ( PERIOD - 1 ) * 2 | PERIOD - 1 | n/a | | TRIPLE_EXPONENTIAL_MOVING_AVERAGE | ( PERIOD - 1 ) * 3 | PERIOD - 1 | n/a | | TRIPLE_EXPONENTIAL_DERIVATIVE | ( PERIOD - 1 ) * 3 + 1 | PERIOD | n/a | | RELATIVE_STRENGTH_INDEX | PERIOD | PERIOD | n/a | | CHANDE_MOMENTUM_OSCILLATOR | PERIOD | PERIOD | PERIOD - 1 | | Algorithm | Default Hold Period | | --- | --- | | Algorithm | Default Hold Period | | KAUFMANS_EFFICIENCY_RATIO() | PERIOD | | KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | PERIOD | --- # InfluxQL transformation functions Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/functions/transformations/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxQL transformation functions modify and return values each row of queried data. Each transformation function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data) and data from [sample\_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). * [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) * [HISTOGRAM()](#histogram) * [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) ## ABS() Returns the absolute value of the field value. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). ### Basic syntax ```sql SELECT ABS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ABS(field_key)` Returns the absolute values of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `ABS(*)` Returns the absolute values of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `ABS()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples [](#calculate-the-absolute-values-of-field-values-associated-with-a-field-key) Calculate the absolute values of field values associated with a field key Return the absolute values of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT ABS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:15:00Z' ``` name: data | time | abs | |--------------------|------------| |2019-08-18T00:00:00Z|8.5040000000| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|8.4190000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|8.3200000000| |2019-08-18T00:12:00Z|2.3430000000| [](#calculate-the-absolute-values-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the absolute values of field values associated with each field key in a measurement Return the absolute values of field values for each field key that stores numeric values in the `data` measurement. The `h2o_feet` measurement has one numeric field `water_level`. ```sql SELECT ABS(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:15:00Z' ``` name: data | time |abs\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| 8.5040000000 | |2019-08-18T00:00:00Z| 2.3520000000 | |2019-08-18T00:06:00Z| 8.4190000000 | |2019-08-18T00:06:00Z| 2.3790000000 | |2019-08-18T00:12:00Z| 8.3200000000 | |2019-08-18T00:12:00Z| 2.3430000000 | [](#calculate-the-absolute-values-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the absolute values of field values associated with a field key and include several clauses Return the absolute values of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT ABS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: data | time | abs | |--------------------|------------| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:24:00Z|8.1300000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:18:00Z|8.2250000000| ### Advanced syntax ```sql SELECT ABS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ABS()` function to those results. `ABS()` supports the following nested functions: [`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-absolute-values-of-mean-values) Calculate the absolute values of mean values Return the absolute values of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT ABS(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` name: data | time | abs | |--------------------|------------| |2019-08-18T00:00:00Z|5.4135000000| |2019-08-18T00:12:00Z|5.3042500000| |2019-08-18T00:24:00Z|5.1682500000| ## ACOS() Returns the arccosine (in radians) of the field value. Field values must be between -1 and 1. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but does not support [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). ### Basic syntax ```sql SELECT ACOS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ACOS(field_key)` Returns the arccosine of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `ACOS(*)` Returns the arccosine of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `ACOS()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. #### Examples The examples below use a subset of data from [sample\_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a), which only includes field values within the calculable range (-1 to 1). This value range is required for the `ACOS()` function: | time | a | |--------------------|-------------------| |2018-06-24T12:01:00Z|\-0.774984088561186| |2018-06-24T12:02:00Z|\-0.921037167720451| |2018-06-24T12:04:00Z|\-0.905980032168252| |2018-06-24T12:05:00Z|\-0.891164752631417| |2018-06-24T12:09:00Z| 0.416579917279588 | |2018-06-24T12:10:00Z| 0.328968116955350 | |2018-06-24T12:11:00Z| 0.263585064411983 | [](#calculate-the-arccosine-of-field-values-associated-with-a-field-key) Calculate the arccosine of field values associated with a field key Return the arccosine of field values in the `a` field key in the `data` measurement. ```sql SELECT ACOS("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | acos | |--------------------|------------| |2018-06-24T12:00:00Z| | |2018-06-24T12:01:00Z|2.4574862443| |2018-06-24T12:02:00Z|2.7415314737| |2018-06-24T12:03:00Z| | |2018-06-24T12:04:00Z|2.7044854503| |2018-06-24T12:05:00Z|2.6707024029| |2018-06-24T12:06:00Z| | |2018-06-24T12:07:00Z| | |2018-06-24T12:08:00Z| | |2018-06-24T12:09:00Z|1.1411163210| |2018-06-24T12:10:00Z|1.2355856616| |2018-06-24T12:11:00Z|1.3040595066| [](#calculate-the-arccosine-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the arccosine of field values associated with each field key in a measurement Return the arccosine of field values for each field key that stores numeric values in the `data` measurement, field `a` and `b`. ```sql SELECT ACOS(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | acos\_a | acos\_b | |--------------------|------------|------------| |2018-06-24T12:00:00Z| |1.7351786976| |2018-06-24T12:01:00Z|2.4574862443|1.4333294161| |2018-06-24T12:02:00Z|2.7415314737|2.0748091141| |2018-06-24T12:03:00Z| |1.6438345404| |2018-06-24T12:04:00Z|2.7044854503| | |2018-06-24T12:05:00Z|2.6707024029|0.7360183965| |2018-06-24T12:06:00Z| |1.2789990384| |2018-06-24T12:07:00Z| |2.1522589654| |2018-06-24T12:08:00Z| |0.6128438977| |2018-06-24T12:09:00Z|1.1411163210| | |2018-06-24T12:10:00Z|1.2355856616| | |2018-06-24T12:11:00Z|1.3040595066|1.7595349692| |2018-06-24T12:12:00Z|1.8681669412|2.5213034266| [](#calculate-the-arccosine-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the arccosine of field values associated with a field key and include several clauses Return the arccosine of field values associated with the `a` field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax) between `2018-06-24T00:00:00Z` and `2018-06-25T00:00:00Z` with results in [descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) results by two points. ```sql SELECT ACOS("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: data | time | acos | |--------------------|------------| |2018-06-24T23:58:00Z|1.5361053361| |2018-06-24T23:57:00Z| | |2018-06-24T23:56:00Z|0.5211076815| |2018-06-24T23:55:00Z|1.647695085 | ### Advanced syntax ```sql SELECT ACOS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ACOS()` function to those results. `ACOS()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-arccosine-of-mean-values) Calculate the arccosine of mean values Return the arccosine of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `a` that are calculated at 3 hour intervals. ```sql SELECT ACOS(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) ``` name: data | time | acos | |--------------------|------------| |2018-06-24T00:00:00Z| | |2018-06-24T03:00:00Z| | |2018-06-24T06:00:00Z| | |2018-06-24T09:00:00Z| | |2018-06-24T12:00:00Z|1.5651603194| |2018-06-24T15:00:00Z|1.6489104619| |2018-06-24T18:00:00Z|1.4851295699| |2018-06-24T21:00:00Z|1.6209901549| |2018-06-25T00:00:00Z|1.7149309371| ## ASIN() Returns the arcsine (in radians) of the field value. Field values must be between -1 and 1. ### Basic syntax ```sql SELECT ASIN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ASIN(field_key)` Returns the arcsine of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `ASIN(*)` Returns the arcsine of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `ASIN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `ASIN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following data from [sample\_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). The following data from this data set only includes field value within the calculable range (-1 to 1) required for the `ASIN()` function: | time | a | |--------------------|-------------------| |2018-06-24T12:01:00Z|\-0.774984088561186| |2018-06-24T12:02:00Z|\-0.921037167720451| |2018-06-24T12:04:00Z|\-0.905980032168252| |2018-06-24T12:05:00Z|\-0.891164752631417| |2018-06-24T12:09:00Z| 0.416579917279588 | |2018-06-24T12:10:00Z| 0.328968116955350 | |2018-06-24T12:11:00Z| 0.263585064411983 | [](#calculate-the-arcsine-of-field-values-associated-with-a-field-key) Calculate the arcsine of field values associated with a field key Return the arcsine of field values in the `a` field key in the `data` measurement. ```sql SELECT ASIN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | asin | |--------------------|--------------| |2018-06-24T12:00:00Z| | |2018-06-24T12:01:00Z|\-0.8866899175| |2018-06-24T12:02:00Z|\-1.1707351469| |2018-06-24T12:03:00Z| | |2018-06-24T12:04:00Z|\-1.1336891235| |2018-06-24T12:05:00Z|\-1.0999060761| |2018-06-24T12:06:00Z| | |2018-06-24T12:07:00Z| | |2018-06-24T12:08:00Z| | |2018-06-24T12:09:00Z| 0.4296800058 | |2018-06-24T12:10:00Z| 0.3352106652 | |2018-06-24T12:11:00Z| 0.2667368202 | |2018-06-24T12:12:00Z|\-0.2973706144| [](#calculate-the-arcsine-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the arcsine of field values associated with each field key in a measurement Return the arcsine of field values for each field key that stores numeric values in the `data` measurement. The `data` measurement has one numeric field: `a`. ```sql SELECT ASIN(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | asin\_a | asin\_b | |--------------------|--------------|--------------| |2018-06-24T12:00:00Z| |\-0.1643823708| |2018-06-24T12:01:00Z|\-0.8866899175| 0.1374669107 | |2018-06-24T12:02:00Z|\-1.1707351469|\-0.5040127873| |2018-06-24T12:03:00Z| |\-0.0730382136| |2018-06-24T12:04:00Z|\-1.1336891235| | |2018-06-24T12:05:00Z|\-1.0999060761| 0.8347779303 | |2018-06-24T12:06:00Z| | 0.2917972884 | |2018-06-24T12:07:00Z| |\-0.5814626386| |2018-06-24T12:08:00Z| | 0.9579524291 | |2018-06-24T12:09:00Z| 0.4296800058 | | |2018-06-24T12:10:00Z| 0.3352106652 | | |2018-06-24T12:11:00Z| 0.2667368202 |\-0.1887386424| |2018-06-24T12:12:00Z|\-0.2973706144|\-0.9505070998| [](#calculate-the-arcsine-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the arcsine of field values associated with a field key and include several clauses Return the arcsine of field values associated with the `a` field key in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2018-06-24T00:00:00Z` and `2018-06-25T00:00:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT ASIN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: data | time | asin | |--------------------|------------| |2018-06-24T23:58:00Z|0.0346909907| |2018-06-24T23:57:00Z| | |2018-06-24T23:56:00Z|1.0496886453| |2018-06-24T23:55:00Z|0.0768987583| ### Advanced syntax ```sql SELECT ASIN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ASIN()` function to those results. `ASIN()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-arcsine-of-mean-values) Calculate the arcsine of mean values Return the arcsine of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `a`s that are calculated at 3-hour intervals. ```sql SELECT ASIN(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) ``` name: data | time | asin | |--------------------|--------------| |2018-06-24T00:00:00Z| | |2018-06-24T03:00:00Z| | |2018-06-24T06:00:00Z| | |2018-06-24T09:00:00Z| | |2018-06-24T12:00:00Z| 0.0056360073 | |2018-06-24T15:00:00Z|\-0.0781141351| |2018-06-24T18:00:00Z| 0.0856667569 | |2018-06-24T21:00:00Z|\-0.0501938281| |2018-06-25T00:00:00Z|\-0.1441346103| ## ATAN() Returns the arctangent (in radians) of the field value. Field values must be between -1 and 1. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `ATAN()` with a `GROUP BY time()` clause, see the [Advanced syntax](#advanced-syntax). ### Basic syntax ```sql SELECT ATAN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ATAN(field_key)` Returns the arctangent of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `ATAN(*)` Returns the arctangent of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `ATAN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. #### Examples The examples below use a subset of data from [sample\_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a) that only includes field values within the calculable range (-1 to 1) required for the of the `ATAN()` function. [](#calculate-the-arctangent-of-field-values-associated-with-a-field-key) Calculate the arctangent of field values associated with a field key Return the arctangent of field values in the `a` field key in the `data` measurement. ```sql SELECT ATAN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | atan | |--------------------|--------------| |2018-06-24T12:00:00Z| 0.9293622934 | |2018-06-24T12:01:00Z|\-0.6593001275| |2018-06-24T12:02:00Z|\-0.7443170184| |2018-06-24T12:03:00Z|\-1.0488818071| |2018-06-24T12:04:00Z|\-0.7361091801| |2018-06-24T12:05:00Z|\-0.7279122495| |2018-06-24T12:06:00Z| 0.8379907133 | |2018-06-24T12:07:00Z|\-0.9117032768| |2018-06-24T12:08:00Z|\-1.0364006848| |2018-06-24T12:09:00Z| 0.3947172008 | |2018-06-24T12:10:00Z| 0.3178167283 | |2018-06-24T12:11:00Z| 0.2577231762 | |2018-06-24T12:12:00Z|\-0.2850291359| [](#calculate-the-arctangent-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the arctangent of field values associated with each field key in a measurement Return the arctangent of field values for each field key that stores numeric values in the `data` measurement–fields `a` and `b`. ```sql SELECT ATAN(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | atan\_a | atan\_b | |--------------------|--------------|--------------| |2018-06-24T12:00:00Z| 0.9293622934 |\-0.1622053541| |2018-06-24T12:01:00Z|\-0.6593001275| 0.1361861379 | |2018-06-24T12:02:00Z|\-0.7443170184|\-0.4499093122| |2018-06-24T12:03:00Z|\-1.0488818071|\-0.0728441751| |2018-06-24T12:04:00Z|\-0.7361091801| 1.0585985451 | |2018-06-24T12:05:00Z|\-0.7279122495| 0.6378113578 | |2018-06-24T12:06:00Z| 0.8379907133 | 0.2801105336 | |2018-06-24T12:07:00Z|\-0.9117032768|\-0.5022647489| |2018-06-24T12:08:00Z|\-1.0364006848| 0.6856298940 | |2018-06-24T12:09:00Z| 0.3947172008 |\-0.8711781065| |2018-06-24T12:10:00Z| 0.3178167283 |\-0.8273348593| |2018-06-24T12:11:00Z| 0.2577231762 |\-0.1854639556| |2018-06-24T12:12:00Z|\-0.2850291359|\-0.6830451940| [](#calculate-the-arctangent-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the arctangent of field values associated with a field key and include several clauses Return the arctangent of field values associated with the `a` field key in[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2017-05-01T00:00:00Z` and `2017-05-09T00:00:00Z` and returns results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT ATAN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: data | time | atan | |--------------------|--------------| |2018-06-24T23:58:00Z| 0.0346701348 | |2018-06-24T23:57:00Z|\-0.8582372146| |2018-06-24T23:56:00Z| 0.7144341473 | |2018-06-24T23:55:00Z|\-0.0766723939| ### Advanced syntax ```sql SELECT ATAN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ATAN()` function to those results. `ATAN()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples of advanced syntax [](#calculate-the-arctangent-of-mean-values) Calculate the arctangent of mean values Return the arctangent of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `a`s that are calculated at 3-hour intervals. ```sql SELECT ATAN(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) ``` name: data | time | atan | |--------------------|--------------| |2018-06-24T00:00:00Z| | |2018-06-24T03:00:00Z| | |2018-06-24T06:00:00Z| | |2018-06-24T09:00:00Z| | |2018-06-24T12:00:00Z| 0.0056359178 | |2018-06-24T15:00:00Z|\-0.0778769005| |2018-06-24T18:00:00Z| 0.0853541301 | |2018-06-24T21:00:00Z|\-0.0501307176| |2018-06-25T00:00:00Z|\-0.1426603174| ## ATAN2() Returns the arctangent of `y/x` in radians. ### Basic syntax ```sql SELECT ATAN2( [ * | | num ], [ | num ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ATAN2(field_key_y, field_key_x)` Returns the arctangent of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key), `field_key_y`, divided by field values associated with `field_key_x`. `ATAN2(*, field_key_x)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement)divided by field values associated with `field_key_x`. `ATAN2()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `ATAN2()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use [sample\_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). [](#calculate-the-arctangent-of-field_key_b-over-field_key_a) Calculate the arctangent of field\_key\_b over field\_key\_a Return the arctangents of field values in the `a` field key divided by values in the `b` field key. Both are part of the `data` measurement. ```sql SELECT ATAN2("a", "b") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | atan2 | |--------------------|--------------| |2018-06-24T12:00:00Z| 1.6923979639 | |2018-06-24T12:01:00Z|\-1.3957831900| |2018-06-24T12:02:00Z|\-2.0537314089| |2018-06-24T12:03:00Z|\-1.6127391493| |2018-06-24T12:04:00Z|\-0.4711275404| |2018-06-24T12:05:00Z|\-0.8770454978| |2018-06-24T12:06:00Z| 1.3174573347 | |2018-06-24T12:07:00Z|\-1.9730696643| |2018-06-24T12:08:00Z|\-1.1199236554| |2018-06-24T12:09:00Z| 2.8043757212 | |2018-06-24T12:10:00Z| 2.8478694533 | |2018-06-24T12:11:00Z| 2.1893985296 | |2018-06-24T12:12:00Z|\-2.7959592806| [](#calculate-the-arctangent-of-values-associated-with-each-field-key-in-a-measurement-divided-by-field_key_a) Calculate the arctangent of values associated with each field key in a measurement divided by field\_key\_a Return the arctangents of all numeric field values in the `data` measurement divided by values in the `a` field key. The `data` measurement has two numeric fields: `a` and `b`. ```sql SELECT ATAN2(*, "a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ``` name: data | time | atan2\_a | atan2\_b | |--------------------|--------------|--------------| |2018-06-24T12:00:00Z| 0.7853981634 |\-0.1216016371| |2018-06-24T12:01:00Z|\-2.3561944902| 2.9665795168 | |2018-06-24T12:02:00Z|\-2.3561944902|\-2.6586575715| |2018-06-24T12:03:00Z|\-2.3561944902|\-3.0996498311| |2018-06-24T12:04:00Z|\-2.3561944902| 2.0419238672 | |2018-06-24T12:05:00Z|\-2.3561944902| 2.4478418246 | |2018-06-24T12:06:00Z| 0.7853981634 | 0.2533389921 | |2018-06-24T12:07:00Z|\-2.3561944902|\-2.7393193161| |2018-06-24T12:08:00Z|\-2.3561944902| 2.6907199822 | |2018-06-24T12:09:00Z| 0.7853981634 |\-1.2335793944| |2018-06-24T12:10:00Z| 0.7853981634 |\-1.2770731265| |2018-06-24T12:11:00Z| 0.7853981634 |\-0.6186022028| |2018-06-24T12:12:00Z|\-2.3561944902|\-1.9164296997| [](#calculate-the-arctangents-of-field-values-and-include-several-clauses) Calculate the arctangents of field values and include several clauses Return the arctangent of field values associated with the `a` field key divided by the `b` field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2018-05-16T12:10:00Z` and `2018-05-16T12:10:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT ATAN2("a", "b") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: data | time | atan2 | |--------------------|--------------| |2018-06-24T23:58:00Z| 0.0166179004 | |2018-06-24T23:57:00Z|\-2.3211306482| |2018-06-24T23:56:00Z| 1.8506549463 | |2018-06-24T23:55:00Z|\-0.0768444917| ### Advanced syntax ```sql SELECT ATAN2(, ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ATAN2()` function to those results. `ATAN2()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-arctangents-of-mean-values) Calculate arctangents of mean values Return the arctangents of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `a`s divided by average `b`s. Averages are calculated at 2-hour intervals. ```sql SELECT ATAN2(MEAN("b"), MEAN("a")) FROM "data" WHERE time >= '2018-06-24T12:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(2h) ``` name: data | time | atan2 | |--------------------|--------------| |2018-06-24T12:00:00Z|\-0.8233039154| |2018-06-24T14:00:00Z| 1.6676707651 | |2018-06-24T16:00:00Z| 2.3853882606 | |2018-06-24T18:00:00Z|\-1.0180694195| |2018-06-24T20:00:00Z|\-0.2601965301| |2018-06-24T22:00:00Z| 2.1893237434 | |2018-06-25T00:00:00Z|\-2.5572285037| ## CEIL() Returns the subsequent value rounded up to the nearest integer. ### Basic syntax ```sql SELECT CEIL( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `CEIL(field_key)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) rounded up to the nearest integer. `CEIL(*)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) rounded up to the nearest integer. `CEIL()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `CEIL()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-ceiling-of-field-values-associated-with-a-field-key) Calculate the ceiling of field values associated with a field key Return field values in the `water_level` field key in the `h2o_feet` measurement rounded up to the nearest integer. ```sql SELECT CEIL("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time | ceil | |--------------------|------------| |2019-08-17T00:00:00Z|3.0000000000| |2019-08-17T00:06:00Z|3.0000000000| |2019-08-17T00:12:00Z|3.0000000000| |2019-08-17T00:18:00Z|3.0000000000| |2019-08-17T00:24:00Z|3.0000000000| |2019-08-17T00:30:00Z|3.0000000000| [](#calculate-the-ceiling-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the ceiling of field values associated with each field key in a measurement Return field values for each field key that stores numeric values in the `h2o_feet`measurement rounded up to the nearest integer. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT CEIL(*) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |ceil\_water\_level| |--------------------|------------------| |2019-08-17T00:00:00Z| 3.0000000000 | |2019-08-17T00:06:00Z| 3.0000000000 | |2019-08-17T00:12:00Z| 3.0000000000 | |2019-08-17T00:18:00Z| 3.0000000000 | |2019-08-17T00:24:00Z| 3.0000000000 | |2019-08-17T00:30:00Z| 3.0000000000 | [](#calculate-the-ceiling-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the ceiling of field values associated with a field key and include several clauses Return field values associated with the `water_level` field key rounded up to the nearest integer in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT CEIL("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | ceil | |--------------------|------------| |2019-08-17T00:18:00Z|3.0000000000| |2019-08-17T00:12:00Z|3.0000000000| |2019-08-17T00:06:00Z|3.0000000000| |2019-08-17T00:00:00Z|3.0000000000| ### Advanced syntax ```sql SELECT CEIL(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `CEIL()` function to those results. `CEIL()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-mean-values-rounded-up-to-the-nearest-integer) Calculate mean values rounded up to the nearest integer Return the [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds them up to the nearest integer. ```sql SELECT CEIL(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | ceil | |--------------------|------------| |2019-08-17T00:00:00Z|3.0000000000| |2019-08-17T00:12:00Z|3.0000000000| |2019-08-17T00:24:00Z|3.0000000000| ## COS() Returns the cosine of the field value. ### Basic syntax ```sql SELECT COS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `COS(field_key)` Returns the cosine of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `COS(*)` Returns the cosine of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `COS()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `COS()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-cosine-of-field-values-associated-with-a-field-key) Calculate the cosine of field values associated with a field key Return the cosine of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT COS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | cos | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.7041346171| |2019-08-18T00:06:00Z|\-0.7230474420| |2019-08-18T00:12:00Z|\-0.6977155876| |2019-08-18T00:18:00Z|\-0.6876182920| |2019-08-18T00:24:00Z|\-0.6390047316| |2019-08-18T00:30:00Z|\-0.6413094611| [](#calculate-the-cosine-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the cosine of field values associated with each field key in a measurement Return the cosine of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT COS(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |cos\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| \-0.7041346171 | |2019-08-18T00:06:00Z| \-0.7230474420 | |2019-08-18T00:12:00Z| \-0.6977155876 | |2019-08-18T00:18:00Z| \-0.6876182920 | |2019-08-18T00:24:00Z| \-0.6390047316 | |2019-08-18T00:30:00Z| \-0.6413094611 | [](#calculate-the-cosine-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the cosine of field values associated with a field key and include several clauses Return the cosine of field values associated with the `water_level` field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT COS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | cos | |--------------------|--------------| |2019-08-18T00:18:00Z|\-0.6876182920| |2019-08-18T00:12:00Z|\-0.6977155876| |2019-08-18T00:06:00Z|\-0.7230474420| |2019-08-18T00:00:00Z|\-0.7041346171| ### Advanced syntax ```sql SELECT COS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `COS()` function to those results. `COS()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-cosine-of-mean-values) Calculate the cosine of mean values Return the cosine of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT COS(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | cos | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.7136560605| |2019-08-18T00:12:00Z|\-0.6926839105| |2019-08-18T00:24:00Z|\-0.6401578165| ## CUMULATIVE\_SUM() Returns the running total of subsequent [field values](/influxdb/v2/reference/glossary/#field-value). ### Basic syntax ```sql SELECT CUMULATIVE_SUM( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `CUMULATIVE_SUM(field_key)` Returns the running total of subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `CUMULATIVE_SUM(/regular_expression/)` Returns the running total of subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `CUMULATIVE_SUM(*)` Returns the running total of subsequent field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `CUMULATIVE_SUM()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `CUMULATIVE_SUM()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-cumulative-sum-of-the-field-values-associated-with-a-field-key) Calculate the cumulative sum of the field values associated with a field key Return the running total of the field values in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT CUMULATIVE_SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |cumulative\_sum| |--------------------|---------------| |2019-08-18T00:00:00Z| 2.3520000000 | |2019-08-18T00:06:00Z| 4.7310000000 | |2019-08-18T00:12:00Z| 7.0740000000 | |2019-08-18T00:18:00Z| 9.4030000000 | |2019-08-18T00:24:00Z| 11.6670000000 | |2019-08-18T00:30:00Z| 13.9340000000 | [](#calculate-the-cumulative-sum-of-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the cumulative sum of the field values associated with each field key in a measurement Return the running total of the field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT CUMULATIVE_SUM(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |cumulative\_sum\_water\_level| |--------------------|-----------------------------| |2019-08-18T00:00:00Z| 2.3520000000 | |2019-08-18T00:06:00Z| 4.7310000000 | |2019-08-18T00:12:00Z| 7.0740000000 | |2019-08-18T00:18:00Z| 9.4030000000 | |2019-08-18T00:24:00Z| 11.6670000000 | |2019-08-18T00:30:00Z| 13.9340000000 | [](#calculate-the-cumulative-sum-of-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the cumulative sum of the field values associated with each field key that matches a regular expression Return the running total of the field values for each field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT CUMULATIVE_SUM(/water/) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |cumulative\_sum\_water\_level| |--------------------|-----------------------------| |2019-08-18T00:00:00Z| 2.3520000000 | |2019-08-18T00:06:00Z| 4.7310000000 | |2019-08-18T00:12:00Z| 7.0740000000 | |2019-08-18T00:18:00Z| 9.4030000000 | |2019-08-18T00:24:00Z| 11.6670000000 | |2019-08-18T00:30:00Z| 13.9340000000 | [](#calculate-the-cumulative-sum-of-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the cumulative sum of the field values associated with a field key and include several clauses Return the running total of the field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT CUMULATIVE_SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time |cumulative\_sum| |--------------------|---------------| |2019-08-18T00:18:00Z| 6.8600000000 | |2019-08-18T00:12:00Z| 9.2030000000 | |2019-08-18T00:06:00Z| 11.5820000000 | |2019-08-18T00:00:00Z| 13.9340000000 | ### Advanced syntax ```sql SELECT CUMULATIVE_SUM(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `CUMULATIVE_SUM()` function to those results. `CUMULATIVE_SUM()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-cumulative-sum-of-mean-values) Calculate the cumulative sum of mean values Return the running total of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT CUMULATIVE_SUM(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time |cumulative\_sum| |--------------------|---------------| |2019-08-18T00:00:00Z| 2.3655000000 | |2019-08-18T00:12:00Z| 4.7015000000 | |2019-08-18T00:24:00Z| 6.9670000000 | ## DERIVATIVE() Returns the rate of change between subsequent [field values](/influxdb/v2/reference/glossary/#field-value). ### Basic syntax ```sql SELECT DERIVATIVE( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` InfluxDB calculates the difference between subsequent field values and converts those results into the rate of change per `unit`. The `unit` argument is an integer followed by a [duration](/influxdb/v2/reference/glossary/#duration) and it is optional. If the query does not specify the `unit` the unit defaults to one second (`1s`). `DERIVATIVE(field_key)` Returns the rate of change between subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `DERIVATIVE(/regular_expression/)` Returns the rate of change between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `DERIVATIVE(*)` Returns the rate of change between subsequent field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples in this section use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-derivative-between-the-field-values-associated-with-a-field-key) Calculate the derivative between the field values associated with a field key Return the one-second rate of change between the `water_level` field values in the `h2o_feet` measurement. ```sql SELECT DERIVATIVE("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time | derivative | |--------------------|--------------| |2019-08-18T00:06:00Z| 0.0000750000 | |2019-08-18T00:12:00Z|\-0.0001000000| |2019-08-18T00:18:00Z|\-0.0000388889| |2019-08-18T00:24:00Z|\-0.0001805556| |2019-08-18T00:30:00Z| 0.0000083333 | The first result (`0.0000750000`) is the one-second rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the one-second rate of change (dividing the difference between the field values’ timestamps in seconds (`360s`) by the default unit (`1s`)): ``` (2.379 - 2.352) / (360s / 1s) ``` [](#calculate-the-derivative-between-the-field-values-associated-with-a-field-key-and-specify-the-unit-option) Calculate the derivative between the field values associated with a field key and specify the unit option Return the six-minute rate of change between the field values in the `water_level` field in the `h2o_feet` measurement. ```sql SELECT DERIVATIVE("water_level",6m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time | derivative | |--------------------|--------------| |2019-08-18T00:06:00Z| 0.0270000000 | |2019-08-18T00:12:00Z|\-0.0360000000| |2019-08-18T00:18:00Z|\-0.0140000000| |2019-08-18T00:24:00Z|\-0.0650000000| |2019-08-18T00:30:00Z| 0.0030000000 | The first result (`0.0270000000`) is the six-minute rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the six-minute rate of change (dividing the difference between the field values’ timestamps in minutes (`6m`) by the specified interval (`6m`)): ``` (2.379 - 2.352) / (6m / 6m) ``` [](#calculate-the-derivative-between-the-field-values-associated-with-each-field-key-in-a-measurement-and-specify-the-unit-option) Calculate the derivative between the field values associated with each field key in a measurement and specify the unit option Returns three-minute rate of change between the field values associated with each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT DERIVATIVE(*,3m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |derivative\_water\_level| |--------------------|------------------------| |2019-08-18T00:06:00Z| 0.0135000000 | |2019-08-18T00:12:00Z| \-0.0180000000 | |2019-08-18T00:18:00Z| \-0.0070000000 | |2019-08-18T00:24:00Z| \-0.0325000000 | |2019-08-18T00:30:00Z| 0.0015000000 | The first result (`0.0135000000`) is the three-minute rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the three-minute rate of change (dividing the difference between the field values’ timestamps in minutes (`6m`) by the specified interval (`3m`)): ``` (2.379 - 2.352) / (6m / 3m) ``` [](#calculate-the-derivative-between-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression-and-specify-the-unit-option) Calculate the derivative between the field values associated with each field key that matches a regular expression and specify the unit option Return the two-minute rate of change between the field values associated with each field key that stores numeric values and includes the word `water` in the`h2o_feet` measurement. ```sql SELECT DERIVATIVE(/water/,2m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |derivative\_water\_level| |--------------------|------------------------| |2019-08-18T00:06:00Z| 0.0090000000 | |2019-08-18T00:12:00Z| \-0.0120000000 | |2019-08-18T00:18:00Z| \-0.0046666667 | |2019-08-18T00:24:00Z| \-0.0216666667 | |2019-08-18T00:30:00Z| 0.0010000000 | The first result (`0.0090000000`) is the two-minute rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the three-minute rate of change (dividing the difference between the field values’ timestamps in minutes (`6m`) by the specified interval (`2m`)): ``` (2.379 - 2.352) / (6m / 2m) ``` [](#calculate-the-derivative-between-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the derivative between the field values associated with a field key and include several clauses Return the one-second rate of change between `water_level` field values in the`h2o_feet` measurement in [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to one and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/) results by two points. ```sql SELECT DERIVATIVE("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 1 OFFSET 2 ``` name: h2o\_feet | time | derivative | |--------------------|------------| |2019-08-18T00:12:00Z|0.0000388889| The only result (`0.0000388889`) is the one-second rate of change between the relevant subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the one-second rate of change (dividing the difference between the field values’ timestamps in seconds (`360`) by the specified rate of change (`1s`)): ``` (2.379 - 2.352) / (360s / 1s) ``` ### Advanced syntax ```sql SELECT DERIVATIVE( ([ * | | // ]) [ , ] ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `DERIVATIVE()` function to those results. The `unit` argument is an integer followed by a [duration](/influxdb/v2/reference/glossary/#duration) and it is optional. If the query does not specify the `unit` the `unit` defaults to the `GROUP BY time()` interval. Note that this behavior is different from the [basic syntax’s](#basic-syntax-1) default behavior. `DERIVATIVE()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-derivative-of-mean-values) Calculate the derivative of mean values Return the 12-minute rate of change between [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT DERIVATIVE(MEAN("water_level")) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` name: h2o\_feet | time | derivative | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.1375000000| |2019-08-18T00:12:00Z|\-0.0295000000| |2019-08-18T00:24:00Z|\-0.0705000000| [](#calculate-the-derivative-of-mean-values-and-specify-the-unit-option) Calculate the derivative of mean values and specify the unit option Return the six-minute rate of change between average `water_level`s that are calculated at 12-minute intervals. ```sql SELECT DERIVATIVE(MEAN("water_level"),6m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` name: h2o\_feet | time | derivative | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.0687500000| |2019-08-18T00:12:00Z|\-0.0147500000| |2019-08-18T00:24:00Z|\-0.0352500000| ## DIFFERENCE() Returns the result of subtraction between subsequent [field values](/influxdb/v2/reference/glossary/#field-value). ### Syntax ```sql SELECT DIFFERENCE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `DIFFERENCE(field_key)` Returns the difference between subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `DIFFERENCE(/regular_expression/)` Returns the difference between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `DIFFERENCE(*)` Returns the difference between subsequent field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `DIFFERENCE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-difference-between-the-field-values-associated-with-a-field-key) Calculate the difference between the field values associated with a field key Return the difference between the subsequent field values in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT DIFFERENCE("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | difference | |--------------------|--------------| |2019-08-18T00:06:00Z| 0.0270000000 | |2019-08-18T00:12:00Z|\-0.0360000000| |2019-08-18T00:18:00Z|\-0.0140000000| |2019-08-18T00:24:00Z|\-0.0650000000| |2019-08-18T00:30:00Z| 0.0030000000 | [](#calculate-the-difference-between-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the difference between the field values associated with each field key in a measurement Return the difference between the subsequent field values for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT DIFFERENCE(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |difference\_water\_level| |--------------------|------------------------| |2019-08-18T00:06:00Z| 0.0270000000 | |2019-08-18T00:12:00Z| \-0.0360000000 | |2019-08-18T00:18:00Z| \-0.0140000000 | |2019-08-18T00:24:00Z| \-0.0650000000 | |2019-08-18T00:30:00Z| 0.0030000000 | [](#calculate-the-difference-between-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the difference between the field values associated with each field key that matches a regular expression Return the difference between the subsequent field values for each field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. ```sql SELECT DIFFERENCE(/water/) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |difference\_water\_level| |--------------------|------------------------| |2019-08-18T00:06:00Z| 0.0270000000 | |2019-08-18T00:12:00Z| \-0.0360000000 | |2019-08-18T00:18:00Z| \-0.0140000000 | |2019-08-18T00:24:00Z| \-0.0650000000 | |2019-08-18T00:30:00Z| 0.0030000000 | [](#calculate-the-difference-between-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the difference between the field values associated with a field key and include several clauses ```sql SELECT DIFFERENCE("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 2 OFFSET 2 ``` name: h2o\_feet | time | difference | |--------------------|------------| |2019-08-18T00:12:00Z|0.0140000000| |2019-08-18T00:06:00Z|0.0360000000| Return the difference between the subsequent field values in the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). They query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to two and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ### Advanced syntax ```sql SELECT DIFFERENCE(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `DIFFERENCE()` function to those results. `DIFFERENCE()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-difference-between-maximum-values) Calculate the difference between maximum values Return the difference between [maximum](/influxdb/v2/query-data/influxql/functions/selectors/#max) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT DIFFERENCE(MAX("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | difference | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.2290000000| |2019-08-18T00:12:00Z|\-0.0360000000| |2019-08-18T00:24:00Z|\-0.0760000000| ## ELAPSED() Returns the difference between subsequent [field value’s](/influxdb/v2/reference/glossary/#field-value) timestamps. ### Syntax ```sql SELECT ELAPSED( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` InfluxDB calculates the difference between subsequent timestamps. The `unit` option is an integer followed by a [duration](/influxdb/v2/reference/glossary/#duration) and it determines the unit of the returned difference. If the query does not specify the `unit` option the query returns the difference between timestamps in nanoseconds. `ELAPSED(field_key)` Returns the difference between subsequent timestamps associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `ELAPSED(/regular_expression/)` Returns the difference between subsequent timestamps associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `ELAPSED(*)` Returns the difference between subsequent timestamps associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `ELAPSED()` supports all field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). #### Examples The examples use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| [](#calculate-the-elapsed-time-between-field-values-associated-with-a-field-key) Calculate the elapsed time between field values associated with a field key Return the elapsed time (in nanoseconds) between subsequent timestamps in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT ELAPSED("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time | elapsed | |--------------------|-----------------------| |2019-08-18T00:06:00Z|360000000000.0000000000| |2019-08-18T00:12:00Z|360000000000.0000000000| [](#calculate-the-elapsed-time-between-field-values-associated-with-a-field-key-and-specify-the-unit-option) Calculate the elapsed time between field values associated with a field key and specify the unit option Return the elapsed time (in minutes) between subsequent timestamps in the `water_level` field key and in the `h2o_feet` measurement. ```sql SELECT ELAPSED("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time | elapsed | |--------------------|------------| |2019-08-18T00:06:00Z|6.0000000000| |2019-08-18T00:12:00Z|6.0000000000| [](#calculate-the-elapsed-time-between-field-values-associated-with-each-field-key-in-a-measurement-and-specify-the-unit-option) Calculate the elapsed time between field values associated with each field key in a measurement and specify the unit option Return the difference (in minutes) between subsequent timestamps associated with each field key in the `h2o_feet`measurement. The `h2o_feet` measurement has two field keys: `level description` and `water_level`. ```sql SELECT ELAPSED(*,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time |elapsed\_level description|elapsed\_water\_level| |--------------------|--------------------------|---------------------| |2019-08-18T00:06:00Z| 6.0000000000 | 6.0000000000 | |2019-08-18T00:12:00Z| 6.0000000000 | 6.0000000000 | [](#calculate-the-elapsed-time-between-field-values-associated-with-each-field-key-that-matches-a-regular-expression-and-specify-the-unit-option) Calculate the elapsed time between field values associated with each field key that matches a regular expression and specify the unit option Return the difference (in seconds) between subsequent timestamps associated with each field key that includes the word `level` in the `h2o_feet` measurement. ```sql SELECT ELAPSED(/level/,1s) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time |elapsed\_level description|elapsed\_water\_level| |--------------------|--------------------------|---------------------| |2019-08-18T00:06:00Z| 360.0000000000 | 360.0000000000 | |2019-08-18T00:12:00Z| 360.0000000000 | 360.0000000000 | [](#calculate-the-elapsed-time-between-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the elapsed time between field values associated with a field key and include several clauses Return the difference (in milliseconds) between subsequent timestamps in the`water_level` field key and in the `h2o_feet` measurement in the[time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-17T00:00:00Z` and `2019-08-17T00:12:00Z` with timestamps in[descending order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to one and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by one point. ```sql SELECT ELAPSED("water_level",1ms) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ORDER BY time DESC LIMIT 1 OFFSET 1 ``` name: h2o\_feet | time | elapsed | |--------------------|-------------------| |2019-08-18T00:00:00Z|\-360000.0000000000| Notice that the result is negative; the [`ORDER BY time DESC` clause](/influxdb/v2/query-data/influxql/explore-data/order-by/) sorts timestamps in descending order so `ELAPSED()` calculates the difference between timestamps in reverse order. ### Common issues with ELAPSED() #### ELAPSED() and units greater than the elapsed time InfluxDB returns `0` if the `unit` option is greater than the difference between the timestamps. ##### Example The timestamps in the `h2o_feet` measurement occur at six-minute intervals. If the query sets the `unit` option to one hour, InfluxDB returns `0`: ```sql SELECT ELAPSED("water_level",1h) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ``` name: h2o\_feet | time | elapsed | |--------------------|------------| |2019-08-18T00:06:00Z|0.0000000000| |2019-08-18T00:12:00Z|0.0000000000| #### ELAPSED() with GROUP BY time() clauses The `ELAPSED()` function supports the [`GROUP BY time()` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) but the query results aren’t particularly useful. Currently, an `ELAPSED()` query with a nested function and a `GROUP BY time()` clause simply returns the interval specified in the `GROUP BY time()` clause. The `GROUP BY time()` clause determines the timestamps in the results; each timestamp marks the start of a time interval. That behavior also applies to nested selector functions (like [`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first) or [`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max)) which would, in all other cases, return a specific timestamp from the raw data. Because the `GROUP BY time()` clause overrides the original timestamps, the `ELAPSED()` calculation always returns the same value as the `GROUP BY time()` interval. ##### Example In the codeblock below, the first query attempts to use the `ELAPSED()` function with a `GROUP BY time()` clause to find the time elapsed (in minutes) between [minimum](/influxdb/v2/query-data/influxql/functions/selectors/#min) `water_level`s. Returns 12 minutes for both time intervals. To get those results, InfluxDB first calculates the minimum `water_level`s at 12-minute intervals. The second query in the codeblock shows the results of that step. The step is the same as using the `MIN()` function with the `GROUP BY time()` clause and without the `ELAPSED()` function. Notice that the timestamps returned by the second query are 12 minutes apart. In the raw data, the first result (`2.0930000000`) occurs at `2019-08-18T00:42:00Z` but the `GROUP BY time()` clause overrides that original timestamp. Because the timestamps are determined by the `GROUP BY time()` interval and not by the original data, the `ELAPSED()` calculation always returns the same value as the `GROUP BY time()` interval. ```sql SELECT ELAPSED(MIN("water_level"),1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:36:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m) ``` name: h2o\_feet | time | elapsed | |--------------------|-------------| |2019-08-18T00:36:00Z|12.0000000000| |2019-08-18T00:48:00Z|12.0000000000| ```sql SELECT MIN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:36:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m) ``` name: h2o\_feet | time | min | |--------------------|------------| |2019-08-18T00:36:00Z|2.0930000000| |2019-08-18T00:48:00Z|2.0870000000| > [!Note] > The first point actually occurs at 2019-08-18T00:42:00Z, not 2019-08-18T00:36:00Z. ## EXP() Returns the exponential of the field value. ### Syntax ```sql SELECT EXP( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `EXP(field_key)` Returns the exponential of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `EXP(*)` Returns the exponential of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `EXP()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `EXP()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-exponential-of-field-values-associated-with-a-field-key) Calculate the exponential of field values associated with a field key Return the exponential of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT EXP("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | exp | |--------------------|-------------| |2019-08-18T00:00:00Z|10.5065618493| |2019-08-18T00:06:00Z|10.7941033617| |2019-08-18T00:12:00Z|10.4124270347| |2019-08-18T00:18:00Z|10.2676687288| |2019-08-18T00:24:00Z|9.6214982905 | |2019-08-18T00:30:00Z|9.6504061254 | [](#calculate-the-exponential-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the exponential of field values associated with each field key in a measurement Return the exponential of field values for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT EXP(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |exp\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| 10.5065618493 | |2019-08-18T00:06:00Z| 10.7941033617 | |2019-08-18T00:12:00Z| 10.4124270347 | |2019-08-18T00:18:00Z| 10.2676687288 | |2019-08-18T00:24:00Z| 9.6214982905 | |2019-08-18T00:30:00Z| 9.6504061254 | [](#calculate-the-exponential-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the exponential of field values associated with a field key and include several clauses ```sql SELECT EXP("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | exp | |--------------------|-------------| |2019-08-18T00:18:00Z|10.2676687288| |2019-08-18T00:12:00Z|10.4124270347| |2019-08-18T00:06:00Z|10.7941033617| |2019-08-18T00:00:00Z|10.5065618493| Return the exponentials of field values associated with the `water_level` field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ### Advanced syntax ```sql SELECT EXP(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `EXP()` function to those results. `EXP()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-exponential-of-mean-values) Calculate the exponential of mean values Return the exponential of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT EXP(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | exp | |--------------------|-------------| |2019-08-18T00:00:00Z|10.6493621676| |2019-08-18T00:12:00Z|10.3397945558| |2019-08-18T00:24:00Z|9.6359413675 | ## FLOOR() Returns the subsequent value rounded down to the nearest integer. ### Syntax ```sql SELECT FLOOR( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `FLOOR(field_key)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) rounded down to the nearest integer. `FLOOR(*)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) rounded down to the nearest integer. `FLOOR()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `FLOOR()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-floor-of-field-values-associated-with-a-field-key) Calculate the floor of field values associated with a field key Return field values in the `water_level` field key in the `h2o_feet` measurement rounded down to the nearest integer. ```sql SELECT FLOOR("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | floor | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:06:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:18:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| |2019-08-18T00:30:00Z|2.0000000000| [](#calculate-the-floor-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the floor of field values associated with each field key in a measurement Return field values for each field key that stores numeric values in the`h2o_feet` measurement rounded down to the nearest integer. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT FLOOR(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |floor\_water\_level| |--------------------|-------------------| |2019-08-18T00:00:00Z| 2.0000000000 | |2019-08-18T00:06:00Z| 2.0000000000 | |2019-08-18T00:12:00Z| 2.0000000000 | |2019-08-18T00:18:00Z| 2.0000000000 | |2019-08-18T00:24:00Z| 2.0000000000 | |2019-08-18T00:30:00Z| 2.0000000000 | [](#calculate-the-floor-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the floor of field values associated with a field key and include several clauses Return field values associated with the `water_level` field key rounded down to the nearest integer in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT FLOOR("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | floor | |--------------------|------------| |2019-08-18T00:18:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:06:00Z|2.0000000000| |2019-08-18T00:00:00Z|2.0000000000| ### Advanced syntax ```sql SELECT FLOOR(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `FLOOR()` function to those results. `FLOOR()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-mean-values-rounded-down-to-the-nearest-integer) Calculate mean values rounded down to the nearest integer Return the [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds them up to the nearest integer. ```sql SELECT FLOOR(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | floor | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| ## HISTOGRAM() *InfluxQL does not currently support histogram generation. For information about creating histograms with data stored in InfluxDB, see[Flux’s `histogram()` function](/flux/v0/stdlib/universe/histogram).* ## LN() Returns the natural logarithm of the field value. ### Syntax ```sql SELECT LN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `LN(field_key)` Returns the natural logarithm of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `LN(*)` Returns the natural logarithm of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `LN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `LN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-natural-logarithm-of-field-values-associated-with-a-field-key) Calculate the natural logarithm of field values associated with a field key Return the natural logarithm of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT LN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | ln | |--------------------|------------| |2019-08-18T00:00:00Z|0.8552660300| |2019-08-18T00:06:00Z|0.8666802313| |2019-08-18T00:12:00Z|0.8514321595| |2019-08-18T00:18:00Z|0.8454389909| |2019-08-18T00:24:00Z|0.8171331603| |2019-08-18T00:30:00Z|0.8184573715| [](#calculate-the-natural-logarithm-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the natural logarithm of field values associated with each field key in a measurement Return the natural logarithm of field values for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT LN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |ln\_water\_level| |--------------------|----------------| |2019-08-18T00:00:00Z| 0.8552660300 | |2019-08-18T00:06:00Z| 0.8666802313 | |2019-08-18T00:12:00Z| 0.8514321595 | |2019-08-18T00:18:00Z| 0.8454389909 | |2019-08-18T00:24:00Z| 0.8171331603 | |2019-08-18T00:30:00Z| 0.8184573715 | [](#calculate-the-natural-logarithm-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the natural logarithm of field values associated with a field key and include several clauses ```sql SELECT LN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | ln | |--------------------|------------| |2019-08-18T00:18:00Z|0.8454389909| |2019-08-18T00:12:00Z|0.8514321595| |2019-08-18T00:06:00Z|0.8666802313| |2019-08-18T00:00:00Z|0.8552660300| Return the natural logarithms of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ### Advanced syntax ```sql SELECT LN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LN()` function to those results. `LN()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-natural-logarithm-of-mean-values) Calculate the natural logarithm of mean values Return the natural logarithm of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT LN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | ln | |--------------------|------------| |2019-08-18T00:00:00Z|0.8609894161| |2019-08-18T00:12:00Z|0.8484400650| |2019-08-18T00:24:00Z|0.8177954851| ## LOG() Returns the logarithm of the field value with base `b`. ### Basic syntax ```sql SELECT LOG( [ * | ], ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `LOG(field_key, b)` Returns the logarithm of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) with base `b`. `LOG(*, b)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) with base `b`. `LOG()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `LOG()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-logarithm-base-4-of-field-values-associated-with-a-field-key) Calculate the logarithm base 4 of field values associated with a field key Return the logarithm base 4 of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT LOG("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | log | |--------------------|------------| |2019-08-18T00:00:00Z|0.6169440301| |2019-08-18T00:06:00Z|0.6251776359| |2019-08-18T00:12:00Z|0.6141784771| |2019-08-18T00:18:00Z|0.6098553198| |2019-08-18T00:24:00Z|0.5894369791| |2019-08-18T00:30:00Z|0.5903921955| [](#calculate-the-logarithm-base-4-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the logarithm base 4 of field values associated with each field key in a measurement Return the logarithm base 4 of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT LOG(*, 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |log\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| 0.6169440301 | |2019-08-18T00:06:00Z| 0.6251776359 | |2019-08-18T00:12:00Z| 0.6141784771 | |2019-08-18T00:18:00Z| 0.6098553198 | |2019-08-18T00:24:00Z| 0.5894369791 | |2019-08-18T00:30:00Z| 0.5903921955 | [](#calculate-the-logarithm-base-4-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the logarithm base 4 of field values associated with a field key and include several clauses Return the logarithm base 4 of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT LOG("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | log | |--------------------|------------| |2019-08-18T00:18:00Z|0.6098553198| |2019-08-18T00:12:00Z|0.6141784771| |2019-08-18T00:06:00Z|0.6251776359| |2019-08-18T00:00:00Z|0.6169440301| ### Advanced syntax ```sql SELECT LOG(( [ * | ] ), ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG()` function to those results. `LOG()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-logarithm-base-4-of-mean-values) Calculate the logarithm base 4 of mean values Return the logarithm base 4 of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT LOG(MEAN("water_level"), 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | log | |--------------------|------------| |2019-08-18T00:00:00Z|0.6210725804| |2019-08-18T00:12:00Z|0.6120201371| |2019-08-18T00:24:00Z|0.5899147454| ## LOG2() Returns the logarithm of the field value to the base 2. ### Basic syntax ```sql SELECT LOG2( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `LOG2(field_key)` Returns the logarithm of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) to the base 2. `LOG2(*)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) to the base 2. `LOG2()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `LOG2()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-logarithm-base-2-of-field-values-associated-with-a-field-key) Calculate the logarithm base 2 of field values associated with a field key Return the logarithm base 2 of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT LOG2("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | log2 | |--------------------|------------| |2019-08-18T00:00:00Z|1.2338880602| |2019-08-18T00:06:00Z|1.2503552718| |2019-08-18T00:12:00Z|1.2283569542| |2019-08-18T00:18:00Z|1.2197106395| |2019-08-18T00:24:00Z|1.1788739582| |2019-08-18T00:30:00Z|1.1807843911| [](#calculate-the-logarithm-base-2-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the logarithm base 2 of field values associated with each field key in a measurement ```sql SELECT LOG2(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |log2\_water\_level| |--------------------|------------------| |2019-08-18T00:00:00Z| 1.2338880602 | |2019-08-18T00:06:00Z| 1.2503552718 | |2019-08-18T00:12:00Z| 1.2283569542 | |2019-08-18T00:18:00Z| 1.2197106395 | |2019-08-18T00:24:00Z| 1.1788739582 | |2019-08-18T00:30:00Z| 1.1807843911 | Return the logarithm base 2 of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. [](#calculate-the-logarithm-base-2-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the logarithm base 2 of field values associated with a field key and include several clauses Return the logarithm base 2 of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT LOG2("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | log2 | |--------------------|------------| |2019-08-18T00:18:00Z|1.2197106395| |2019-08-18T00:12:00Z|1.2283569542| |2019-08-18T00:06:00Z|1.2503552718| |2019-08-18T00:00:00Z|1.2338880602| ### Advanced syntax ```sql SELECT LOG2(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG2()` function to those results. `LOG2()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-logarithm-base-2-of-mean-values) Calculate the logarithm base 2 of mean values Return the logarithm base 2 of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT LOG2(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | log2 | |--------------------|------------| |2019-08-18T00:00:00Z|1.2421451608| |2019-08-18T00:12:00Z|1.2240402742| |2019-08-18T00:24:00Z|1.1798294909| ## LOG10() Returns the logarithm of the field value to the base 10. ### Basic syntax ```sql SELECT LOG10( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `LOG10(field_key)` Returns the logarithm of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) to the base 10. `LOG10(*)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) to the base 10. `LOG10()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `LOG10()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-logarithm-base-10-of-field-values-associated-with-a-field-key) Calculate the logarithm base 10 of field values associated with a field key Return the logarithm base 10 of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT LOG10("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | log10 | |--------------------|------------| |2019-08-18T00:00:00Z|0.3714373174| |2019-08-18T00:06:00Z|0.3763944420| |2019-08-18T00:12:00Z|0.3697722886| |2019-08-18T00:18:00Z|0.3671694885| |2019-08-18T00:24:00Z|0.3548764225| |2019-08-18T00:30:00Z|0.3554515201| [](#calculate-the-logarithm-base-10-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the logarithm base 10 of field values associated with each field key in a measurement Return the logarithm base 10 of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT LOG10(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |log10\_water\_level| |--------------------|-------------------| |2019-08-18T00:00:00Z| 0.3714373174 | |2019-08-18T00:06:00Z| 0.3763944420 | |2019-08-18T00:12:00Z| 0.3697722886 | |2019-08-18T00:18:00Z| 0.3671694885 | |2019-08-18T00:24:00Z| 0.3548764225 | |2019-08-18T00:30:00Z| 0.3554515201 | [](#calculate-the-logarithm-base-10-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the logarithm base 10 of field values associated with a field key and include several clauses Return the logarithm base 10 of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT LOG10("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | log10 | |--------------------|------------| |2019-08-18T00:18:00Z|0.3671694885| |2019-08-18T00:12:00Z|0.3697722886| |2019-08-18T00:06:00Z|0.3763944420| |2019-08-18T00:00:00Z|0.3714373174| ### Advanced syntax ```sql SELECT LOG10(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG10()` function to those results. `LOG10()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-logarithm-base-10-of-mean-values) Calculate the logarithm base 10 of mean values Return the logarithm base 10 of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT LOG10(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | log10 | |--------------------|------------| |2019-08-18T00:00:00Z|0.3739229524| |2019-08-18T00:12:00Z|0.3684728384| |2019-08-18T00:24:00Z|0.3551640665| ## MOVING\_AVERAGE() Returns the rolling average across a window of subsequent [field values](/influxdb/v2/reference/glossary/#field-value). ### Basic syntax ```sql SELECT MOVING_AVERAGE( [ * | | // ] , ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `MOVING_AVERAGE()` calculates the rolling average across a window of `N` subsequent field values. The `N` argument is an integer and it is required. `MOVING_AVERAGE(field_key,N)` Returns the rolling average across `N` field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `MOVING_AVERAGE(/regular_expression/,N)` Returns the rolling average across `N` field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `MOVING_AVERAGE(*,N)` Returns the rolling average across `N` field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `MOVING_AVERAGE()` int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-moving-average-of-the-field-values-associated-with-a-field-key) Calculate the moving average of the field values associated with a field key Return the rolling average across a two-field-value window for the `water_level` field key and the `h2o_feet` measurement. ```sql SELECT MOVING_AVERAGE("water_level",2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |moving\_average| |--------------------|---------------| |2019-08-18T00:06:00Z| 2.3655000000 | |2019-08-18T00:12:00Z| 2.3610000000 | |2019-08-18T00:18:00Z| 2.3360000000 | |2019-08-18T00:24:00Z| 2.2965000000 | |2019-08-18T00:30:00Z| 2.2655000000 | The first result (`2.3655000000`) is the average of the first two points in the raw data: (`2.3520000000 + 2.3790000000) / 2`). The second result (`2.3610000000`) is the average of the second two points in the raw data: (`2.3790000000 + 2.3430000000) / 2`). [](#calculate-the-moving-average-of-the-field-values-associated-with-each-field-key-in-a-measurement) Calculate the moving average of the field values associated with each field key in a measurement Return the rolling average across a three-field-value window for each field key that stores numeric values in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT MOVING_AVERAGE(*,3) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |moving\_average\_water\_level| |--------------------|-----------------------------| |2019-08-18T00:12:00Z| 2.3580000000 | |2019-08-18T00:18:00Z| 2.3503333333 | |2019-08-18T00:24:00Z| 2.3120000000 | |2019-08-18T00:30:00Z| 2.2866666667 | [](#calculate-the-moving-average-of-the-field-values-associated-with-each-field-key-that-matches-a-regular-expression) Calculate the moving average of the field values associated with each field key that matches a regular expression Return the rolling average across a four-field-value window for each numeric field with a field key that includes the word `level` in the `h2o_feet` measurement. ```sql SELECT MOVING_AVERAGE(/level/,4) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ``` name: h2o\_feet | time |moving\_average\_water\_level| |--------------------|-----------------------------| |2019-08-18T00:18:00Z| 2.3507500000 | |2019-08-18T00:24:00Z| 2.3287500000 | |2019-08-18T00:30:00Z| 2.3007500000 | [](#calculate-the-moving-average-of-the-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the moving average of the field values associated with a field key and include several clauses Return the rolling average across a two-field-value window for the `water_level`field key in the `h2o_feet` measurement in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to two and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by three points. ```sql SELECT MOVING_AVERAGE("water_level",2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 2 OFFSET 3 ``` name: h2o\_feet | time |moving\_average| |--------------------|---------------| |2019-08-18T00:06:00Z| 2.3610000000 | |2019-08-18T00:00:00Z| 2.3655000000 | ### Advanced syntax ```sql SELECT MOVING_AVERAGE( ([ * | | // ]) , N ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `MOVING_AVERAGE()` function to those results. `MOVING_AVERAGE()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-moving-average-of-maximum-values) Calculate the moving average of maximum values Return the rolling average across a two-value window of [maximum](/influxdb/v2/query-data/influxql/functions/selectors/#max) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT MOVING_AVERAGE(MAX("water_level"),2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ``` name: h2o\_feet | time |moving\_average| |--------------------|---------------| |2019-08-18T00:00:00Z| 2.4935000000 | |2019-08-18T00:12:00Z| 2.3610000000 | |2019-08-18T00:24:00Z| 2.3050000000 | ## NON\_NEGATIVE\_DERIVATIVE() Returns the non-negative rate of change between subsequent [field values](/influxdb/v2/reference/glossary/#field-value). Non-negative rates of change include positive rates of change and rates of change that equal zero. ### Basic syntax ```sql SELECT NON_NEGATIVE_DERIVATIVE( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` InfluxDB calculates the difference between subsequent field values and converts those results into the rate of change per `unit`. The `unit` argument is an integer followed by a [duration](/influxdb/v2/reference/glossary/#duration) and it is optional. If the query does not specify the `unit`, the unit defaults to one second (`1s`).`NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. `NON_NEGATIVE_DERIVATIVE(field_key)` Returns the non-negative rate of change between subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `NON_NEGATIVE_DERIVATIVE(/regular_expression/)` Returns the non-negative rate of change between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `NON_NEGATIVE_DERIVATIVE(*)` Returns the non-negative rate of change between subsequent field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `NON_NEGATIVE_DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `NON_NEGATIVE_DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples See the examples in the [`DERIVATIVE()` documentation](#basic-syntax-8).`NON_NEGATIVE_DERIVATIVE()` behaves the same as the `DERIVATIVE()` function but `NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. ### Advanced syntax ```sql SELECT NON_NEGATIVE_DERIVATIVE( ([ * | | // ]) [ , ] ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `NON_NEGATIVE_DERIVATIVE()` function to those results. The `unit` argument is an integer followed by a [duration](/influxdb/v2/reference/glossary/#duration) and it is optional. If the query does not specify the `unit`, the `unit` defaults to the `GROUP BY time()` interval. Note that this behavior is different from the [basic syntax’s](#basic-syntax-4) default behavior.`NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. `NON_NEGATIVE_DERIVATIVE()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples See the examples in the [`DERIVATIVE()` documentation](#advanced-syntax-8).`NON_NEGATIVE_DERIVATIVE()` behaves the same as the `DERIVATIVE()` function but `NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. ## NON\_NEGATIVE\_DIFFERENCE() Returns the non-negative result of subtraction between subsequent [field values](/influxdb/v2/reference/glossary/#field-value). Non-negative results of subtraction include positive differences and differences that equal zero. ### Basic syntax ```sql SELECT NON_NEGATIVE_DIFFERENCE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `NON_NEGATIVE_DIFFERENCE(field_key)` Returns the non-negative difference between subsequent field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `NON_NEGATIVE_DIFFERENCE(/regular_expression/)` Returns the non-negative difference between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/). `NON_NEGATIVE_DIFFERENCE(*)` Returns the non-negative difference between subsequent field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `NON_NEGATIVE_DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `NON_NEGATIVE_DIFFERENCE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples See the examples in the [`DIFFERENCE()` documentation](#basic-syntax-9).`NON_NEGATIVE_DIFFERENCE()` behaves the same as the `DIFFERENCE()` function but `NON_NEGATIVE_DIFFERENCE()` returns only positive differences or differences that equal zero. ### Advanced syntax ```sql SELECT NON_NEGATIVE_DIFFERENCE(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `NON_NEGATIVE_DIFFERENCE()` function to those results. `NON_NEGATIVE_DIFFERENCE()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples See the examples in the [`DIFFERENCE()` documentation](#advanced-syntax-9).`NON_NEGATIVE_DIFFERENCE()` behaves the same as the `DIFFERENCE()` function but `NON_NEGATIVE_DIFFERENCE()` returns only positive differences or differences that equal zero. ## POW() Returns the field value to the power of `x`. ### Basic syntax ```sql SELECT POW( [ * | ], ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `POW(field_key, x)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) to the power of `x`. `POW(*, x)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) to the power of `x`. `POW()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `POW()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-field-values-associated-with-a-field-key-to-the-power-of-4) Calculate field values associated with a field key to the power of 4 Return field values in the `water_level` field key in the `h2o_feet` measurement multiplied to a power of 4. ```sql SELECT POW("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | pow | |--------------------|-------------| |2019-08-18T00:00:00Z|30.6019618652| |2019-08-18T00:06:00Z|32.0315362489| |2019-08-18T00:12:00Z|30.1362461432| |2019-08-18T00:18:00Z|29.4223904261| |2019-08-18T00:24:00Z|26.2727594844| |2019-08-18T00:30:00Z|26.4122914255| [](#calculate-field-values-associated-with-each-field-key-in-a-measurement-to-the-power-of-4) Calculate field values associated with each field key in a measurement to the power of 4 Return field values for each field key that stores numeric values in the `h2o_feet` measurement multiplied to the power of 4. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT POW(*, 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |pow\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| 30.6019618652 | |2019-08-18T00:06:00Z| 32.0315362489 | |2019-08-18T00:12:00Z| 30.1362461432 | |2019-08-18T00:18:00Z| 29.4223904261 | |2019-08-18T00:24:00Z| 26.2727594844 | |2019-08-18T00:30:00Z| 26.4122914255 | [](#calculate-field-values-associated-with-a-field-key-to-the-power-of-4-and-include-several-clauses) Calculate field values associated with a field key to the power of 4 and include several clauses Return field values associated with the `water_level` field key multiplied to the power of 4 in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT POW("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | pow | |--------------------|-------------| |2019-08-18T00:18:00Z|29.4223904261| |2019-08-18T00:12:00Z|30.1362461432| |2019-08-18T00:06:00Z|32.0315362489| |2019-08-18T00:00:00Z|30.6019618652| ### Advanced syntax ```sql SELECT POW(( [ * | ] ), ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `POW()` function to those results. `POW()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-mean-values-to-the-power-of-4) Calculate mean values to the power of 4 Return [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals multiplied to the power of 4. ```sql SELECT POW(MEAN("water_level"), 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | pow | |--------------------|-------------| |2019-08-18T00:00:00Z|31.3106302459| |2019-08-18T00:12:00Z|29.7777139548| |2019-08-18T00:24:00Z|26.3424561663| ## ROUND() Returns the subsequent value rounded to the nearest integer. ### Basic syntax ```sql SELECT ROUND( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `ROUND(field_key)` Returns the field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key) rounded to the nearest integer. `ROUND(*)` Returns the field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement) rounded to the nearest integer. `ROUND()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/. To use `ROUND()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#round-field-values-associated-with-a-field-key) Round field values associated with a field key Return field values in the `water_level` field key in the `h2o_feet` measurement rounded to the nearest integer. ```sql SELECT ROUND("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | round | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:06:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:18:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| |2019-08-18T00:30:00Z|2.0000000000| [](#round-field-values-associated-with-each-field-key-in-a-measurement) Round field values associated with each field key in a measurement Return field values for each numeric field in the `h2o_feet` measurement rounded to the nearest integer. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT ROUND(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |round\_water\_level| |--------------------|-------------------| |2019-08-18T00:00:00Z| 2.0000000000 | |2019-08-18T00:06:00Z| 2.0000000000 | |2019-08-18T00:12:00Z| 2.0000000000 | |2019-08-18T00:18:00Z| 2.0000000000 | |2019-08-18T00:24:00Z| 2.0000000000 | |2019-08-18T00:30:00Z| 2.0000000000 | [](#round-field-values-associated-with-a-field-key-and-include-several-clauses) Round field values associated with a field key and include several clauses Return field values associated with the `water_level` field key rounded to the nearest integer in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT ROUND("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | round | |--------------------|------------| |2019-08-18T00:18:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:06:00Z|2.0000000000| |2019-08-18T00:00:00Z|2.0000000000| ### Advanced syntax ```sql SELECT ROUND(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ROUND()` function to those results. `ROUND()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-mean-values-rounded-to-the-nearest-integer) Calculate mean values rounded to the nearest integer Return the [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds to the nearest integer. ```sql SELECT ROUND(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | round | |--------------------|------------| |2019-08-18T00:00:00Z|2.0000000000| |2019-08-18T00:12:00Z|2.0000000000| |2019-08-18T00:24:00Z|2.0000000000| ## SIN() Returns the sine of the field value. ### Basic syntax ```sql SELECT SIN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `SIN(field_key)` Returns the sine of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `SIN(*)` Returns the sine of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `SIN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `SIN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-sine-of-field-values-associated-with-a-field-key) Calculate the sine of field values associated with a field key Return the sine of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT SIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | sin | |--------------------|------------| |2019-08-18T00:00:00Z|0.7100665046| |2019-08-18T00:06:00Z|0.6907983763| |2019-08-18T00:12:00Z|0.7163748731| |2019-08-18T00:18:00Z|0.7260723687| |2019-08-18T00:24:00Z|0.7692028035| |2019-08-18T00:30:00Z|0.7672823308| [](#calculate-the-sine-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the sine of field values associated with each field key in a measurement Return the sine of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT SIN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |sin\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| 0.7100665046 | |2019-08-18T00:06:00Z| 0.6907983763 | |2019-08-18T00:12:00Z| 0.7163748731 | |2019-08-18T00:18:00Z| 0.7260723687 | |2019-08-18T00:24:00Z| 0.7692028035 | |2019-08-18T00:30:00Z| 0.7672823308 | [](#calculate-the-sine-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the sine of field values associated with a field key and include several clauses Return the sine of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT SIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | sin | |--------------------|------------| |2019-08-18T00:18:00Z|0.7260723687| |2019-08-18T00:12:00Z|0.7163748731| |2019-08-18T00:06:00Z|0.6907983763| |2019-08-18T00:00:00Z|0.7100665046| ### Advanced syntax ```sql SELECT SIN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `SIN()` function to those results. `SIN()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-sine-of-mean-values) Calculate the sine of mean values Return the sine of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT SIN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | sin | |--------------------|------------| |2019-08-18T00:00:00Z|0.7004962722| |2019-08-18T00:12:00Z|0.7212412912| |2019-08-18T00:24:00Z|0.7682434314| ## SQRT() Returns the square root of field value. ### Basic syntax ```sql SELECT SQRT( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `SQRT(field_key)` Returns the square root of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `SQRT(*)` Returns the square root field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `SQRT()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `SQRT()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-square-root-of-field-values-associated-with-a-field-key) Calculate the square root of field values associated with a field key Return the square roots of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT SQRT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | sqrt | |--------------------|------------| |2019-08-18T00:00:00Z|1.5336231610| |2019-08-18T00:06:00Z|1.5424007261| |2019-08-18T00:12:00Z|1.5306861207| |2019-08-18T00:18:00Z|1.5261061562| |2019-08-18T00:24:00Z|1.5046594299| |2019-08-18T00:30:00Z|1.5056560032| [](#calculate-the-square-root-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the square root of field values associated with each field key in a measurement Return the square roots of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT SQRT(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |sqrt\_water\_level| |--------------------|------------------| |2019-08-18T00:00:00Z| 1.5336231610 | |2019-08-18T00:06:00Z| 1.5424007261 | |2019-08-18T00:12:00Z| 1.5306861207 | |2019-08-18T00:18:00Z| 1.5261061562 | |2019-08-18T00:24:00Z| 1.5046594299 | |2019-08-18T00:30:00Z| 1.5056560032 | [](#calculate-the-square-root-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the square root of field values associated with a field key and include several clauses Return the square roots of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT SQRT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | sqrt | |--------------------|------------| |2019-08-18T00:18:00Z|1.5261061562| |2019-08-18T00:12:00Z|1.5306861207| |2019-08-18T00:06:00Z|1.5424007261| |2019-08-18T00:00:00Z|1.5336231610| ### Advanced syntax ```sql SELECT SQRT(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `SQRT()` function to those results. `SQRT()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-square-root-of-mean-values) Calculate the square root of mean values Return the square roots of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT SQRT(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | sqrt | |--------------------|------------| |2019-08-18T00:00:00Z|1.5380182054| |2019-08-18T00:12:00Z|1.5283978540| |2019-08-18T00:24:00Z|1.5051577990| ## TAN() Returns the tangent of the field value. ### Basic syntax ```sql SELECT TAN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` `TAN(field_key)` Returns the tangent of field values associated with the [field key](/influxdb/v2/reference/glossary/#field-key). `TAN(*)` Returns the tangent of field values associated with each field key in the [measurement](/influxdb/v2/reference/glossary/#measurement). `TAN()` supports int64 and float64 field value [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `TAN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). #### Examples The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data): ```sql SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |water\_level| |--------------------|------------| |2019-08-18T00:00:00Z|2.3520000000| |2019-08-18T00:06:00Z|2.3790000000| |2019-08-18T00:12:00Z|2.3430000000| |2019-08-18T00:18:00Z|2.3290000000| |2019-08-18T00:24:00Z|2.2640000000| |2019-08-18T00:30:00Z|2.2670000000| [](#calculate-the-tangent-of-field-values-associated-with-a-field-key) Calculate the tangent of field values associated with a field key Return the tangent of field values in the `water_level` field key in the `h2o_feet` measurement. ```sql SELECT TAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time | tan | |--------------------|--------------| |2019-08-18T00:00:00Z|\-1.0084243657| |2019-08-18T00:06:00Z|\-0.9553984098| |2019-08-18T00:12:00Z|\-1.0267433979| |2019-08-18T00:18:00Z|\-1.0559235802| |2019-08-18T00:24:00Z|\-1.2037513424| |2019-08-18T00:30:00Z|\-1.1964307053| [](#calculate-the-tangent-of-field-values-associated-with-each-field-key-in-a-measurement) Calculate the tangent of field values associated with each field key in a measurement Return the tangent of field values for each numeric field in the `h2o_feet` measurement. The `h2o_feet` measurement has one numeric field: `water_level`. ```sql SELECT TAN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ``` name: h2o\_feet | time |tan\_water\_level| |--------------------|-----------------| |2019-08-18T00:00:00Z| \-1.0084243657 | |2019-08-18T00:06:00Z| \-0.9553984098 | |2019-08-18T00:12:00Z| \-1.0267433979 | |2019-08-18T00:18:00Z| \-1.0559235802 | |2019-08-18T00:24:00Z| \-1.2037513424 | |2019-08-18T00:30:00Z| \-1.1964307053 | [](#calculate-the-tangent-of-field-values-associated-with-a-field-key-and-include-several-clauses) Calculate the tangent of field values associated with a field key and include several clauses Return the tangent of field values associated with the `water_level`field key in the [time range](/influxdb/v2/query-data/influxql/explore-data/time-and-timezone/#time-syntax)between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in[descending timestamp order](/influxdb/v2/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/v2/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/v2/query-data/influxql/explore-data/offset-and-soffset/)results by two points. ```sql SELECT TAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 ``` name: h2o\_feet | time | tan | |--------------------|--------------| |2019-08-18T00:18:00Z|\-1.0559235802| |2019-08-18T00:12:00Z|\-1.0267433979| |2019-08-18T00:06:00Z|\-0.9553984098| |2019-08-18T00:00:00Z|\-1.0084243657| ### Advanced syntax ```sql SELECT TAN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] ``` The advanced syntax requires a [`GROUP BY time() `clause](/influxdb/v2/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `TAN()` function to those results. `TAN()` supports the following nested functions:[`COUNT()`](/influxdb/v2/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/v2/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/v2/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/v2/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/v2/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/v2/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/v2/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/v2/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/v2/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-the-tangent-of-mean-values) Calculate the tangent of mean values Return the tangent of [mean](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. ```sql SELECT TAN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) ``` name: h2o\_feet | time | tan | |--------------------|--------------| |2019-08-18T00:00:00Z|\-0.9815600413| |2019-08-18T00:12:00Z|\-1.0412271461| |2019-08-18T00:24:00Z|\-1.2000844348| | time | abs | | --- | --- | | time | abs | | 2019-08-18T00:00:00Z | 8.5040000000 | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 8.4190000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 8.3200000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | time | abs_water_level | | --- | --- | | time | abs_water_level | | 2019-08-18T00:00:00Z | 8.5040000000 | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 8.4190000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 8.3200000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | time | abs | | --- | --- | | time | abs | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:24:00Z | 8.1300000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:18:00Z | 8.2250000000 | | time | abs | | --- | --- | | time | abs | | 2019-08-18T00:00:00Z | 5.4135000000 | | 2019-08-18T00:12:00Z | 5.3042500000 | | 2019-08-18T00:24:00Z | 5.1682500000 | | time | a | | --- | --- | | time | a | | 2018-06-24T12:01:00Z | -0.774984088561186 | | 2018-06-24T12:02:00Z | -0.921037167720451 | | 2018-06-24T12:04:00Z | -0.905980032168252 | | 2018-06-24T12:05:00Z | -0.891164752631417 | | 2018-06-24T12:09:00Z | 0.416579917279588 | | 2018-06-24T12:10:00Z | 0.328968116955350 | | 2018-06-24T12:11:00Z | 0.263585064411983 | | time | acos | | --- | --- | | time | acos | | 2018-06-24T12:00:00Z | | | 2018-06-24T12:01:00Z | 2.4574862443 | | 2018-06-24T12:02:00Z | 2.7415314737 | | 2018-06-24T12:03:00Z | | | 2018-06-24T12:04:00Z | 2.7044854503 | | 2018-06-24T12:05:00Z | 2.6707024029 | | 2018-06-24T12:06:00Z | | | 2018-06-24T12:07:00Z | | | 2018-06-24T12:08:00Z | | | 2018-06-24T12:09:00Z | 1.1411163210 | | 2018-06-24T12:10:00Z | 1.2355856616 | | 2018-06-24T12:11:00Z | 1.3040595066 | | time | acos_a | acos_b | | --- | --- | --- | | time | acos_a | acos_b | | 2018-06-24T12:00:00Z | | 1.7351786976 | | 2018-06-24T12:01:00Z | 2.4574862443 | 1.4333294161 | | 2018-06-24T12:02:00Z | 2.7415314737 | 2.0748091141 | | 2018-06-24T12:03:00Z | | 1.6438345404 | | 2018-06-24T12:04:00Z | 2.7044854503 | | | 2018-06-24T12:05:00Z | 2.6707024029 | 0.7360183965 | | 2018-06-24T12:06:00Z | | 1.2789990384 | | 2018-06-24T12:07:00Z | | 2.1522589654 | | 2018-06-24T12:08:00Z | | 0.6128438977 | | 2018-06-24T12:09:00Z | 1.1411163210 | | | 2018-06-24T12:10:00Z | 1.2355856616 | | | 2018-06-24T12:11:00Z | 1.3040595066 | 1.7595349692 | | 2018-06-24T12:12:00Z | 1.8681669412 | 2.5213034266 | | time | acos | | --- | --- | | time | acos | | 2018-06-24T23:58:00Z | 1.5361053361 | | 2018-06-24T23:57:00Z | | | 2018-06-24T23:56:00Z | 0.5211076815 | | 2018-06-24T23:55:00Z | 1.647695085 | | time | acos | | --- | --- | | time | acos | | 2018-06-24T00:00:00Z | | | 2018-06-24T03:00:00Z | | | 2018-06-24T06:00:00Z | | | 2018-06-24T09:00:00Z | | | 2018-06-24T12:00:00Z | 1.5651603194 | | 2018-06-24T15:00:00Z | 1.6489104619 | | 2018-06-24T18:00:00Z | 1.4851295699 | | 2018-06-24T21:00:00Z | 1.6209901549 | | 2018-06-25T00:00:00Z | 1.7149309371 | | time | a | | --- | --- | | time | a | | 2018-06-24T12:01:00Z | -0.774984088561186 | | 2018-06-24T12:02:00Z | -0.921037167720451 | | 2018-06-24T12:04:00Z | -0.905980032168252 | | 2018-06-24T12:05:00Z | -0.891164752631417 | | 2018-06-24T12:09:00Z | 0.416579917279588 | | 2018-06-24T12:10:00Z | 0.328968116955350 | | 2018-06-24T12:11:00Z | 0.263585064411983 | | time | asin | | --- | --- | | time | asin | | 2018-06-24T12:00:00Z | | | 2018-06-24T12:01:00Z | -0.8866899175 | | 2018-06-24T12:02:00Z | -1.1707351469 | | 2018-06-24T12:03:00Z | | | 2018-06-24T12:04:00Z | -1.1336891235 | | 2018-06-24T12:05:00Z | -1.0999060761 | | 2018-06-24T12:06:00Z | | | 2018-06-24T12:07:00Z | | | 2018-06-24T12:08:00Z | | | 2018-06-24T12:09:00Z | 0.4296800058 | | 2018-06-24T12:10:00Z | 0.3352106652 | | 2018-06-24T12:11:00Z | 0.2667368202 | | 2018-06-24T12:12:00Z | -0.2973706144 | | time | asin_a | asin_b | | --- | --- | --- | | time | asin_a | asin_b | | 2018-06-24T12:00:00Z | | -0.1643823708 | | 2018-06-24T12:01:00Z | -0.8866899175 | 0.1374669107 | | 2018-06-24T12:02:00Z | -1.1707351469 | -0.5040127873 | | 2018-06-24T12:03:00Z | | -0.0730382136 | | 2018-06-24T12:04:00Z | -1.1336891235 | | | 2018-06-24T12:05:00Z | -1.0999060761 | 0.8347779303 | | 2018-06-24T12:06:00Z | | 0.2917972884 | | 2018-06-24T12:07:00Z | | -0.5814626386 | | 2018-06-24T12:08:00Z | | 0.9579524291 | | 2018-06-24T12:09:00Z | 0.4296800058 | | | 2018-06-24T12:10:00Z | 0.3352106652 | | | 2018-06-24T12:11:00Z | 0.2667368202 | -0.1887386424 | | 2018-06-24T12:12:00Z | -0.2973706144 | -0.9505070998 | | time | asin | | --- | --- | | time | asin | | 2018-06-24T23:58:00Z | 0.0346909907 | | 2018-06-24T23:57:00Z | | | 2018-06-24T23:56:00Z | 1.0496886453 | | 2018-06-24T23:55:00Z | 0.0768987583 | | time | asin | | --- | --- | | time | asin | | 2018-06-24T00:00:00Z | | | 2018-06-24T03:00:00Z | | | 2018-06-24T06:00:00Z | | | 2018-06-24T09:00:00Z | | | 2018-06-24T12:00:00Z | 0.0056360073 | | 2018-06-24T15:00:00Z | -0.0781141351 | | 2018-06-24T18:00:00Z | 0.0856667569 | | 2018-06-24T21:00:00Z | -0.0501938281 | | 2018-06-25T00:00:00Z | -0.1441346103 | | time | atan | | --- | --- | | time | atan | | 2018-06-24T12:00:00Z | 0.9293622934 | | 2018-06-24T12:01:00Z | -0.6593001275 | | 2018-06-24T12:02:00Z | -0.7443170184 | | 2018-06-24T12:03:00Z | -1.0488818071 | | 2018-06-24T12:04:00Z | -0.7361091801 | | 2018-06-24T12:05:00Z | -0.7279122495 | | 2018-06-24T12:06:00Z | 0.8379907133 | | 2018-06-24T12:07:00Z | -0.9117032768 | | 2018-06-24T12:08:00Z | -1.0364006848 | | 2018-06-24T12:09:00Z | 0.3947172008 | | 2018-06-24T12:10:00Z | 0.3178167283 | | 2018-06-24T12:11:00Z | 0.2577231762 | | 2018-06-24T12:12:00Z | -0.2850291359 | | time | atan_a | atan_b | | --- | --- | --- | | time | atan_a | atan_b | | 2018-06-24T12:00:00Z | 0.9293622934 | -0.1622053541 | | 2018-06-24T12:01:00Z | -0.6593001275 | 0.1361861379 | | 2018-06-24T12:02:00Z | -0.7443170184 | -0.4499093122 | | 2018-06-24T12:03:00Z | -1.0488818071 | -0.0728441751 | | 2018-06-24T12:04:00Z | -0.7361091801 | 1.0585985451 | | 2018-06-24T12:05:00Z | -0.7279122495 | 0.6378113578 | | 2018-06-24T12:06:00Z | 0.8379907133 | 0.2801105336 | | 2018-06-24T12:07:00Z | -0.9117032768 | -0.5022647489 | | 2018-06-24T12:08:00Z | -1.0364006848 | 0.6856298940 | | 2018-06-24T12:09:00Z | 0.3947172008 | -0.8711781065 | | 2018-06-24T12:10:00Z | 0.3178167283 | -0.8273348593 | | 2018-06-24T12:11:00Z | 0.2577231762 | -0.1854639556 | | 2018-06-24T12:12:00Z | -0.2850291359 | -0.6830451940 | | time | atan | | --- | --- | | time | atan | | 2018-06-24T23:58:00Z | 0.0346701348 | | 2018-06-24T23:57:00Z | -0.8582372146 | | 2018-06-24T23:56:00Z | 0.7144341473 | | 2018-06-24T23:55:00Z | -0.0766723939 | | time | atan | | --- | --- | | time | atan | | 2018-06-24T00:00:00Z | | | 2018-06-24T03:00:00Z | | | 2018-06-24T06:00:00Z | | | 2018-06-24T09:00:00Z | | | 2018-06-24T12:00:00Z | 0.0056359178 | | 2018-06-24T15:00:00Z | -0.0778769005 | | 2018-06-24T18:00:00Z | 0.0853541301 | | 2018-06-24T21:00:00Z | -0.0501307176 | | 2018-06-25T00:00:00Z | -0.1426603174 | | time | atan2 | | --- | --- | | time | atan2 | | 2018-06-24T12:00:00Z | 1.6923979639 | | 2018-06-24T12:01:00Z | -1.3957831900 | | 2018-06-24T12:02:00Z | -2.0537314089 | | 2018-06-24T12:03:00Z | -1.6127391493 | | 2018-06-24T12:04:00Z | -0.4711275404 | | 2018-06-24T12:05:00Z | -0.8770454978 | | 2018-06-24T12:06:00Z | 1.3174573347 | | 2018-06-24T12:07:00Z | -1.9730696643 | | 2018-06-24T12:08:00Z | -1.1199236554 | | 2018-06-24T12:09:00Z | 2.8043757212 | | 2018-06-24T12:10:00Z | 2.8478694533 | | 2018-06-24T12:11:00Z | 2.1893985296 | | 2018-06-24T12:12:00Z | -2.7959592806 | | time | atan2_a | atan2_b | | --- | --- | --- | | time | atan2_a | atan2_b | | 2018-06-24T12:00:00Z | 0.7853981634 | -0.1216016371 | | 2018-06-24T12:01:00Z | -2.3561944902 | 2.9665795168 | | 2018-06-24T12:02:00Z | -2.3561944902 | -2.6586575715 | | 2018-06-24T12:03:00Z | -2.3561944902 | -3.0996498311 | | 2018-06-24T12:04:00Z | -2.3561944902 | 2.0419238672 | | 2018-06-24T12:05:00Z | -2.3561944902 | 2.4478418246 | | 2018-06-24T12:06:00Z | 0.7853981634 | 0.2533389921 | | 2018-06-24T12:07:00Z | -2.3561944902 | -2.7393193161 | | 2018-06-24T12:08:00Z | -2.3561944902 | 2.6907199822 | | 2018-06-24T12:09:00Z | 0.7853981634 | -1.2335793944 | | 2018-06-24T12:10:00Z | 0.7853981634 | -1.2770731265 | | 2018-06-24T12:11:00Z | 0.7853981634 | -0.6186022028 | | 2018-06-24T12:12:00Z | -2.3561944902 | -1.9164296997 | | time | atan2 | | --- | --- | | time | atan2 | | 2018-06-24T23:58:00Z | 0.0166179004 | | 2018-06-24T23:57:00Z | -2.3211306482 | | 2018-06-24T23:56:00Z | 1.8506549463 | | 2018-06-24T23:55:00Z | -0.0768444917 | | time | atan2 | | --- | --- | | time | atan2 | | 2018-06-24T12:00:00Z | -0.8233039154 | | 2018-06-24T14:00:00Z | 1.6676707651 | | 2018-06-24T16:00:00Z | 2.3853882606 | | 2018-06-24T18:00:00Z | -1.0180694195 | | 2018-06-24T20:00:00Z | -0.2601965301 | | 2018-06-24T22:00:00Z | 2.1893237434 | | 2018-06-25T00:00:00Z | -2.5572285037 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | ceil | | --- | --- | | time | ceil | | 2019-08-17T00:00:00Z | 3.0000000000 | | 2019-08-17T00:06:00Z | 3.0000000000 | | 2019-08-17T00:12:00Z | 3.0000000000 | | 2019-08-17T00:18:00Z | 3.0000000000 | | 2019-08-17T00:24:00Z | 3.0000000000 | | 2019-08-17T00:30:00Z | 3.0000000000 | | time | ceil_water_level | | --- | --- | | time | ceil_water_level | | 2019-08-17T00:00:00Z | 3.0000000000 | | 2019-08-17T00:06:00Z | 3.0000000000 | | 2019-08-17T00:12:00Z | 3.0000000000 | | 2019-08-17T00:18:00Z | 3.0000000000 | | 2019-08-17T00:24:00Z | 3.0000000000 | | 2019-08-17T00:30:00Z | 3.0000000000 | | time | ceil | | --- | --- | | time | ceil | | 2019-08-17T00:18:00Z | 3.0000000000 | | 2019-08-17T00:12:00Z | 3.0000000000 | | 2019-08-17T00:06:00Z | 3.0000000000 | | 2019-08-17T00:00:00Z | 3.0000000000 | | time | ceil | | --- | --- | | time | ceil | | 2019-08-17T00:00:00Z | 3.0000000000 | | 2019-08-17T00:12:00Z | 3.0000000000 | | 2019-08-17T00:24:00Z | 3.0000000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | cos | | --- | --- | | time | cos | | 2019-08-18T00:00:00Z | -0.7041346171 | | 2019-08-18T00:06:00Z | -0.7230474420 | | 2019-08-18T00:12:00Z | -0.6977155876 | | 2019-08-18T00:18:00Z | -0.6876182920 | | 2019-08-18T00:24:00Z | -0.6390047316 | | 2019-08-18T00:30:00Z | -0.6413094611 | | time | cos_water_level | | --- | --- | | time | cos_water_level | | 2019-08-18T00:00:00Z | -0.7041346171 | | 2019-08-18T00:06:00Z | -0.7230474420 | | 2019-08-18T00:12:00Z | -0.6977155876 | | 2019-08-18T00:18:00Z | -0.6876182920 | | 2019-08-18T00:24:00Z | -0.6390047316 | | 2019-08-18T00:30:00Z | -0.6413094611 | | time | cos | | --- | --- | | time | cos | | 2019-08-18T00:18:00Z | -0.6876182920 | | 2019-08-18T00:12:00Z | -0.6977155876 | | 2019-08-18T00:06:00Z | -0.7230474420 | | 2019-08-18T00:00:00Z | -0.7041346171 | | time | cos | | --- | --- | | time | cos | | 2019-08-18T00:00:00Z | -0.7136560605 | | 2019-08-18T00:12:00Z | -0.6926839105 | | 2019-08-18T00:24:00Z | -0.6401578165 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | cumulative_sum | | --- | --- | | time | cumulative_sum | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 4.7310000000 | | 2019-08-18T00:12:00Z | 7.0740000000 | | 2019-08-18T00:18:00Z | 9.4030000000 | | 2019-08-18T00:24:00Z | 11.6670000000 | | 2019-08-18T00:30:00Z | 13.9340000000 | | time | cumulative_sum_water_level | | --- | --- | | time | cumulative_sum_water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 4.7310000000 | | 2019-08-18T00:12:00Z | 7.0740000000 | | 2019-08-18T00:18:00Z | 9.4030000000 | | 2019-08-18T00:24:00Z | 11.6670000000 | | 2019-08-18T00:30:00Z | 13.9340000000 | | time | cumulative_sum_water_level | | --- | --- | | time | cumulative_sum_water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 4.7310000000 | | 2019-08-18T00:12:00Z | 7.0740000000 | | 2019-08-18T00:18:00Z | 9.4030000000 | | 2019-08-18T00:24:00Z | 11.6670000000 | | 2019-08-18T00:30:00Z | 13.9340000000 | | time | cumulative_sum | | --- | --- | | time | cumulative_sum | | 2019-08-18T00:18:00Z | 6.8600000000 | | 2019-08-18T00:12:00Z | 9.2030000000 | | 2019-08-18T00:06:00Z | 11.5820000000 | | 2019-08-18T00:00:00Z | 13.9340000000 | | time | cumulative_sum | | --- | --- | | time | cumulative_sum | | 2019-08-18T00:00:00Z | 2.3655000000 | | 2019-08-18T00:12:00Z | 4.7015000000 | | 2019-08-18T00:24:00Z | 6.9670000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | derivative | | --- | --- | | time | derivative | | 2019-08-18T00:06:00Z | 0.0000750000 | | 2019-08-18T00:12:00Z | -0.0001000000 | | 2019-08-18T00:18:00Z | -0.0000388889 | | 2019-08-18T00:24:00Z | -0.0001805556 | | 2019-08-18T00:30:00Z | 0.0000083333 | | time | derivative | | --- | --- | | time | derivative | | 2019-08-18T00:06:00Z | 0.0270000000 | | 2019-08-18T00:12:00Z | -0.0360000000 | | 2019-08-18T00:18:00Z | -0.0140000000 | | 2019-08-18T00:24:00Z | -0.0650000000 | | 2019-08-18T00:30:00Z | 0.0030000000 | | time | derivative_water_level | | --- | --- | | time | derivative_water_level | | 2019-08-18T00:06:00Z | 0.0135000000 | | 2019-08-18T00:12:00Z | -0.0180000000 | | 2019-08-18T00:18:00Z | -0.0070000000 | | 2019-08-18T00:24:00Z | -0.0325000000 | | 2019-08-18T00:30:00Z | 0.0015000000 | | time | derivative_water_level | | --- | --- | | time | derivative_water_level | | 2019-08-18T00:06:00Z | 0.0090000000 | | 2019-08-18T00:12:00Z | -0.0120000000 | | 2019-08-18T00:18:00Z | -0.0046666667 | | 2019-08-18T00:24:00Z | -0.0216666667 | | 2019-08-18T00:30:00Z | 0.0010000000 | | time | derivative | | --- | --- | | time | derivative | | 2019-08-18T00:12:00Z | 0.0000388889 | | time | derivative | | --- | --- | | time | derivative | | 2019-08-18T00:00:00Z | -0.1375000000 | | 2019-08-18T00:12:00Z | -0.0295000000 | | 2019-08-18T00:24:00Z | -0.0705000000 | | time | derivative | | --- | --- | | time | derivative | | 2019-08-18T00:00:00Z | -0.0687500000 | | 2019-08-18T00:12:00Z | -0.0147500000 | | 2019-08-18T00:24:00Z | -0.0352500000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | difference | | --- | --- | | time | difference | | 2019-08-18T00:06:00Z | 0.0270000000 | | 2019-08-18T00:12:00Z | -0.0360000000 | | 2019-08-18T00:18:00Z | -0.0140000000 | | 2019-08-18T00:24:00Z | -0.0650000000 | | 2019-08-18T00:30:00Z | 0.0030000000 | | time | difference_water_level | | --- | --- | | time | difference_water_level | | 2019-08-18T00:06:00Z | 0.0270000000 | | 2019-08-18T00:12:00Z | -0.0360000000 | | 2019-08-18T00:18:00Z | -0.0140000000 | | 2019-08-18T00:24:00Z | -0.0650000000 | | 2019-08-18T00:30:00Z | 0.0030000000 | | time | difference_water_level | | --- | --- | | time | difference_water_level | | 2019-08-18T00:06:00Z | 0.0270000000 | | 2019-08-18T00:12:00Z | -0.0360000000 | | 2019-08-18T00:18:00Z | -0.0140000000 | | 2019-08-18T00:24:00Z | -0.0650000000 | | 2019-08-18T00:30:00Z | 0.0030000000 | | time | difference | | --- | --- | | time | difference | | 2019-08-18T00:12:00Z | 0.0140000000 | | 2019-08-18T00:06:00Z | 0.0360000000 | | time | difference | | --- | --- | | time | difference | | 2019-08-18T00:00:00Z | -0.2290000000 | | 2019-08-18T00:12:00Z | -0.0360000000 | | 2019-08-18T00:24:00Z | -0.0760000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2019-08-18T00:06:00Z | 360000000000.0000000000 | | 2019-08-18T00:12:00Z | 360000000000.0000000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2019-08-18T00:06:00Z | 6.0000000000 | | 2019-08-18T00:12:00Z | 6.0000000000 | | time | elapsed_level description | elapsed_water_level | | --- | --- | --- | | time | elapsed_level description | elapsed_water_level | | 2019-08-18T00:06:00Z | 6.0000000000 | 6.0000000000 | | 2019-08-18T00:12:00Z | 6.0000000000 | 6.0000000000 | | time | elapsed_level description | elapsed_water_level | | --- | --- | --- | | time | elapsed_level description | elapsed_water_level | | 2019-08-18T00:06:00Z | 360.0000000000 | 360.0000000000 | | 2019-08-18T00:12:00Z | 360.0000000000 | 360.0000000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2019-08-18T00:00:00Z | -360000.0000000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2019-08-18T00:06:00Z | 0.0000000000 | | 2019-08-18T00:12:00Z | 0.0000000000 | | time | elapsed | | --- | --- | | time | elapsed | | 2019-08-18T00:36:00Z | 12.0000000000 | | 2019-08-18T00:48:00Z | 12.0000000000 | | time | min | | --- | --- | | time | min | | 2019-08-18T00:36:00Z | 2.0930000000 | | 2019-08-18T00:48:00Z | 2.0870000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | exp | | --- | --- | | time | exp | | 2019-08-18T00:00:00Z | 10.5065618493 | | 2019-08-18T00:06:00Z | 10.7941033617 | | 2019-08-18T00:12:00Z | 10.4124270347 | | 2019-08-18T00:18:00Z | 10.2676687288 | | 2019-08-18T00:24:00Z | 9.6214982905 | | 2019-08-18T00:30:00Z | 9.6504061254 | | time | exp_water_level | | --- | --- | | time | exp_water_level | | 2019-08-18T00:00:00Z | 10.5065618493 | | 2019-08-18T00:06:00Z | 10.7941033617 | | 2019-08-18T00:12:00Z | 10.4124270347 | | 2019-08-18T00:18:00Z | 10.2676687288 | | 2019-08-18T00:24:00Z | 9.6214982905 | | 2019-08-18T00:30:00Z | 9.6504061254 | | time | exp | | --- | --- | | time | exp | | 2019-08-18T00:18:00Z | 10.2676687288 | | 2019-08-18T00:12:00Z | 10.4124270347 | | 2019-08-18T00:06:00Z | 10.7941033617 | | 2019-08-18T00:00:00Z | 10.5065618493 | | time | exp | | --- | --- | | time | exp | | 2019-08-18T00:00:00Z | 10.6493621676 | | 2019-08-18T00:12:00Z | 10.3397945558 | | 2019-08-18T00:24:00Z | 9.6359413675 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | floor | | --- | --- | | time | floor | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | 2019-08-18T00:30:00Z | 2.0000000000 | | time | floor_water_level | | --- | --- | | time | floor_water_level | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | 2019-08-18T00:30:00Z | 2.0000000000 | | time | floor | | --- | --- | | time | floor | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:00:00Z | 2.0000000000 | | time | floor | | --- | --- | | time | floor | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | ln | | --- | --- | | time | ln | | 2019-08-18T00:00:00Z | 0.8552660300 | | 2019-08-18T00:06:00Z | 0.8666802313 | | 2019-08-18T00:12:00Z | 0.8514321595 | | 2019-08-18T00:18:00Z | 0.8454389909 | | 2019-08-18T00:24:00Z | 0.8171331603 | | 2019-08-18T00:30:00Z | 0.8184573715 | | time | ln_water_level | | --- | --- | | time | ln_water_level | | 2019-08-18T00:00:00Z | 0.8552660300 | | 2019-08-18T00:06:00Z | 0.8666802313 | | 2019-08-18T00:12:00Z | 0.8514321595 | | 2019-08-18T00:18:00Z | 0.8454389909 | | 2019-08-18T00:24:00Z | 0.8171331603 | | 2019-08-18T00:30:00Z | 0.8184573715 | | time | ln | | --- | --- | | time | ln | | 2019-08-18T00:18:00Z | 0.8454389909 | | 2019-08-18T00:12:00Z | 0.8514321595 | | 2019-08-18T00:06:00Z | 0.8666802313 | | 2019-08-18T00:00:00Z | 0.8552660300 | | time | ln | | --- | --- | | time | ln | | 2019-08-18T00:00:00Z | 0.8609894161 | | 2019-08-18T00:12:00Z | 0.8484400650 | | 2019-08-18T00:24:00Z | 0.8177954851 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | log | | --- | --- | | time | log | | 2019-08-18T00:00:00Z | 0.6169440301 | | 2019-08-18T00:06:00Z | 0.6251776359 | | 2019-08-18T00:12:00Z | 0.6141784771 | | 2019-08-18T00:18:00Z | 0.6098553198 | | 2019-08-18T00:24:00Z | 0.5894369791 | | 2019-08-18T00:30:00Z | 0.5903921955 | | time | log_water_level | | --- | --- | | time | log_water_level | | 2019-08-18T00:00:00Z | 0.6169440301 | | 2019-08-18T00:06:00Z | 0.6251776359 | | 2019-08-18T00:12:00Z | 0.6141784771 | | 2019-08-18T00:18:00Z | 0.6098553198 | | 2019-08-18T00:24:00Z | 0.5894369791 | | 2019-08-18T00:30:00Z | 0.5903921955 | | time | log | | --- | --- | | time | log | | 2019-08-18T00:18:00Z | 0.6098553198 | | 2019-08-18T00:12:00Z | 0.6141784771 | | 2019-08-18T00:06:00Z | 0.6251776359 | | 2019-08-18T00:00:00Z | 0.6169440301 | | time | log | | --- | --- | | time | log | | 2019-08-18T00:00:00Z | 0.6210725804 | | 2019-08-18T00:12:00Z | 0.6120201371 | | 2019-08-18T00:24:00Z | 0.5899147454 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | log2 | | --- | --- | | time | log2 | | 2019-08-18T00:00:00Z | 1.2338880602 | | 2019-08-18T00:06:00Z | 1.2503552718 | | 2019-08-18T00:12:00Z | 1.2283569542 | | 2019-08-18T00:18:00Z | 1.2197106395 | | 2019-08-18T00:24:00Z | 1.1788739582 | | 2019-08-18T00:30:00Z | 1.1807843911 | | time | log2_water_level | | --- | --- | | time | log2_water_level | | 2019-08-18T00:00:00Z | 1.2338880602 | | 2019-08-18T00:06:00Z | 1.2503552718 | | 2019-08-18T00:12:00Z | 1.2283569542 | | 2019-08-18T00:18:00Z | 1.2197106395 | | 2019-08-18T00:24:00Z | 1.1788739582 | | 2019-08-18T00:30:00Z | 1.1807843911 | | time | log2 | | --- | --- | | time | log2 | | 2019-08-18T00:18:00Z | 1.2197106395 | | 2019-08-18T00:12:00Z | 1.2283569542 | | 2019-08-18T00:06:00Z | 1.2503552718 | | 2019-08-18T00:00:00Z | 1.2338880602 | | time | log2 | | --- | --- | | time | log2 | | 2019-08-18T00:00:00Z | 1.2421451608 | | 2019-08-18T00:12:00Z | 1.2240402742 | | 2019-08-18T00:24:00Z | 1.1798294909 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | log10 | | --- | --- | | time | log10 | | 2019-08-18T00:00:00Z | 0.3714373174 | | 2019-08-18T00:06:00Z | 0.3763944420 | | 2019-08-18T00:12:00Z | 0.3697722886 | | 2019-08-18T00:18:00Z | 0.3671694885 | | 2019-08-18T00:24:00Z | 0.3548764225 | | 2019-08-18T00:30:00Z | 0.3554515201 | | time | log10_water_level | | --- | --- | | time | log10_water_level | | 2019-08-18T00:00:00Z | 0.3714373174 | | 2019-08-18T00:06:00Z | 0.3763944420 | | 2019-08-18T00:12:00Z | 0.3697722886 | | 2019-08-18T00:18:00Z | 0.3671694885 | | 2019-08-18T00:24:00Z | 0.3548764225 | | 2019-08-18T00:30:00Z | 0.3554515201 | | time | log10 | | --- | --- | | time | log10 | | 2019-08-18T00:18:00Z | 0.3671694885 | | 2019-08-18T00:12:00Z | 0.3697722886 | | 2019-08-18T00:06:00Z | 0.3763944420 | | 2019-08-18T00:00:00Z | 0.3714373174 | | time | log10 | | --- | --- | | time | log10 | | 2019-08-18T00:00:00Z | 0.3739229524 | | 2019-08-18T00:12:00Z | 0.3684728384 | | 2019-08-18T00:24:00Z | 0.3551640665 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | moving_average | | --- | --- | | time | moving_average | | 2019-08-18T00:06:00Z | 2.3655000000 | | 2019-08-18T00:12:00Z | 2.3610000000 | | 2019-08-18T00:18:00Z | 2.3360000000 | | 2019-08-18T00:24:00Z | 2.2965000000 | | 2019-08-18T00:30:00Z | 2.2655000000 | | time | moving_average_water_level | | --- | --- | | time | moving_average_water_level | | 2019-08-18T00:12:00Z | 2.3580000000 | | 2019-08-18T00:18:00Z | 2.3503333333 | | 2019-08-18T00:24:00Z | 2.3120000000 | | 2019-08-18T00:30:00Z | 2.2866666667 | | time | moving_average_water_level | | --- | --- | | time | moving_average_water_level | | 2019-08-18T00:18:00Z | 2.3507500000 | | 2019-08-18T00:24:00Z | 2.3287500000 | | 2019-08-18T00:30:00Z | 2.3007500000 | | time | moving_average | | --- | --- | | time | moving_average | | 2019-08-18T00:06:00Z | 2.3610000000 | | 2019-08-18T00:00:00Z | 2.3655000000 | | time | moving_average | | --- | --- | | time | moving_average | | 2019-08-18T00:00:00Z | 2.4935000000 | | 2019-08-18T00:12:00Z | 2.3610000000 | | 2019-08-18T00:24:00Z | 2.3050000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | pow | | --- | --- | | time | pow | | 2019-08-18T00:00:00Z | 30.6019618652 | | 2019-08-18T00:06:00Z | 32.0315362489 | | 2019-08-18T00:12:00Z | 30.1362461432 | | 2019-08-18T00:18:00Z | 29.4223904261 | | 2019-08-18T00:24:00Z | 26.2727594844 | | 2019-08-18T00:30:00Z | 26.4122914255 | | time | pow_water_level | | --- | --- | | time | pow_water_level | | 2019-08-18T00:00:00Z | 30.6019618652 | | 2019-08-18T00:06:00Z | 32.0315362489 | | 2019-08-18T00:12:00Z | 30.1362461432 | | 2019-08-18T00:18:00Z | 29.4223904261 | | 2019-08-18T00:24:00Z | 26.2727594844 | | 2019-08-18T00:30:00Z | 26.4122914255 | | time | pow | | --- | --- | | time | pow | | 2019-08-18T00:18:00Z | 29.4223904261 | | 2019-08-18T00:12:00Z | 30.1362461432 | | 2019-08-18T00:06:00Z | 32.0315362489 | | 2019-08-18T00:00:00Z | 30.6019618652 | | time | pow | | --- | --- | | time | pow | | 2019-08-18T00:00:00Z | 31.3106302459 | | 2019-08-18T00:12:00Z | 29.7777139548 | | 2019-08-18T00:24:00Z | 26.3424561663 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | round | | --- | --- | | time | round | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | 2019-08-18T00:30:00Z | 2.0000000000 | | time | round_water_level | | --- | --- | | time | round_water_level | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | 2019-08-18T00:30:00Z | 2.0000000000 | | time | round | | --- | --- | | time | round | | 2019-08-18T00:18:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:06:00Z | 2.0000000000 | | 2019-08-18T00:00:00Z | 2.0000000000 | | time | round | | --- | --- | | time | round | | 2019-08-18T00:00:00Z | 2.0000000000 | | 2019-08-18T00:12:00Z | 2.0000000000 | | 2019-08-18T00:24:00Z | 2.0000000000 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | sin | | --- | --- | | time | sin | | 2019-08-18T00:00:00Z | 0.7100665046 | | 2019-08-18T00:06:00Z | 0.6907983763 | | 2019-08-18T00:12:00Z | 0.7163748731 | | 2019-08-18T00:18:00Z | 0.7260723687 | | 2019-08-18T00:24:00Z | 0.7692028035 | | 2019-08-18T00:30:00Z | 0.7672823308 | | time | sin_water_level | | --- | --- | | time | sin_water_level | | 2019-08-18T00:00:00Z | 0.7100665046 | | 2019-08-18T00:06:00Z | 0.6907983763 | | 2019-08-18T00:12:00Z | 0.7163748731 | | 2019-08-18T00:18:00Z | 0.7260723687 | | 2019-08-18T00:24:00Z | 0.7692028035 | | 2019-08-18T00:30:00Z | 0.7672823308 | | time | sin | | --- | --- | | time | sin | | 2019-08-18T00:18:00Z | 0.7260723687 | | 2019-08-18T00:12:00Z | 0.7163748731 | | 2019-08-18T00:06:00Z | 0.6907983763 | | 2019-08-18T00:00:00Z | 0.7100665046 | | time | sin | | --- | --- | | time | sin | | 2019-08-18T00:00:00Z | 0.7004962722 | | 2019-08-18T00:12:00Z | 0.7212412912 | | 2019-08-18T00:24:00Z | 0.7682434314 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | sqrt | | --- | --- | | time | sqrt | | 2019-08-18T00:00:00Z | 1.5336231610 | | 2019-08-18T00:06:00Z | 1.5424007261 | | 2019-08-18T00:12:00Z | 1.5306861207 | | 2019-08-18T00:18:00Z | 1.5261061562 | | 2019-08-18T00:24:00Z | 1.5046594299 | | 2019-08-18T00:30:00Z | 1.5056560032 | | time | sqrt_water_level | | --- | --- | | time | sqrt_water_level | | 2019-08-18T00:00:00Z | 1.5336231610 | | 2019-08-18T00:06:00Z | 1.5424007261 | | 2019-08-18T00:12:00Z | 1.5306861207 | | 2019-08-18T00:18:00Z | 1.5261061562 | | 2019-08-18T00:24:00Z | 1.5046594299 | | 2019-08-18T00:30:00Z | 1.5056560032 | | time | sqrt | | --- | --- | | time | sqrt | | 2019-08-18T00:18:00Z | 1.5261061562 | | 2019-08-18T00:12:00Z | 1.5306861207 | | 2019-08-18T00:06:00Z | 1.5424007261 | | 2019-08-18T00:00:00Z | 1.5336231610 | | time | sqrt | | --- | --- | | time | sqrt | | 2019-08-18T00:00:00Z | 1.5380182054 | | 2019-08-18T00:12:00Z | 1.5283978540 | | 2019-08-18T00:24:00Z | 1.5051577990 | | time | water_level | | --- | --- | | time | water_level | | 2019-08-18T00:00:00Z | 2.3520000000 | | 2019-08-18T00:06:00Z | 2.3790000000 | | 2019-08-18T00:12:00Z | 2.3430000000 | | 2019-08-18T00:18:00Z | 2.3290000000 | | 2019-08-18T00:24:00Z | 2.2640000000 | | 2019-08-18T00:30:00Z | 2.2670000000 | | time | tan | | --- | --- | | time | tan | | 2019-08-18T00:00:00Z | -1.0084243657 | | 2019-08-18T00:06:00Z | -0.9553984098 | | 2019-08-18T00:12:00Z | -1.0267433979 | | 2019-08-18T00:18:00Z | -1.0559235802 | | 2019-08-18T00:24:00Z | -1.2037513424 | | 2019-08-18T00:30:00Z | -1.1964307053 | | time | tan_water_level | | --- | --- | | time | tan_water_level | | 2019-08-18T00:00:00Z | -1.0084243657 | | 2019-08-18T00:06:00Z | -0.9553984098 | | 2019-08-18T00:12:00Z | -1.0267433979 | | 2019-08-18T00:18:00Z | -1.0559235802 | | 2019-08-18T00:24:00Z | -1.2037513424 | | 2019-08-18T00:30:00Z | -1.1964307053 | | time | tan | | --- | --- | | time | tan | | 2019-08-18T00:18:00Z | -1.0559235802 | | 2019-08-18T00:12:00Z | -1.0267433979 | | 2019-08-18T00:06:00Z | -0.9553984098 | | 2019-08-18T00:00:00Z | -1.0084243657 | | time | tan | | --- | --- | | time | tan | | 2019-08-18T00:00:00Z | -0.9815600413 | | 2019-08-18T00:12:00Z | -1.0412271461 | | 2019-08-18T00:24:00Z | -1.2000844348 | --- # Manage your data using InfluxQL Source: https://docs.influxdata.com/influxdb/v2/query-data/influxql/manage-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the following data management commands to write and delete data with InfluxQL: * [Write data with INSERT](#write-data-with-insert) * [Delete series with DELETE](#delete-series-with-delete) * [Delete measurements with DROP MEASUREMENT](#delete-measurements-with-drop-measurement) ## Write data with INSERT The `INSERT` statement writes [line protocol](/influxdb/v2/reference/syntax/line-protocol/)to a database and retention policy. ### Syntax ```sql INSERT [INTO [.]] ``` * The `INTO` clause is optional. If the command does not include `INTO`, you must specify the database with `USE ` when using the [InfluxQL shell](/influxdb/v2/tools/influxql-shell/)or with the `db` query string parameter in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) request. ### Examples * [Insert data into the a specific database and retention policy](#insert-data-into-the-a-specific-database-and-retention-policy) * [Insert data into the a the default retention policy of a database](#insert-data-into-the-a-the-default-retention-policy-of-a-database) * [Insert data into the currently used database](#insert-data-into-the-currently-used-database) #### Insert data into the a specific database and retention policy ```sql INSERT INTO mydb.myrp example-m,tag1=value1 field1=1i 1640995200000000000 ``` #### Insert data into the a the default retention policy of a database ```sql INSERT INTO mydb example-m,tag1=value1 field1=1i 1640995200000000000 ``` #### Insert data into the currently used database The following example uses the [InfluxQL shell](/influxdb/v2/tools/influxql-shell). ```sql USE mydb INSERT example-m,tag1=value1 field1=1i 1640995200000000000 ``` ## Delete series with DELETE The `DELETE` statement deletes all points from a [series](/influxdb/v2/reference/glossary/#series) in a database. ### Syntax ```sql DELETE FROM WHERE [=''] | [

InfluxDB storage engine

An overview of the InfluxDB storage engine architecture.

InfluxDB file system layout

The InfluxDB file system layout depends on the operating system, package manager, or containerization platform used to install InfluxDB.

Data retention in InfluxDB

The InfluxDB retention service checks for and removes data with timestamps beyond the defined retention period of the bucket the data is stored in.

InfluxDB runtime

Learn how to collect Go runtime profiling and tracing information to help with InfluxDB performance analysis and debugging.

``` ### [Sample data](/influxdb/v2/reference/sample-data/) Use sample data to familiarize yourself with time series data and InfluxDB. InfluxData provides many sample time series datasets to use with InfluxDB and InfluxDB Cloud. ### [Prometheus metric parsing formats](/influxdb/v2/reference/prometheus-metrics/) When scraping [Prometheus-formatted metrics](https://prometheus.io/docs/concepts/data_model/) and writing them to InfluxDB, metrics are parsed and stored in InfluxDB in different formats. ### [Usage telemetry](/influxdb/v2/reference/telemetry/) InfluxData collects information, or *telemetry data*, about the usage of InfluxDB to help improve the product. Learn what data InfluxDB collects and sends to InfluxData, how it’s used, and how you can opt out. ### [Frequently asked questions](/influxdb/v2/reference/faq/) Find answers to common questions related to InfluxDB OSS. ### [Glossary](/influxdb/v2/reference/glossary/) Terms related to InfluxData products and platforms. ### [Contribute to InfluxDB OSS](/influxdb/v2/reference/contributing/) Find important information about what’s included in new versions of InfluxData products. --- # Command line tools Source: https://docs.influxdata.com/influxdb/v2/reference/cli/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB provides command line tools designed to aid in managing and working with InfluxDB from the command line. The following command line interfaces (CLIs) are available: ### [influx - InfluxDB command line interface](/influxdb/v2/reference/cli/influx/) The `influx` CLI includes commands to manage many aspects of InfluxDB, including buckets, organizations, users, tasks, etc. ### [influxd - InfluxDB service](/influxdb/v2/reference/cli/influxd/) The `influxd` service starts and runs all the processes necessary for InfluxDB to function. [cli](/influxdb/v2/tags/cli/) --- # influx - InfluxDB command line interface Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx` command line interface (CLI) includes commands to manage many aspects of InfluxDB, including buckets, organizations, users, tasks, etc. > [!Note] > #### InfluxDB OSS v2 and influx CLI versions > > Beginning with **InfluxDB 2.1**, the `influx` CLI is packaged and versioned separately > from InfluxDB. > InfluxDB and `influx` CLI versions may differ, but compatibility is noted for each command. * [Download and install the influx CLI](#download-and-install-the-influx-cli) * [Use Homebrew](#use-homebrew) * [Manually download and install](#manually-download-and-install) * [Download from your browser](#download-from-your-browser) * [Download from the command line](#download-from-the-command-line) * [Provide required authentication credentials](#provide-required-authentication-credentials) * [Credential precedence](#credential-precedence) * [Usage](#usage) * [Commands](#commands) * [Flags](#flags) * [Flag patterns and conventions](#flag-patterns-and-conventions) * [Mapped environment variables](#mapped-environment-variables) * [Shorthand and longhand flags](#shorthand-and-longhand-flags) * [Flag input types](#flag-input-types) * [string](#string) * [stringArray](#stringarray) * [integer](#integer) * [duration](#duration) ## Download and install the influx CLI [macOS](#macos)[Linux](#linux)[Windows](#windows) Do one of the following: * [Use Homebrew](#use-homebrew) * [Manually download and install](#manually-download-and-install) ### Use Homebrew ```sh brew install influxdb-cli ``` > [!Note] > If you used Homebrew to install **InfluxDB 2.10**, the `influxdb-cli`formula was downloaded as a dependency and should already be installed. > If installed, `influxdb-cli` will appear in the output of the following command: > > ``` > brew list | grep influxdb-cli > ``` ### Manually download and install 1. **Download the `influx` CLI package.** [influx CLI v2.9.1 (macOS)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-darwin-amd64.tar.gz) 2. **Unpackage the downloaded package.** Do one of the following: * Double-click the downloaded package file in **Finder**. * Run the following command in a macOS command prompt application such**Terminal** or **[iTerm2](https://www.iterm2.com/)**: ``` # Unpackage contents to the current working directory tar zxvf ~/Downloads/influxdb2-client-2.9.1-darwin-amd64.tar.gz ``` 3. **(Optional) Place the binary in your `$PATH`.** ``` # (Optional) Copy the influx binary to your $PATH sudo cp ~/Downloads/influxdb2-client-2.9.1-darwin-amd64/influx /usr/local/bin/ ``` If you do not move the `influx` binary into your `$PATH`, prefix the executable`./` to run it in place. 4. **(macOS Catalina and newer) Authorize the `influx` binary.** macOS requires downloaded binaries to be signed by registered Apple developers. When you first attempt to run `influx`, macOS will prevent it from running. To authorize the `influx` binary: 1. Attempt to run an `influx` command. 2. Open **System Preferences** and click **Security & Privacy**. 3. Under the **General** tab, there is a message about `influx` being blocked. Click **Open Anyway**. 1. **Download the influx CLI package.** Download the `influx` CLI package [from your browser](#download-from-your-browser)or [from the command line](#download-from-the-command-line). #### Download from your browser #### [influx CLI v2.9.1 (amd64)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-amd64.tar.gz)[influx CLI v2.9.1 (arm)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-arm64.tar.gz) #### Download from the command line #### ``` # amd64 curl -O \ https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-amd64.tar.gz ``` ``` # arm curl -O \ https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-arm64.tar.gz \ ``` 2. **Unpackage the downloaded package.** ***Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary.* ``` # amd64 tar xvzf influxdb2-client-2.9.1-linux-amd64.tar.gz ``` ``` # arm tar xvzf influxdb2-client-2.9.1-linux-arm64.tar.gz ``` 3. **(Optional) Place the unpackaged `influx` executable in your system `$PATH`.** ``` sudo cp ./influx /usr/local/bin/ ``` If you do not move the `influx` binary into your `$PATH`, prefix the executable`./` to run it in place. > [!Note] > #### Use Powershell for Windows > > Use Powershell for running `influx` CLI commands. > Command Prompt is not fully compatible. 1. **Download the `influx` CLI package.** [influx CLI v2.9.1 (Windows)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-windows-amd64.zip) 2. **Expand the downloaded archive.** Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired. ``` > Expand-Archive .\influxdb2-client-2.9.1-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\' > mv 'C:\Program Files\InfluxData\influxdb2-client-2.9.1-windows-amd64' 'C:\Program Files\InfluxData\influx' ``` 3. **Grant network access to the `influx` CLI.** When using the `influx` CLI for the first time, **Windows Defender** displays the following message: > > > Windows Defender Firewall has blocked some features of this app. > > To grant the `influx` CLI the required access, do the following: 1. Select **Private networks, such as my home or work network**. 2. Click **Allow access**. ## Provide required authentication credentials To avoid having to pass your InfluxDB **host**, **API token**, and **organization**with each command, store them in an `influx` CLI configuration (config).`influx` commands that require these credentials automatically retrieve these credentials from the active config. Use the [`influx config create` command](/influxdb/v2/reference/cli/influx/config/create/)to create an `influx` CLI config and set it as active: ```sh influx config create --config-name CONFIG_NAME \ --host-url http://localhost:8086 \ --org ORG_NAME \ --token API_TOKEN \ --active ``` For more information about managing CLI configurations, see the[`influx config` documentation](/influxdb/v2/reference/cli/influx/config/). ### Credential precedence Provide credentials using any of the following supported methods. The `influx` CLI uses the following precedence when retrieving credentials: 1. Command line flags (`--host`, `--org -o`, `--token -t`) 2. Environment variables (`INFLUX_HOST`, `INFLUX_ORG`, `INFLUX_TOKEN`) 3. CLI configuration file Command line flags override environment variables, which override configuration file values. ## Usage ``` influx [flags] influx [command] ``` ## Commands | Command | Description | |-----------------------------------------------------------------|--------------------------------------------------------------------------| | [apply](/influxdb/v2/reference/cli/influx/apply/) | Apply an InfluxDB template | | [auth](/influxdb/v2/reference/cli/influx/auth/) | API token management commands | | [backup](/influxdb/v2/reference/cli/influx/backup/) | Back up data *(InfluxDB OSS only)* | | [bucket](/influxdb/v2/reference/cli/influx/bucket/) | Bucket management commands | |[bucket-schema](/influxdb/v2/reference/cli/influx/bucket-schema/)| Manage InfluxDB bucket schemas *(InfluxDB Cloud only)* | | [completion](/influxdb/v2/reference/cli/influx/completion/) | Generate completion scripts | | [config](/influxdb/v2/reference/cli/influx/config/) | Configuration management commands | | [dashboards](/influxdb/v2/reference/cli/influx/dashboards/) | List dashboards | | [delete](/influxdb/v2/reference/cli/influx/delete/) | Delete points from InfluxDB | | [export](/influxdb/v2/reference/cli/influx/export/) | Export resources as a template | | [help](/influxdb/v2/reference/cli/influx/help/) | Help about any command | | [org](/influxdb/v2/reference/cli/influx/org/) | Organization management commands | | [ping](/influxdb/v2/reference/cli/influx/ping/) | Check the InfluxDB `/health` endpoint | | [query](/influxdb/v2/reference/cli/influx/query/) | Execute a Flux query | | [restore](/influxdb/v2/reference/cli/influx/restore/) | Restore backup data *(InfluxDB OSS only)* | | [scripts](/influxdb/v2/reference/cli/influx/scripts) | Scripts management commands *(InfluxDB Cloud only)* | | [secret](/influxdb/v2/reference/cli/influx/secret/) | Manage secrets | | [setup](/influxdb/v2/reference/cli/influx/setup/) |Create default username, password, org, bucket, etc. *(InfluxDB OSS only)*| | [stacks](/influxdb/v2/reference/cli/influx/stacks/) | Manage InfluxDB stacks | | [task](/influxdb/v2/reference/cli/influx/task/) | Task management commands | | [telegrafs](/influxdb/v2/reference/cli/influx/telegrafs/) | Telegraf configuration management commands | | [template](/influxdb/v2/reference/cli/influx/template/) | Summarize and validate an InfluxDB template | | [user](/influxdb/v2/reference/cli/influx/user/) | User management commands | | [v1](/influxdb/v2/reference/cli/influx/v1/) | Work with the v1 compatibility API | | [version](/influxdb/v2/reference/cli/influx/version/) | Print the influx CLI version | | [write](/influxdb/v2/reference/cli/influx/write/) | Write points to InfluxDB | ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `influx` command| ### Flag patterns and conventions The `influx` CLI uses the following patterns and conventions: * [Mapped environment variables](#mapped-environment-variables) * [Shorthand and longhand flags](#shorthand-and-longhand-flags) * [Flag input types](#flag-input-types) #### Mapped environment variables `influx` CLI flags mapped to environment variables are listed in the **Mapped to**column of the Flags table in each command documentation. Mapped flags inherit the value of the environment variable. To override environment variables, set the flag explicitly in your command. [](#view-mapped-environment-variables) View mapped environment variables > [!Note] > Some `influx` CLI commands may not support all mapped environment variables. > For more information about what mapped environment variables each command supports, > see the command documentation. | Environment variable | Description | |------------------------|---------------------------------------------------------------------| | `INFLUX_ACTIVE_CONFIG` | CLI configuration to use for commands | | `INFLUX_BUCKET_ID` | Bucket ID | | `INFLUX_BUCKET_NAME` | Bucket name | | `INFLUX_CONFIGS_PATH` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| | `INFLUX_HIDE_HEADERS` | Hide table headers in command output (default `false`) | | `INFLUX_HOST` | HTTP address of InfluxDB (default `http://localhost:8086`) | | `INFLUX_NAME` | InfluxDB Username | | `INFLUX_ORG` | InfluxDB Organization name | |`INFLUX_ORG_DESCRIPTION`| Organization description | | `INFLUX_ORG_ID` | InfluxDB Organization ID | | `INFLUX_OUTPUT_JSON` | Return command output JSON | | `INFLUX_SKIP_VERIFY` | Skip TLS certificate verification | | `INFLUX_TOKEN` | InfluxDB API token | #### Shorthand and longhand flags Many `influx` CLI flags support both shorthand and longhand forms. * **shorthand:** a shorthand flag begins with a single hyphen followed by a single letter (for example: `-c`). * **longhand:** a longhand flag starts with two hyphens followed by a multi-letter, hyphen-spaced flag name (for example: `--active-config`). Commands can use both shorthand and longhand flags in a single execution. #### Flag input types `influx` CLI flag input types are listed in each the table of flags for each command. Flags support the following input types: ##### string Text string, but the flag can be used **only once** per command execution. ##### stringArray Single text string, but the flag can be used **multiple times** per command execution. ##### integer Sequence of digits representing an integer value. ##### duration Length of time represented by an integer and a duration unit (`1ns`, `1us`, `1µs`, `1ms`, `1s`, `1m`, `1h`, `1d`, `1w`). #### Related * [Install and use the influx CLI](/influxdb/v2/tools/influx-cli/) [cli](/influxdb/v2/tags/cli/) | Command | Description | | --- | --- | | Command | Description | | apply | Apply an InfluxDB template | | auth | API token management commands | | backup | Back up data (InfluxDB OSS only) | | bucket | Bucket management commands | | bucket-schema | Manage InfluxDB bucket schemas (InfluxDB Cloud only) | | completion | Generate completion scripts | | config | Configuration management commands | | dashboards | List dashboards | | delete | Delete points from InfluxDB | | export | Export resources as a template | | help | Help about any command | | org | Organization management commands | | ping | Check the InfluxDB /health endpoint | | query | Execute a Flux query | | restore | Restore backup data (InfluxDB OSS only) | | scripts | Scripts management commands (InfluxDB Cloud only) | | secret | Manage secrets | | setup | Create default username, password, org, bucket, etc. (InfluxDB OSS only) | | stacks | Manage InfluxDB stacks | | task | Task management commands | | telegrafs | Telegraf configuration management commands | | template | Summarize and validate an InfluxDB template | | user | User management commands | | v1 | Work with the v1 compatibility API | | version | Print the influx CLI version | | write | Write points to InfluxDB | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the influx command | | Environment variable | Description | | --- | --- | | Environment variable | Description | | INFLUX_ACTIVE_CONFIG | CLI configuration to use for commands | | INFLUX_BUCKET_ID | Bucket ID | | INFLUX_BUCKET_NAME | Bucket name | | INFLUX_CONFIGS_PATH | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | | INFLUX_HIDE_HEADERS | Hide table headers in command output (default false ) | | INFLUX_HOST | HTTP address of InfluxDB (default http://localhost:8086 ) | | INFLUX_NAME | InfluxDB Username | | INFLUX_ORG | InfluxDB Organization name | | INFLUX_ORG_DESCRIPTION | Organization description | | INFLUX_ORG_ID | InfluxDB Organization ID | | INFLUX_OUTPUT_JSON | Return command output JSON | | INFLUX_SKIP_VERIFY | Skip TLS certificate verification | | INFLUX_TOKEN | InfluxDB API token | --- # influx apply Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/apply/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx apply` command applies InfluxDB templates.*For information about finding and using InfluxDB templates, see[Use InfluxDB templates](/influxdb/v2/tools/influxdb-templates/use/).* ## Usage ``` influx apply [flags] ``` ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------------|-------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--disable-color` | Disable color in output | | | | |`--disable-table-borders`| Disable table borders | | | |`-e`| `--encoding` | Encoding of the input stream | string | | | | `--env-ref` |Environment references to provide with the template (format: `--env-ref=REF_KEY=REF_VALUE`)| string | | |`-f`| `--file` | Path to template file (supports HTTP(S) URLs or file paths) | string | | | | `--filter` | Resources to skip when applying the template (filter by `kind` or `resource`) | string | | | | `--force` | Ignore warnings about destructive changes | | | |`-h`| `--help` | Help for the `apply` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name that owns the bucket (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID that owns the bucket (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-q`| `--quiet` | Disable output printing | | | |`-R`| `--recurse` | Recurse through files in the directory specified in `-f`, `--file` | | | | | `--secret` | Secrets to provide with the template (format: `--secret=SECRET_KEY=SECRET_VALUE`) | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--stack-id` | Stack ID to associate when applying the template | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples: how to apply a template or stack > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [from a file](#apply-a-template-from-a-file) * [from a URL](#apply-a-template-from-a-url) * [from a stack that has associated templates](#apply-a-stack-that-has-associated-templates) * [a template to a stack](#apply-a-template-to-a-stack) * [multiple template files together](#apply-multiple-template-files-together) * [a template from stdin](#apply-a-template-from-stdin) * [all templates in a directory](#apply-all-templates-in-a-directory) * [recursively from a directory](#recursively-apply-templates-from-a-directory) * [from multiple sources](#apply-templates-from-multiple-sources) * [skip resources](#apply-a-template-but-skip-resources) ##### Apply a template from a file ```sh influx apply --file path/to/template.json ``` ##### Apply a template from a URL ```sh influx apply --file https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml ``` ##### Apply a stack that has associated templates To apply all templates associated with a stack ID to a new stack: ```sh influx apply --stack-id $STACK_ID ``` ##### Apply a template to a stack ```sh influx apply --file path/to/template.json --stack-id $STACK_ID ``` ##### Apply multiple template files together ```sh influx apply \ --file path/to/template_1.json \ --file path/to/template_2.yml ``` ##### Apply a template from stdin ```sh cat template.json | influx apply --encoding json ``` ##### Apply all templates in a directory ```sh influx apply --file path/to/template_directory ``` ##### Recursively apply templates from a directory ```sh influx apply --recurse --file path/to/template_directory ``` ##### Apply templates from multiple sources ```sh influx apply \ --file path/to/template.yml --file path/to/templates_directory --file https://example.com/template.json ``` ##### Apply a template, but skip resources ```sh # The following example skips all buckets and the dashboard # whose metadata.name field matches "example-dashboard". # Filter format: # --filter=kind=Bucket # --filter=resource=Label:$Label_TMPL_NAME influx apply \ --file path/to/template.yml \ --filter kind=Bucket \ --filter resource=Dashboard:example-dashboard ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Flag | | Description | Input Type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input Type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --disable-color | Disable color in output | | | | | --disable-table-borders | Disable table borders | | | | -e | --encoding | Encoding of the input stream | string | | | | --env-ref | Environment references to provide with the template (format: --env-ref=REF_KEY=REF_VALUE ) | string | | | -f | --file | Path to template file (supports HTTP(S) URLs or file paths) | string | | | | --filter | Resources to skip when applying the template (filter by kind or resource ) | string | | | | --force | Ignore warnings about destructive changes | | | | -h | --help | Help for the apply command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name that owns the bucket (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID that owns the bucket (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -q | --quiet | Disable output printing | | | | -R | --recurse | Recurse through files in the directory specified in -f , --file | | | | | --secret | Secrets to provide with the template (format: --secret=SECRET_KEY=SECRET_VALUE ) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --stack-id | Stack ID to associate when applying the template | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx auth Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth` command and its subcommands manage API tokens in InfluxDB. ## Usage ``` influx auth [flags] influx auth [command] ``` #### Command aliases `auth`, `authorization` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------|--------------------| | [active](/influxdb/v2/reference/cli/influx/auth/active) | Activate API token | | [create](/influxdb/v2/reference/cli/influx/auth/create) | Create API token | | [delete](/influxdb/v2/reference/cli/influx/auth/delete) | Delete API token | | [list](/influxdb/v2/reference/cli/influx/auth/list) | List API tokens | |[inactive](/influxdb/v2/reference/cli/influx/auth/inactive)|Inactivate API token| ## Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `auth` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authentication](/influxdb/v2/tags/authentication/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | active | Activate API token | | create | Create API token | | delete | Delete API token | | list | List API tokens | | inactive | Inactivate API token | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the auth command | --- # influx auth active Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/active/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth active` command activates an API token. Only active tokens authorize access to InfluxDB. ## Usage ``` influx auth active [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `active` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | |`-i`| `--id` | (Required) API token ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Activate an API token ```sh influx auth active --id 06c86c40a9f36000 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the active command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | ( Required ) API token ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx auth create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI 2.5.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth create` command creates an API token in InfluxDB. **Issue resolved**: Using influx CLI 2.4 prevented you from creating an **all-access** or **operator** token using the `influx auth create` command. This issue is resolved in the influx 2.5 CLI release. Please [upgrade to the latest version](/influxdb/v2/tools/influx-cli/) of the influx cli. ## Usage ``` influx auth create [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------------------|---------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--all-access` | Grants all permissions in a single organization | | | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | API token description | string | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--operator` | *(InfluxDB OSS only)* Grants all permissions in all organizations | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--read-bucket` | Grant permission to read a specified bucket ID |stringArray| | | | `--read-buckets` | Grant permission to read **all** organization buckets | | | | | `--read-checks` | Grant permission to read checks | | | | | `--read-dashboards` | Grant permission to read dashboards | | | | | `--read-dbrps` | Grant permission to read database retention policy mappings | | | | |`--read-notificationEndpoints` | Grant permission to read notificationEndpoints | | | | | `--read-notificationRules` | Grant permission to read notificationRules | | | | | `--read-orgs` | Grant permission to read organizations | | | | | `--read-remotes` | Grant permission to read remote configurations | | | | | `--read-replications` | Grant permission to read replication configurations | | | | | `--read-tasks` | Grant permission to read tasks | | | | | `--read-telegrafs` | Grant permission to read Telegraf configurations | | | | | `--read-users` | Grant permission to read organization users | | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-u`| `--user` | Username | string | | | | `--write-annotations` | Grant permission to create annotations | | | | | `--write-bucket` | Grant permission to write to specified a bucket ID |stringArray| | | | `--write-buckets` | Grant permission to create and update **all** organization buckets | | | | | `--write-checks` | Grant permission to create checks | | | | | `--write-dashboards` | Grant permission to create and update dashboards | | | | | `--write-dbrps` | Grant permission to create database retention policy mappings | | | | |`--write-notificationEndpoints`| Grant permission to create notificationEndpoints | | | | | `--write-notificationRules` | Grant permission to create notificationRules | | | | | `--write-orgs` | Grant permission to create and update organizations | | | | | `--write-remotes` | Grant permission to create and update remote configurations | | | | | `--write-replications` | Grant permission to create and update replication configurations | | | | | `--write-tasks` | Grant permission to create and update tasks | | | | | `--write-telegrafs` | Grant permission to create and update Telegraf configurations | | | | | `--write-users` | Grant permission to create and update organization users | | | | | `--write-variables` | Grant permission to create and update variables | | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Create an All Access API token](#create-an-all-access-api-token) or [Create an Operator API token](#create-an-operator-api-token) * [Create an API token with specified read and write permissions](#create-an-api-token-with-specified-read-and-write-permissions) * [Create a token with read and write access to specific buckets](#create-an-api-token-with-read-and-write-access-to-specific-buckets) * [Create a read-only API token](#create-a-read-only-api-token) ### Create an All Access API token Create an [All Access token](/influxdb/cloud/admin/tokens/#all-access-token) to grant permissions to all resources in an organization. ```sh influx auth create \ --all-access ``` ### Create an Operator API token Create an [Operator token](/influxdb/v2/admin/tokens/#operator-token) to grant permissions to all resources in all organizations. ```sh influx auth create \ --operator ``` ### Create an API token with specified read and write permissions ```sh influx auth create \ --read-buckets \ --read-checks \ --read-dashboards \ --read-dbrps \ --read-notificationEndpoints \ --read-notificationRules \ --read-orgs \ --read-remotes \ --read-replications \ --read-tasks \ --read-telegrafs \ --read-users \ --write-annotations \ --write-buckets \ --write-checks \ --write-dashboards \ --write-dbrps \ --write-notificationEndpoints \ --write-notificationRules \ --write-orgs \ --write-remotes \ --write-replications \ --write-tasks \ --write-telegrafs \ --write-users \ --write-variables ``` ### Create an API token with read and write access to specific buckets ```sh influx auth create \ --read-bucket 0000000000000001 \ --read-bucket 0000000000000002 \ --write-bucket 0000000000000001 \ --write-bucket 0000000000000002 ``` ### Create a read-only API token ```sh influx auth create \ --read-buckets \ --read-checks \ --read-dashboards \ --read-dbrps \ --read-notificationEndpoints \ --read-notificationRules \ --read-orgs \ --read-remotes \ --read-replications \ --read-tasks \ --read-telegrafs \ --read-users ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --all-access | Grants all permissions in a single organization | | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | API token description | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --operator | (InfluxDB OSS only) Grants all permissions in all organizations | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --read-bucket | Grant permission to read a specified bucket ID | stringArray | | | | --read-buckets | Grant permission to read all organization buckets | | | | | --read-checks | Grant permission to read checks | | | | | --read-dashboards | Grant permission to read dashboards | | | | | --read-dbrps | Grant permission to read database retention policy mappings | | | | | --read-notificationEndpoints | Grant permission to read notificationEndpoints | | | | | --read-notificationRules | Grant permission to read notificationRules | | | | | --read-orgs | Grant permission to read organizations | | | | | --read-remotes | Grant permission to read remote configurations | | | | | --read-replications | Grant permission to read replication configurations | | | | | --read-tasks | Grant permission to read tasks | | | | | --read-telegrafs | Grant permission to read Telegraf configurations | | | | | --read-users | Grant permission to read organization users | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | -u | --user | Username | string | | | | --write-annotations | Grant permission to create annotations | | | | | --write-bucket | Grant permission to write to specified a bucket ID | stringArray | | | | --write-buckets | Grant permission to create and update all organization buckets | | | | | --write-checks | Grant permission to create checks | | | | | --write-dashboards | Grant permission to create and update dashboards | | | | | --write-dbrps | Grant permission to create database retention policy mappings | | | | | --write-notificationEndpoints | Grant permission to create notificationEndpoints | | | | | --write-notificationRules | Grant permission to create notificationRules | | | | | --write-orgs | Grant permission to create and update organizations | | | | | --write-remotes | Grant permission to create and update remote configurations | | | | | --write-replications | Grant permission to create and update replication configurations | | | | | --write-tasks | Grant permission to create and update tasks | | | | | --write-telegrafs | Grant permission to create and update Telegraf configurations | | | | | --write-users | Grant permission to create and update organization users | | | | | --write-variables | Grant permission to create and update variables | | | --- # influx auth delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth delete` command deletes an API token from InfluxDB. ## Usage ``` influx auth delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) API token ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete an API token ```sh influx auth delete --id 06c86c40a9f36000 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) API token ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx auth inactive Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/inactive/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth inactive` command inactivates an API token in InfluxDB. Inactive tokens **do not** authorize access to InfluxDB. To temporarily disable client access to InfluxDB, inactivate the authentication token the client is using rather than delete the token. If you delete the token, you have to generate a new token and update the client with the new token. By setting a token to inactive, you can [activate the token](/influxdb/v2/reference/cli/influx/auth/active/)to grant the client access without having to modify the client. ## Usage ``` influx auth inactive [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `inactive` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) API token ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Inactivate an API token ```sh influx auth inactive --id 06c86c40a9f36000 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the inactive command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) API token ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx auth list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/auth/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx auth list` command lists and searches API tokens in InfluxDB. ## Usage ``` influx auth list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | API token ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-u`| `--user` | Username | string | | | | `--user-id` | User ID | string | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List all API tokens ```sh influx auth list ``` ##### List API tokens associated with a user ```sh influx auth list --user username ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | API token ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | | | | --org-id | Organization ID (mutually exclusive with --org ) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | -u | --user | Username | string | | | | --user-id | User ID | string | | --- # influx backup Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/backup/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.2 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx backup` command backs up data stored in InfluxDB to a specified directory. ## Usage ``` influx backup [flags] path ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--bucket-id` | ID of the bucket to back up from (mutually exclusive with `--bucket`) | string | | |`-b`| `--bucket` | Name of the bucket to back up from (mutually exclusive with `--bucket-id`) | string | | | | `--compression` |Compression for local backup files. Defaults to `gzip`. Set to `none` to disable. If `--gzip-compression-level=none` and `--compression` is unset, defaults to `none`.| string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | |`--gzip-compression-level`| Server-side gzip compression level for the backup download: `default`, `full` (best compression), `speedy` (fastest), or `none`. *(2.8.0+)* | string | | |`-h`| `--help` | Help for the `backup` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | string | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Back up all data to a directory](#back-up-all-data-to-a-directory) * [Back up all data to the current working directory](#back-up-all-data-to-the-current-working-directory) * [Back up a specific bucket to a directory](#back-up-a-specific-bucket-to-a-directory) * [Back up using a faster server-side compression level](#back-up-using-a-faster-server-side-compression-level) ##### Back up all data to a directory ```sh influx backup /path/to/backup/dir/ ``` ##### Back up all data to the current working directory ```sh influx backup ./ ``` ##### Back up a specific bucket to a directory ```sh influx backup --bucket example-bucket /path/to/backup/dir/ ``` ##### Back up using a faster server-side compression level *Requires InfluxDB 2.9.0+ and `influx` CLI 2.8.0+.* ```sh influx backup --gzip-compression-level speedy /path/to/backup/dir/ ``` #### Related * [Back up data](/influxdb/v2/admin/backup-restore/backup/) * [influx restore](/influxdb/v2/reference/cli/influx/restore/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [backup](/influxdb/v2/tags/backup/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --bucket-id | ID of the bucket to back up from (mutually exclusive with --bucket ) | string | | | -b | --bucket | Name of the bucket to back up from (mutually exclusive with --bucket-id ) | string | | | | --compression | Compression for local backup files. Defaults to gzip . Set to none to disable. If --gzip-compression-level=none and --compression is unset, defaults to none . | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --gzip-compression-level | Server-side gzip compression level for the backup download: default , full (best compression), speedy (fastest), or none . (2.8.0+) | string | | | -h | --help | Help for the backup command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default: http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | string | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket-schema Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket-schema/ * influx CLI 2.1.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Note] > #### Works with InfluxDB Cloud bucket schemas > > `influx bucket-schema` and its subcommands work with [InfluxDB Cloud bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema). > This feature is not available in InfluxDB OSS v2.3. The `influx bucket-schema` command and its subcommands manage schemas for InfluxDB buckets. ## Usage ``` influx bucket-schema [flags] influx bucket-schema [command] ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------------------|----------------------| |[create](/influxdb/v2/reference/cli/influx/bucket-schema/create)|Create a bucket schema| | [list](/influxdb/v2/reference/cli/influx/bucket-schema/list) | List bucket schemas | |[update](/influxdb/v2/reference/cli/influx/bucket-schema/update)|Update a bucket schema| ## Flags |Flag| | Description | |----|--------|------------------------------------| |`-h`|`--help`|Help for the `bucket-schema` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [buckets](/influxdb/v2/tags/buckets/)[bucket-schema](/influxdb/v2/tags/bucket-schema/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a bucket schema | | list | List bucket schemas | | update | Update a bucket schema | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the bucket-schema command | --- # influx bucket-schema create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket-schema/create/ * influx CLI 2.1.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Note] > #### Works with InfluxDB Cloud bucket schemas > > `influx bucket-schema` and its subcommands work with [InfluxDB Cloud bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema). > This feature is not available in InfluxDB OSS v2.3. The `influx bucket-schema create` command sets the schema for a measurement in an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). ## Usage ```sh influx bucket-schema create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | |`-n`| `--bucket` | (Required) Bucket name (mutually exclusive with `--bucket-id`) | string | | |`-i`| `--bucket-id` | (Required) Bucket ID (mutually exclusive with `--bucket`) | string | | | | `--columns-file` |(Required) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file).| string | | | |`--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Create a schema with columns format](#create-a-schema-with-columns-format) | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-x`|`--extended-output`| Print column information for each measurement schema (default: false) | | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | (Required) Measurement name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Create a schema using the influx CLI](#create-a-schema-using-the-influx-cli) * [Create a schema and print column information](#create-a-schema-and-print-column-information) * [Create a schema with columns format](#create-a-schema-with-columns-format) ### Create a schema using the influx CLI ```sh influx bucket-schema create \ --bucket example-bucket \ --name temperature \ --columns-file columns.csv ``` ### Create a schema and print column information ```sh influx bucket-schema create \ --bucket example-bucket \ --name cpu \ --columns-file columns.csv \ --extended-output ``` ### Create a schema with columns format By default, InfluxDB attempts to detect the **columns file** format. If your file’s extension doesn’t match the format, set the format with the [`columns-format` flag](/influxdb/cloud/reference/cli/influx/bucket-schema/create). ```sh influx bucket-schema create \ --bucket example-bucket \ --name cpu \ --columns-file columns.json \ --columns-format ndjson ``` ```sh influx bucket-schema create \ --bucket example-bucket \ --name cpu \ --columns-file columns.txt \ --columns-format csv ``` #### Related | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -n | --bucket | ( Required ) Bucket name (mutually exclusive with --bucket-id ) | string | | | -i | --bucket-id | ( Required ) Bucket ID (mutually exclusive with --bucket ) | string | | | | --columns-file | ( Required ) Path to column definitions file. For more information, see Create a columns file . | string | | | | --columns-format | Columns file format ( csv , ndjson , json , default: auto ). For more information, see Create a schema with columns format | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -x | --extended-output | Print column information for each measurement schema (default: false) | | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | ( Required ) Measurement name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket-schema list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket-schema/list/ * influx CLI 2.1.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Note] > #### Works with InfluxDB Cloud bucket schemas > > `influx bucket-schema` and its subcommands work with [InfluxDB Cloud bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema). > This feature is not available in InfluxDB OSS v2.3. The `influx bucket-schema list` command lists the schemas of an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). ## Usage ```sh influx bucket-schema list [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | |`-n`| `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | | |`-i`| `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-x`|`--extended-output`|Print column information for each measurement schema (default: false)| | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Measurement name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### List all schemas of a bucket and print column information ```sh influx bucket-schema list \ --bucket example-bucket --extended-output ``` ### Print column details for a single measurement ```sh influx bucket-schema list \ --bucket example-bucket \ --name cpu \ --extended-output ``` #### Related | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -n | --bucket | Bucket name (mutually exclusive with --bucket-id ) | string | | | -i | --bucket-id | Bucket ID (mutually exclusive with --bucket ) | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -x | --extended-output | Print column information for each measurement schema (default: false) | | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Measurement name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket-schema update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket-schema/update/ * influx CLI 2.1.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Note] > #### Works with InfluxDB Cloud bucket schemas > > `influx bucket-schema` and its subcommands work with [InfluxDB Cloud bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema). > This feature is not available in InfluxDB OSS v2.3. The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). `bucket-schema update` requires a bucket with at least one defined schema. ## Usage ```sh influx bucket-schema update [flags] ``` ##### Supported operations * Adding new columns to a schema ##### Unsupported operations * Modify existing columns in a schema * Delete columns from a schema ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | |`-n`| `--bucket` | (Required) Bucket name (mutually exclusive with `--bucket-id`) | string | | |`-i`| `--bucket-id` | (Required) Bucket ID (mutually exclusive with `--bucket`) | string | | | | `--columns-file` |(Required) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file).| string | | | |`--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Update a schema with columns format](#update-a-schema-with-columns-format) | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-x`|`--extended-output`| Print column information for each measurement schema (default: false) | | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | (Required) Measurement name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Update a schema using the influx CLI](#update-a-schema-using-the-influx-cli) * [Update a schema and print column information](#update-a-schema-and-print-column-information) * [Update a schema with columns format](#update-a-schema-specifying-the-columns-format) ### Update a schema using the influx CLI ```sh influx bucket-schema update \ --bucket example-bucket \ --name temperature \ --columns-file columns.csv ``` ### Update a schema and print column information ```sh influx bucket-schema update \ --bucket example-bucket \ --name cpu \ --columns-file columns.csv \ -extended-output ``` ### Update a schema with columns format By default, InfluxDB attempts to detect the **columns file** format. If your file’s extension doesn’t match the format, set the format with the `columns-format` flag. ```sh influx bucket-schema update \ --bucket example-bucket \ --name cpu \ --columns-file columns.json \ --columns-format ndjson ``` ```sh influx bucket-schema update \ --bucket example-bucket \ --name cpu \ --columns-file columns.txt \ --columns-format csv ``` #### Related | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -n | --bucket | ( Required ) Bucket name (mutually exclusive with --bucket-id ) | string | | | -i | --bucket-id | ( Required ) Bucket ID (mutually exclusive with --bucket ) | string | | | | --columns-file | ( Required ) Path to column definitions file. For more information, see Create a columns file . | string | | | | --columns-format | Columns file format ( csv , ndjson , json , default: auto ). For more information, see Update a schema with columns format | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -x | --extended-output | Print column information for each measurement schema (default: false) | | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | ( Required ) Measurement name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx bucket` command and its subcommands manage buckets in InfluxDB. ## Usage ``` influx bucket [flags] influx bucket [command] ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------|-------------| |[create](/influxdb/v2/reference/cli/influx/bucket/create)|Create bucket| |[delete](/influxdb/v2/reference/cli/influx/bucket/delete)|Delete bucket| | [list](/influxdb/v2/reference/cli/influx/bucket/list) |List buckets | |[update](/influxdb/v2/reference/cli/influx/bucket/update)|Update bucket| ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `bucket` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [buckets](/influxdb/v2/tags/buckets/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create bucket | | delete | Delete bucket | | list | List buckets | | update | Update bucket | | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the bucket command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.3.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx bucket create` command creates a bucket in InfluxDB. ## Usage ```sh influx bucket create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Bucket description | string | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-r`| `--retention` | Duration bucket retains data (0 is infinite, default is 0) | duration | | | | `--schema-type` |Bucket schema type (`explicit`, default `implicit`) *(Cloud only)*. For more information, see [Manage bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/).| string | | | |`--shard-group-duration`| Bucket shard group duration (OSS only) | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | > [!Note] > #### Retention periods > > The minimum retention period is **one hour**. Valid `--retention` units: > > * nanoseconds (`ns`) > * microseconds (`us` or `µs`) > * milliseconds (`ms`) > * seconds (`s`) > * minutes (`m`) > * hours (`h`) > * days (`d`) > * weeks (`w`) ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Create a bucket with infinite data retention](#create-a-bucket-with-infinite-data-retention) * [Create a bucket that retains data for 30 days](#create-a-bucket-that-retains-data-for-30-days) * [Create a bucket with a description](#create-a-bucket-with-a-description) * [Create a bucket with a custom shard group duration](#create-a-bucket-with-a-custom-shard-group-duration) * [Create a bucket with an explicit schema](#create-a-bucket-with-an-explicit-schema) ##### Create a bucket with infinite data retention ```sh influx bucket create --name example-bucket ``` ##### Create a bucket that retains data for 30 days ```sh influx bucket create \ --name example-bucket \ --retention 30d ``` ##### Create a bucket with a description ```sh influx bucket create \ --name example-bucket \ --description "Example bucket description" ``` ##### Create a bucket with a custom shard group duration Custom shard group durations are only supported in **InfluxDB OSS**. The shard group duration must be shorter than the bucket’s retention period. For more information, see [InfluxDB shards and shard groups](/influxdb/v2/reference/internals/shards/). ```sh influx bucket create \ --name example-bucket \ --retention 30d \ --shard-group-duration 2d ``` ##### Create a bucket with an explicit schema > [!Important] > [Explicit bucket schemas](/influxdb/cloud/reference/cli/influx/bucket-schema) are only > supported in **InfluxDB Cloud**. > For more information, see [Manage bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). ```sh influx bucket create \ --name my_schema_bucket \ --schema-type explicit ``` #### Related * [Create a bucket](/influxdb/v2/admin/buckets/create-bucket/) * [InfluxDB shards and shard groups](/influxdb/v2/reference/internals/shards/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Bucket description | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Bucket name | string | INFLUX_BUCKET_NAME | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -r | --retention | Duration bucket retains data (0 is infinite, default is 0) | duration | | | | --schema-type | Bucket schema type ( explicit , default implicit ) (Cloud only) . For more information, see Manage bucket schema . | string | | | | --shard-group-duration | Bucket shard group duration (OSS only) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx bucket delete` command deletes a bucket from InfluxDB and all the data it contains. ## Usage ```sh influx bucket delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Bucket ID *(required if no `--name`)* | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Bucket name *(requires `--org` or `org-id`)* | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a bucket by name ```sh influx bucket delete --name example-bucket ``` ##### Delete a bucket by ID ```sh influx bucket delete --id 06c86c40a9f36000 ``` #### Related * [Delete a bucket](/influxdb/v2/admin/buckets/delete-bucket/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Bucket ID (required if no --name ) | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Bucket name (requires --org or org-id ) | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.3.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx bucket list` command lists and searches for buckets in InfluxDB. ## Usage ``` influx bucket list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|----------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Bucket ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--limit` |Total number of buckets to fetch from the server, or 0 to return all buckets| string | | |`-n`| `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` | | | `--offset` | Number of buckets to skip over in the list | integer | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--page-size` | Number of buckets to fetch per request to the server (default 20) | | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all buckets](#list-all-buckets) * [List a bucket by name](#list-a-bucket-by-name) * [List a bucket by ID](#list-a-bucket-by-id) ##### List all buckets ```sh influx bucket list ``` ##### List a bucket by name ```sh influx bucket list --name example-bucket ``` ##### List a bucket by ID ```sh influx bucket list --id 06c86c40a9f36000 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Bucket ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --limit | Total number of buckets to fetch from the server, or 0 to return all buckets | string | | | -n | --name | Bucket name | string | INFLUX_BUCKET_NAME | | | --offset | Number of buckets to skip over in the list | integer | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --page-size | Number of buckets to fetch per request to the server (default 20) | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx bucket update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx bucket update` command updates information associated with buckets in InfluxDB. ## Usage ``` influx bucket update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Bucket description | string | | |`-h`| `--help` | Help for the `update` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) Bucket ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | New bucket name | string | `INFLUX_BUCKET_NAME` | |`-r`| `--retention` |New duration bucket will retain data. For detail, see [Retention periods](/influxdb/v2/reference/cli/influx/bucket/update/#retention-periods).| duration | | | |`--shard-group-duration`| Custom shard group duration for the bucket (OSS only) | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | > [!Note] > #### Retention periods > > The minimum retention period is **one hour**. Valid `--retention` units: > > * nanoseconds (`ns`) > * microseconds (`us` or `µs`) > * milliseconds (`ms`) > * seconds (`s`) > * minutes (`m`) > * hours (`h`) > * days (`d`) > * weeks (`w`) > > For an **infinite** retention period, set the number to 0. For example, `0s`. ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update the name of a bucket ```sh influx bucket update \ --id 06c86c40a9f36000 \ --name new-bucket-name ``` ##### Update the retention period of a bucket ```sh influx bucket update \ --id 06c86c40a9f36000 \ --retention 90d ``` ##### Update the shard group duration of a bucket Custom shard group durations are only supported in **InfluxDB OSS**. The shard group duration must be shorter than the buckets retention period. ```sh influx bucket update \ --id 06c86c40a9f36000 \ --shard-group-duration 2d ``` #### Related * [Update a bucket](/influxdb/v2/admin/buckets/update-bucket/) * [InfluxDB shards and shard groups](/influxdb/v2/reference/internals/shards/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Bucket description | string | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) Bucket ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | New bucket name | string | INFLUX_BUCKET_NAME | | -r | --retention | New duration bucket will retain data. For detail, see Retention periods . | duration | | | | --shard-group-duration | Custom shard group duration for the bucket (OSS only) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx completion Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/completion/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx completion` command outputs `influx` shell completion scripts for a specified shell (`bash` or `zsh`). ## Usage ``` influx completion [bash|zsh] [flags] ``` ## Flags |Flag| | Description | |----|--------|---------------------------------| |`-h`|`--help`|Help for the `completion` command| ## Install completion scripts Add the appropriate installation command below to your `.bashrc` or `.zshrc`. #### Completion snippets in .bashrc or .zshrc [bash](#bash)[zsh](#zsh) ```sh # macOS $ source $(brew --prefix)/etc/bash_completion.d $ source <(influx completion bash) # Ubuntu $ source /etc/bash_completion.d $ source <(influx completion bash) ``` ```sh # macOS $ source <(influx completion zsh) # Ubuntu $ source <(influx completion zsh) ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [cli](/influxdb/v2/tags/cli/)[tools](/influxdb/v2/tags/tools/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the completion command | --- # influx config Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/config/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx config` command displays the active InfluxDB connection configuration and manages multiple connection configurations stored, by default, in `~/.influxdbv2/configs`. Each connection includes a URL, token, associated organization, and active setting. InfluxDB reads the token from the active connection configuration, so you don’t have to manually enter a token to log into InfluxDB. ## Usage ``` influx config [flags] influx config [command] influx config ``` ##### Quickly switch between configurations ```sh # Syntax influx config # Example influx config local-config ``` To quickly switch back to the previous configuration, use the following command: ```sh influx config - ``` ## Examples ```sh # Show the active connection configuration influx config # Set a connection configuration as active influx config local-config ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------------|----------------------------------------| |[create](/influxdb/v2/reference/cli/influx/config/create/)| Create a connection configuration | | [list](/influxdb/v2/reference/cli/influx/config/list/) | List connection configurations | | [delete](/influxdb/v2/reference/cli/influx/config/rm/) | Delete a connection configuration | | [set](/influxdb/v2/reference/cli/influx/config/set/) |Set or update a connection configuration| ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `config` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [config](/influxdb/v2/tags/config/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a connection configuration | | list | List connection configurations | | delete | Delete a connection configuration | | set | Set or update a connection configuration | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the config command | --- # influx config create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/config/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI 2.5.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx config create` command creates a InfluxDB connection configuration and stores it in a local file: | OS/Platform | CLI config file path | |----------------------------|-----------------------------------| | macOS | `~/.influxdbv2/configs` | |Linux (installed as binary) | `~/.influxdbv2/configs` | |Linux (installed as service)| `~/var/lib/influxdb/configs` | | Windows |`%USERPROFILE%\.influxdbv2\configs`| | Docker (DockerHub) | `/etc/influxdb2/configs` | | Docker (Quay.io) | `/root/.influxdbv2/configs` | | Kubernetes | `/etc/influxdb2/configs` | To view CLI connection configurations after creating them, use [influx config list](/influxdb/v2/reference/cli/influx/config/list/). > [!Note] > **Note:** If you create multiple connection configurations (for example, separate admin and user configurations), use [`influx config `](/influxdb/v2/reference/cli/influx/config/) to switch to the configuration you want to use. ## Usage ``` influx config create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-a`| `--active` | Set the specified connection to be the active configuration. | | | |`-n`| `--config-name` | (Required) Name of the new configuration. | string | | |`-h`| `--help` | Help for the `create` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-u`| `--host-url` | (Required) Connection URL for the new configuration. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-p`|`--username-password`|**(OSS only)** Username (and optionally password) to use for authentication.
Include `username:password` to ensure a session is automatically authenticated. Include `username` (without password) to prompt for a password before creating the session.| string | | ## Examples * [Create a connection configuration and set it active](#create-a-connection-configuration-and-set-it-active) * [Create a connection configuration without setting it active](#create-a-connection-configuration-without-setting-it-active) * [Create a connection configuration that uses a username and password](#create-a-connection-configuration-that-uses-a-username-and-password) #### Create a connection configuration and set it active ```sh influx config create --active \ -n config-name \ -u http://localhost:8086 \ -t mySuP3rS3cr3tT0keN \ -o example-org ``` #### Create a connection configuration without setting it active ```sh influx config create \ -n config-name \ -u http://localhost:8086 \ -t mySuP3rS3cr3tT0keN \ -o example-org ``` #### Create a connection configuration that uses a username and password The **`influx` CLI 2.4.0+** lets you create connection configurations that authenticate with **InfluxDB OSS 2.4+** using the username and password combination that you would use to log into the InfluxDB user interface (UI). The CLI retrieves a session cookie and stores it, unencrypted, in your[configs path](/influxdb/v2/reference/internals/file-system-layout/#configs-path). Use the `--username-password`, `-p` option to provide your username and password using the `:` syntax. If no password is provided, the CLI will prompt for a password after each command that requires authentication. ```sh influx config create \ -n config-name \ -u http://localhost:8086 \ -p example-user:example-password \ -o example-org ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | OS/Platform | CLI config file path | | --- | --- | | OS/Platform | CLI config file path | | macOS | ~/.influxdbv2/configs | | Linux (installed as binary) | ~/.influxdbv2/configs | | Linux (installed as service) | ~/var/lib/influxdb/configs | | Windows | %USERPROFILE%\.influxdbv2\configs | | Docker (DockerHub) | /etc/influxdb2/configs | | Docker (Quay.io) | /root/.influxdbv2/configs | | Kubernetes | /etc/influxdb2/configs | | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -a | --active | Set the specified connection to be the active configuration. | | | | -n | --config-name | ( Required ) Name of the new configuration. | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -u | --host-url | ( Required ) Connection URL for the new configuration. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name | string | | | -t | --token | API token | string | INFLUX_TOKEN | | -p | --username-password | (OSS only) Username (and optionally password) to use for authentication. Include username:password to ensure a session is automatically authenticated. Include username (without password) to prompt for a password before creating the session. | string | | --- # influx config list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/config/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx config list` command lists all InfluxDB connection configurations in the `configs` file (by default, stored at `~/.influxdbv2/configs`). Each connection configuration includes a URL, API token, and active setting. An asterisk (`*`) indicates the active configuration. ## Usage ``` influx config list [flags] ``` #### Command aliases `list`, `ls` ## Flags |Flag| | Description |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|----------------|-------------------------------------|---------------------------------------------------------------------------------| |`-h`| `--help` | Help for the `list` command | | | |`--hide-headers`|Hide table headers (default `false`) | `INFLUX_HIDE_HEADERS` | | | `--json` |Output data as JSON (default `false`)| `INFLUX_OUTPUT_JSON` | #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Maps to ? | | --- | --- | --- | --- | | Flag | | Description | Maps to ? | | -h | --help | Help for the list command | | | | --hide-headers | Hide table headers (default false ) | INFLUX_HIDE_HEADERS | | | --json | Output data as JSON (default false ) | INFLUX_OUTPUT_JSON | --- # influx config rm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/config/rm/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx config rm` command removes an InfluxDB connection configuration from the `configs` file (by default, stored at `~/.influxdbv2/configs`). ## Usage ``` influx config rm [flags] ``` #### Command aliases `rm`, `remove`, `delete` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|----------------|-------------------------------------|----------|---------------------------------------------------------------------------------| |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers`|Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--json` |Output data as JSON (default `false`)| | `INFLUX_OUTPUT_JSON` | ## Examples ##### Delete a connection configuration ```sh influx config rm local-config ``` ##### Delete multiple connection configurations ```sh influx config rm config-1 config-2 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | --- # influx config set Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/config/set/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI 2.5.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx config set` command updates information in an InfluxDB connection configuration in the `configs` file (by default, stored at `~/.influxdbv2/configs`). ## Usage ``` influx config set [flags] ``` #### Command aliases `set` , `update` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-a`| `--active` | Set the specified connection to active | | | |`-n`| `--config-name` | Name for the InfluxDB connection configuration to set or update | string | | |`-h`| `--help` | Help for the `set` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-u`| `--host-url` | URL for InfluxDB connection configuration to set or update | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name for the connection configuration | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-p`|`--username-password`|**(OSS only)** Username (and optionally password) to use for authentication.
Include `username:password` to ensure a session is automatically authenticated. Include `username` (without password) to prompt for a password before creating the session.| string | | ## Examples ##### Update a connection configuration and set it to active ```sh influx config set --active \ -n config-name \ -t mySuP3rS3cr3tT0keN \ -o example-org ``` ##### Update a connection configuration and do not set it to active ```sh influx config set \ -n config-name \ -t mySuP3rS3cr3tT0keN \ -o example-org ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -a | --active | Set the specified connection to active | | | | -n | --config-name | Name for the InfluxDB connection configuration to set or update | string | | | -h | --help | Help for the set command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -u | --host-url | URL for InfluxDB connection configuration to set or update | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name for the connection configuration | string | | | -t | --token | API token | string | INFLUX_TOKEN | | -p | --username-password | (OSS only) Username (and optionally password) to use for authentication. Include username:password to ensure a session is automatically authenticated. Include username (without password) to prompt for a password before creating the session. | string | | --- # influx dashboards Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/dashboards/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx dashboards` command lists existing InfluxDB dashboards. ## Usage ```sh influx dashboards [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `dashboards` command | | | | |`--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Dashboard ID to retrieve |stringArray| | | | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List all dashboards ```sh influx dashboards ``` ##### List only specific dashboards ```sh influx dashboards \ --id 068ad4a493f2d000 \ --id 0623f2dabc000121 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [telegraf](/influxdb/v2/tags/telegraf/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the dashboards command | | | | | --hide-headers | Hide table headers | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Dashboard ID to retrieve | stringArray | | | | --json | Output data as JSON | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/delete/ * influx CLI 2.0.3+ * InfluxDB 2.0.3+ * Updated in CLI v2.3.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx delete` command deletes [points](/influxdb/v2/reference/glossary/#point)from an InfluxDB bucket in a specified time range. Select points to delete within the specified time range using [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate). #### Deleting data without a delete predicate Running `influx delete` without the `-p` or `--predicate` flag deletes all data with timestamps between the specified`--start` and `--stop` times in the specified bucket. #### Cannot delete data by field InfluxDB 2.10 does not support deleting data **by field**. ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|-------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | |`-b`| `--bucket` | Name of bucket to remove data from (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | | | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | | |`--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-p`| `--predicate` |InfluxQL-like predicate string (see [Delete predicate](/influxdb/v2/reference/syntax/delete-predicate))| string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--start` | (Required) Start time in RFC3339 format (i.e. `2009-01-02T23:00:00Z`) | string | | | | `--stop` | (Required) Stop time in RFC3339 format (i.e. `2009-01-02T23:00:00Z`) | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Delete all points in a measurement](#delete-all-points-in-a-measurement) * [Delete points in a measurement with a specific tag value](#delete-points-in-a-measurement-with-a-specific-tag-value) * [Delete all points within a specified time frame](#delete-all-points-within-a-specified-time-frame) ##### Delete all points in a measurement ```sh influx delete \ --bucket example-bucket \ --start 1970-01-01T00:00:00Z \ --stop $(date -u +"%Y-%m-%dT%H:%M:%SZ") \ --predicate '_measurement="example-measurement"' ``` ##### Delete points in a measurement with a specific tag value ```sh influx delete \ --bucket example-bucket \ --start 1970-01-01T00:00:00Z \ --stop $(date -u +"%Y-%m-%dT%H:%M:%SZ") \ --predicate '_measurement="example-measurement" AND host="old-host"' ``` ##### Delete all points within a specified time frame ```sh influx delete \ --bucket example-bucket \ --start 2020-03-01T00:00:00Z \ --stop 2020-11-14T00:00:00Z ``` #### Related * [Delete data](/influxdb/v2/write-data/delete-data/) * [Delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [delete](/influxdb/v2/tags/delete/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -b | --bucket | Name of bucket to remove data from (mutually exclusive with --bucket-id ) | string | INFLUX_BUCKET_NAME | | | --bucket-id | Bucket ID (mutually exclusive with --bucket ) | string | INFLUX_BUCKET_ID | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -p | --predicate | InfluxQL-like predicate string (see Delete predicate ) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --start | ( Required ) Start time in RFC3339 format (i.e. 2009-01-02T23:00:00Z ) | string | | | | --stop | ( Required ) Stop time in RFC3339 format (i.e. 2009-01-02T23:00:00Z ) | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx export Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/export/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx export` command exports existing resources as an InfluxDB template.*For detailed examples of exporting InfluxDB templates, see[Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/).* ## Usage ``` influx export [flags] influx export [command] ``` ## Available subcommands | Subcommand | Description | |--------------------------------------------------------|----------------------------------------------------------| | [all](/influxdb/v2/reference/cli/influx/export/all/) | Export all resources in an organization as a template | |[stack](/influxdb/v2/reference/cli/influx/export/stack/)|Export all resources associated with a stack as a template| ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------------|--------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--bucket-names` | Comma-separated list of bucket names | string | | | | `--buckets` | Comma-separated list of bucket IDs | string | | | | `--check-names` | Comma-separated list of check names | string | | | | `--checks` | Comma-separated list of check IDs | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--dashboard-names` | Comma-separated list of dashboard names | string | | | | `--dashboards` | Comma-separated list of dashboard IDs | string | | | | `--endpoint-names` | Comma-separated list of notification endpoint names | string | | | | `--endpoints` | Comma-separated list of notification endpoint IDs | string | | |`-f`| `--file` |Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions.| string | | |`-h`| `--help` | Help for the `export` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:9999`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--label-names` | Comma-separated list of label names | string | | | | `--labels` | Comma-separated list of label IDs | string | | | | `--resource-type` | Resource type associated with all IDs via stdin | string | | | | `--rule-names` | Comma-separated list of notification rule names | string | | | | `--rules` | Comma-separated list of notification rule IDs | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--stack-id` | Stack ID to include resources from in export | string | | | | `--task-names` | Comma-separated list of task names | string | | | | `--tasks` | Comma-separated list of task IDs | string | | | |`--telegraf-config-names`| Comma-separated list of Telegraf configuration names | string | | | | `--telegraf-configs` | Comma-separated list of Telegraf configuration IDs | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | | | `--variable-names` | Comma-separated list of variable names | string | | | | `--variables` | Comma-separated list of variable IDs | string | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Export buckets by ID](#export-buckets-by-id) * [Export buckets, labels, and dashboards by ID](#export-buckets-labels-and-dashboards-by-id) * [Export buckets, labels, and dashboards by name](#export-buckets-labels-and-dashboards-by-name) * [Export all resources associated with a stack](#export-all-resources-associated-with-a-stack) * [Export resources both associated and not associated with a stack](#export-resources-both-associated-and-not-associated-with-a-stack) ##### Export buckets by ID ```sh influx export --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 ``` ##### Export buckets, labels, and dashboards by ID ```sh influx export \ --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 \ --labels o0x0oox0Xxoxx001,o0x0oox0Xxoxx002 \ --dashboards 0XxXooXoo0xooXo0X1,0XxXooXoo0xooXo0X2 ``` ##### Export buckets, labels, and dashboards by name ```sh influx export \ --bucket-names bucket1,bucket2,bucket3 \ --label-names label1,label2,label3 \ --dashboard-names dashboard1,dashboard2,dashboard3 ``` ##### Export all resources associated with a stack ```sh influx export --stack-id 0Xx0oox00XXoxxoo1 ``` ##### Export resources both associated and not associated with a stack ```sh influx export \ --stack-id 0Xx0oox00XXoxxoo1 \ --buckets o0x0oox0Xxoxx001,0XxXooXoo0xooXo0X2 \ --dashboard-names bucket1 ``` #### Related * [Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Subcommand | Description | | --- | --- | | Subcommand | Description | | all | Export all resources in an organization as a template | | stack | Export all resources associated with a stack as a template | | Flag | | Description | Input Type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input Type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --bucket-names | Comma-separated list of bucket names | string | | | | --buckets | Comma-separated list of bucket IDs | string | | | | --check-names | Comma-separated list of check names | string | | | | --checks | Comma-separated list of check IDs | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --dashboard-names | Comma-separated list of dashboard names | string | | | | --dashboards | Comma-separated list of dashboard IDs | string | | | | --endpoint-names | Comma-separated list of notification endpoint names | string | | | | --endpoints | Comma-separated list of notification endpoint IDs | string | | | -f | --file | Template output file. Defaults to stdout. Use .yml or .json file extensions. | string | | | -h | --help | Help for the export command | | | | | --host | HTTP address of InfluxDB (default http://localhost:9999 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --label-names | Comma-separated list of label names | string | | | | --labels | Comma-separated list of label IDs | string | | | | --resource-type | Resource type associated with all IDs via stdin | string | | | | --rule-names | Comma-separated list of notification rule names | string | | | | --rules | Comma-separated list of notification rule IDs | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --stack-id | Stack ID to include resources from in export | string | | | | --task-names | Comma-separated list of task names | string | | | | --tasks | Comma-separated list of task IDs | string | | | | --telegraf-config-names | Comma-separated list of Telegraf configuration names | string | | | | --telegraf-configs | Comma-separated list of Telegraf configuration IDs | string | | | -t | --token | API token | string | INFLUX_TOKEN | | | --variable-names | Comma-separated list of variable names | string | | | | --variables | Comma-separated list of variable IDs | string | | --- # influx export all Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/export/all/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx export all` command exports all resources in an organization as an InfluxDB template.*For detailed examples of exporting InfluxDB templates, see[Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/).* > [!Note] > To export resources as a template, you must use the **Operator token** created for > the initial InfluxDB user or an **All Access token**. > For information about creating an All Access API token, see [Create an API token](/influxdb/v2/admin/tokens/create-token/). ## Usage ``` influx export all [flags] ``` ## Flags |Flag| | Description |Input Type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|-----------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-f`| `--file` | Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions. | string | | | | `--filter` |Specify resources to export by labelName or resourceKind (format: `--filter=labelName=example`)|stringArray| | |`-h`| `--help` | Help for the `export all` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Organization name that owns the resources (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID that owns the resources (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Resources The following resources can be exported: * Bucket * Check * CheckDeadman * CheckThreshold * Dashboard * Label * NotificationEndpoint * NotificationEndpointHTTP * NotificationEndpointPagerDuty * NotificationEndpointSlack * NotificationRule * Task * Telegraf * Variable For additional information on each resource, please see[template resources](/influxdb/v2/tools/influxdb-templates/#template-resources). ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Export all resources in an organization as a template](#export-all-resources-in-an-organization-as-a-template) * [Export all bucket resources as a template](#export-all-bucket-resources-as-a-template) * [Export all resources associated with label Foo](#export-all-resources-associated-with-label-foo) * [Export all bucket resources and with label Foo](#export-all-bucket-resources-with-label-foo) * [Export all bucket or dashboard resources with label Foo](#export-all-bucket-or-dashboard-resources-with-label-foo) ##### Export all resources in an organization as a template ```sh influx export all ``` ##### Export all bucket resources as a template ```sh influx export all --filter=resourceKind=Bucket ``` ##### Export all resources associated with label Foo ```sh influx export all --filter=labelName=Foo ``` ##### Export all bucket resources and with label Foo ```sh influx export all \ --filter=resourceKind=Bucket \ --filter=labelName=Foo ``` ##### Export all bucket or dashboard resources with label Foo ```sh influx export all \ --filter=resourceKind=Bucket \ --filter=resourceKind=Dashboard \ --filter=labelName=Foo ``` #### Related * [Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input Type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input Type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --file | Template output file. Defaults to stdout. Use .yml or .json file extensions. | string | | | | --filter | Specify resources to export by labelName or resourceKind (format: --filter=labelName=example ) | stringArray | | | -h | --help | Help for the export all command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Organization name that owns the resources (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID that owns the resources (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx export stack Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/export/stack/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx export stack` command exports all resources associated with a stack as a template. All `metadata.name` fields remain the same. > [!Note] > To export resources as a template, you must use the **Operator token** created for > the initial InfluxDB user or an **All Access token**. > For information about creating an All Access API token, see [Create an API token](/influxdb/v2/admin/tokens/create-token/). ## Usage ``` influx export stack [flags] ``` ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|--------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-f`| `--file` |Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions.| string | | |`-h`| `--help` | Help for the `export stack` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Organization name that owns the resources (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID that owns the resources (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Export a stack as a template ```sh influx export stack $STACK_ID ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input Type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input Type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --file | Template output file. Defaults to stdout. Use .yml or .json file extensions. | string | | | -h | --help | Help for the export stack command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Organization name that owns the resources (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID that owns the resources (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx help Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/help/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx help` command provides help for any command in the `influx` command line interface. ## Usage ``` influx help [command] [flags] ``` ## Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `help` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the help command | --- # influx org Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org` command and its subcommands manage organization information in InfluxDB. ## Usage ``` influx org [flags] influx org [command] ``` #### Command aliases `org`, `organization` ## Subcommands | Subcommand | Description | |--------------------------------------------------------|--------------------------------| | [create](/influxdb/v2/reference/cli/influx/org/create) | Create an organization | | [delete](/influxdb/v2/reference/cli/influx/org/delete) | Delete an organization | | [list](/influxdb/v2/reference/cli/influx/org/list) | List organizations | |[members](/influxdb/v2/reference/cli/influx/org/members)|Organization membership commands| | [update](/influxdb/v2/reference/cli/influx/org/update) | Update an organization | ## Flags |Flag| | Description | |----|--------|--------------------------| |`-h`|`--help`|Help for the `org` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [organizations](/influxdb/v2/tags/organizations/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create an organization | | delete | Delete an organization | | list | List organizations | | members | Organization membership commands | | update | Update an organization | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the org command | --- # influx org create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org create` creates an organization in InfluxDB. ## Usage ``` influx org create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Description of the organization | | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | (Required) Organization name | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create an organization ```sh influx org create --name example-org ``` ##### Create an organization with a description ```sh influx org create \ --name example-org \ --description "Example organization description" ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Description of the organization | | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | ( Required ) Organization name | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org delete` command deletes an organization in InfluxDB. ## Usage ``` influx org delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) Organization ID | string | `INFLUX_ORG_ID` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete an organization ```sh influx org delete --id 0Xx0oox00XXoxxoo1 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) Organization ID | string | INFLUX_ORG_ID | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org list` lists and searches for organizations in InfluxDB. ## Usage ``` influx org list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Organization ID | string | `INFLUX_ORG_ID` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Organization name | string | `INFLUX_ORG` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all organizations](#list-all-organizations) * [List a specific organization by name](#list-a-specific-organization-by-name) * [List a specific organization by ID](#list-a-specific-organization-by-id) ##### List all organizations ```sh influx org list ``` ##### List a specific organization by name ```sh influx org list --name example-org ``` ##### List a specific organization by ID ```sh influx org list --id 0Xx0oox00XXoxxoo1 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Organization ID | string | INFLUX_ORG_ID | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Organization name | string | INFLUX_ORG | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org members Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/members/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org members` command and its subcommands manage organization members in InfluxDB. ## Usage ``` influx org members [flags] influx org members [command] ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------|--------------------------| | [add](/influxdb/v2/reference/cli/influx/org/members/add) | Add organization member | | [list](/influxdb/v2/reference/cli/influx/org/members/list) |List organization members | |[remove](/influxdb/v2/reference/cli/influx/org/members/remove)|Remove organization member| ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `members` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [members](/influxdb/v2/tags/members/)[organizations](/influxdb/v2/tags/organizations/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | add | Add organization member | | list | List organization members | | remove | Remove organization member | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the members command | --- # influx org members add Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/members/add/ * influx CLI 2.0.0+ * InfluxDB OSS only * Updated in CLI v2.4.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org members add` command adds a member to an organization in InfluxDB. ## Usage ``` influx org members add [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------|----------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-h`| `--help` | Help for the `add` command | | | | | `--host` |HTTP address of InfluxDB (default `http://localhost:8086`)| string | `INFLUX_HOST` | |`-i`| `--id` | Organization ID | string | `INFLUX_ORG_ID` | |`-m`| `--member` | User ID | string | | |`-n`| `--name` | Organization name | string | `INFLUX_ORG` | | | `--owner` | Set new member as an owner | | | | |`--skip-verify`| Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Add a member to an organization ```sh influx org members add \ --member 00x0oo0X0xxxo000 \ --name example-org ``` ##### Add a member to an organization and make them an owner ```sh influx org members add \ --member 00x0oo0X0xxxo000 \ --name example-org \ --owner ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Add a member](/influxdb/v2/admin/organizations/members/add-member/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -h | --help | Help for the add command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | Organization ID | string | INFLUX_ORG_ID | | -m | --member | User ID | string | | | -n | --name | Organization name | string | INFLUX_ORG | | | --owner | Set new member as an owner | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org members list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/members/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org members list` command lists members within an organization in InfluxDB. ## Usage ``` influx org members list [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|----------------|----------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers`| Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` |HTTP address of InfluxDB (default `http://localhost:8086`)| string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Organization ID | string | `INFLUX_ORG_ID` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Organization name | string | `INFLUX_ORG` | | |`--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List members of an organization ```sh influx org members list \ --name example-org ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Organization ID | string | INFLUX_ORG_ID | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Organization name | string | INFLUX_ORG | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org members remove Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/members/remove/ * influx CLI 2.0.0+ * InfluxDB OSS only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org members remove` command removes a member from an organization in InfluxDB. ## Usage ``` influx org members remove [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------|----------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-h`| `--help` | Help for the `remove` command | | | | | `--host` |HTTP address of InfluxDB (default `http://localhost:8086`)| string | `INFLUX_HOST` | | |`--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Organization ID | string | `INFLUX_ORG_ID` | |`-m`| `--member` | Member ID | string | | |`-n`| `--name` | Organization name | string | `INFLUX_ORG` | | |`--skip-verify`| Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Remove a member from an organization ```sh influx org members remove \ --member 00x0oo0X0xxxo000 \ --name example-org ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -h | --help | Help for the remove command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Organization ID | string | INFLUX_ORG_ID | | -m | --member | Member ID | string | | | -n | --name | Organization name | string | INFLUX_ORG | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx org update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/org/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx org update` command updates information related to organizations in InfluxDB. ## Usage ``` influx org update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | New description for the organization | string | `INFLUX_ORG_DESCRIPTION` | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) Organization ID | string | `INFLUX_ORG_ID` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | New organization name | string | `INFLUX_ORG` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update the name of an organization ```sh influx org update \ --id 0Xx0oox00XXoxxoo1 --name new-org-name ``` ##### Update the description of an organization ```sh influx org update \ --id 0Xx0oox00XXoxxoo1 --description "New example organization description" ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | New description for the organization | string | INFLUX_ORG_DESCRIPTION | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) Organization ID | string | INFLUX_ORG_ID | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | New organization name | string | INFLUX_ORG | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx ping Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/ping/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx ping` command checks the health of a running InfluxDB instance by querying the `/health` endpoint. It does not require an API token. ## Usage ``` influx ping [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `ping` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [ping](/influxdb/v2/tags/ping/)[health](/influxdb/v2/tags/health/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the ping command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | --- # influx query Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/query/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx query` command executes a literal Flux query provided as a string or a literal Flux query contained in a file. ## Usage ``` influx query [query literal] [flags] ``` > [!Note] > #### Remove unnecessary columns in large datasets > > When using the `influx query` command to query and download large datasets, > drop columns such as `_start` and `_stop` to optimize the download file size. > > ``` > // ... > |> drop(columns: ["_start", "_stop"]) > ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-f`| `--file` | Path to Flux script file | string | | |`-h`| `--help` | Help for the `query` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-p`| `--profilers` | Flux query profilers to enable (comma-separated) | string | | |`-r`| `--raw` | Output raw query results (annotated CSV) | | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Query InfluxDB with a Flux string](#query-influxdb-with-a-flux-string) * [Query InfluxDB using a Flux file](#query-influxdb-with-a-flux-file) * [Query InfluxDB and return annotated CSV](#query-influxdb-and-return-annotated-csv) * [Query InfluxDB and append query profile data to results](#query-influxdb-and-append-query-profile-data-to-results) ##### Query InfluxDB with a Flux string ```sh influx query 'from(bucket:"example-bucket") |> range(start:-1m)' ``` ##### Query InfluxDB with a Flux file ```sh influx query --file /path/to/example-query.flux ``` ##### Query InfluxDB and return annotated CSV ```sh influx query 'from(bucket:"example-bucket") |> range(start:-1m)' --raw ``` ##### Query InfluxDB and append query profile data to results *For more information about profilers, see [Flux profilers](/flux/v0/stdlib/profiler/#available-profilers).* ```sh influx query \ --profilers operator,query \ 'from(bucket:"example-bucket") |> range(start:-1m)' ``` #### Related * [Query data in InfluxDB](/influxdb/v2/query-data/) * [Use the influx query command](/influxdb/v2/query-data/execute-queries/influx-query/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [query](/influxdb/v2/tags/query/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --file | Path to Flux script file | string | | | -h | --help | Help for the query command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -p | --profilers | Flux query profilers to enable (comma-separated) | string | | | -r | --raw | Output raw query results (annotated CSV) | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx remote Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/remote/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Configure InfluxDB Edge Data Replication remotes and replication streams to > replicate data from InfluxDB OSS to remote buckets on InfluxDB Cloud, InfluxDB > Enterprise, or another InfluxDB OSS instance. Currently, you cannot configure > remotes and replication streams on InfluxDB Cloud. Use the `influx remote` command to manage connections to remote instances of InfluxDB. Remote connections are used to replicate data on write at the bucket level. ## Usage ``` influx remote [command options] [arguments...] ``` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------|------------------------------| |[`create`](/influxdb/v2/reference/cli/influx/remote/create)|Create a new remote connection| |[`delete`](/influxdb/v2/reference/cli/influx/remote/delete)| Delete a remote connection | | [`list`](/influxdb/v2/reference/cli/influx/remote/list) | List remote connections | |[`update`](/influxdb/v2/reference/cli/influx/remote/update)| Update a remote connection | ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `remote` command| #### Related * [influx replication](/influxdb/v2/reference/cli/influx/replication/) * [Edge Data Replication](/influxdb/v2/write-data/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a new remote connection | | delete | Delete a remote connection | | list | List remote connections | | update | Update a remote connection | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the remote command | --- # influx remote create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/remote/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote create` command creates a new remote InfluxDB connection for replicating data. ## Usage ``` influx remote create [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|----------------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| | | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | |`-o`| `--org` | Organization name | string | `INFLUX_ORG` | |`-n`| `--name` | Remote connection name | string | | |`-d`| `--description` | Remote connection description | string | | | | `--remote-url` | Remote InfluxDB instance URL | string | | | | `--remote-api-token` | Remote InfluxDB API token | string | | | | `--remote-org-id` | Remote InfluxDB organization ID | string | | | |`--allow-insecure-tls`| Allows insecure TLS (self-signed certificates) | | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Create a new remote with InfluxDB Cloud ```sh influx remote create \ --name myremote \ --org-id \ --token \ --remote-url \ --remote-api-token \ --remote-org-id ``` #### Related * [influx replication](/influxdb/v2/reference/cli/influx/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | | --org-id | Organization ID | string | INFLUX_ORG_ID | | -o | --org | Organization name | string | INFLUX_ORG | | -n | --name | Remote connection name | string | | | -d | --description | Remote connection description | string | | | | --remote-url | Remote InfluxDB instance URL | string | | | | --remote-api-token | Remote InfluxDB API token | string | | | | --remote-org-id | Remote InfluxDB organization ID | string | | | | --allow-insecure-tls | Allows insecure TLS (self-signed certificates) | | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx remote delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/remote/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote delete` command delete an existing remote InfluxDB connection used for replication. ## Usage ``` influx remote delete [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-i`| `--id` | Remote connection ID to delete | | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`|`--active-config`| CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Delete a remote 1. Use `influx remote list` to get the ID for the remote you want to delete. ``` $ influx remote list --org-id --token ID Name Org ID 0ooxX0xxXo0x myremote [...] ``` 2. Use the following command to delete the remote: ``` influx remote delete \ --org-id \ --token \ --id 0ooxX0xxXo0x ``` #### Related * [influx replication](/influxdb/v2/reference/cli/influx/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -i | --id | Remote connection ID to delete | | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx remote list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/remote/list/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote list` command lists all remote InfluxDB connections used for replication. ## Usage ``` influx remote list [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-n`| `--name` | Filter remote connections by name | | | | | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | |`-o`| `--org` | Organization name | string | `INFLUX_ORG` | | | `--remote-url` | Filter remote connections by remote URL | string | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`|`--active-config`| CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### List all remotes ```sh influx remote list ``` ### List a specific remote by name ```sh influx remote list --name example-name ``` #### Related * [influx replication](/influxdb/v2/reference/cli/influx/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -n | --name | Filter remote connections by name | | | | | --org-id | Organization ID | string | INFLUX_ORG_ID | | -o | --org | Organization name | string | INFLUX_ORG | | | --remote-url | Filter remote connections by remote URL | string | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx remote update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/remote/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote update` command updates an existing InfluxDB remote connection used for replicating data. ## Usage ``` influx remote update [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|----------------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-i`| `--id` | Remote connection ID to update | string | | |`-n`| `--name` | New name for the remote connection | string | | |`-d`| `--description` | New remote connection description | string | | | | `--remote-url` | New remote InfluxDB URL | string | | | | `--remote-api-token` | New remote InfluxDB API token | string | | | | `--remote-org-id` | New remote organization ID | string | | | |`--allow-insecure-tls`| Allows insecure TLS connections | | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Update a remote 1. Use `influx remote list` to get the ID for the remote you want to update. ``` $ influx remote list ID Name Org ID 0ooxX0xxXo0x myremote [...] ``` 2. Use the following command to update the remote: ``` influx remote update \ --id 0ooxX0xxXo0x --name new-example-name --description new-example-description --remote-url http://new-example-url.com --remote-api-token myN3wS3crE7t0k3n== --remote-org-id new-example-org-id ``` #### Related * [influx replication](/influxdb/v2/reference/cli/influx/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -i | --id | Remote connection ID to update | string | | | -n | --name | New name for the remote connection | string | | | -d | --description | New remote connection description | string | | | | --remote-url | New remote InfluxDB URL | string | | | | --remote-api-token | New remote InfluxDB API token | string | | | | --remote-org-id | New remote organization ID | string | | | | --allow-insecure-tls | Allows insecure TLS connections | | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx repl Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/repl/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). #### Removed in InfluxDB 2.0 beta-16 The `influx repl` command was removed in **InfluxDB 2.0 beta-16**. To use the Flux REPL, build the REPL from source. For more information, see the [Flux GitHub repository](https://github.com/influxdata/flux/#readme). The `influx repl` command opens an interactive Read-Eval-Print Loop (REPL) from which you can run Flux commands. ## Usage ``` influx repl [flags] ``` > [!Note] > Use **ctrl + d** to exit the REPL. To use the Flux REPL, you must first authenticate with a [token](/influxdb/v2/admin/tokens/view-tokens/). ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `repl` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [query](/influxdb/v2/tags/query/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the repl command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx replication Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/replication/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx replication` command and its subcommands manage InfluxDB Edge Data Replication. ## Usage ``` influx replication [command options] [arguments...] ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------|----------------------------------------| |[create](/influxdb/v2/reference/cli/influx/replication/create)| Create a new replication stream | |[delete](/influxdb/v2/reference/cli/influx/replication/delete)| Delete a replication stream | | [list](/influxdb/v2/reference/cli/influx/replication/list) |List all replication streams and metrics| |[update](/influxdb/v2/reference/cli/influx/replication/update)| Update a replication stream | ## Flags |Flag| | Description | |----|--------|----------------------------------| |`-h`|`--help`|Help for the `replication` command| #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a new replication stream | | delete | Delete a replication stream | | list | List all replication streams and metrics | | update | Update a replication stream | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the replication command | --- # influx replication create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/replication/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication create` command creates a new InfluxDB replication stream. ## Usage ``` influx replication create [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|------------------------------|--------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-n`| `--name` | Replication stream name | string | | |`-d`| `--description` | Replication stream description | string | | | | `--org-id` | Local organization ID | string | `INFLUX_ORG_ID` | |`-o`| `--org` | Local organization name | string | `INFLUX_ORG` | | | `--remote-id` | Remote connection ID to replicate data to | string | | | | `--local-bucket-id` | Local bucket ID to replicate data from | string | | | | `--remote-bucket` |Remote bucket name to replicate data to (mutually exclusive with `--remote-bucket-id`)| string | | | | `--remote-bucket-id` |Remote bucket ID to replicate data to (mutually exclusive with `--remote-bucket-name`)| string | | | | `--max-queue-bytes` | Max queue size in bytes (default: `67108860`) | integer | | | | `--drop-non-retryable-data` | Drop data when a non-retryable error is encountered | | | | |`--no-drop-non-retryable-data`| Do not drop data when a non-retryable error is encountered | | | | | `--max-age` | Specify a maximum age (in seconds) for data before it is dropped | integer | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Create a replication stream 1. [Create a remote connection](/influxdb/v2/reference/cli/influx/remote/create/), if you haven’t already. 2. Use `influx remote list` to get the ID for the remote you want to replicate data to. ``` $ influx remote list ID Name Org ID 0ooxX0xxXo0x myremote [...] ``` 3. Create the replication: ``` influx replication create \ --name myreplication --local-bucket example-local-bucket --remote-bucket example-remote-bucket --remote-id 0ooxX0xxXo0x ``` #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) [write](/influxdb/v2/tags/write/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -n | --name | Replication stream name | string | | | -d | --description | Replication stream description | string | | | | --org-id | Local organization ID | string | INFLUX_ORG_ID | | -o | --org | Local organization name | string | INFLUX_ORG | | | --remote-id | Remote connection ID to replicate data to | string | | | | --local-bucket-id | Local bucket ID to replicate data from | string | | | | --remote-bucket | Remote bucket name to replicate data to (mutually exclusive with --remote-bucket-id ) | string | | | | --remote-bucket-id | Remote bucket ID to replicate data to (mutually exclusive with --remote-bucket-name ) | string | | | | --max-queue-bytes | Max queue size in bytes (default: 67108860 ) | integer | | | | --drop-non-retryable-data | Drop data when a non-retryable error is encountered | | | | | --no-drop-non-retryable-data | Do not drop data when a non-retryable error is encountered | | | | | --max-age | Specify a maximum age (in seconds) for data before it is dropped | integer | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx replication delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/replication/delete/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication delete` command deletes an InfluxDB replication stream. ## Usage ``` influx replication delete [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-i`| `--id` | Replication stream ID to delete | string | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`|`--active-config`| CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Delete a replication 1. Use `influx replication list` to get the ID for the replication you want to delete. ``` $ influx replication list ID Name Org ID 0ooxX0xxXo0x myreplication [...] ``` 2. Use the following command to delete the replication: ``` influx replication delete --id 0ooxX0xxXo0x ``` #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -i | --id | Replication stream ID to delete | string | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx replication list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/replication/list/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication list` command lists all InfluxDB replication streams and their corresponding metrics. The following metrics are listed for each replication and provide information about how the replication queue is performing: * **Latest Status Code**: Status code of the last `write` request to the remote. This should be a 204 during healthy operation. * **Remaining Bytes to be Synced**: Number of bytes that have not been synced to the remote. This number should stay close to 0 and should not be constantly increasing. * **Current Queue Bytes on Disk**: Total size of the replication queue in bytes. The replication queue is cleaned up every `--max-age` seconds. If your queue is filling up your disk, lower this value at the cost of potentially lower reliability. ## Usage ``` influx replication list [command options] [arguments...] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-n`| `--name` | Filter replication streams by name | string | | | | `--org-id` | Local organization ID | string | `INFLUX_ORG_ID` | |`-o`| `--org` | Local organization name | string | `INFLUX_ORG` | | | `--remote-id` | Filter replication streams by remote connection ID | string | | | |`--local-bucket-id`| Filter replication streams by local bucket | string | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### List all replication streams ```sh influx replication list --org-id --token ``` ### List a replication stream by name ```sh influx replication list --name example-replication-name ``` #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -n | --name | Filter replication streams by name | string | | | | --org-id | Local organization ID | string | INFLUX_ORG_ID | | -o | --org | Local organization name | string | INFLUX_ORG | | | --remote-id | Filter replication streams by remote connection ID | string | | | | --local-bucket-id | Filter replication streams by local bucket | string | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx replication update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/replication/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication update` command updates an InfluxDB replication stream. ## Usage ``` influx replication update [command options] [arguments...] ``` ## Flag |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|------------------------------|--------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-i`| `--id` | Replication stream ID to update | string | | |`-n`| `--name` | New replication stream name | string | | |`-d`| `--description` | New replication stream description | string | | | | `--remote-id` | New remote connection ID to send data to | string | | | | `--remote-bucket` |Remote bucket name to replicate data to (mutually exclusive with `--remote-bucket-id`)| string | | | | `--remote-bucket-id` |Remote bucket ID to replicate data to (mutually exclusive with `--remote-bucket-name`)| string | | | | `--max-queue-bytes` | New max queue size in bytes (default: `0`) | integer | | | | `--drop-non-retryable-data` | Drop data when a non-retryable error is encountered | | | | |`--no-drop-non-retryable-data`| Do not drop data when a non-retryable error is encountered | | | | | `--max-age` | Specify a maximum age (in seconds) for data before it is dropped | integer | | | | `--host` | InfluxDB HTTP address (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | |`-t`| `--token` | InfluxDB API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ### Update a replication 1. Use `influx replication list` to get the ID for the replication you want to update. ``` $ influx replication list ID Name Org ID 0ooxX0xxXo0x myreplication [...] ``` 2. Use the following command to update the replication: ``` influx replication update \ --id 0ooxX0xxXo0x --name new-replication-name --description new-replication-description --replication-url http://new-replication-url.com --replication-api-token new-replication-api-token --replication-org-id new-replication-org-id ``` #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -i | --id | Replication stream ID to update | string | | | -n | --name | New replication stream name | string | | | -d | --description | New replication stream description | string | | | | --remote-id | New remote connection ID to send data to | string | | | | --remote-bucket | Remote bucket name to replicate data to (mutually exclusive with --remote-bucket-id ) | string | | | | --remote-bucket-id | Remote bucket ID to replicate data to (mutually exclusive with --remote-bucket-name ) | string | | | | --max-queue-bytes | New max queue size in bytes (default: 0 ) | integer | | | | --drop-non-retryable-data | Drop data when a non-retryable error is encountered | | | | | --no-drop-non-retryable-data | Do not drop data when a non-retryable error is encountered | | | | | --max-age | Specify a maximum age (in seconds) for data before it is dropped | integer | | | | --host | InfluxDB HTTP address (default http://localhost:8086 ) | string | INFLUX_HOST | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -c | --active-config | CLI configuration to use for command | string | | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | -t | --token | InfluxDB API token | string | INFLUX_TOKEN | --- # influx restore Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/restore/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.7 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx restore` command restores backup data and metadata from an InfluxDB OSS backup directory. ### The restore process When restoring data from a backup file set, InfluxDB temporarily moves existing data and metadata while `restore` runs. After `restore` completes, the temporary data is deleted. If the restore process fails, InfluxDB preserves the data in the temporary location. *For information about recovering from a failed restore process, see[Restore data](/influxdb/v2/admin/backup-restore/restore/#recover-from-a-failed-restore).* > [!Note] > #### Cannot restore to existing buckets > > The `influx restore` command cannot restore data to existing buckets. > Use the `--new-bucket` flag to create a bucket with a new name and restore data into it. > To restore data and retain bucket names, [delete existing buckets](/influxdb/v2/admin/buckets/delete-bucket/)and then begin the restore process. ## Usage ``` influx restore [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|------------------|-----------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config` | CLI configuration to use for command | string | | |`-b`| `--bucket` | Name of the bucket to restore (mutually exclusive with `--bucket-id`) | string | | | | `--bucket-id` | ID of the bucket to restore (mutually exclusive with `--bucket`) | string | | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--full` | Fully restore and replace all data on server | | | |`-h`| `--help` | Help for the `restore` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--new-bucket` | Name of the bucket to restore to | string | | | | `--new-org` | Name of the organization to restore to | string | | | |`--operator-token`|Operator token to use when restoring a backup that contains only hashed tokens. Used by `--full` only. *(2.8.0+)*| string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Restore backup data](#restore-backup-data) * [Restore backup data for a specific bucket into a new bucket](#restore-backup-data-for-a-specific-bucket-into-a-new-bucket) * [Restore and replace all data](#restore-and-replace-all-data) * [Restore a backup that contains hashed tokens](#restore-a-backup-that-contains-hashed-tokens) ##### Restore backup data ```sh influx restore /path/to/backup/dir/ ``` ##### Restore backup data for a specific bucket into a new bucket ```sh influx restore \ --bucket example-bucket \ --new-bucket new-example-bucket \ /path/to/backup/dir/ ``` ##### Restore and replace all data > [!Note] > `influx restore --full` restores all time series data *and* InfluxDB key-value > data such as tokens, dashboards, users, etc. ```sh influx restore --full /path/to/backup/dir/ ``` ##### Restore a backup that contains hashed tokens If the backup was taken from an instance with [token hashing](/influxdb/v2/admin/tokens/#token-hashing) enabled (the default in **InfluxDB OSS 2.9.0+**), the backup does not contain a plaintext operator token. Supply the operator token with `--operator-token`so the CLI can authenticate post-restore requests. *Requires `influx` CLI 2.8.0+.* ```sh influx restore \ --full \ --operator-token OPERATOR_TOKEN \ /path/to/backup/dir/ ``` #### Related * [Restore data](/influxdb/v2/admin/backup-restore/restore/) * [influx backup](/influxdb/v2/reference/cli/influx/backup/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [restore](/influxdb/v2/tags/restore/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -b | --bucket | Name of the bucket to restore (mutually exclusive with --bucket-id ) | string | | | | --bucket-id | ID of the bucket to restore (mutually exclusive with --bucket ) | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --full | Fully restore and replace all data on server | | | | -h | --help | Help for the restore command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --new-bucket | Name of the bucket to restore to | string | | | | --new-org | Name of the organization to restore to | string | | | | --operator-token | Operator token to use when restoring a backup that contains only hashed tokens. Used by --full only. (2.8.0+) | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | | | | --org-id | Organization ID (mutually exclusive with --org ) | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts` command and its subcommands manage [invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) in InfluxDB. ### Usage ``` influx scripts [command] ``` ### Subcommands | Subcommand | Description | |--------------------------------------------------------------|---------------| | [create](/influxdb/v2/reference/cli/influx/scripts/create) | Create script | | [delete](/influxdb/v2/reference/cli/influx/scripts/delete) | Delete script | | [invoke](/influxdb/v2/reference/cli/influx/scripts/invoke) | Invoke script | | [list](/influxdb/v2/reference/cli/influx/scripts/list) | List scripts | |[retrieve](/influxdb/v2/reference/cli/influx/scripts/retrieve)|Retrieve script| | [update](/influxdb/v2/reference/cli/influx/scripts/update) | Update script | ### Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `scripts` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) [scripts](/influxdb/v2/tags/scripts/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create script | | delete | Delete script | | invoke | Invoke script | | list | List scripts | | retrieve | Retrieve script | | update | Update script | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the scripts command | --- # influx scripts create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/create/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts create` command creates an invokable script in InfluxDB. ## Usage ``` influx scripts create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | (Required) Purpose or functionality of the script | string | | |`-f`| `--file` | Path to file containing the script to be executed | string | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-l`| `--language` | (Required) Language the script is written in | string | | |`-n`| `--name` | (Required) Script name of the script | string | | |`-s`| `--script` | Contents of the script to be executed | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a script using raw Flux ```sh export FLUX_SCRIPT=' from(bucket: "example-bucket") |> range(start: -10h) |> filter(fn: (r) => r._measurement == "m") |> aggregateWindow(every: 1h, fn: mean) |> to(bucket: "default-ds-1d", org: "my-org") ' influx scripts create \ -n "example-script" \ -d "a simple example" \ -l "flux" \ -s $FLUX_SCRIPT ``` ##### Create a script from a file ```sh influx scripts create \ -n "example-script" \ -d "a simple example" \ -l "flux" \ -f /path/to/example-script.flux ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | ( Required ) Purpose or functionality of the script | string | | | -f | --file | Path to file containing the script to be executed | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -l | --language | ( Required ) Language the script is written in | string | | | -n | --name | ( Required ) Script name of the script | string | | | -s | --script | Contents of the script to be executed | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/delete/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts delete` command deletes an invokable script in InfluxDB. ## Usage ``` influx scripts delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-i`| `--scriptID` | (Required) Script ID | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a script ```sh influx scripts delete -i 0Xx0oox00XXoxxoo1 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -i | --scriptID | ( Required ) Script ID | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts invoke Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/invoke/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts invoke` command executes an invokable script in InfluxDB. ## Usage ``` influx scripts invoke [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-f`| `--file` | File name containing the script parameters, in JSON | string | | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-p`| `--params` | JSON string containing script parameters | string | | |`-i`| `--scriptID` | (Required) Script ID | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Invoke a script](#invoke-a-script) * [Invoke a script with parameters](#invoke-a-script-with-parameters) ##### Invoke a script ```sh influx scripts invoke -i 0Xx0oox00XXoxxoo1 ``` ##### Invoke a script with parameters ```sh influx scripts invoke \ -i 0Xx0oox00XXoxxoo1 \ -p "{ \"myParameter\": \"example-data\" }" ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --file | File name containing the script parameters, in JSON | string | | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -p | --params | JSON string containing script parameters | string | | | -i | --scriptID | ( Required ) Script ID | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/list/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts list` command lists and searches for invokable scripts in InfluxDB. ## Usage ``` influx scripts list [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-l`| `--limit` | Number of scripts to return (default `0`) | integer | | |`-o`| `--offset` | Pagination offset (default `0`) | integer | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all invokable scripts](#list-all-invokable-scripts) * [Limit the number of invokable scripts returned to 20](#limit-the-number-of-invokable-scripts-returned-to-20) ##### List all invokable scripts ```sh influx scripts list ``` ##### Limit the number of invokable scripts returned to 20 ```sh influx scripts list --limit 20 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -l | --limit | Number of scripts to return (default 0 ) | integer | | | -o | --offset | Pagination offset (default 0 ) | integer | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts retrieve Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/retrieve/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts retrieve` command retrieves invokable script information from InfluxDB. ## Usage ``` influx scripts retrieve [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-i`| `--scriptID` | (Required) Script ID | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Retrieve a script ```sh influx scripts retrieve -i 0Xx0oox00XXoxxoo1 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -i | --scriptID | ( Required ) Script ID | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx scripts update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/scripts/update/ * influx CLI 2.4.0+ * InfluxDB Cloud only This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx scripts update` command updates information related to an invokable script in InfluxDB. ## Usage ``` influx scripts update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | New script description | string | | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-n`| `--name` | New script name | string | | |`-s`| `--script` | New script contents | string | | |`-i`| `--scriptID` | (Required) Script ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update the source code of an invokable script ```sh export UPDATED_FLUX=' from(bucket: "example-bucket") |> range(start: -10h) |> filter(fn: (r) => r._measurement == "m") |> aggregateWindow(every: 1h, fn: mean) |> to(bucket: "default-ds-1d", org: "my-org") ' influx scripts update \ -i 0Xx0oox00XXoxxoo1 \ -s $UPDATED_FLUX ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | New script description | string | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -n | --name | New script name | string | | | -s | --script | New script contents | string | | | -i | --scriptID | ( Required ) Script ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx secret Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/secret/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx secret` command manages [secrets](/influxdb/v2/reference/glossary/#secret). ## Usage ``` influx secret [flags] influx secret [subcommand] ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------------|----------------------| |[delete](/influxdb/v2/reference/cli/influx/secret/delete/)| Delete a secret | | [list](/influxdb/v2/reference/cli/influx/secret/list/) | List secrets | |[update](/influxdb/v2/reference/cli/influx/secret/update/)|Add or update a secret| ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `secret` command| #### Related * [Manage secrets](/influxdb/v2/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/v2/tags/secrets/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | delete | Delete a secret | | list | List secrets | | update | Add or update a secret | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the secret command | --- # influx secret delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/secret/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx secret delete` command deletes secrets. ## Usage ``` influx secret delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-k`| `--key` | (Required) Secret key | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a secret ```sh influx secret delete --key EXAMPLE_SECRET_KEY ``` #### Related * [Manage secrets](/influxdb/v2/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/v2/tags/secrets/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -k | --key | ( Required ) Secret key | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx secret list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/secret/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx secret list` command lists secret keys. ## Usage ``` influx secret list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List all secret keys ```sh influx secret list ``` #### Related * [Manage secrets](/influxdb/v2/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/v2/tags/secrets/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx secret update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/secret/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx secret update` command adds and updates secrets. Provide the secret key with the `-k` or `--key` flag. You may also provide the secret value with the `-v` or `--value` flag. If you do not provide the secret value with the `-v` or `--value` flag, enter the value when prompted. Providing a secret value with the `-v` or `--value` flag may expose the secret in your command history. ## Usage ``` influx secret update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-k`| `--key` | (Required) Secret key | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-v`| `--value` | (Required) Secret value | string | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Add a secret ```sh influx secret update \ --key EXAMPLE_KEY \ --value EXAMPLE_VALUE ``` ##### Update an existing secret ```sh influx secret update \ --key EXAMPLE_KEY \ --value NEW_EXAMPLE_VALUE ``` #### Related * [Manage secrets](/influxdb/v2/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/v2/tags/secrets/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -k | --key | ( Required ) Secret key | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | -v | --value | ( Required ) Secret value | string | | --- # influx server-config Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/server-config/ * influx CLI 2.3.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx server-config` command displays the InfluxDB runtime [server configuration](/influxdb/v2/reference/config-options/). > [!Note] > To display the server configuration, you must use an [operator token](/influxdb/v2/admin/tokens/#operator-token). ## Usage ``` influx server-config [flags] influx server-config [command] ``` ## Examples ```sh # Show the server configuration. influx server-config # Show the server configuration as YAML. influx server-config --yaml ``` ## Flags |Flag| | Description | |----|-----------------|---------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| |`-h`| `--help` | Help for the `list` command | | |`--hide-headers` | Hide table headers (default `false`) | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | | | `--http-debug` | Inspect communication with InfluxDB servers | |`-i`| `--id` | Organization ID | | | `--json` | Output data as JSON (default `false`) | |`-n`| `--name` | Organization name | | | `--skip-verify` | Skip TLS certificate verification | |`-t`| `--token` | API token | | | `--toml` | Output configuration as TOML instead of JSON | | | `--yaml` | Output configuration as YAML instead of JSON | #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [config](/influxdb/v2/tags/config/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -c | --active-config | CLI configuration to use for command | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | | -h | --help | Help for the list command | | | --hide-headers | Hide table headers (default false ) | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | | | --http-debug | Inspect communication with InfluxDB servers | | -i | --id | Organization ID | | | --json | Output data as JSON (default false ) | | -n | --name | Organization name | | | --skip-verify | Skip TLS certificate verification | | -t | --token | API token | | | --toml | Output configuration as TOML instead of JSON | | | --yaml | Output configuration as YAML instead of JSON | --- # influx setup Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/setup/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.3 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx setup` command walks through the initial InfluxDB OSS setup process, creating a default user, organization, and bucket. > [!Note] > The **Operator token** created in the InfluxDB setup process has full read and write > access to all organizations in the database. ## Usage ``` influx setup [flags] ``` ## Flags |Flag| | Description |Data type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|---------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | |`-b`| `--bucket` | Primary bucket name | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-f`| `--force` | Skip confirmation prompt | | | |`-h`| `--help` | Help for the `setup` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-o`| `--org` | Primary organization name | string | | |`-p`| `--password` | Password for primary user | string | | |`-r`| `--retention` | Duration bucket will retain data (0 is infinite, default is 0) |duration | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | Token for admin user (auto-generated by default) | string | `INFLUX_TOKEN` | |`-u`| `--username` | Primary username | string | | > [!Note] > Valid `--retention` units are nanoseconds (`ns`), microseconds (`us` or `µs`), > milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). ## Examples ##### Set up InfluxDB interactively with prompts for required information ```sh influx setup ``` ##### Set up InfluxDB with all required information and skip confirmation ``` influx setup \ --org example-org \ --bucket example-bucket \ --username example-user \ --password ExAmPl3PA55W0rD \ --force ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [get-started](/influxdb/v2/tags/get-started/) | Flag | | Description | Data type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Data type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -b | --bucket | Primary bucket name | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --force | Skip confirmation prompt | | | | -h | --help | Help for the setup command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -o | --org | Primary organization name | string | | | -p | --password | Password for primary user | string | | | -r | --retention | Duration bucket will retain data (0 is infinite, default is 0) | duration | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | Token for admin user (auto-generated by default) | string | INFLUX_TOKEN | | -u | --username | Primary username | string | | --- # influx stacks Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/stacks/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx stacks` command and its subcommands list and manage InfluxDB stacks and associated resources. ## Usage ``` influx stacks [flags] influx stacks [command] ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------------|------------------| | [init](/influxdb/v2/reference/cli/influx/stacks/init/) |Initialize a stack| |[remove](/influxdb/v2/reference/cli/influx/stacks/remove/)| Remove a stack | ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `stacks` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--stack-id` | Stack IDs to filter by |stringArray| | | | `--stack-name` | Stack names to filter by |stringArray| | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all stacks](#list-all-stacks) * [Filter stacks by name](#filter-stacks-by-name) * [Filter stacks by ID](#filter-stacks-by-id) ##### List all stacks ```sh influx stacks ``` ##### Filter stacks by name ```sh influx stacks \ --stack-name stack1 \ --stack-name stack2 ``` ##### Filter stacks by ID ```sh influx stacks \ --stack-id 0Xx0oox00XXoxxoo1 \ --stack-id 0Xx0oox00XXoxxoo2 ``` #### Related * [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | init | Initialize a stack | | remove | Remove a stack | | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the stacks command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --stack-id | Stack IDs to filter by | stringArray | | | | --stack-name | Stack names to filter by | stringArray | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx stacks init Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/stacks/init/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx stacks init` command initializes an InfluxDB stack. ## Usage ``` influx stacks init [flags] ``` ## Flags |Flag| | Description | Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------------|---------------------------------------------------------------------|---------------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `init` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-d`|`--stack-description`| Stack description | string | | |`-n`| `--stack-name` | Stack name | string | | |`-u`| `--template-url` | Template URLs to associate with a stack |list of strings| | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Initialize a stack with a name and description ```sh influx stacks init -n "Example Stack" -d "InfluxDB stack for monitoring some awesome stuff" ``` ##### Initialize a stack with a name and URLs to associate with the stack ```sh influx stacks init -n "Example Stack" -u https://example.com/template-1.yml ``` #### Related * [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the init command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -d | --stack-description | Stack description | string | | | -n | --stack-name | Stack name | string | | | -u | --template-url | Template URLs to associate with a stack | list of strings | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx stacks remove Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/stacks/remove/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx stacks remove` command removes an InfluxDB stack and all associated resources. ## Usage ``` influx stacks remove [flags] ``` #### Command aliases `remove`, `rm`, `uninstall` ## Flags |Flag| | Description | Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|---------------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | | | `--force` | Skip confirmation prompt. | | | |`-h`| `--help` | Help for the `remove` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--stack-id` | Stack IDs to remove |list of strings| | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Remove a stack and all of its associated resources ```sh influx stacks remove --stack-id 0Xx0oox00XXoxxoo1 ``` #### Related * [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --force | Skip confirmation prompt. | | | | -h | --help | Help for the remove command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --stack-id | Stack IDs to remove | list of strings | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx stacks update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/stacks/update/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ * Updated in CLI v2.0.4 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx stacks update` command updates an InfluxDB stack. ## Usage ``` influx stacks update [flags] ``` ## Flags |Flag| | Description | Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|---------------------|---------------------------------------------------------------------|---------------|---------------------------------------------------------------------------------| | | `--addResource` | Associate an existing resource with a stack | string | | |`-c`| `--active-config` | CLI configuration to use for command | string | | | | `--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-f`| `--export-file` | Destination for exported template | string | | |`-h`| `--help` | Help for the `update` command | | | | | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--stack-id` | The stack ID to update | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-d`|`--stack-description`| Stack description | string | | |`-n`| `--stack-name` | Stack name | string | | |`-u`| `--template-url` | Template URLs to associate with a stack |list of strings| | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | #### Export an updated template To prevent accidental changes, we **strongly recommend** exporting a new template any time you add additional resources to a stack using the `--addResource` flag with the `influx stack update` command. The updated stack will differ from the previous template. If you apply the outdated template, InfluxDB will revert the updates and remove the added resources. ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Update a stack with a name and description](#update-a-stack-with-a-name-and-description) * [Update a stack with a name and urls to associate with stack](#update-a-stack-with-a-name-and-urls-to-associate-with-stack) * [Update a stack with new resources to manage](#update-a-stack-with-new-resources-to-manage) * [Update a stack with new resources and export the stack as a template](#update-a-stack-with-new-resources-and-export-the-stack-as-a-template) ##### Update a stack with a name and description ```sh influx stack update \ -i ab12cd34ef56 \ -n "New stack name" \ -d "New stack description" ``` ##### Update a stack with a name and URLs to associate with stack ```sh influx stack update \ -i ab12cd34ef56 \ -n "New stack name" \ --template-url https://example.com/template-1.yml \ --template-url https://example.com/template-2.yml ``` ##### Update a stack with new resources to manage ```sh influx stacks update \ --stack-id ab12cd34ef56 \ --addResource=Bucket=12ab34cd56ef \ --addResource=Dashboard=98zy76xw54vu ``` ##### Update a stack with new resources and export the stack as a template ```sh influx stacks update \ --stack-id ab12cd34ef56 \ --addResource=Bucket=12ab34cd56ef \ --export-file /path/to/template-file.yml ``` #### Related * [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | | --addResource | Associate an existing resource with a stack | string | | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --export-file | Destination for exported template | string | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --stack-id | The stack ID to update | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -d | --stack-description | Stack description | string | | | -n | --stack-name | Stack name | string | | | -u | --template-url | Template URLs to associate with a stack | list of strings | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task` command and its subcommands manage tasks in InfluxDB. ### Usage ``` influx task [flags] influx task [command] ``` ### Subcommands | Subcommand | Description | |-------------------------------------------------------------------|----------------------| | [create](/influxdb/v2/reference/cli/influx/task/create) | Create task | | [delete](/influxdb/v2/reference/cli/influx/task/delete) | Delete task | | [list](/influxdb/v2/reference/cli/influx/task/list) | List tasks | | [log](/influxdb/v2/reference/cli/influx/task/log) | Log related commands | |[retry-failed](/influxdb/v2/reference/cli/influx/task/retry-failed)|Retry failed task runs| | [run](/influxdb/v2/reference/cli/influx/task/run) | Run related commands | | [update](/influxdb/v2/reference/cli/influx/task/update) | Update task | ### Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `task` command| #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [tasks](/influxdb/v2/tags/tasks/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create task | | delete | Delete task | | list | List tasks | | log | Log related commands | | retry-failed | Retry failed task runs | | run | Run related commands | | update | Update task | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the task command | --- # influx task create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.4.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task create` command creates a task in InfluxDB. ## Usage ``` influx task create [task literal] [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-r`| `--cron` |*(InfluxDB Cloud only)* Cron expression to define when the task runs | string | | |`-e`| `--every` | *(InfluxDB Cloud only)* Interval at which the task runs | string | | |`-f`| `--file` | Path to Flux script file | string | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | *(InfluxDB Cloud only)* Task name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--script-id` | *(InfluxDB Cloud only)* Invokable script ID to execute | string | | | |`--script-params`| *(InfluxDB Cloud only)* Invokable script JSON parameters | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a task using raw Flux ```sh export FLUX_TASK=' option task = { name: "Example Task", every: 1d } from(bucket: "example-bucket") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "m") |> aggregateWindow(every: 1h, fn: mean) |> to(bucket: "default-ds-1d", org: "my-org") ' influx task create $FLUX_TASK ``` ##### Create a task from a file ```sh influx task create --file /path/to/example-task.flux ``` ##### Create a task using an invokable script ```sh influx task create \ --name "my task" \ --every "10h" \ --script-id 0001234 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -r | --cron | (InfluxDB Cloud only) Cron expression to define when the task runs | string | | | -e | --every | (InfluxDB Cloud only) Interval at which the task runs | string | | | -f | --file | Path to Flux script file | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | (InfluxDB Cloud only) Task name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --script-id | (InfluxDB Cloud only) Invokable script ID to execute | string | | | | --script-params | (InfluxDB Cloud only) Invokable script JSON parameters | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task delete` command deletes a task in InfluxDB. ## Usage ``` influx task delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) Task ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a task ```sh influx task delete --id 0Xx0oox00XXoxxoo1 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) Task ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task list` command lists and searches for tasks in InfluxDB. ## Usage ``` influx task list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Task ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--limit` | Number of tasks to find (default `100`) | integer | | |`-o`| `--org` | Task organization name | string | `INFLUX_ORG` | | | `--org-id` | Task organization ID | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-n`| `--user-id` | Task owner ID | string | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all tasks](#list-all-tasks) * [List a specific task](#list-a-specific-task) * [Limit the number of tasks returned to 20](#limit-the-number-of-tasks-returned-to-20) * [List all tasks created by a specific user](#list-all-tasks-created-by-a-specific-user) ##### List all tasks ```sh influx task list ``` ##### List a specific task ```sh influx task list --id 0Xx0oox00XXoxxoo1 ``` ##### Limit the number of tasks returned to 20 ```sh influx task list --limit 20 ``` ##### List all tasks created by a specific user ```sh influx task list --user-id 0Xx0oox00XXoxxoo1 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Task ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --limit | Number of tasks to find (default 100 ) | integer | | | -o | --org | Task organization name | string | INFLUX_ORG | | | --org-id | Task organization ID | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | -n | --user-id | Task owner ID | string | | --- # influx task log Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/log/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task log` command and its subcommand `list` output log information related to a task. ## Usage ``` influx task log [flags] influx task log [command] ``` ## Subcommands | Subcommand | Description | |-------------------------------------------------------|------------------| |[list](/influxdb/v2/reference/cli/influx/task/log/list)|List logs for task| ## Flags |Flag| | Description | |----|--------|--------------------------| |`-h`|`--help`|Help for the `log` command| #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [logs](/influxdb/v2/tags/logs/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | list | List logs for task | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the log command | --- # influx task log list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/log/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task log list` command outputs log information related to a task. ## Usage ``` influx task log list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--run-id` | Run ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--task-id` | (Required) Task ID | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List logs from all task executions ```sh influx task log list --task-id 0Xx0oox00XXoxxoo1 ``` ##### List logs from a specific task execution ```sh influx task log list \ --task-id 0Xx0oox00XXoxxoo1 \ --run-id ox0Xx0ooxx00XXoo2 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --run-id | Run ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --task-id | ( Required ) Task ID | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task retry-failed Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/retry-failed/ * influx CLI 2.0.5+ * InfluxDB 2.0.5+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task retry-failed` command retries failed InfluxDB task runs. ## Usage ``` influx task retry-failed [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|-------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| | | `--after` | Retry task runs that occurred after this time (RFC3339 timestamp) | string | | |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--before` | Retry task runs that occurred before this time (RFC3339 timestamp) | string | | | | `--dry-run` | Print information about task runs that would be retried | | | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | Task ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Task organization name | string | `INFLUX_ORG` | | | `--org-id` | Task organization ID | string | `INFLUX_ORG_ID` | | | `--run-limit` |Maximum number of failed runs to retry per task (`1-500`, default `100`) | integer | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--task-limit` |Maximum number of tasks to retry failed runs for (`1-500`, default `100`)| integer | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token > [!Note] > #### Required permissions > > Use an [**Operator** or**All Access** token](/influxdb/v2/admin/tokens/) to retry failed tasks. * [Retry failed task runs for a specific task ID](#retry-failed-task-runs-for-a-specific-task-id) * [Retry failed task runs that occurred before a specific time](#retry-failed-task-runs-that-occurred-before-a-specific-time) * [Retry failed task runs that occurred after a specific time](#retry-failed-task-runs-that-occurred-after-a-specific-time) * [Retry failed task runs that occurred in a specific time range](#retry-failed-task-runs-that-occurred-in-a-specific-time-range) * [Retry failed runs for a limited number of tasks](#retry-failed-runs-for-a-limited-number-of-tasks) * [Retry a limited number of failed runs for a task](#retry-a-limited-number-of-failed-runs-for-a-task) * [Print information about runs that will be retried](#print-information-about-runs-that-will-be-retried) ##### Retry failed task runs for a specific task ID ```sh influx task retry-failed \ --id 0Xx0oox00XXoxxoo1 ``` ##### Retry failed task runs that occurred before a specific time ```sh influx task retry-failed \ --before 2021-01-01T00:00:00Z ``` ##### Retry failed task runs that occurred after a specific time ```sh influx task retry-failed \ --after 2021-01-01T00:00:00Z ``` ##### Retry failed task runs that occurred in a specific time range ```sh influx task retry-failed \ --after 2021-01-01T00:00:00Z \ --before 2021-01-01T23:59:59Z ``` ##### Retry failed runs for a limited number of tasks ```sh influx task retry-failed \ --task-limit 5 ``` ##### Retry a limited number of failed runs for a task ```sh influx task retry-failed \ --id 0Xx0oox00XXoxxoo1 \ --run-limit 5 ``` ##### Print information about runs that will be retried ```sh influx task retry-failed \ --dry-run ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | | --after | Retry task runs that occurred after this time (RFC3339 timestamp) | string | | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --before | Retry task runs that occurred before this time (RFC3339 timestamp) | string | | | | --dry-run | Print information about task runs that would be retried | | | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | Task ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Task organization name | string | INFLUX_ORG | | | --org-id | Task organization ID | string | INFLUX_ORG_ID | | | --run-limit | Maximum number of failed runs to retry per task ( 1-500 , default 100 ) | integer | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --task-limit | Maximum number of tasks to retry failed runs for ( 1-500 , default 100 ) | integer | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task run Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/run/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task run` command and its subcommand `list` output information related to runs of a task. ## Usage ``` influx task run [flags] influx task run [command] ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------|--------------------| | [list](/influxdb/v2/reference/cli/influx/task/run/list) |List runs for a task| |[retry](/influxdb/v2/reference/cli/influx/task/run/retry)| Retry a task | ## Flags |Flag| | Description | |----|--------|--------------------------| |`-h`|`--help`|Help for the `run` command| #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Subcommand | Description | | --- | --- | | Subcommand | Description | | list | List runs for a task | | retry | Retry a task | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the run command | --- # influx task run list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/run/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task run list` command outputs information related to runs of a task. ## Usage ``` influx task run list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | | `--after` | After-time for filtering | string | | | | `--before` | Before-time for filtering | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--limit` | Limit the number of results | integer | | | | `--run-id` | Run ID | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--task-id` | (Required) Task ID | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all runs of a task](#list-all-runs-of-a-task) * [List a specific run of a task](#list-a-specific-run-of-a-task) * [Limit the number of returned task runs to 20](#limit-the-number-of-returned-task-runs-to-20) ##### List all runs of a task ```sh influx task run list --task-id 0Xx0oox00XXoxxoo1 ``` ##### List a specific run of a task ```sh influx task run list \ --task-id 0Xx0oox00XXoxxoo1 \ --run-id ox0Xx0ooxx00XXoo2 ``` ##### Limit the number of returned task runs to 20 ```sh influx task run list \ --task-id 0Xx0oox00XXoxxoo1 \ --limit 20 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --after | After-time for filtering | string | | | | --before | Before-time for filtering | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --limit | Limit the number of results | integer | | | | --run-id | Run ID | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --task-id | ( Required ) Task ID | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task run retry Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/run/retry/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task run retry` command retries to run a task in InfluxDB. ## Usage ``` influx task run retry [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `retry` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-r`| `--run-id` | (Required) Run ID | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-i`| `--task-id` | (Required) Task ID | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token > [!Note] > #### Required permissions > > Use an [**Operator** or**All Access** token](/influxdb/v2/admin/tokens/) to retry tasks. ##### Retry a task run ```sh influx task run retry \ --task-id 0Xx0oox00XXoxxoo1 \ --run-id ox0Xx0ooxx00XXoo2 ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the retry command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -r | --run-id | ( Required ) Run ID | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -i | --task-id | ( Required ) Task ID | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx task update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/task/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.4.0 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx task update` command updates information related to tasks in InfluxDB. ## Usage ``` influx task update [task literal] [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-f`| `--file` | Path to Flux script file | string | | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | string | | |`-i`| `--id` | (Required) Task ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--script-id` | *(InfluxDB Cloud only)* Invokable script ID to execute | string | | | |`--script-params`| *(InfluxDB Cloud only)* Invokable script JSON parameters | string | | | | `--status` | Update task status (`active` or `inactive`) | string | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Example > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Update a task from a Flux string](#update-a-task-from-a-flux-string) * [Update a task from a Flux file](#update-a-task-from-a-flux-file) * [Update a task from a script ID](#update-a-task-from-a-script-id) * [Enable a task](#enable-a-task) * [Disable a task](#disable-a-task) ##### Update a task from a Flux string ```sh export UPDATED_FLUX_TASK=' option task = { name: "Example Task", every: 1d } from(bucket: "example-bucket") |> range(start: -task.every) |> filter(fn: (r) => r._measurement == "m") |> aggregateWindow(every: 1h, fn: mean) |> to(bucket: "default-ds-1d", org: "my-org") ' influx task update \ --id 0001234 \ $UPDATED_FLUX_TASK ``` ##### Update a task from a Flux file ```sh influx task update \ --id 0001234 \ --file /path/to/example-task.flux ``` ##### Update a task from a script ID ```sh influx task update \ --id 0001234 \ --script-id 0004567 ``` ##### Enable a task ```sh influx task update \ --id 0001234 \ --status active ``` ##### Disable a task ```sh influx task update \ --id 0001234 \ --status inactive ``` #### Related * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -f | --file | Path to Flux script file | string | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | string | | | -i | --id | ( Required ) Task ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --script-id | (InfluxDB Cloud only) Invokable script ID to execute | string | | | | --script-params | (InfluxDB Cloud only) Invokable script JSON parameters | string | | | | --status | Update task status ( active or inactive ) | string | | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx telegrafs Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/telegrafs/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx telegrafs` command lists Telegraf configurations. Subcommands manage Telegraf configurations. ## Usage ```sh influx telegrafs [flags] influx telegrafs [command] ``` ## Subcommands | Subcommand | Description | |------------------------------------------------------------|-------------------------------| |[create](/influxdb/v2/reference/cli/influx/telegrafs/create)|Create a Telegraf configuration| | [rm](/influxdb/v2/reference/cli/influx/telegrafs/rm) |Remove a Telegraf configuration| |[update](/influxdb/v2/reference/cli/influx/telegrafs/update)|Update a Telegraf configuration| ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `telegrafs` command | | | | |`--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | |`-i`| `--id` | Telegraf configuration ID to retrieve | string | | | | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List all Telegraf configurations ```sh influx telegrafs ``` ##### List a Telegraf configuration with the specified ID ```sh influx telegrafs --id 0Xx0oox00XXoxxoo1 ``` #### Related * [Telegraf configurations](/influxdb/v2/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [telegraf](/influxdb/v2/tags/telegraf/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a Telegraf configuration | | rm | Remove a Telegraf configuration | | update | Update a Telegraf configuration | | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the telegrafs command | | | | | --hide-headers | Hide table headers | | INFLUX_HIDE_HEADERS | | -i | --id | Telegraf configuration ID to retrieve | string | | | | --json | Output data as JSON | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx telegrafs create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/telegrafs/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx telegrafs create` command creates a Telegraf configuration in InfluxDB using a provided Telegraf configuration file. ## Usage ```sh influx telegrafs create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Telegraf configuration description | string | | |`-f`| `--file` | Path to Telegraf configuration | string | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | | | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Telegraf configuration name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a Telegraf configuration ```sh influx telegrafs create \ --name "Example configuration name" \ --description "Example Telegraf configuration description" \ --file /path/to/telegraf.conf ``` ##### Create a Telegraf configuration via stdin ```sh cat /path/to/telegraf.conf | influx telegrafs create \ --name "Example configuration name" \ --description "Example Telegraf configuration description" \ ``` #### Related * [Telegraf configurations](/influxdb/v2/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Telegraf configuration description | string | | | -f | --file | Path to Telegraf configuration | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers | | INFLUX_HIDE_HEADERS | | | --json | Output data as JSON | | INFLUX_OUTPUT_JSON | | -n | --name | Telegraf configuration name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx telegrafs rm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/telegrafs/rm/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx telegrafs rm` command removes Telegraf configurations from InfluxDB. ## Usage ```sh influx telegrafs rm [flags] ``` #### Command aliases `rm`, `remove` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `rm` command | | | | |`--hide-headers` | Hide the table headers | | `INFLUX_HIDE_HEADERS` | |`-i`| `--id` | Telegraf configuration ID to remove |stringArray| | | | `--json` | Output data as json | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Remove a Telegraf configuration ```sh influx telegrafs rm --id ab12cd34ef56 ``` ##### Remove multiple Telegraf configurations ```sh influx telegrafs rm \ --i 0Xx0oox00XXoxxoo1 \ --i oox0Xx0ox00XXxoo2 ``` #### Related * [Telegraf configurations](/influxdb/v2/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the rm command | | | | | --hide-headers | Hide the table headers | | INFLUX_HIDE_HEADERS | | -i | --id | Telegraf configuration ID to remove | stringArray | | | | --json | Output data as json | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx telegrafs update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/telegrafs/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx telegrafs update` command updates a Telegraf configuration to match the specified parameters. If a name or description are not provided, they are set to an empty string. ## Usage ```sh influx telegrafs update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Telegraf configuration description | string | | |`-f`| `--file` | Path to Telegraf configuration | string | | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | | | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Telegraf configuration name | string | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update a Telegraf configuration ```sh influx telegrafs update \ --id 0Xx0oox00XXoxxoo1 \ --name "Example configuration name" \ --description "Example Telegraf configuration description" \ --file /path/to/telegraf.conf ``` ##### Update a Telegraf configuration via stdin ```sh cat /path/to/telegraf.conf | influx telegrafs update \ --id 0Xx0oox00XXoxxoo1 \ --name "Example configuration name" \ --description "Example Telegraf configuration description" \ ``` #### Related * [Telegraf configurations](/influxdb/v2/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Telegraf configuration description | string | | | -f | --file | Path to Telegraf configuration | string | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers | | INFLUX_HIDE_HEADERS | | | --json | Output data as JSON | | INFLUX_OUTPUT_JSON | | -n | --name | Telegraf configuration name | string | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx template Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/template/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx template` command summarizes the specified InfluxDB template. The command returns information about all resources included in the template. ## Usage ``` influx template [flags] influx template [command] ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------|-------------------| |[validate](/influxdb/v2/reference/cli/influx/template/validate)|Validate a template| ## Flags |Flag| | Description |Input Type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------------|------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| | | `--disable-color` | Disable color in output | | | | |`--disable-table-borders`| Disable table borders | | | |`-e`| `--encoding` | Template encoding (`yaml`,`yml`,`json`, or `jsonnet`) | string | | |`-f`| `--file` | Path to template file (supports HTTP(S) URLs or file paths) |stringArray| | |`-h`| `--help` | Help for the `template` command | | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-R`| `--recurse` |Recurse through files in the directory specified in `-f`, `--file`| | | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token **Summarize InfluxDB Templates:** * [from a local file](#summarize-an-influxdb-template-from-a-local-file) * [from multiple files](#summarize-influxdb-templates-from-multiple-files) * [from a URL](#summarize-an-influxdb-template-from-a-url) * [from a directory](#summarize-all-influxdb-templates-in-a-directory) * [using a specific encoding](#specify-the-encoding-of-the-influxdb-template-to-summarize) ##### Summarize an InfluxDB template from a local file ```sh influx template --file /path/to/template.yml ``` ##### Summarize InfluxDB templates from multiple files ```sh influx template \ --file /path/to/template1.yml \ --file /path/to/template2.yml ``` ##### Summarize an InfluxDB template from a URL ```sh influx template --file https://example.com/path/to/template.yml ``` ##### Summarize all InfluxDB templates in a directory ```sh influx template \ --file /path/to/template/dir/ \ --recurse ``` ##### Specify the encoding of the InfluxDB template to summarize ```sh influx template \ --file /path/to/template \ --encoding json ``` #### Related * [InfluxDB templates](/influxdb/v2/tools/influxdb-templates/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/v2/tags/templates/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | validate | Validate a template | | Flag | | Description | Input Type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input Type | Maps to ? | | | --disable-color | Disable color in output | | | | | --disable-table-borders | Disable table borders | | | | -e | --encoding | Template encoding ( yaml , yml , json , or jsonnet ) | string | | | -f | --file | Path to template file (supports HTTP(S) URLs or file paths) | stringArray | | | -h | --help | Help for the template command | | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -R | --recurse | Recurse through files in the directory specified in -f , --file | | | --- # influx template validate Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/template/validate/ * influx CLI 2.0.1+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx template validate` command validates the provided InfluxDB template. ## Usage ``` influx template validate [flags] ``` ## Flags |Flag| | Description |Input Type | |----|------------|------------------------------------------------------------------|-----------| |`-e`|`--encoding`| Template encoding | string | |`-f`| `--file` | Path to template file (supports HTTP(S) URLs or file paths) |stringArray| |`-h`| `--help` | Help for the `validate` command | | |`-R`|`--recurse` |Recurse through files in the directory specified in `-f`, `--file`| | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token **Validate InfluxDB Templates:** * [from a local file](#validate-an-influxdb-template-from-a-local-file) * [from multiple files](#validate-influxdb-templates-from-multiple-files) * [from a URL](#validate-an-influxdb-template-from-a-url) * [from a directory](#validate-all-influxdb-templates-in-a-directory) * [using a specific encoding](#specify-the-encoding-of-the-influxdb-template-to-validate) ##### Validate an InfluxDB template from a local file ```sh influx template validate --file /path/to/template.yml ``` ##### Validate InfluxDB templates from multiple files ```sh influx template validate \ --file /path/to/template1.yml \ --file /path/to/template2.yml ``` ##### Validate an InfluxDB template from a URL ```sh influx template validate --file https://example.com/path/to/template.yml ``` ##### Validate all InfluxDB templates in a directory ```sh influx template validate \ --file /path/to/template/dir/ \ --recurse ``` ##### Specify the encoding of the InfluxDB template to validate ```sh influx template validate \ --file /path/to/template \ --encoding json ``` #### Related * [InfluxDB templates](/influxdb/v2/tools/influxdb-templates/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | -e | --encoding | Template encoding | string | | -f | --file | Path to template file (supports HTTP(S) URLs or file paths) | stringArray | | -h | --help | Help for the validate command | | | -R | --recurse | Recurse through files in the directory specified in -f , --file | | --- # influx transpile Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/transpile/ * influx CLI 2.0.0 – 2.0.5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Warning] > ### Removed in InfluxDB OSS 2.0.5 > > The `influx transpile` command was removed in **InfluxDB 2.0.5**.[Use InfluxQL to query InfluxDB](/influxdb/v2/query-data/influxql/). > For information about manually converting InfluxQL queries to Flux, see: > > * [Get started with Flux](/flux/v0/get-started/) > * [Query data with Flux](/influxdb/v2/query-data/flux/) > * [Migrate continuous queries to Flux tasks](/influxdb/v2/upgrade/v1-to-v2/migrate-cqs/) The `influx transpile` command transpiles an InfluxQL query to Flux source code. The transpiled query assumes the bucket name is `/`and includes absolute time ranges using the provided `--now` time. ## Usage ``` influx transpile [InfluxQL query] [flags] ``` > [!Note] > The InfluxQL query must be valid and contain both a database and measurement. > See the [InfluxQL documentation](/influxdb/v1/query_language/) for more information. ## Flags |Flag| | Description | |----|--------|--------------------------------------------------------------------------| |`-h`|`--help`| Help for the `transpile` command | | |`--now` |RFC3339Nano timestamp to use as `now()` time (default is current UTC time)| ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Transpile InfluxQL queries to Flux ```sh ## Transpile an InfluxQL query that specifies the database, ## retention policy, and measurement. influx transpile 'SELECT example-field FROM db.rp.measurement' ## Transpile InfluxQL query using default retention policy influx transpile 'SELECT example-field FROM db..measurement' ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the transpile command | | | --now | RFC3339Nano timestamp to use as now() time (default is current UTC time) | --- # influx user Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user` command and its subcommands manage user information in InfluxDB. ## Usage ``` influx user [flags] influx user [command] ``` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------|------------------------| | [create](/influxdb/v2/reference/cli/influx/user/create) | Create a user | | [delete](/influxdb/v2/reference/cli/influx/user/delete) | Delete a user | | [list](/influxdb/v2/reference/cli/influx/user/list) | List users | |[password](/influxdb/v2/reference/cli/influx/user/password)|Update a user’s password| | [update](/influxdb/v2/reference/cli/influx/user/update) | Update a user | ## Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `user` command| #### Related * [Manage users](/influxdb/v2/admin/users/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [users](/influxdb/v2/tags/users/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create a user | | delete | Delete a user | | list | List users | | password | Update a user’s password | | update | Update a user | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the user command | --- # influx user create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user create` command creates a user in InfluxDB. ## Usage ``` influx user create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | (Required) Username | string | `INFLUX_NAME` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-p`| `--password` | User password | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a user ```sh influx user create \ --name example-username \ --password ExAmPl3PA55W0rD ``` #### Related * [Manage users](/influxdb/v2/admin/users/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | ( Required ) Username | string | INFLUX_NAME | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -p | --password | User password | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx user delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user delete` command deletes a specified user in InfluxDB. ## Usage ``` influx user delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | |`-i`| `--id` | (Required) User ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a user ```sh influx user delete --id 0Xx0oox00XXoxxoo1 ``` #### Related * [Manage users](/influxdb/v2/admin/users/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | ( Required ) User ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx user list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user list` command lists users in InfluxDB. ## Usage ``` influx user list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | |`-i`| `--id` | User ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Username | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all users](#list-all-users) * [List a specific user by username](#list-a-specific-user-by-username) * [List a specific user by ID](#list-a-specific-user-by-id) ##### List all users ```sh influx user list ``` ##### List a specific user by username ```sh influx user list --name example-username ``` ##### List a specific user by ID ```sh influx user list --id 0Xx0oox00XXoxxoo1 ``` #### Related * [Manage users](/influxdb/v2/admin/users/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | User ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Username | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx user password Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/password/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user password` command updates the password for a user in InfluxDB. ## Usage ``` influx user password [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `password` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | |`-i`| `--id` | User ID | string | | |`-n`| `--name` | Username | string | | | | `--password` | Use `password` flag to send your password instead of typing it in | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update a user password using a username ```sh influx user password --name example-username # Prompts for password ``` ##### Update a user password using a user ID ```sh influx user password --id 0Xx0oox00XXoxxoo1 # Prompts for password ``` #### Related * [Change your password](/influxdb/v2/admin/users/change-password/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the password command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | User ID | string | | | -n | --name | Username | string | | | | --password | Use password flag to send your password instead of typing it in | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx user update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/user/update/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx user update` command updates information related to a user in InfluxDB. ## Usage ``` influx user update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|---------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| CLI configuration to use for command | string | | | |`--configs-path` |Path to `influx` CLI configurations (default `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | |`-i`| `--id` | (Required) User ID | string | | | | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | |`-n`| `--name` | Username | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update a username ```sh influx user update \ --id 0Xx0oox00XXoxxoo1 \ --name new-username ``` #### Related * [Manage users](/influxdb/v2/admin/users/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the update command | | | | | --hide-headers | Hide table headers (default false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | -i | --id | ( Required ) User ID | string | | | | --json | Output data as JSON (default false ) | | INFLUX_OUTPUT_JSON | | -n | --name | Username | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx v1 Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1` command provides commands for working with the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) in InfluxDB 2.10. ## Usage ``` influx v1 [flags] influx v1 [command] ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------|-----------------------------------------------------------------| | [auth](/influxdb/v2/reference/cli/influx/v1/auth/) | Authorization management commands for v1 APIs | | [dbrp](/influxdb/v2/reference/cli/influx/v1/dbrp/) |Database retention policy mapping management commands for v1 APIs| |[shell](/influxdb/v2/reference/cli/influx/v1/shell/)| Start an InfluxQL shell | ## Flags |Flag| | Description | |----|--------|-------------------------| |`-h`|`--help`|Help for the `v1` command| #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) | Subcommand | Description | | --- | --- | | Subcommand | Description | | auth | Authorization management commands for v1 APIs | | dbrp | Database retention policy mapping management commands for v1 APIs | | shell | Start an InfluxQL shell | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the v1 command | --- # influx v1 auth Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth` subcommands provide authorization management for the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). InfluxDB 2.10 uses [API tokens](/influxdb/v2/admin/tokens/) to authorize API requests. The [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/) lets clients authenticate with InfluxDB 2.10 using the InfluxDB 1.x convention of username and password. > [!Note] > v1-compatible authorizations are separate from the credentials used to log > into the InfluxDB user interface. ## Usage ``` influx v1 auth [flags] influx v1 auth [command] ``` #### Command aliases `auth`, `authorization` ## Commands | Command | Description | |-----------------------------------------------------------------------|--------------------------------------------| | [create](/influxdb/v2/reference/cli/influx/v1/auth/create/) | Create authorization | | [delete](/influxdb/v2/reference/cli/influx/v1/auth/delete/) | Delete authorization | | [list](/influxdb/v2/reference/cli/influx/v1/auth/list/) | List authorizations | | [set-active](/influxdb/v2/reference/cli/influx/v1/auth/set-active/) | Activate an authorization | |[set-inactive](/influxdb/v2/reference/cli/influx/v1/auth/set-inactive/)| Deactivate an authorization | |[set-password](/influxdb/v2/reference/cli/influx/v1/auth/set-password/)|Set a password for an existing authorization| ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `v1 auth `command| #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Command | Description | | --- | --- | | Command | Description | | create | Create authorization | | delete | Delete authorization | | list | List authorizations | | set-active | Activate an authorization | | set-inactive | Deactivate an authorization | | set-password | Set a password for an existing authorization | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the v1 auth command | --- # influx v1 auth create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/create/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.3 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth create` command creates a legacy authorization with the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth create [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|----------------------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | |`-d`| `--description` | Token description | string | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | | | `--no-password` |Don’t prompt for a password (to use the token, you must set a password with `influx v1 auth set-password`)| | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--password` | Password to set on the authorization | | | | | `--read-bucket` | Bucket ID to assign read permissions to |stringArray| | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | | | `--username` | (Required) Token username | string | | | |`--write-bucket` | Bucket ID to assign write permissions to |stringArray| | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a v1 authorization with read and write permissions ```sh # Create an authorization with read and write access to bucket 00xX00o0X001 # but only read access to bucket 00xX00o0X002 influx v1 auth create \ --read-bucket 00xX00o0X001 \ --read-bucket 00xX00o0X002 \ --write-bucket 00xX00o0X001 \ --username example-user ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -d | --description | Token description | string | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | | --no-password | Don’t prompt for a password (to use the token, you must set a password with influx v1 auth set-password ) | | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --password | Password to set on the authorization | | | | | --read-bucket | Bucket ID to assign read permissions to | stringArray | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | | --username | ( Required ) Token username | string | | | | --write-bucket | Bucket ID to assign write permissions to | stringArray | | --- # influx v1 auth delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/delete/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth delete` command deletes an authorization in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | |`-i`| `--id` | (Required) Authorization ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | | | `--username` | Authorization username | string | `INFLUX_USERNAME` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a v1 authorization ```sh influx v1 auth delete --id 00xX00o0X001 ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | -i | --id | ( Required ) Authorization ID | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | | --username | Authorization username | string | INFLUX_USERNAME | --- # influx v1 auth list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/list/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth list` command lists and searches authorizations in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | |`-i`| `--id` | Authorization ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-u`| `--user` | InfluxDB user | string | | | | `--user-id` | InfluxDB user ID | string | | | | `--username` | Authorization username | string | `INFLUX_USERNAME` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [List all v1 authorizations](#list-all-v1-authorizations) * [List v1 authorizations associated with a username](#list-v1-authorizations-associated-with-a-username) * [List v1 authorizations associated with a user ID](#list-v1-authorizations-associated-with-a-user-id) * [List a specific v1 authorization by ID](#list-a-specific-v1-authorization-by-id) ##### List all v1 authorizations ```sh influx v1 auth list ``` ##### List v1 authorizations associated with a username ```sh influx v1 auth list --user example-username ``` ##### List v1 authorizations associated with a user ID ```sh influx v1 auth list --user-id 00xX00o0X001 ``` ##### List a specific v1 authorization by ID ```sh influx v1 auth list --id 00xX00o0X001 ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the list command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | -i | --id | Authorization ID | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | -u | --user | InfluxDB user | string | | | | --user-id | InfluxDB user ID | string | | | | --username | Authorization username | string | INFLUX_USERNAME | --- # influx v1 auth set-active Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/set-active/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth set-active` command activates an authorization in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). Only active authorizations grant access to InfluxDB. ## Usage ``` influx v1 auth set-active [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `$INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `set-active` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | | | `--host` | (Required) HTTP address of InfluxDB | string | `$INFLUX_HOST` | |`-i`| `--id` | Authorization ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `$INFLUX_TOKEN` | | | `--username` | Authorization username | string | `$INFLUX_USERNAME` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Activate a v1 authorization ```sh influx v1 auth set-active --id 00xX00o0X001 ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | $INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | $INFLUX_CONFIGS_PATH | | -h | --help | Help for the set-active command | | | | | --hide-headers | Hide the table headers (default: false ) | | $INFLUX_HIDE_HEADERS | | | --host | ( Required ) HTTP address of InfluxDB | string | $INFLUX_HOST | | -i | --id | Authorization ID | string | | | | --json | Output data as JSON (default: false ) | | $INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | $INFLUX_TOKEN | | | --username | Authorization username | string | $INFLUX_USERNAME | --- # influx v1 auth set-inactive Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/set-inactive/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth set-inactive` command deactivates an authorization in the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). Inactive authorizations **do not** grant access to InfluxDB. ## Usage ``` influx v1 auth set-inactive [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `set-inactive` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | |`-i`| `--id` | (Required) Authorization ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | | | `--username` | Authorization username | string | `INFLUX_USERNAME` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Deactivate a v1 authorization ```sh influx v1 auth set-inactive --id 00xX00o0X001 ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the set-inactive command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | -i | --id | ( Required ) Authorization ID | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | | --username | Authorization username | string | INFLUX_USERNAME | --- # influx v1 auth set-password Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/auth/set-password/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.3 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 auth set-password` command sets a password for an existing authorization in the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth set-password [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `set-password` command | | | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | |`-i`| `--id` | Authorization ID | string | | | | `--password` | Password to set on the authorization | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | | | `--username` | Authorization username | string | `INFLUX_USERNAME` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Set a password for a v1 authorization ```sh influx v1 auth set-password \ --id 00xX00o0X001 \ --password ExAmPl3PA55W0rD ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/v2/tags/authorization/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the set-password command | | | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | -i | --id | Authorization ID | string | | | | --password | Password to set on the authorization | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | | | --username | Authorization username | string | INFLUX_USERNAME | --- # influx v1 dbrp Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/dbrp/ * influx CLI 2.0.2+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 dbrp` subcommands manage database and retention policy mappings (DBRP) for the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp [flags] influx v1 dbrp [command] ``` ## Commands | Command | Description | |-----------------------------------------------------------|---------------------| |[create](/influxdb/v2/reference/cli/influx/v1/dbrp/create/)|Create a DBRP mapping| |[delete](/influxdb/v2/reference/cli/influx/v1/dbrp/delete/)|Delete a DBRP mapping| | [list](/influxdb/v2/reference/cli/influx/v1/dbrp/list/) | List DBRP mappings | |[update](/influxdb/v2/reference/cli/influx/v1/dbrp/update/)|Update a DBRP mapping| ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `v1 dbrp `command| #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/v2/tags/dbrp/) | Command | Description | | --- | --- | | Command | Description | | create | Create a DBRP mapping | | delete | Delete a DBRP mapping | | list | List DBRP mappings | | update | Update a DBRP mapping | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the v1 dbrp command | --- # influx v1 dbrp create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/dbrp/create/ * influx CLI 2.0.2+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 dbrp create` command creates a DBRP mapping with the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | | `--bucket-id` | Bucket ID to map to | | | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | | | `--db` | InfluxDB v1 database to map from | | | | | `--default` | Set DBRP mapping’s retention policy as default | | | |`-h`| `--help` | Help for the `create` command | | | | |`--hide-headers` | Hide table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--rp` | InfluxDB v1 retention policy to map from | | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Create a DBRP mapping ```sh influx v1 dbrp create \ --bucket-id 12ab34cd56ef \ --db example-db \ --rp example-rp \ --default ``` If a DBRP mapping already exists for the database name, the `--default` flag sets the new mapping as the default. #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/v2/tags/dbrp/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --bucket-id | Bucket ID to map to | | | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --db | InfluxDB v1 database to map from | | | | | --default | Set DBRP mapping’s retention policy as default | | | | -h | --help | Help for the create command | | | | | --hide-headers | Hide table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --rp | InfluxDB v1 retention policy to map from | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx v1 dbrp delete Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/dbrp/delete/ * influx CLI 2.0.2+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 dbrp delete` command deletes a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | |`-h`| `--help` | Help for the `delete` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--id` | (Required) DBRP ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Delete a DBRP mapping ```sh influx v1 dbrp delete --id 12ab34cd56ef ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/v2/tags/dbrp/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | -h | --help | Help for the delete command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --id | ( Required ) DBRP ID | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx v1 dbrp list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/dbrp/list/ * influx CLI 2.0.2+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 dbrp list` command lists and searches DBRP mappings in the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp list [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | | `--bucket-id` | Bucket ID | | | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | | | `--db` | Filter DBRP mappings by database | | | | | `--default` | Limit results to default mapping | | | |`-h`| `--help` | Help for the `list` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--id` | Limit results to a specified mapping | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--rp` | Filter DBRP mappings by InfluxDB v1 retention policy | string | `INFLUX_ORG` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### List all DBRP mappings in your organization ```sh influx v1 dbrp list ``` ##### List DBRP mappings for specific buckets ```sh influx v1 dbrp list \ --bucket-id 12ab34cd56ef78 \ --bucket-id 09zy87xw65vu43 ``` ##### List DBRP mappings with a specific database ```sh influx v1 dbrp list --db example-db ``` ##### List DBRP mappings with a specific retention policy ```sh influx v1 dbrp list --rp example-rp ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [dbrp](/influxdb/v2/tags/dbrp/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --bucket-id | Bucket ID | | | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --db | Filter DBRP mappings by database | | | | | --default | Limit results to default mapping | | | | -h | --help | Help for the list command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --id | Limit results to a specified mapping | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --rp | Filter DBRP mappings by InfluxDB v1 retention policy | string | INFLUX_ORG | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx v1 dbrp update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/dbrp/update/ * influx CLI 2.0.2+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 dbrp update` command updates a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | | | `--default` | Set DBRP mapping’s retention policy as default | | | |`-h`| `--help` | Help for the `update` command | | | | |`--hide-headers` | Hide the table headers (default: `false`) | | `INFLUX_HIDE_HEADERS` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--id` | (Required) DBRP ID | string | | | | `--json` | Output data as JSON (default: `false`) | | `INFLUX_OUTPUT_JSON` | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-r`| `--rp` | InfluxDB v1 retention policy to map from | | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Set a DBRP mapping as default ```sh influx v1 dbrp update \ --id 12ab34cd56ef78 \ --default ``` ##### Update the retention policy of a DBRP mapping ```sh influx v1 dbrp update \ --id 12ab34cd56ef78 \ --rp new-rp-name ``` #### Related * [Upgrade from InfluxDB 1.x to 2.10](/influxdb/v2/install/upgrade/v1-to-v2/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [`influx` CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/v2/tags/dbrp/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --default | Set DBRP mapping’s retention policy as default | | | | -h | --help | Help for the update command | | | | | --hide-headers | Hide the table headers (default: false ) | | INFLUX_HIDE_HEADERS | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --id | ( Required ) DBRP ID | string | | | | --json | Output data as JSON (default: false ) | | INFLUX_OUTPUT_JSON | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -r | --rp | InfluxDB v1 retention policy to map from | | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx v1 shell Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/v1/shell/ * influx CLI 2.4.0+ * InfluxDB 2.0.1+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx v1 shell` subcommand starts an InfluxQL shell (REPL). > [!Note] > #### Set up database and retention policy (DBRP) mapping > > InfluxQL queries require a database and retention policy to query data. > In InfluxDB 2.10, databases and retention policies have been > combined and replaced with [buckets](/influxdb/v2/reference/glossary/#bucket). > To use the InfluxQL to query an InfluxDB 2.10 bucket, first > map your DBRP combinations to an appropriate bucket. For more information, see[Query data with InfluxQL](/influxdb/v2/query-data/influxql/). ## Usage ```sh influx v1 shell [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-----------------|------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------| |`-c`|`--active-config`| Config name to use for command | string | `INFLUX_ACTIVE_CONFIG` | | |`--configs-path` |Path to the influx CLI configurations (default: `~/.influxdbv2/configs`)| string | `INFLUX_CONFIGS_PATH` | | | `--host` | HTTP address of InfluxDB | string | `INFLUX_HOST` | | | `--http-debug` | Inspect communication with InfluxDB servers. | | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Start an InfluxQL shell ```sh influx v1 shell ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) * [Query data with InfluxQL](/influxdb/v2/query-data/influxql/) * [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) [InfluxQL](/influxdb/v2/tags/influxql/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | Config name to use for command | string | INFLUX_ACTIVE_CONFIG | | | --configs-path | Path to the influx CLI configurations (default: ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --host | HTTP address of InfluxDB | string | INFLUX_HOST | | | --http-debug | Inspect communication with InfluxDB servers. | | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | -t | --token | API token | string | INFLUX_TOKEN | --- # influx version Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/version/ * influx CLI 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx version` command outputs the current version of the `influx`command line interface (CLI). ## Usage ``` influx version [flags] ``` ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `version` command| [influx](/influxdb/v2/tags/influx/)[cli](/influxdb/v2/tags/cli/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the version command | --- # influx write Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/write/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ * Updated in CLI v2.0.5 This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx write` command writes data to InfluxDB via stdin or from a specified file. Write data using [line protocol](/influxdb/v2/reference/syntax/line-protocol),[annotated CSV](/influxdb/v2/reference/syntax/annotated-csv), or[extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended/). If you write CSV data, CSV annotations determine how the data translates into line protocol. ## Usage ``` influx write [flags] influx write [command] ``` > [!Note] > ### Required data > > To write data to InfluxDB, you must provide the following for each row: > > * **measurement** > * **field** > * **value** > > #### Line protocol > > In **line protocol**, the [structure of the line data](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)determines the measurement, field, and value. > > #### Annotated CSV > > In **annotated CSV**, measurements, fields, and values are represented by the`_measurement`, `_field`, and `_value` columns. > Their types are determined by CSV annotations. > To successfully write annotated CSV to InfluxDB, include all[annotation rows](/influxdb/v2/reference/syntax/annotated-csv/#annotations). > > #### Extended annotated CSV > > In **extended annotated CSV**, measurements, fields, and values and their types are determined by[CSV annotations](/influxdb/v2/reference/syntax/annotated-csv/extended/#csv-annotations). ## Subcommands | Subcommand | Description | |--------------------------------------------------------|-----------------------------------| |[dryrun](/influxdb/v2/reference/cli/influx/write/dryrun)|Write to stdout instead of InfluxDB| ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | |`-b`| `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | | | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--compression` |Input compression (`none` or `gzip`, default is `none` unless input file ends with `.gz`.)| string | | | | `--debug` | Output errors to stderr | | | | | `--encoding` | Character encoding of input (default `UTF-8`) | string | | | | `--errors-file` | Path to a file used for recording rejected row errors | string | | |`-f`| `--file` | File to import |stringArray| | | | `--format` | Input format (`lp` or `csv`, default `lp`) | string | | | | `--header` | Prepend header line to CSV input data | string | | |`-h`| `--help` | Help for the `write` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | | |`--max-line-length`| Maximum number of bytes that can be read for a single line (default `16000000`) | integer | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-p`| `--precision` |[Precision](/influxdb/v2/write-data/#timestamp-precision) of the timestamps (default `ns`)| string | `INFLUX_PRECISION` | | | `--rate-limit` | Throttle write rate (examples: `5MB/5min` or `1MB/s`). | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--skipHeader` | Skip first *n* rows of input data | integer | | | |`--skipRowOnError` | Output CSV errors to stderr, but continue processing | | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-u`| `--url` | URL to import data from |stringArray| | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ###### Write line protocol * [via stdin](#write-line-protocol-via-stdin) * [from a file](#write-line-protocol-from-a-file) * [and skip header lines](#skip-header-lines-in-a-file) * [from multiple files](#write-line-protocol-from-multiple-files) * [from a URL](#write-line-protocol-from-a-url) * [from multiple URLs](#write-line-protocol-from-multiple-urls) * [from multiple sources](#write-line-protocol-from-multiple-sources) * [from a compressed file](#write-line-protocol-from-a-compressed-file) ###### Write CSV data * [annotated CSV via stdin](#write-annotated-csv-data-via-stdin) * [extended annotated CSV via stdin](#write-extended-annotated-csv-data-via-stdin) * [from a file](#write-annotated-csv-data-from-a-file) * [from multiple files](#write-annotated-csv-data-from-multiple-files) * [from a URL](#write-annotated-csv-data-from-a-url) * [from multiple URLs](#write-annotated-csv-data-from-multiple-urls) * [from multiple sources](#write-annotated-csv-data-from-multiple-sources) * [and prepend annotation headers](#prepend-csv-data-with-annotation-headers) * [from a compressed file](#write-annotated-csv-data-from-a-compressed-file) * [using rate limiting](#write-annotated-csv-data-using-rate-limiting) ### Line protocol ##### Write line protocol via stdin ```sh influx write --bucket example-bucket " m,host=host1 field1=1.2,field2=5i 1640995200000000000 m,host=host2 field1=2.4,field2=3i 1640995200000000000 " ``` ##### Write line protocol from a file ```sh influx write \ --bucket example-bucket \ --file path/to/line-protocol.txt ``` ##### Skip header lines in a file ```sh influx write \ --bucket example-bucket \ --file path/to/line-protocol.txt --skipHeader 8 ``` ##### Write line protocol from multiple files ```sh influx write \ --bucket example-bucket \ --file path/to/line-protocol-1.txt \ --file path/to/line-protocol-2.txt ``` ##### Write line protocol from a URL ```sh influx write \ --bucket example-bucket \ --url https://example.com/line-protocol.txt ``` ##### Write line protocol from multiple URLs ```sh influx write \ --bucket example-bucket \ --url https://example.com/line-protocol-1.txt \ --url https://example.com/line-protocol-2.txt ``` ##### Write line protocol from multiple sources ```sh influx write \ --bucket example-bucket \ --file path/to/line-protocol-1.txt \ --url https://example.com/line-protocol-2.txt ``` ##### Write line protocol from a compressed file ``` # The influx CLI assumes files with the .gz extension use gzip compression influx write \ --bucket example-bucket \ --file path/to/line-protocol.txt.gz # Specify gzip compression for gzipped files without the .gz extension influx write \ --bucket example-bucket \ --file path/to/line-protocol.txt.comp \ --compression gzip ``` ### CSV ##### Write annotated CSV data via stdin ```sh influx write \ --bucket example-bucket \ --format csv \ "#group,false,false,false,false,true,true #datatype,string,long,dateTime:RFC3339,double,string,string #default,_result,,,,, ,result,table,_time,_value,_field,_measurement ,,0,2020-12-18T18:16:11Z,72.7,temp,sensorData ,,0,2020-12-18T18:16:21Z,73.8,temp,sensorData ,,0,2020-12-18T18:16:31Z,72.7,temp,sensorData ,,0,2020-12-18T18:16:41Z,72.8,temp,sensorData ,,0,2020-12-18T18:16:51Z,73.1,temp,sensorData " ``` ##### Write extended annotated CSV data via stdin ```sh influx write \ --bucket example-bucket \ --format csv \ "#constant measurement,sensorData #datatype dateTime:RFC3339,double time,temperature 2020-12-18T18:16:11Z,72.7 2020-12-18T18:16:21Z,73.8 2020-12-18T18:16:31Z,72.7 2020-12-18T18:16:41Z,72.8 2020-12-18T18:16:51Z,73.1 " ``` ##### Write annotated CSV data from a file ```sh influx write \ --bucket example-bucket \ --file path/to/data.csv ``` ##### Write annotated CSV data from multiple files ```sh influx write \ --bucket example-bucket \ --file path/to/data-1.csv \ --file path/to/data-2.csv ``` ##### Write annotated CSV data from a URL ```sh influx write \ --bucket example-bucket \ --url https://example.com/data.csv ``` ##### Write annotated CSV data from multiple URLs ```sh influx write \ --bucket example-bucket \ --url https://example.com/data-1.csv \ --url https://example.com/data-2.csv ``` ##### Write annotated CSV data from multiple sources ```sh influx write \ --bucket example-bucket \ --file path/to/data-1.csv \ --url https://example.com/data-2.csv ``` ##### Prepend CSV data with annotation headers ```sh influx write \ --bucket example-bucket \ --header "#constant measurement,birds" \ --header "#datatype dateTime:2006-01-02,long,tag" \ --file path/to/data.csv ``` ##### Write annotated CSV data from a compressed file ``` # The influx CLI assumes files with the .gz extension use gzip compression influx write \ --bucket example-bucket \ --file path/to/data.csv.gz # Specify gzip compression for gzipped files without the .gz extension influx write \ --bucket example-bucket \ --file path/to/data.csv.comp \ --compression gzip ``` ##### Write annotated CSV data using rate limiting ```sh influx write \ --bucket example-bucket \ --file path/to/data.csv \ --rate-limit 5MB/5min ``` #### Related * [Write data to InfluxDB](/influxdb/v2/write-data/) * [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/) * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) * [Extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended/) * [influx CLI—Provide required authentication credentials](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/v2/reference/cli/influx/#flag-patterns-and-conventions) [write](/influxdb/v2/tags/write/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | dryrun | Write to stdout instead of InfluxDB | | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -b | --bucket | Bucket name (mutually exclusive with --bucket-id ) | string | INFLUX_BUCKET_NAME | | | --bucket-id | Bucket ID (mutually exclusive with --bucket ) | string | INFLUX_BUCKET_ID | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --compression | Input compression ( none or gzip , default is none unless input file ends with .gz .) | string | | | | --debug | Output errors to stderr | | | | | --encoding | Character encoding of input (default UTF-8 ) | string | | | | --errors-file | Path to a file used for recording rejected row errors | string | | | -f | --file | File to import | stringArray | | | | --format | Input format ( lp or csv , default lp ) | string | | | | --header | Prepend header line to CSV input data | string | | | -h | --help | Help for the write command | | | | | --host | HTTP address of InfluxDB (default http://localhost:8086 ) | string | INFLUX_HOST | | | --max-line-length | Maximum number of bytes that can be read for a single line (default 16000000 ) | integer | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -p | --precision | Precision of the timestamps (default ns ) | string | INFLUX_PRECISION | | | --rate-limit | Throttle write rate (examples: 5MB/5min or 1MB/s ). | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --skipHeader | Skip first n rows of input data | integer | | | | --skipRowOnError | Output CSV errors to stderr, but continue processing | | | | -t | --token | API token | string | INFLUX_TOKEN | | -u | --url | URL to import data from | stringArray | | --- # influx write dryrun Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/write/dryrun/ * influx CLI 2.0.0+ * InfluxDB 2.0.0+ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influx write dryrun` command prints write output to stdout instead of writing to InfluxDB. Use this command to test writing data. Supports [line protocol](/influxdb/v2/reference/syntax/line-protocol),[annotated CSV](/influxdb/v2/reference/syntax/annotated-csv), and[extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended). Output is always **line protocol**. ## Usage ``` influx write dryrun [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/v2/reference/cli/influx/#view-mapped-environment-variables)| |----|-------------------|-------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------| |`-c`| `--active-config` | CLI configuration to use for command | string | | |`-b`| `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | | | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | | | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | | | `--debug` | Output errors to stderr | | | | | `--encoding` | Character encoding of input (default `UTF-8`) | string | | | | `--errors-file` | Path to a file used for recording rejected row errors | string | | |`-f`| `--file` | File to import |stringArray| | | | `--format` | Input format (`lp` or `csv`, default `lp`) | string | | | | `--header` | Prepend header line to CSV input data | string | | |`-h`| `--help` | Help for the `dryrun` command | | | | | `--host` | HTTP address of InfluxDB (default `http://localhost:9999`) | string | `INFLUX_HOST` | | |`--max-line-length`|Maximum number of bytes that can be read for a single line (default `16000000`)| integer | | |`-o`| `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | | | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | |`-p`| `--precision` | Precision of the timestamps (default `ns`) | string | `INFLUX_PRECISION` | | | `--rate-limit` | Throttle write rate (examples: `5MB/5min` or `1MB/s`). | string | | | | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | | | `--skipHeader` | Skip first *n* rows of input data | integer | | | |`--skipRowOnError` | Output CSV errors to stderr, but continue processing | | | |`-t`| `--token` | API token | string | `INFLUX_TOKEN` | |`-u`| `--url` | URL to import data from |stringArray| | ## Examples > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token * [Dry run writing line protocol](#line-protocol) * [via stdin](#dry-run-writing-line-protocol-via-stdin) * [from a file](#dry-run-writing-line-protocol-from-a-file) * [from multiple files](#dry-run-writing-line-protocol-from-multiple-files) * [from a URL](#dry-run-writing-line-protocol-from-a-url) * [from multiple URLs](#dry-run-writing-line-protocol-from-multiple-urls) * [from multiple sources](#dry-run-writing-line-protocol-from-multiple-sources) * [Dry run writing CSV data](#csv) * [via stdin](#dry-run-writing-annotated-csv-data-via-stdin) * [from a file](#dry-run-writing-annotated-csv-data-from-a-file) * [from multiple files](#dry-run-writing-annotated-csv-data-from-multiple-files) * [from a URL](#dry-run-writing-annotated-csv-data-from-a-url) * [from multiple URLs](#dry-run-writing-annotated-csv-data-from-multiple-urls) * [from multiple sources](#dry-run-writing-annotated-csv-data-from-multiple-sources) * [and prepending annotation headers](#dry-run-prepending-csv-data-with-annotation-headers) ### Line protocol ##### Dry run writing line protocol via stdin ```sh influx write --bucket example-bucket " m,host=host1 field1=1.2 m,host=host2 field1=2.4 m,host=host1 field2=5i m,host=host2 field2=3i " ``` ##### Dry run writing line protocol from a file ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/line-protocol.txt ``` ##### Dry run writing line protocol from multiple files ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/line-protocol-1.txt \ --file path/to/line-protocol-2.txt ``` ##### Dry run writing line protocol from a URL ```sh influx write dryrun \ --bucket example-bucket \ --url https://example.com/line-protocol.txt ``` ##### Dry run writing line protocol from multiple URLs ```sh influx write dryrun \ --bucket example-bucket \ --url https://example.com/line-protocol-1.txt \ --url https://example.com/line-protocol-2.txt ``` ##### Dry run writing line protocol from multiple sources ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/line-protocol-1.txt \ --url https://example.com/line-protocol-2.txt ``` ### CSV ##### Dry run writing annotated CSV data via stdin ```sh influx write dryrun \ --bucket example-bucket \ --format csv \ "#datatype measurement,tag,tag,field,field,ignored,time m,cpu,host,time_steal,usage_user,nothing,time cpu,cpu1,host1,0,2.7,a,1482669077000000000 cpu,cpu1,host2,0,2.2,b,1482669087000000000 " ``` ##### Dry run writing annotated CSV data from a file ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/data.csv ``` ##### Dry run writing annotated CSV data from multiple files ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/data-1.csv \ --file path/to/data-2.csv ``` ##### Dry run writing annotated CSV data from a URL ```sh influx write dryrun \ --bucket example-bucket \ --url https://example.com/data.csv ``` ##### Dry run writing annotated CSV data from multiple URLs ```sh influx write dryrun \ --bucket example-bucket \ --url https://example.com/data-1.csv \ --url https://example.com/data-2.csv ``` ##### Dry run writing annotated CSV data from multiple sources ```sh influx write dryrun \ --bucket example-bucket \ --file path/to/data-1.csv \ --url https://example.com/data-2.csv ``` ##### Dry run prepending CSV data with annotation headers ```sh influx write dryrun \ --bucket example-bucket \ --header "#constant measurement,birds" \ --header "#datatype dataTime:2006-01-02,long,tag" \ --file path/to/data.csv ``` #### Related * [Write data to InfluxDB](/influxdb/v2/write-data/) * [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/) * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) * [Extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended/) [write](/influxdb/v2/tags/write/) | Flag | | Description | Input type | Maps to ? | | --- | --- | --- | --- | --- | | Flag | | Description | Input type | Maps to ? | | -c | --active-config | CLI configuration to use for command | string | | | -b | --bucket | Bucket name (mutually exclusive with --bucket-id ) | string | INFLUX_BUCKET_NAME | | | --bucket-id | Bucket ID (mutually exclusive with --bucket ) | string | INFLUX_BUCKET_ID | | | --configs-path | Path to influx CLI configurations (default ~/.influxdbv2/configs ) | string | INFLUX_CONFIGS_PATH | | | --debug | Output errors to stderr | | | | | --encoding | Character encoding of input (default UTF-8 ) | string | | | | --errors-file | Path to a file used for recording rejected row errors | string | | | -f | --file | File to import | stringArray | | | | --format | Input format ( lp or csv , default lp ) | string | | | | --header | Prepend header line to CSV input data | string | | | -h | --help | Help for the dryrun command | | | | | --host | HTTP address of InfluxDB (default http://localhost:9999 ) | string | INFLUX_HOST | | | --max-line-length | Maximum number of bytes that can be read for a single line (default 16000000 ) | integer | | | -o | --org | Organization name (mutually exclusive with --org-id ) | string | INFLUX_ORG | | | --org-id | Organization ID (mutually exclusive with --org ) | string | INFLUX_ORG_ID | | -p | --precision | Precision of the timestamps (default ns ) | string | INFLUX_PRECISION | | | --rate-limit | Throttle write rate (examples: 5MB/5min or 1MB/s ). | string | | | | --skip-verify | Skip TLS certificate verification | | INFLUX_SKIP_VERIFY | | | --skipHeader | Skip first n rows of input data | integer | | | | --skipRowOnError | Output CSV errors to stderr, but continue processing | | | | -t | --token | API token | string | INFLUX_TOKEN | | -u | --url | URL to import data from | stringArray | | --- # influxd - InfluxDB service Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd` daemon starts and runs all the processes necessary for InfluxDB to function. ## Usage ``` influxd [flags] influxd [command] ``` > [!Note] > For information about other available InfluxDB configuration methods, see[InfluxDB configuration options](/influxdb/v2/reference/config-options/). ## Commands | Command | Description | |----------------------------------------------------------------|-----------------------------------------------------------------------------| | [downgrade](/influxdb/v2/reference/cli/influxd/downgrade/) | Downgrade metadata schema to match an older release | | help | Output help information for `influxd` | | [inspect](/influxdb/v2/reference/cli/influxd/inspect/) | Inspect on-disk database data | |[print-config](/influxdb/v2/reference/cli/influxd/print-config/)|(**Deprecated**) Print full influxd configuration for the current environment| | [recovery](/influxdb/v2/reference/cli/influxd/recovery/) | Recover operator access to InfluxDB | | [run](/influxdb/v2/reference/cli/influxd/run/) | Start the influxd server ***(default)*** | | [upgrade](/influxdb/v2/reference/cli/influxd/upgrade/) | Upgrade a 1.x version of InfluxDB to 2.10 | | [version](/influxdb/v2/reference/cli/influxd/version/) | Output the current version of InfluxDB | ## Flags * [--assets-path](/influxdb/v2/reference/config-options/#assets-path) * [--bolt-path](/influxdb/v2/reference/config-options/#bolt-path) * [--e2e-testing](/influxdb/v2/reference/config-options/#e2e-testing) * [--engine-path](/influxdb/v2/reference/config-options/#engine-path) * [--feature-flags](/influxdb/v2/reference/config-options/#feature-flags) * [--flux-log-enabled](/influxdb/v2/reference/config-options/#flux-log-enabled) * [--hardening-enabled](/influxdb/v2/reference/config-options/#hardening-enabled) * [--health-auth-mode](/influxdb/v2/reference/config-options/#health-auth-mode) * -h, --help * [--http-bind-address](/influxdb/v2/reference/config-options/#http-bind-address) * [--http-idle-timeout](/influxdb/v2/reference/config-options/#http-idle-timeout) * [--http-read-header-timeout](/influxdb/v2/reference/config-options/#http-read-header-timeout) * [--http-read-timeout](/influxdb/v2/reference/config-options/#http-read-timeout) * [--http-user-query-bytes-enabled](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled) * [--http-user-write-bytes-enabled](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled) * [--http-write-timeout](/influxdb/v2/reference/config-options/#http-write-timeout) * [--influxql-max-select-buckets](/influxdb/v2/reference/config-options/#influxql-max-select-buckets) * [--influxql-max-select-point](/influxdb/v2/reference/config-options/#influxql-max-select-point) * [--influxql-max-select-series](/influxdb/v2/reference/config-options/#influxql-max-select-series) * [--influxql-max-time-range](/influxdb/v2/reference/config-options/#influxql-max-time-range) * [--instance-id](/influxdb/v2/reference/config-options/#instance-id) * [--log-level](/influxdb/v2/reference/config-options/#log-level) * [--metrics-disabled](/influxdb/v2/reference/config-options/#metrics-disabled) * [--nats-max-payload-bytes](/influxdb/v2/reference/config-options/#nats-max-payload-bytes)*- (deprecated in InfluxDB 2.2)* * [--nats-port](/influxdb/v2/reference/config-options/#nats-port)*- (deprecated in InfluxDB 2.2)* * [--no-tasks](/influxdb/v2/reference/config-options/#no-tasks) * [--overwrite-pid-file](/influxdb/v2/reference/config-options/#overwrite-pid-file) * [--pid-file](/influxdb/v2/reference/config-options/#pid-file) * [--pprof-disabled](/influxdb/v2/reference/config-options/#pprof-disabled) * [--query-concurrency](/influxdb/v2/reference/config-options/#query-concurrency) * [--query-initial-memory-bytes](/influxdb/v2/reference/config-options/#query-initial-memory-bytes) * [--query-max-memory-bytes](/influxdb/v2/reference/config-options/#query-max-memory-bytes) * [--query-memory-bytes](/influxdb/v2/reference/config-options/#query-memory-bytes) * [--query-queue-size](/influxdb/v2/reference/config-options/#query-queue-size) * [--reporting-disabled](/influxdb/v2/reference/config-options/#reporting-disabled) * [--secret-store](/influxdb/v2/reference/config-options/#secret-store) * [--session-length](/influxdb/v2/reference/config-options/#session-length) * [--session-renew-disabled](/influxdb/v2/reference/config-options/#session-renew-disabled) * [--sqlite-path](/influxdb/v2/reference/config-options/#sqlite-path) * [--startup-error-linger](/influxdb/v2/reference/config-options/#startup-error-linger) * [--storage-cache-max-memory-size](/influxdb/v2/reference/config-options/#storage-cache-max-memory-size) * [--storage-cache-snapshot-memory-size](/influxdb/v2/reference/config-options/#storage-cache-snapshot-memory-size) * [--storage-cache-snapshot-write-cold-duration](/influxdb/v2/reference/config-options/#storage-cache-snapshot-write-cold-duration) * [--storage-compact-full-write-cold-duration](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration) * [--storage-compact-throughput](/influxdb/v2/reference/config-options/#storage-compact-throughput) * [--storage-compact-throughput-burst](/influxdb/v2/reference/config-options/#storage-compact-throughput-burst) * [--storage-max-concurrent-compactions](/influxdb/v2/reference/config-options/#storage-max-concurrent-compactions) * [--storage-max-index-log-file-size](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size) * [--storage-no-validate-field-size](/influxdb/v2/reference/config-options/#storage-no-validate-field-size) * [--storage-retention-check-interval](/influxdb/v2/reference/config-options/#storage-retention-check-interval) * [--storage-series-file-max-concurrent-snapshot-compactions](/influxdb/v2/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) * [--storage-series-id-set-cache-size](/influxdb/v2/reference/config-options/#storage-series-id-set-cache-size) * [--storage-shard-precreator-advance-period](/influxdb/v2/reference/config-options/#storage-shard-precreator-advance-period) * [--storage-shard-precreator-check-interval](/influxdb/v2/reference/config-options/#storage-shard-precreator-check-interval) * [--storage-tsm-use-madv-willneed](/influxdb/v2/reference/config-options/#storage-tsm-use-madv-willneed) * [--storage-validate-keys](/influxdb/v2/reference/config-options/#storage-validate-keys) * [--storage-wal-flush-on-shutdown](/influxdb/v2/reference/config-options/#storage-wal-flush-on-shutdown) * [--storage-wal-fsync-delay](/influxdb/v2/reference/config-options/#storage-wal-fsync-delay) * [--storage-wal-max-concurrent-writes](/influxdb/v2/reference/config-options/#storage-wal-max-concurrent-writes) * [--storage-wal-max-write-delay](/influxdb/v2/reference/config-options/#storage-wal-max-write-delay) * [--storage-write-timeout](/influxdb/v2/reference/config-options/#storage-write-timeout) * [--store](/influxdb/v2/reference/config-options/#store) * [--strong-passwords](/influxdb/v2/reference/config-options/#strong-passwords) * [--testing-always-allow-setup](/influxdb/v2/reference/config-options/#testing-always-allow-setup) * [--tls-cert](/influxdb/v2/reference/config-options/#tls-cert) * [--tls-key](/influxdb/v2/reference/config-options/#tls-key) * [--tls-min-version](/influxdb/v2/reference/config-options/#tls-min-version) * [--tls-strict-ciphers](/influxdb/v2/reference/config-options/#tls-strict-ciphers) * [--tracing-type](/influxdb/v2/reference/config-options/#tracing-type) * [--ui-disabled](/influxdb/v2/reference/config-options/#ui-disabled) * [--use-hashed-tokens](/influxdb/v2/reference/config-options/#use-hashed-tokens) * [--vault-addr](/influxdb/v2/reference/config-options/#vault-addr) * [--vault-cacert](/influxdb/v2/reference/config-options/#vault-cacert) * [--vault-capath](/influxdb/v2/reference/config-options/#vault-capath) * [--vault-client-cert](/influxdb/v2/reference/config-options/#vault-client-cert) * [--vault-client-key](/influxdb/v2/reference/config-options/#vault-client-key) * [--vault-client-timeout](/influxdb/v2/reference/config-options/#vault-client-timeout) * [--vault-max-retries](/influxdb/v2/reference/config-options/#vault-max-retries) * [--vault-skip-verify](/influxdb/v2/reference/config-options/#vault-skip-verify) * [--vault-tls-server-name](/influxdb/v2/reference/config-options/#vault-tls-server-name) * [--vault-token](/influxdb/v2/reference/config-options/#vault-token) ## Exit codes *Available in InfluxDB OSS v2.10 and later.* When the `influxd` server fails to start, its exit code tells you whether restarting can help. The codes follow the BSD `sysexits.h` convention. |Code| Name | Meaning | Restart helps? | |----|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------| | 0 | `EX_OK` | Startup and shutdown succeeded, including a shutdown requested by a signal. | — | | 1 | — | An error with no category. Subcommands such as `inspect`, `upgrade`, and `recovery` report all failures with this code. | Unknown | | 64 | `EX_USAGE` | The command line is wrong: an unknown flag, a flag value that can’t be parsed, or an unexpected argument. | No | | 65 | `EX_DATAERR` | The data on disk isn’t readable by this version–for example, InfluxDB 1.x `_series` or `index` directories under `--engine-path`. | No | | 66 | `EX_NOINPUT` | A path doesn’t exist or is the wrong type–for example, `--engine-path` points to a file, or a parent directory is missing. | No | | 69 |`EX_UNAVAILABLE`| A required resource is in use: the `--http-bind-address` port, an existing `--pid-file`, or a dependency that refused the connection. | Only after the conflict clears | | 70 | `EX_SOFTWARE` | Startup failed without an operating system cause. Read the error and the log. | No | | 71 | `EX_OSERR` | The operating system ran out of file descriptors or memory. | After you raise the limits | | 73 | `EX_CANTCREAT` | A file can’t be created or extended: the disk is full, a quota is exhausted, or the file system is read-only. |After you free space or make the file system writable| | 74 | `EX_IOERR` | An I/O error occurred while reading or writing, usually from hardware or a failing file system. | No | | 75 | `EX_TEMPFAIL` | An operation didn’t finish: a dependency timed out, `SIGINT` interrupted startup, or shutdown exceeded its time limit. | Yes | | 77 | `EX_NOPERM` | Permission was denied on a data directory, PID file, TLS certificate, or privileged port. | No | | 78 | `EX_CONFIG` |A configuration value is wrong–for example, 1.x keys in a 2.x configuration file, a configuration file that can’t be parsed, or an invalid option value.| No | To retrieve the startup error from the `/health` and `/ready` endpoints before `influxd` exits, set [`startup-error-linger`](/influxdb/v2/reference/config-options/#startup-error-linger). ### Prevent restart loops with systemd If `influxd` exits with a code that a restart can’t fix, systemd restarts it into the same failure. To stop restarting on those codes, add `RestartPreventExitStatus` to the `influxd` service unit: ```ini [Service] Restart=on-failure RestartPreventExitStatus=64 65 66 70 74 77 78 ``` #### Related * [InfluxDB configuration options](/influxdb/v2/reference/config-options/) [influxd](/influxdb/v2/tags/influxd/)[cli](/influxdb/v2/tags/cli/) | Command | Description | | --- | --- | | Command | Description | | downgrade | Downgrade metadata schema to match an older release | | help | Output help information for influxd | | inspect | Inspect on-disk database data | | print-config | ( Deprecated ) Print full influxd configuration for the current environment | | recovery | Recover operator access to InfluxDB | | run | Start the influxd server (default) | | upgrade | Upgrade a 1.x version of InfluxDB to 2.10 | | version | Output the current version of InfluxDB | | Code | Name | Meaning | Restart helps? | | --- | --- | --- | --- | | Code | Name | Meaning | Restart helps? | | 0 | EX_OK | Startup and shutdown succeeded, including a shutdown requested by a signal. | — | | 1 | — | An error with no category. Subcommands such as inspect , upgrade , and recovery report all failures with this code. | Unknown | | 64 | EX_USAGE | The command line is wrong: an unknown flag, a flag value that can’t be parsed, or an unexpected argument. | No | | 65 | EX_DATAERR | The data on disk isn’t readable by this version–for example, InfluxDB 1.x _series or index directories under --engine-path . | No | | 66 | EX_NOINPUT | A path doesn’t exist or is the wrong type–for example, --engine-path points to a file, or a parent directory is missing. | No | | 69 | EX_UNAVAILABLE | A required resource is in use: the --http-bind-address port, an existing --pid-file , or a dependency that refused the connection. | Only after the conflict clears | | 70 | EX_SOFTWARE | Startup failed without an operating system cause. Read the error and the log. | No | | 71 | EX_OSERR | The operating system ran out of file descriptors or memory. | After you raise the limits | | 73 | EX_CANTCREAT | A file can’t be created or extended: the disk is full, a quota is exhausted, or the file system is read-only. | After you free space or make the file system writable | | 74 | EX_IOERR | An I/O error occurred while reading or writing, usually from hardware or a failing file system. | No | | 75 | EX_TEMPFAIL | An operation didn’t finish: a dependency timed out, SIGINT interrupted startup, or shutdown exceeded its time limit. | Yes | | 77 | EX_NOPERM | Permission was denied on a data directory, PID file, TLS certificate, or privileged port. | No | | 78 | EX_CONFIG | A configuration value is wrong–for example, 1.x keys in a 2.x configuration file, a configuration file that can’t be parsed, or an invalid option value. | No | --- # influxd downgrade Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/downgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influxd downgrade` command to downgrade the metadata schema used by`influxd` to match the metadata schema of a older release. InfluxDB does not guarantee backwards-compatibility with earlier releases. Attempting to start an older `influxd` binary with a BoltDB or SQLite file that has been migrated to a newer schema will result in a startup error. This command downgrades metadata schemas to match the schemas of an older release and allows the older `influxd` binary to boot successfully. > [!Note] > Run this command **prior** to downgrading the `influxd` binary. ## Usage ```sh influxd downgrade [flags] ``` ## Flags |Flag| | Description |Input type| |----|---------------|--------------------------------------------------------------------------------|----------| | | `--bolt-path` | Path to BoltDB database (default is `~/.influxdbv2/influxd.bolt`) | string | |`-h`| `--help` | Help for `downgrade` | | | | `--log-level` | Log level (`debug`, `info` *(default*), `warn` or `error`) | string | | |`--sqlite-path`|Path to SQLite database (default is `influxd.sqlite` in the bolt path directory)| string | ## Examples ##### Downgrade to InfluxDB 2.0 ```sh influxd downgrade 2.0 ``` #### Related * [Downgrade InfluxDB](/influxdb/v2/install/upgrade/downgrade/) | Flag | | Description | Input type | | --- | --- | --- | --- | | Flag | | Description | Input type | | | --bolt-path | Path to BoltDB database (default is ~/.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for downgrade | | | | --log-level | Log level ( debug , info (default ), warn or error ) | string | | | --sqlite-path | Path to SQLite database (default is influxd.sqlite in the bolt path directory) | string | --- # influxd inspect Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect` commands and subcommands inspecting on-disk InfluxDB time series data. ## Usage ```sh influxd inspect [subcommand] ``` ## Subcommands | Subcommand | Description | |----------------------------------------------------------------------------------|---------------------------------------| | [build-tsi](/influxdb/v2/reference/cli/influxd/inspect/build-tsi/) | Rebuild the TSI index and series file | | [check-schema](/influxdb/v2/reference/cli/influxd/inspect/check-schema/) |Check for conflicts between shard types| | [delete-tsm](/influxdb/v2/reference/cli/influxd/inspect/delete-tsm/) | Delete a measurement from a TSM file | | [dump-tsi](/influxdb/v2/reference/cli/influxd/inspect/dump-tsi/) | Output low level TSI information | | [dump-tsm](/influxdb/v2/reference/cli/influxd/inspect/dump-tsm/) | Output low level TSM information | | [dump-wal](/influxdb/v2/reference/cli/influxd/inspect/dump-wal/) | Output TSM data from WAL files | | [export-index](/influxdb/v2/reference/cli/influxd/inspect/export-index/) | Export TSI index data | | [export-lp](/influxdb/v2/reference/cli/influxd/inspect/export-lp/) | Export TSM data to line protocol | | [merge-schema](/influxdb/v2/reference/cli/influxd/inspect/merge-schema/) | Merge a set of schema files | | [report-db](/influxdb/v2/reference/cli/influxd/inspect/report-db/) | Report the cardinality of a bucket | | [report-tsi](/influxdb/v2/reference/cli/influxd/inspect/report-tsi/) | Report the cardinality of TSI files | | [report-tsm](/influxdb/v2/reference/cli/influxd/inspect/report-tsm/) | Report information about TSM files | |[verify-seriesfile](/influxdb/v2/reference/cli/influxd/inspect/verify-seriesfile/)| Verify the integrity of series files | | [verify-tombstone](/influxdb/v2/reference/cli/influxd/inspect/verify-tombstone/) |Verify the integrity of tombstone files| | [verify-tsm](/influxdb/v2/reference/cli/influxd/inspect/verify-tsm/) | Verify the integrity of TSM files | | [verify-wal](/influxdb/v2/reference/cli/influxd/inspect/verify-wal/) | Verify the integrity of WAL files | ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `inspect` command| [inspect](/influxdb/v2/tags/inspect/) | Subcommand | Description | | --- | --- | | Subcommand | Description | | build-tsi | Rebuild the TSI index and series file | | check-schema | Check for conflicts between shard types | | delete-tsm | Delete a measurement from a TSM file | | dump-tsi | Output low level TSI information | | dump-tsm | Output low level TSM information | | dump-wal | Output TSM data from WAL files | | export-index | Export TSI index data | | export-lp | Export TSM data to line protocol | | merge-schema | Merge a set of schema files | | report-db | Report the cardinality of a bucket | | report-tsi | Report the cardinality of TSI files | | report-tsm | Report information about TSM files | | verify-seriesfile | Verify the integrity of series files | | verify-tombstone | Verify the integrity of tombstone files | | verify-tsm | Verify the integrity of TSM files | | verify-wal | Verify the integrity of WAL files | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the inspect command | --- # influxd inspect build-tsi Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/build-tsi/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect build-tsi` command rebuilds the TSI index and, if necessary, the series file. ## Usage ```sh influxd inspect build-tsi [flags] ``` InfluxDB builds the index by reading all Time-Structured Merge tree (TSM) indexes and Write Ahead Log (WAL) entries in the TSM and WAL data directories. If the series file directory is missing, it rebuilds the series file. If the TSI index directory already exists, the command will fail. ### Adjust performance Use the following options to adjust the performance of the indexing process: ##### –max-log-file-size `--max-log-file-size` determines how much of an index to store in memory before compacting it into memory-mappable index files. If you find the memory requirements of your TSI index are too high, consider decreasing this setting. ##### –max-cache-size `--max-cache-size` defines the maximum cache size. The indexing process replays WAL files into a `tsm1.Cache`. If the maximum cache size is too low, the indexing process will fail. Increase `--max-cache-size` to account for the size of your WAL files. ##### –batch-size `--batch-size` defines the size of the batches written into the index. Altering the batch size can improve performance but may result in significantly higher memory usage. ## Flags |Flag| | Description |Input Type| |----|-----------------------|-----------------------------------------------------------------------------------------------|----------| | | `--batch-size` | Size of the batches to write to the index. Defaults to `10000`. [See above](#--batch-size). | integer | | | `--bucket-id` | Bucket ID (required if `--shard-id` is present). | string | | |`--compact-series-file`| Compact existing series file. Does not rebuilt index. | | | | `--concurrency` |Number of workers to dedicate to shard index building. Defaults to `GOMAXPROCS` (8 by default).| integer | | | `--data-path` | Path to the TSM data directory. Default is `~/.influxdbv2/engine/data`. | string | |`-h`| `--help` | Help for the `build-tsi` command. | | | | `--max-cache-size` | Maximum cache size. Defaults to `1073741824`. [See above](#--max-cache-size). | uinteger | | | `--max-log-file-size` | Maximum log file size. Defaults to `1048576`. [See above](#--max-log-file-size) . | integer | | | `--shard-id` | Shard ID (requires a `--bucket-id`). | string | |`-v`| `--verbose` | Enable verbose output. | | | | `--wal-path` | Path to the WAL data directory. Defaults to `~/.influxdbv2/engine/wal`. | string | [tsi](/influxdb/v2/tags/tsi/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --batch-size | Size of the batches to write to the index. Defaults to 10000 . See above . | integer | | | --bucket-id | Bucket ID (required if --shard-id is present). | string | | | --compact-series-file | Compact existing series file. Does not rebuilt index. | | | | --concurrency | Number of workers to dedicate to shard index building. Defaults to GOMAXPROCS (8 by default). | integer | | | --data-path | Path to the TSM data directory. Default is ~/.influxdbv2/engine/data . | string | | -h | --help | Help for the build-tsi command. | | | | --max-cache-size | Maximum cache size. Defaults to 1073741824 . See above . | uinteger | | | --max-log-file-size | Maximum log file size. Defaults to 1048576 . See above . | integer | | | --shard-id | Shard ID (requires a --bucket-id ). | string | | -v | --verbose | Enable verbose output. | | | | --wal-path | Path to the WAL data directory. Defaults to ~/.influxdbv2/engine/wal . | string | --- # influxd inspect check-schema Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/check-schema/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect check-schema` command checks for conflicts between shard types. ## Usage ```sh influxd inspect check-schema [flags] ``` ## Flags |Flag| | Description |Input Type| |----|------------------|----------------------------------------------------------------------|----------| | |`--conflicts-file`| File to write shard conflicts to (default is `conflicts.json`). | string | |`-h`| `--help` | View help for the `check-schema` command. | | | | `--log-level` |Log level used for the command (`debug`, `info` (default), or `error`)| string | | | `--path` | Directory path to `fields.idx` files (default is `./`) | string | | | `--schema-file` | File to write schema data to (default is `schema.json`). | string | [shards](/influxdb/v2/tags/shards/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --conflicts-file | File to write shard conflicts to (default is conflicts.json ). | string | | -h | --help | View help for the check-schema command. | | | | --log-level | Log level used for the command ( debug , info (default), or error ) | string | | | --path | Directory path to fields.idx files (default is ./ ) | string | | | --schema-file | File to write schema data to (default is schema.json ). | string | --- # influxd inspect delete-tsm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/delete-tsm/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect delete-tsm` command deletes a measurement from a raw TSM file. ## Usage ```sh influxd inspect delete-tsm [flags] ``` ## Flags |Flag| | Description |Input Type| |----|---------------|-----------------------------------------------------|----------| |`-h`| `--help` | Help for `delete-tsm` | | | |`--measurement`| Name of the measurement to delete | string | | | `--sanitize` |Remove all keys with non-printable unicode characters| | |`-v`| `--verbose` | Enable verbose logging | | ## Examples ##### Delete a measurement from a TSM file ```sh influxd inspect delete-tsm \ --measurement example-measurement ``` ##### Remove non-printable unicode characters from all TSM files ```sh influxd inspect delete-tsm --sanitize ``` [tsm](/influxdb/v2/tags/tsm/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | -h | --help | Help for delete-tsm | | | | --measurement | Name of the measurement to delete | string | | | --sanitize | Remove all keys with non-printable unicode characters | | | -v | --verbose | Enable verbose logging | | --- # influxd inspect dump-tsi Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/dump-tsi/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect dump-tsi` command outputs low-level information about Time Series Index (`tsi1`) files. ## Usage ```sh influxd inspect dump-tsi [flags] ``` ## Flags |Flag| | Description |Input Type| |----|----------------------|--------------------------------------|----------| |`-h`| `--help` | Help for the `dump-tsi` command. | | | |`--measurement-filter`|Regular expression measurement filter.| string | | | `--measurements` | Show raw measurement data. | | | | `--series` | Show raw series data. | | | | `--series-file` | Path to series file. | string | | | `--tag-key-filter` | Regular expression tag key filter. | string | | | `--tag-keys` | Show raw tag key data. | | | | `--tag-value-filter` | Regular expression tag value filter. | string | | | `--tag-value-series` | Show raw series data for each value. | | | | `--tag-values` | Show raw tag value data. | | [tsi](/influxdb/v2/tags/tsi/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | -h | --help | Help for the dump-tsi command. | | | | --measurement-filter | Regular expression measurement filter. | string | | | --measurements | Show raw measurement data. | | | | --series | Show raw series data. | | | | --series-file | Path to series file. | string | | | --tag-key-filter | Regular expression tag key filter. | string | | | --tag-keys | Show raw tag key data. | | | | --tag-value-filter | Regular expression tag value filter. | string | | | --tag-value-series | Show raw series data for each value. | | | | --tag-values | Show raw tag value data. | | --- # influxd inspect dump-tsm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/dump-tsm/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect dump-tsm` command outputs low-level information about Time Series Merge Tree (`tsm1`) files. ## Usage ```sh influxd inspect dump-tsm [flags] ``` ## Flags |Flag| | Description |Input Type| |----|--------------|----------------------------------------------|----------| | | `--all` | Output all TSM data \* | | | | `--blocks` | Output raw block data. | | | |`--file-path` | Path to TSM file. | string | | |`--filter-key`|Only display data matching this key substring.| string | |`-h`| `--help` | Help for `dump-tsm`. | | | | `--index` | Dump raw index data. | | *\* Using the `--all` flag may print a significant amount of information.* [tsm](/influxdb/v2/tags/tsm/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --all | Output all TSM data * | | | | --blocks | Output raw block data. | | | | --file-path | Path to TSM file. | string | | | --filter-key | Only display data matching this key substring. | string | | -h | --help | Help for dump-tsm . | | | | --index | Dump raw index data. | | --- # influxd inspect dump-wal Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/dump-wal/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect dump-wal` command outputs data from Write Ahead Log (WAL) files for debugging purposes. Given at least one WAL file path as an argument, the tool parses and prints out the entries in each file. ## Usage ```sh influxd inspect dump-wal [flags] ``` ## Output details The `--find-duplicates` flag determines the `influxd inspect dump-wal` output. **Without `--find-duplicates`**, the command outputs the following for each file: * The file name * For each entry in a file: - The type of the entry (`[write]` or `[delete-bucket-range]`) - The formatted entry contents **With `--find-duplicates`**, the command outputs the following for each file): * The file name * A list of keys with timestamps in the wrong order ## Flags |Flag| | Description | |----|-------------------|--------------------------------------------------------------------------| | |`--find-duplicates`|Ignore dumping entries; only report keys in the WAL that are out of order.| |`-h`| `--help` | Help for the `dump-wal` command. | [wal](/influxdb/v2/tags/wal/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | | --find-duplicates | Ignore dumping entries; only report keys in the WAL that are out of order. | | -h | --help | Help for the dump-wal command. | --- # influxd inspect export-index Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/export-index/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect export-index` command exports all series in a TSI index to SQL format for inspection and debugging. ## Usage ```sh influxd inspect export-index [flags] ``` ## Flags |Flag| | Description |Input type| |----|---------------|-------------------------------------------------------------------------------------------------------------------------|----------| |`-h`| `--help` | Help for the `export-index` command. | | | |`--index-path` | Path to the [`index` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). | string | | |`--series-path`|Path to the [`_series` directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout).| string | [inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input type | | --- | --- | --- | --- | | Flag | | Description | Input type | | -h | --help | Help for the export-index command. | | | | --index-path | Path to the index directory . | string | | | --series-path | Path to the _series directory . | string | --- # influxd inspect export-lp Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/export-lp/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect export-lp` command exports all time-structured merge tree (TSM) data in a bucket to [line protocol](/influxdb/v2/reference/syntax/line-protocol/). ## Usage ```sh influxd inspect export-lp [flags] ``` ## Flags |Flag| | Description |Input type| |----|---------------|----------------------------------------------------|----------| | | `--bucket-id` | (Required) Bucket ID | string | | | `--compress` | Compress output with gzip | | | | `--end` | End time to export (RFC3339 format) | string | | |`--engine-path`|(Required) Path to persistent InfluxDB engine files | string | |`-h`| `--help` | Help for the `export-lp` command. | | | | `--log-level` |Log-level (`debug`, `info` *(default)*, or `error`) | string | | |`--measurement`| Measurement name(s) to export | strings | | |`--output-path`|(Required) Output path (file path or stdout *(`-`)*)| string | | | `--start` | Start time to export (RFC3339 format) | string | ## Examples * [Export all data in a bucket as line protocol](#export-all-data-in-a-bucket-as-line-protocol) * [Export data in measurements as line protocol](#export-data-in-measurements-as-line-protocol) * [Export data in specified time range as line protocol](#export-data-in-specified-time-range-as-line-protocol) ##### Export all data in a bucket as line protocol [To a file](#to-a-file)[To stdout](#to-stdout) ```sh influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --output-path path/to/export.lp ``` ```sh influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --output-path - ``` ##### Export data in measurements as line protocol [To a file](#to-a-file-2)[To stdout](#to-stdout-2) ```sh # Export a single measurement influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --measurement example-measurement \ --output-path path/to/export.lp # Export multiple measurements influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --measurement example-measurement-1,example-measurement-2 \ --output-path path/to/export.lp ``` ```sh # Export a single measurement influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --measurement example-measurement \ --output-path - # Export multiple measurements influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --measurement example-measurement-1,example-measurement-2 \ --output-path - ``` ##### Export data in specified time range as line protocol [To a file](#to-a-file-3)[To stdout](#to-stdout-3) ```sh influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --start 2021-01-01T00:00:00Z \ --end 2021-01-31T23:59:59Z \ --output-path path/to/export.lp ``` ```sh influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --start 2021-01-01T00:00:00Z \ --end 2021-01-31T23:59:59Z \ --output-path - ``` [inspect](/influxdb/v2/tags/inspect/)[export](/influxdb/v2/tags/export/) | Flag | | Description | Input type | | --- | --- | --- | --- | | Flag | | Description | Input type | | | --bucket-id | ( Required ) Bucket ID | string | | | --compress | Compress output with gzip | | | | --end | End time to export (RFC3339 format) | string | | | --engine-path | ( Required ) Path to persistent InfluxDB engine files | string | | -h | --help | Help for the export-lp command. | | | | --log-level | Log-level ( debug , info (default) , or error ) | string | | | --measurement | Measurement name(s) to export | strings | | | --output-path | ( Required ) Output path (file path or stdout ( - ) ) | string | | | --start | Start time to export (RFC3339 format) | string | --- # influxd inspect merge-schema Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/merge-schema/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect merge-schema` command merges a set of schema files. ## Usage ```sh influxd inspect merge-schema [flags] ``` ## Flags |Flag| | Description |Input Type| |----|------------------|-------------------------------------------------------------|----------| | |`--conflicts-file`|File to write shard conflicts to (default is `conflicts.json`| string | |`-h`| `--help` | View help for the `merge-schema` command. | | | | `--schema-file` | File to write schema data to (default is `schema.json`). | string | [shards](/influxdb/v2/tags/shards/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --conflicts-file | File to write shard conflicts to (default is conflicts.json | string | | -h | --help | View help for the merge-schema command. | | | | --schema-file | File to write schema data to (default is schema.json ). | string | --- # influxd inspect report-db Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/report-db/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect report-db` command analyzes an InfluxDB bucket and reports the cardinality of data stored in the bucket. ## Usage ```sh influxd inspect report-db [flags] ``` ## Flags |Flag| | Description |Input Type| |----|------------|--------------------------------------------------------------------------------------------------|----------| | | `--c` | Worker concurrency (default is `1`). | integer | | |`--db-path` | (Required) Path to InfluxDB data directory. | string | | |`--detailed`| Include field and tag counts in output. | | | | `--exact` | Report exact counts. | | |`-h`| `--help` | View help for the `report-db` command. | | | | `--rollup` |Rollup level: `t` (total), `b` (bucket), `r` (retention policy), or `m` (measurement) *(default)*.| string | ## Examples * [Report the cardinality of measurements in all buckets](#report-the-cardinality-of-measurements-in-all-buckets) * [Report the cardinality of measurements in a specific bucket](#report-the-cardinality-of-measurements-in-a-specific-bucket) * [Report the cardinality of all buckets](#report-the-cardinality-of-all-buckets) * [Report the cardinality of all retention policies](#report-the-cardinality-of-all-retention-policies) * [Report the total cardinality of your InfluxDB instance](#report-the-total-cardinality-of-your-influxdb-instance) * [Include tag and field counts in your cardinality summary](#include-tag-and-field-counts-in-your-cardinality-summary) ### Report the cardinality of measurements in all buckets * Use the `--db-path` flag to provide the path to your[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). ```sh # Syntax influxd inspect report-db --db-path # Example influxd inspect report-db --db-path ~/.influxdbv2/engine/data ``` ### Report the cardinality of measurements in a specific bucket * Use the `--db-path` flag to provide the path to the[Bucket directory (bucket ID)](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout)in your [InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). ```sh # Syntax influxd inspect report-db --db-path / # Example influxd inspect report-db --db-path ~/.influxdbv2/engine/data/000xX00xxXx000x0 ``` ### Report the cardinality of all buckets * Use the `--db-path` flag to provide the path to your[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * Use the `--rollup` flag with the value, `b`, to return a bucket-level summary of cardinality. ```sh # Syntax influxd inspect report-db \ --db-path \ --rollup b # Example influxd inspect report-db \ --db-path ~/.influxdbv2/engine/data \ --rollup b ``` ### Report the cardinality of all retention policies * Use the `--db-path` flag to provide the path to your[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * Use the `--rollup` flag with the value, `r`, to return a retention-policy-level summary of cardinality. ```sh # Syntax influxd inspect report-db \ --db-path \ --rollup r # Example influxd inspect report-db \ --db-path ~/.influxdbv2/engine/data \ --rollup r ``` ### Report the total cardinality of your InfluxDB instance * Use the `--db-path` flag to provide the path to your[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * Use the `--rollup` flag with the value, `t`, to return a summary of total cardinality. ```sh # Syntax influxd inspect report-db \ --db-path \ --rollup t # Example influxd inspect report-db \ --db-path ~/.influxdbv2/engine/data \ --rollup t ``` ### Include tag and field counts in your cardinality summary * Use the `--db-path` flag to provide the path to your[InfluxDB data directory](/influxdb/v2/reference/internals/file-system-layout/#tsm-directories-and-files-layout). * Include the `--detailed` flag to return detailed cardinality summaries with tag and field counts. ```sh # Syntax influxd inspect report-db \ --db-path \ --detailed # Example influxd inspect report-db \ --db-path ~/.influxdbv2/engine/data \ --detailed ``` [cardinality](/influxdb/v2/tags/cardinality/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --c | Worker concurrency (default is 1 ). | integer | | | --db-path | ( Required ) Path to InfluxDB data directory. | string | | | --detailed | Include field and tag counts in output. | | | | --exact | Report exact counts. | | | -h | --help | View help for the report-db command. | | | | --rollup | Rollup level: t (total), b (bucket), r (retention policy), or m (measurement) (default) . | string | --- # influxd inspect report-tsi Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/report-tsi/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect report-tsi` command analyzes Time Series Index (TSI) within a specified bucket and reports the cardinality of data stored in the bucket segmented by shard and measurement. ## Usage ```sh influxd inspect report-tsi [flags] ``` ## Flags |Flag| | Description |Input Type| |----|---------------|--------------------------------------------------------------------------------------------|----------| |`-b`| `--bucket-id` | (Required) Process data for specified bucket ID. | string | |`-c`|`--concurrency`|Number of workers to run concurrently (default is the number of available processing units).| integer | | | `--data-path` | Path to data directory (default `~/.influxdbv2/engine/data`). | string | |`-h`| `--help` | View Help for the `report-tsi` command. | | |`-t`| `-top` | Limit results to the top n. | integer | [tsi](/influxdb/v2/tags/tsi/)[cardinality](/influxdb/v2/tags/cardinality/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | -b | --bucket-id | ( Required ) Process data for specified bucket ID. | string | | -c | --concurrency | Number of workers to run concurrently (default is the number of available processing units). | integer | | | --data-path | Path to data directory (default ~/.influxdbv2/engine/data ). | string | | -h | --help | View Help for the report-tsi command. | | | -t | -top | Limit results to the top n. | integer | --- # influxd inspect report-tsm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/report-tsm/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect report-tsm` command analyzes Time-Structured Merge Tree (TSM) files within a storage engine directory and reports the cardinality within the files and the time range the data covers. This command only reports on the index within each TSM file. It does not read any block data. To reduce heap requirements, by default `report-tsm` estimates the overall cardinality in the file set by using the HLL++ algorithm. Determine exact cardinalities by using the `--exact` flag. ## Usage ```sh influxd inspect report-tsm [flags] ``` ## Output details `influxd inspect report-tsm` outputs the following for each TSM file: * The full file name. * The series cardinality within the file. * The number of series first encountered within the file. * The minimum and maximum timestamp associated with TSM data in the file. * The time to load the TSM index and apply any tombstones. The summary section then outputs the total time range and series cardinality for the file set. Depending on the `--detailed` flag, series cardinality is segmented in the following ways: * Series cardinality for each organization. * Series cardinality for each bucket. * Series cardinality for each measurement. * Number of field keys for each measurement. * Number of tag values for each tag key. ## Flags |Flag| | Description |Input Type| |----|-------------|------------------------------------------------------------------------------------------------|----------| | |`--data-path`| Path to data directory (defaults to `~/.influxdbv2/engine/data`). | string | | |`--detailed` |Emit series cardinality segmented by measurements, tag keys, and fields. ***May take a while***.| | | | `--exact` | Calculate an exact cardinality count. ***May use significant memory***. | | |`-h`| `--help` | Help for the `report-tsm` command. | | | | `--pattern` | Only process TSM files containing pattern. | string | [tsm](/influxdb/v2/tags/tsm/)[cardinality](/influxdb/v2/tags/cardinality/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --data-path | Path to data directory (defaults to ~/.influxdbv2/engine/data ). | string | | | --detailed | Emit series cardinality segmented by measurements, tag keys, and fields. May take a while . | | | | --exact | Calculate an exact cardinality count. May use significant memory . | | | -h | --help | Help for the report-tsm command. | | | | --pattern | Only process TSM files containing pattern. | string | --- # influxd inspect verify-seriesfile Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/verify-seriesfile/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect verify-seriesfile` command verifies the integrity of series files. ## Usage ```sh influxd inspect verify-seriesfile [flags] ``` ## Flags |Flag| | Description |Input Type| |----|---------------|---------------------------------------------------------------------------------------------|----------| | | `--bucket-id` | Verify series files from a specific bucket. | string | |`-c`|`--concurrency`|Number of workers to run concurrently (defaults to the number of available processing units).| integer | | | `--data-path` | Path to data directory (defaults to `~/.influxdbv2/engine/data`). | string | |`-h`| `--help` | Help for the `verify-seriesfile` command. | | | |`--series-path`| Path to series file (overrides `--data-path` and `--bucket-id`). | string | |`-v`| `--verbose` | Enable verbose output. | | [inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bucket-id | Verify series files from a specific bucket. | string | | -c | --concurrency | Number of workers to run concurrently (defaults to the number of available processing units). | integer | | | --data-path | Path to data directory (defaults to ~/.influxdbv2/engine/data ). | string | | -h | --help | Help for the verify-seriesfile command. | | | | --series-path | Path to series file (overrides --data-path and --bucket-id ). | string | | -v | --verbose | Enable verbose output. | | --- # influxd inspect verify-tombstone Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/verify-tombstone/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect verify-tombstone` command verifies the integrity of tombstone files. ## Usage ```sh influxd inspect verify-tombstone [flags] ``` ## Flags |Flag| | Description |Input Type| |----|---------------|--------------------------------------------------------------------|----------| | |`--engine-path`| Path to find tombstone files (defaults to `~/.influxdbv2/engine`). | string | |`-h`| `--help` | Help for `verify-tombstone`. | | |`-v`| `--verbose` | Verbose output (emit periodic progress). | | | | `--vv` |Very verbose output (emit every tombstone entry key and time range).| | [inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --engine-path | Path to find tombstone files (defaults to ~/.influxdbv2/engine ). | string | | -h | --help | Help for verify-tombstone . | | | -v | --verbose | Verbose output (emit periodic progress). | | | | --vv | Very verbose output (emit every tombstone entry key and time range). | | --- # influxd inspect verify-tsm Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/verify-tsm/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect verify-tsm` command verifies the integrity of TSM files. ## Usage ```sh influxd inspect verify-tsm [flags] ``` ## Flags |Flag| | Description |Input Type| |----|---------------|-----------------------------------------------------------------------|----------| | |`--check-utf8` |Verify series keys are valid UTF-8 (skips block checksum verification).| | | |`--engine-path`| Storage engine directory path (default is `~/.influxdbv2/engine`). | string | |`-h`| `--help` | Help for `verify-tsm`. | | |`-v`| `--verbose` | Enable verbose logging. | | [tsm](/influxdb/v2/tags/tsm/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --check-utf8 | Verify series keys are valid UTF-8 (skips block checksum verification). | | | | --engine-path | Storage engine directory path (default is ~/.influxdbv2/engine ). | string | | -h | --help | Help for verify-tsm . | | | -v | --verbose | Enable verbose logging. | | --- # influxd inspect verify-wal Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/verify-wal/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd inspect verify-wal` command analyzes the Write-Ahead Log (WAL) to check if there are any corrupt files. If it finds corrupt files, the command returns the names of those files. It also returns the total number of entries in each scanned WAL file. ## Usage ```sh influxd inspect verify-wal [flags] ``` ## Output details `influxd inspect verify-wal` outputs the following for each file: * The file name. * The first position of any identified corruption or “clean” if no corruption is found. After the verification is complete, it returns a summary with: * The number of WAL files scanned. * The number of WAL entries scanned. * A list of files found to be corrupt. ## Flags |Flag| | Description |Input Type| |----|------------|-------------------------------------------------------------|----------| |`-h`| `--help` | Help for the `verify-wal` command. | | |`-v`|`--verbose` | Enable verbose logging. | | | |`--wal-path`|Path to WAL directory (default is `~/.influxdbv2/engine/wal`)| string | [wal](/influxdb/v2/tags/wal/)[inspect](/influxdb/v2/tags/inspect/) | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | -h | --help | Help for the verify-wal command. | | | -v | --verbose | Enable verbose logging. | | | | --wal-path | Path to WAL directory (default is ~/.influxdbv2/engine/wal ) | string | --- # influxd recovery Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery` command and subcommands provide tools for recovering operator access to InfluxDB by directly modifying authorization, organization, and user data stored on disk. ## Usage ```sh influxd recovery [flags] influxd recovery [command] ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------|----------------------------------------------| |[auth](/influxdb/v2/reference/cli/influxd/recovery/auth/)|Manage on-disk authorization data for recovery| | [org](/influxdb/v2/reference/cli/influxd/recovery/org/) |Manage on-disk organization data for recovery | |[user](/influxdb/v2/reference/cli/influxd/recovery/user/)| Manage on-disk user data for recovery | ## Flags |Flag| | Description | |----|--------|-------------------| |`-h`|`--help`|Help for `recovery`| | Subcommand | Description | | --- | --- | | Subcommand | Description | | auth | Manage on-disk authorization data for recovery | | org | Manage on-disk organization data for recovery | | user | Manage on-disk user data for recovery | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for recovery | --- # influxd recovery auth Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/auth/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery auth` command and subcommands manage on-disk authorization data for recovery purposes. ## Usage ```sh influxd recovery auth [flags] influxd recovery auth [command] ``` ## Subcommands | Subcommand | Description | |------------------------------------------------------------------------------------|------------------------------------| |[create-operator](/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator/)|Create new operator token for a user| | [list](/influxdb/v2/reference/cli/influxd/recovery/auth/list/) | List authorizations | ## Flags |Flag| | Description | |----|--------|---------------| |`-h`|`--help`|Help for `auth`| | Subcommand | Description | | --- | --- | | Subcommand | Description | | create-operator | Create new operator token for a user | | list | List authorizations | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for auth | --- # influxd recovery auth create-operator Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery auth create-operator` command creates a new[Operator token](/influxdb/v2/admin/tokens/#operator-token) directly on disk for a specified user. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery auth create-operator [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|--------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `create-operator` | | | | `--org` | (Required) Organization name | string | | |`--username` | (Required) Username to assign the operator token to | string | ## Examples ##### Generate a new operator token ```sh influxd recovery auth create-operator \ --org example-org \ --username example-user ``` | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~/.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for create-operator | | | | --org | ( Required ) Organization name | string | | | --username | ( Required ) Username to assign the operator token to | string | --- # influxd recovery auth list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/auth/list/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery auth list` command lists authorizations stored on disk and outputs data associated with each authorization. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery auth list [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|--------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `list` | | | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~/.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for list | | --- # influxd recovery org Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/org/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery org` command and subcommands manage on-disk organization data for recovery purposes. ## Usage ```sh influxd recovery org [flags] influxd recovery org [command] ``` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------------|------------------| |[create](/influxdb/v2/reference/cli/influxd/recovery/org/create/)| Create new org | | [list](/influxdb/v2/reference/cli/influxd/recovery/org/list/) |List organizations| ## Flags |Flag| | Description | |----|--------|--------------| |`-h`|`--help`|Help for `org`| | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create new org | | list | List organizations | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for org | --- # influxd recovery org create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/org/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery org create` command creates a new organization directly on disk for recovery purposes. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery org create [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|--------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `create` | | | | `--org` | Organization name | string | ## Examples ##### Create a new organization directly on disk ```sh influxd recovery org create --org example-org ``` | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~/.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for create | | | | --org | Organization name | string | --- # influxd recovery org list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/org/list/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery org list` command lists organizations stored on disk and outputs data associated with each organization. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery org list [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|--------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `list` | | | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~/.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for list | | --- # influxd recovery user Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/user/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery user` command and subcommands manage on-disk user data for recovery purposes. ## Usage ```sh influxd recovery user [flags] influxd recovery user [command] ``` ## Subcommands | Subcommand | Description | |------------------------------------------------------------------|-----------------| |[create](/influxdb/v2/reference/cli/influxd/recovery/user/create/)| Create new user | | [list](/influxdb/v2/reference/cli/influxd/recovery/user/list/) | List users | | [update](/influxdb/v2/reference/cli/influxd/recovery/user/list/) |Update a password| ## Flags |Flag| | Description | |----|--------|---------------| |`-h`|`--help`|Help for `user`| | Subcommand | Description | | --- | --- | | Subcommand | Description | | create | Create new user | | list | List users | | update | Update a password | | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for user | --- # influxd recovery user create Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/user/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery user create` command creates a new user directly on disk for recovery purposes. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery user create [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|-------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `create` | | | |`--password` | Password for the new user | string | | |`--username` | Username of the new user | string | ## Examples ##### Create a new user directly on disk ```sh influxd recovery user create \ --username example-username \ --password ExAmPL3-paS5W0rD ``` | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for create | | | | --password | Password for the new user | string | | | --username | Username of the new user | string | --- # influxd recovery user list Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/user/list/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd recovery user list` command lists users stored on disk and outputs data associated with each user. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery user list [flags] ``` ## Flags |Flag| | Description |Input Type| |----|-------------|-------------------------------------------------------------|----------| | |`--bolt-path`|Path to the BoltDB file (default `~.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `list` | | | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for list | | --- # influxd recovery user update Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/recovery/user/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use `influxd recovery user update` to update a password. Useful when you forget your username and need to update your credentials. To retrieve all usernames in the system, use [`influxd recovery user list`](/influxdb/v2/reference/cli/influxd/recovery/user/list/) or use [`influxd recovery user create`](/influxdb/v2/reference/cli/influxd/recovery/user/create/) to create new user for recovery purposes. > [!Note] > This command can only be executed when the InfluxDB server (`influxd`) is not running. ## Usage ```sh influxd recovery user update [flags] ``` ## Flags |Flag| | Description |Input Type| |----|--------------------|-------------------------------------------------------------|----------| | | `--bolt-path` |Path to the BoltDB file (default `~.influxdbv2/influxd.bolt`)| string | |`-h`| `--help` | Help for `update` | | | |`--id` or `username`| Enter the ID or name for an existing user | string | | | `--password` | New password for the specified user | string | ## Examples ##### Update a user password ```sh influxd recovery user update \ --username example-username \ --password ExAmPL3-paS5W0rD ``` | Flag | | Description | Input Type | | --- | --- | --- | --- | | Flag | | Description | Input Type | | | --bolt-path | Path to the BoltDB file (default ~.influxdbv2/influxd.bolt ) | string | | -h | --help | Help for update | | | | --id or username | Enter the ID or name for an existing user | string | | | --password | New password for the specified user | string | --- # influxd run Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/run/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd run` command is the default command for `influxd`. It starts and runs all the processes necessary for InfluxDB to function. ## Usage ``` influxd run [flags] ``` > [!Note] > Because `run` is the default command for `influxd`, the following commands are the same: > > ``` > influxd > influxd run > ``` > [!Note] > For information about other available InfluxDB configuration methods, see[InfluxDB configuration options](/influxdb/v2/reference/config-options/). ## Flags * [--assets-path](/influxdb/v2/reference/config-options/#assets-path) * [--bolt-path](/influxdb/v2/reference/config-options/#bolt-path) * [--e2e-testing](/influxdb/v2/reference/config-options/#e2e-testing) * [--engine-path](/influxdb/v2/reference/config-options/#engine-path) * [--feature-flags](/influxdb/v2/reference/config-options/#feature-flags) * [--flux-log-enabled](/influxdb/v2/reference/config-options/#flux-log-enabled) * [--hardening-enabled](/influxdb/v2/reference/config-options/#hardening-enabled) * [--health-auth-mode](/influxdb/v2/reference/config-options/#health-auth-mode) * -h, --help * [--http-bind-address](/influxdb/v2/reference/config-options/#http-bind-address) * [--http-idle-timeout](/influxdb/v2/reference/config-options/#http-idle-timeout) * [--http-read-header-timeout](/influxdb/v2/reference/config-options/#http-read-header-timeout) * [--http-read-timeout](/influxdb/v2/reference/config-options/#http-read-timeout) * [--http-user-query-bytes-enabled](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled) * [--http-user-write-bytes-enabled](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled) * [--http-write-timeout](/influxdb/v2/reference/config-options/#http-write-timeout) * [--influxql-max-select-buckets](/influxdb/v2/reference/config-options/#influxql-max-select-buckets) * [--influxql-max-select-point](/influxdb/v2/reference/config-options/#influxql-max-select-point) * [--influxql-max-select-series](/influxdb/v2/reference/config-options/#influxql-max-select-series) * [--influxql-max-time-range](/influxdb/v2/reference/config-options/#influxql-max-time-range) * [--instance-id](/influxdb/v2/reference/config-options/#instance-id) * [--log-level](/influxdb/v2/reference/config-options/#log-level) * [--metrics-disabled](/influxdb/v2/reference/config-options/#metrics-disabled) * [--nats-max-payload-bytes](/influxdb/v2/reference/config-options/#nats-max-payload-bytes)*- (deprecated in InfluxDB 2.2)* * [--nats-port](/influxdb/v2/reference/config-options/#nats-port)*- (deprecated in InfluxDB 2.2)* * [--no-tasks](/influxdb/v2/reference/config-options/#no-tasks) * [--overwrite-pid-file](/influxdb/v2/reference/config-options/#overwrite-pid-file) * [--pid-file](/influxdb/v2/reference/config-options/#pid-file) * [--pprof-disabled](/influxdb/v2/reference/config-options/#pprof-disabled) * [--query-concurrency](/influxdb/v2/reference/config-options/#query-concurrency) * [--query-initial-memory-bytes](/influxdb/v2/reference/config-options/#query-initial-memory-bytes) * [--query-max-memory-bytes](/influxdb/v2/reference/config-options/#query-max-memory-bytes) * [--query-memory-bytes](/influxdb/v2/reference/config-options/#query-memory-bytes) * [--query-queue-size](/influxdb/v2/reference/config-options/#query-queue-size) * [--reporting-disabled](/influxdb/v2/reference/config-options/#reporting-disabled) * [--secret-store](/influxdb/v2/reference/config-options/#secret-store) * [--session-length](/influxdb/v2/reference/config-options/#session-length) * [--session-renew-disabled](/influxdb/v2/reference/config-options/#session-renew-disabled) * [--sqlite-path](/influxdb/v2/reference/config-options/#sqlite-path) * [--startup-error-linger](/influxdb/v2/reference/config-options/#startup-error-linger) * [--storage-cache-max-memory-size](/influxdb/v2/reference/config-options/#storage-cache-max-memory-size) * [--storage-cache-snapshot-memory-size](/influxdb/v2/reference/config-options/#storage-cache-snapshot-memory-size) * [--storage-cache-snapshot-write-cold-duration](/influxdb/v2/reference/config-options/#storage-cache-snapshot-write-cold-duration) * [--storage-compact-full-write-cold-duration](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration) * [--storage-compact-throughput](/influxdb/v2/reference/config-options/#storage-compact-throughput) * [--storage-compact-throughput-burst](/influxdb/v2/reference/config-options/#storage-compact-throughput-burst) * [--storage-max-concurrent-compactions](/influxdb/v2/reference/config-options/#storage-max-concurrent-compactions) * [--storage-max-index-log-file-size](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size) * [--storage-no-validate-field-size](/influxdb/v2/reference/config-options/#storage-no-validate-field-size) * [--storage-retention-check-interval](/influxdb/v2/reference/config-options/#storage-retention-check-interval) * [--storage-series-file-max-concurrent-snapshot-compactions](/influxdb/v2/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) * [--storage-series-id-set-cache-size](/influxdb/v2/reference/config-options/#storage-series-id-set-cache-size) * [--storage-shard-precreator-advance-period](/influxdb/v2/reference/config-options/#storage-shard-precreator-advance-period) * [--storage-shard-precreator-check-interval](/influxdb/v2/reference/config-options/#storage-shard-precreator-check-interval) * [--storage-tsm-use-madv-willneed](/influxdb/v2/reference/config-options/#storage-tsm-use-madv-willneed) * [--storage-validate-keys](/influxdb/v2/reference/config-options/#storage-validate-keys) * [--storage-wal-flush-on-shutdown](/influxdb/v2/reference/config-options/#storage-wal-flush-on-shutdown) * [--storage-wal-fsync-delay](/influxdb/v2/reference/config-options/#storage-wal-fsync-delay) * [--storage-wal-max-concurrent-writes](/influxdb/v2/reference/config-options/#storage-wal-max-concurrent-writes) * [--storage-wal-max-write-delay](/influxdb/v2/reference/config-options/#storage-wal-max-write-delay) * [--storage-write-timeout](/influxdb/v2/reference/config-options/#storage-write-timeout) * [--store](/influxdb/v2/reference/config-options/#store) * [--strong-passwords](/influxdb/v2/reference/config-options/#strong-passwords) * [--testing-always-allow-setup](/influxdb/v2/reference/config-options/#testing-always-allow-setup) * [--tls-cert](/influxdb/v2/reference/config-options/#tls-cert) * [--tls-key](/influxdb/v2/reference/config-options/#tls-key) * [--tls-min-version](/influxdb/v2/reference/config-options/#tls-min-version) * [--tls-strict-ciphers](/influxdb/v2/reference/config-options/#tls-strict-ciphers) * [--tracing-type](/influxdb/v2/reference/config-options/#tracing-type) * [--ui-disabled](/influxdb/v2/reference/config-options/#ui-disabled) * [--use-hashed-tokens](/influxdb/v2/reference/config-options/#use-hashed-tokens) * [--vault-addr](/influxdb/v2/reference/config-options/#vault-addr) * [--vault-cacert](/influxdb/v2/reference/config-options/#vault-cacert) * [--vault-capath](/influxdb/v2/reference/config-options/#vault-capath) * [--vault-client-cert](/influxdb/v2/reference/config-options/#vault-client-cert) * [--vault-client-key](/influxdb/v2/reference/config-options/#vault-client-key) * [--vault-client-timeout](/influxdb/v2/reference/config-options/#vault-client-timeout) * [--vault-max-retries](/influxdb/v2/reference/config-options/#vault-max-retries) * [--vault-skip-verify](/influxdb/v2/reference/config-options/#vault-skip-verify) * [--vault-tls-server-name](/influxdb/v2/reference/config-options/#vault-tls-server-name) * [--vault-token](/influxdb/v2/reference/config-options/#vault-token) #### Related * [InfluxDB configuration options](/influxdb/v2/reference/config-options/) [influxd](/influxdb/v2/tags/influxd/)[cli](/influxdb/v2/tags/cli/) --- # influxd upgrade Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/upgrade/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influxd upgrade` command to upgrade an instance of InfluxDB 1.x to InfluxDB 2.10. This command copies all data in [databases](/influxdb/v1/concepts/glossary/#database) and[retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp) (used in 1.x) over to [buckets](/influxdb/v2/reference/glossary/#bucket) (used in 2.10). Be sure to back up all data before upgrading with `influx upgrade`. This command performs the following actions: 1. Creates the InfluxDB 2.x configuration file using 1.x configuration file options. Unsupported 1.x options are reported to standard output. If the configuration file is not available, the 1.x database folder can be passed via th `--v1-dir` flag. 2. Copies and upgrades 1.x database files. In InfluxDB OSS v2.10 and later, the upgrade maps the 1.x `coordinator.max-time-range` option to [`influxql-max-time-range`](/influxdb/v2/reference/config-options/#influxql-max-time-range). The target 2.x database directory is specified by the `--engine-path` option. If changed, the bolt path can be specified by the `--bolt-path` option. ## Usage ``` influxd upgrade [flags] influxd upgrade [command] ``` ## Flags |Flag| | Description |Input type| |----|--------------------------------|----------------------------------------------------------------------------------------------------------|----------| |`-m`| `--bolt-path` | Path for boltdb database (default `~/.influxdbv2/influxd.bolt`) | string | |`-b`| `--bucket` | Primary bucket name | string | | | `--config-file` | Custom InfluxDB 1.x config file path (default `~/.influxdb/influxdb.conf`) | string | | |`--continuous-query-export-path`| Path for exported 1.x continuous queries (default `~/continuous_queries.txt`) | string | |`-e`| `--engine-path` | Path for persistent engine files (default `~/.influxdbv2/engine`) | string | |`-f`| `--force` | Skip the confirmation prompt | | |`-h`| `--help` | Help for `influxd upgrade` | | |`-c`| `--influx-configs-path` | Path for 2.x `influx` CLI configurations file (default `~/.influxdbv2/configs`) | | | | `--log-level` | Supported log levels are `debug`, `info`, `warn`, and `error` (default `info`) | string | | | `--log-path` | Custom log file path (default `~/upgrade.log`) | string | |`-o`| `--org` | Primary organization name | string | | | `--overwrite-existing-v2` | Overwrite existing files at the output paths instead of aborting the upgrade process | | |`-p`| `--password` | Password for username | string | |`-r`| `--retention` | Duration bucket will retain data (default `0`; retains data infinitely) | string | |`-t`| `--token` | Token for username. If not specified, a token is auto-generated. | string | |`-u`| `--username` | Primary username | string | | | `--v1-dir` |Path to source 1.x `db` directory containing `meta`, `data`, and `wal` sub-folders (default `~/.influxdb`)| string | | | `--v2-config-path` | Destination path for upgraded 2.x configuration file (default `~/.influxdbv2/config.toml`) | string | |`-v`| `--verbose` | Verbose output | | | Flag | | Description | Input type | | --- | --- | --- | --- | | Flag | | Description | Input type | | -m | --bolt-path | Path for boltdb database (default ~/.influxdbv2/influxd.bolt ) | string | | -b | --bucket | Primary bucket name | string | | | --config-file | Custom InfluxDB 1.x config file path (default ~/.influxdb/influxdb.conf ) | string | | | --continuous-query-export-path | Path for exported 1.x continuous queries (default ~/continuous_queries.txt ) | string | | -e | --engine-path | Path for persistent engine files (default ~/.influxdbv2/engine ) | string | | -f | --force | Skip the confirmation prompt | | | -h | --help | Help for influxd upgrade | | | -c | --influx-configs-path | Path for 2.x influx CLI configurations file (default ~/.influxdbv2/configs ) | | | | --log-level | Supported log levels are debug , info , warn , and error (default info ) | string | | | --log-path | Custom log file path (default ~/upgrade.log ) | string | | -o | --org | Primary organization name | string | | | --overwrite-existing-v2 | Overwrite existing files at the output paths instead of aborting the upgrade process | | | -p | --password | Password for username | string | | -r | --retention | Duration bucket will retain data (default 0 ; retains data infinitely) | string | | -t | --token | Token for username. If not specified, a token is auto-generated. | string | | -u | --username | Primary username | string | | | --v1-dir | Path to source 1.x db directory containing meta , data , and wal sub-folders (default ~/.influxdb ) | string | | | --v2-config-path | Destination path for upgraded 2.x configuration file (default ~/.influxdbv2/config.toml ) | string | | -v | --verbose | Verbose output | | --- # influxd version Source: https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/version/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The `influxd version` command outputs the current version of InfluxDB. ## Usage ``` influxd version [flags] ``` ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `version` command| [influxd](/influxdb/v2/tags/influxd/)[cli](/influxdb/v2/tags/cli/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the version command | --- # InfluxDB configuration options Source: https://docs.influxdata.com/influxdb/v2/reference/config-options/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Customize your InfluxDB configuration by using [`influxd`](/influxdb/v2/reference/cli/influxd/)configuration flags, setting environment variables, or defining configuration options in a configuration file. * [View your runtime server configuration](#view-your-runtime-server-configuration) * [Configuration precedence](#configuration-precedence) * [InfluxDB configuration file](#influxdb-configuration-file) * [Configuration options](#configuration-options) ### View your runtime server configuration Use the `influx` CLI or the InfluxDB API to get the runtime server configuration of your InfluxDB instance. Server configuration commands require an [Operator token](/influxdb/v2/admin/tokens/#operator-token). #### View your server configuration with the CLI Use the [`influx server-config` command](/influxdb/v2/reference/cli/influx/server-config/)to retrieve your runtime server configuration. ```sh influx server-config ``` ### View your server configuration with the API Use the `/api/v2/config` InfluxDB API endpoint to retrieve your runtime server configuration. ``` GET http://localhost:8086/api/v2/config ``` ### Configuration precedence InfluxDB honors configuration settings using the following precedence: 1. `influxd` flags 2. Environment variables 3. Configuration file settings ### InfluxDB configuration file When `influxd` starts, it checks for a file named `config.*` **in the current working directory**. The file extension depends on the syntax of the configuration file. InfluxDB configuration files support the following syntaxes: * **YAML** (`.yaml`, `.yml`) * **TOML** (`.toml`) * **JSON** (`.json`) To customize the directory path of the configuration file, set the `INFLUXD_CONFIG_PATH`environment variable to your custom path. ```sh export INFLUXD_CONFIG_PATH=/path/to/custom/config/directory ``` On startup, `influxd` will check for a `config.*` in the `INFLUXD_CONFIG_PATH` directory. ##### Example configuration file [YAML](#yaml)[TOML](#toml)[JSON](#json) ```yaml query-concurrency: 20 query-queue-size: 15 secret-store: vault session-length: 120 tls-cert: /path/to/influxdb.crt tls-key: /path/to/influxdb.key ``` ```toml query-concurrency = 20 query-queue-size = 15 secret-store = "vault" session-length = 120 tls-cert = "/path/to/influxdb.crt" tls-key = "/path/to/influxdb.key" ``` ```json { "query-concurrency": 20, "query-queue-size": 15, "secret-store": "vault", "session-length": 120, "tls-cert": "/path/to/influxdb.crt", "tls-key": "/path/to/influxdb.key" } ``` > [!Note] > Only non-default settings need to be defined in the configuration file. ## Configuration options To configure InfluxDB, use the following configuration options when starting the[`influxd` service](/influxdb/v2/reference/cli/influxd): * [assets-path](#assets-path) * [bolt-path](#bolt-path) * [e2e-testing](#e2e-testing) * [engine-path](#engine-path) * [feature-flags](#feature-flags) * [flux-log-enabled](#flux-log-enabled) * [hardening-enabled](#hardening-enabled) * [health-auth-mode](#health-auth-mode) * [http-bind-address](#http-bind-address) * [http-idle-timeout](#http-idle-timeout) * [http-read-header-timeout](#http-read-header-timeout) * [http-read-timeout](#http-read-timeout) * [http-user-query-bytes-enabled](#http-user-query-bytes-enabled) * [http-user-write-bytes-enabled](#http-user-write-bytes-enabled) * [http-write-timeout](#http-write-timeout) * [influxql-max-select-buckets](#influxql-max-select-buckets) * [influxql-max-select-point](#influxql-max-select-point) * [influxql-max-select-series](#influxql-max-select-series) * [influxql-max-time-range](#influxql-max-time-range) * [instance-id](#instance-id) * [log-level](#log-level) * [metrics-disabled](#metrics-disabled) * [nats-max-payload-bytes](#nats-max-payload-bytes) *- (deprecated)* * [nats-port](#nats-port) *- (deprecated)* * [no-tasks](#no-tasks) * [overwrite-pid-file](#overwrite-pid-file) * [pid-file](#pid-file) * [pprof-disabled](#pprof-disabled) * [query-concurrency](#query-concurrency) * [query-initial-memory-bytes](#query-initial-memory-bytes) * [query-max-memory-bytes](#query-max-memory-bytes) * [query-memory-bytes](#query-memory-bytes) * [query-queue-size](#query-queue-size) * [reporting-disabled](#reporting-disabled) * [secret-store](#secret-store) * [session-length](#session-length) * [session-renew-disabled](#session-renew-disabled) * [sqlite-path](#sqlite-path) * [startup-error-linger](#startup-error-linger) * [storage-cache-max-memory-size](#storage-cache-max-memory-size) * [storage-cache-snapshot-memory-size](#storage-cache-snapshot-memory-size) * [storage-cache-snapshot-write-cold-duration](#storage-cache-snapshot-write-cold-duration) * [storage-compact-full-write-cold-duration](#storage-compact-full-write-cold-duration) * [storage-compact-throughput](#storage-compact-throughput) * [storage-compact-throughput-burst](#storage-compact-throughput-burst) * [storage-max-concurrent-compactions](#storage-max-concurrent-compactions) * [storage-max-index-log-file-size](#storage-max-index-log-file-size) * [storage-no-validate-field-size](#storage-no-validate-field-size) * [storage-retention-check-interval](#storage-retention-check-interval) * [storage-series-file-max-concurrent-snapshot-compactions](#storage-series-file-max-concurrent-snapshot-compactions) * [storage-series-id-set-cache-size](#storage-series-id-set-cache-size) * [storage-shard-precreator-advance-period](#storage-shard-precreator-advance-period) * [storage-shard-precreator-check-interval](#storage-shard-precreator-check-interval) * [storage-tsm-use-madv-willneed](#storage-tsm-use-madv-willneed) * [storage-validate-keys](#storage-validate-keys) * [storage-wal-fsync-delay](#storage-wal-fsync-delay) * [storage-wal-max-concurrent-writes](#storage-wal-max-concurrent-writes) * [storage-wal-max-write-delay](#storage-wal-max-write-delay) * [storage-write-timeout](#storage-write-timeout) * [store](#store) * [strong-passwords](#strong-passwords) * [testing-always-allow-setup](#testing-always-allow-setup) * [tls-cert](#tls-cert) * [tls-key](#tls-key) * [tls-min-version](#tls-min-version) * [tls-strict-ciphers](#tls-strict-ciphers) * [tracing-type](#tracing-type) * [ui-disabled](#ui-disabled) * [use-hashed-tokens](#use-hashed-tokens) * [vault-addr](#vault-addr) * [vault-cacert](#vault-cacert) * [vault-capath](#vault-capath) * [vault-client-cert](#vault-client-cert) * [vault-client-key](#vault-client-key) * [vault-client-timeout](#vault-client-timeout) * [vault-max-retries](#vault-max-retries) * [vault-skip-verify](#vault-skip-verify) * [vault-tls-server-name](#vault-tls-server-name) * [vault-token](#vault-token) ### assets-path Override the default InfluxDB user interface (UI) assets by serving assets from the specified directory.*Typically, InfluxData internal use only.* | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--assets-path`|`INFLUXD_ASSETS_PATH`| `assets-path` | ###### influxd flag ```sh influxd --assets-path=/path/to/custom/assets-dir ``` ###### Environment variable ```sh export INFLUXD_ASSETS_PATH=/path/to/custom/assets-dir ``` ###### Configuration file [YAML](#yaml-2)[TOML](#toml-2)[JSON](#json-2) ```yml assets-path: /path/to/custom/assets-dir ``` ```toml assets-path = "/path/to/custom/assets-dir" ``` ```json { "assets-path": "/path/to/custom/assets-dir" } ``` ### bolt-path Path to the [BoltDB](https://github.com/boltdb/bolt) database. BoltDB is a key value store written in Go. InfluxDB uses BoltDB to store data including organization and user information, UI data, REST resources, and other key value data. **Default:** `~/.influxdbv2/influxd.bolt` |influxd flag |Environment variable|Configuration key| |-------------|--------------------|-----------------| |`--bolt-path`|`INFLUXD_BOLT_PATH` | `bolt-path` | ###### influxd flag ```sh influxd --bolt-path=~/.influxdbv2/influxd.bolt ``` ###### Environment variable ```sh export INFLUXD_BOLT_PATH=~/.influxdbv2/influxd.bolt ``` ###### Configuration file [YAML](#yaml-3)[TOML](#toml-3)[JSON](#json-3) ```yml bolt-path: ~/.influxdbv2/influxd.bolt ``` ```toml bolt-path = "~/.influxdbv2/influxd.bolt" ``` ```json { "bolt-path": "~/.influxdbv2/influxd.bolt" } ``` ### e2e-testing Add a `/debug/flush` endpoint to the InfluxDB HTTP API to clear stores. InfluxData uses this endpoint in end-to-end testing. | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--e2e-testing`|`INFLUXD_E2E_TESTING`| `e2e-testing` | ###### influxd flag ```sh influxd --e2e-testing ``` ###### Environment variable ```sh export INFLUXD_E2E_TESTING=true ``` ###### Configuration file [YAML](#yaml-4)[TOML](#toml-4)[JSON](#json-4) ```yml e2e-testing: true ``` ```toml e2e-testing = true ``` ```json { "e2e-testing": true } ``` ### engine-path Path to persistent storage engine files where InfluxDB stores all Time-Structure Merge Tree (TSM) data on disk. **Default:** `~/.influxdbv2/engine` | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--engine-path`|`INFLUXD_ENGINE_PATH`| `engine-path` | ###### influxd flag ```sh influxd --engine-path=~/.influxdbv2/engine ``` ###### Environment variable ```sh export INFLUXD_ENGINE_PATH=~/.influxdbv2/engine ``` ###### Configuration file [YAML](#yaml-5)[TOML](#toml-5)[JSON](#json-5) ```yml engine-path: ~/.influxdbv2/engine ``` ```toml engine-path = "~/.influxdbv2/engine" ``` ```json { "engine-path": "~/.influxdbv2/engine" } ``` ### feature-flags Enable, disable, or override default values for feature flags. > [!Note] > Feature flags are used to develop and test experimental features and are > intended for internal use only. | influxd flag | Environment variable |Configuration key| |-----------------|-----------------------|-----------------| |`--feature-flags`|`INFLUXD_FEATURE_FLAGS`| `feature-flags` | ###### influxd flag ```sh influxd --feature-flags flag1=value2,flag2=value2 ``` ###### Environment variable ```sh export INFLUXD_FEATURE_FLAGS="{\"flag1\":\value1\",\"flag2\":\"value2\"}" ``` ###### Configuration file [YAML](#yaml-6)[TOML](#toml-6)[JSON](#json-6) ```yml feature-flags: flag1: "value1" flag2: "value2" ``` ```toml [feature-flags] flag1 = "value1" glag2 = "value2" ``` ```json { "feature-flags": { "flag1": "value1", "flag2": "value2" } } ``` ### flux-log-enabled Include option to show detailed logs for Flux queries, including the following log fields: * `compiler_type`: Compiler used for processing the query (will always be Flux). * `response_size`: Size of the response, in bytes. * `query`: The textual representation of the query. * `err`: Errors encountered while processing the query. * `stat_total_duration`: Total duration to process the query. * `stat_compile_duration`: Duration to compile the query. * `stat_execute_duration`: Duration to execute the query. * `stat_max_allocated`: Maximum amount of memory allocated while processing the query, in - bytes. * `stat_total_allocated`: Total amount of memory allocated while processing the query, in bytes. This includes memory that was freed and then used again. **Default:** `false` | influxd flag | Environment variable |Configuration key | |--------------------|--------------------------|------------------| |`--flux-log-enabled`|`INFLUXD_FLUX_LOG_ENABLED`|`flux-log-enabled`| ###### influxd flag ```sh influxd --flux-log-enabled ``` ###### Environment variable ```sh export INFLUXD_FLUX_LOG_ENABLED=true ``` ###### Configuration file [YAML](#yaml-7)[TOML](#toml-7)[JSON](#json-7) ```yml flux-log-enabled: true ``` ```toml flux-log-enabled = "true" ``` ```json { "flux-log-enabled": "true" } ``` ### hardening-enabled Enable [additional security features](/influxdb/v2/admin/security/enable-hardening/)in InfluxDB. In InfluxDB OSS v2.10 and later, hardening also restricts the detail that the`/health` and `/ready` endpoints return to callers without operator permissions. To keep full `/health` and `/ready` responses with hardening enabled, set [`health-auth-mode`](#health-auth-mode) to `disabled`. **Default:** `false` | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--hardening-enabled`|`INFLUXD_HARDENING_ENABLED`|`hardening-enabled`| ###### influxd flag ```sh influxd --hardening-enabled ``` ###### Environment variable ```sh export INFLUXD_HARDENING_ENABLED=true ``` ###### Configuration file [YAML](#yaml-8)[TOML](#toml-8)[JSON](#json-8) ```yml hardening-enabled: true ``` ```toml hardening-enabled = true ``` ```json { "hardening-enabled": true } ``` ### health-auth-mode *Available in InfluxDB OSS v2.10 and later.* Controls whether the `/health` and `/ready` endpoints require operator permissions to return check details. By default, `/health` and `/ready` don’t require authentication and return full check details. After a failed startup, check messages contain the raw error text, which can include file system paths and other configuration details. To hide these details from callers without operator permissions, set this option to `required`. This option never changes the HTTP status code, so liveness and readiness probes without credentials keep working. A caller without operator permissions receives a reduced response body: check names and statuses, without messages or build information. If startup fails before InfluxDB can verify tokens, every caller receives the reduced response body. Valid values: * `auto`: Restrict details only when [`hardening-enabled`](#hardening-enabled) is `true`. * `required`: Always restrict details. * `disabled`: Never restrict details, even when `hardening-enabled` is `true`. Write the value explicitly, for example `--health-auth-mode=required`.`true` and `false` aren’t valid values. **Default:** `auto` | influxd flag | Environment variable |Configuration key | |--------------------|--------------------------|------------------| |`--health-auth-mode`|`INFLUXD_HEALTH_AUTH_MODE`|`health-auth-mode`| ###### influxd flag ```sh influxd --health-auth-mode=required ``` ###### Environment variable ```sh export INFLUXD_HEALTH_AUTH_MODE=required ``` ###### Configuration file [YAML](#yaml-9)[TOML](#toml-9)[JSON](#json-9) ```yml health-auth-mode: required ``` ```toml health-auth-mode = "required" ``` ```json { "health-auth-mode": "required" } ``` ### http-bind-address Bind address for the InfluxDB HTTP API. Customize the URL and port for the InfluxDB API and UI. **Default:** `:8086` | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--http-bind-address`|`INFLUXD_HTTP_BIND_ADDRESS`|`http-bind-address`| ###### influxd flag ```sh influxd --http-bind-address=:8086 ``` ###### Environment variable ```sh export INFLUXD_HTTP_BIND_ADDRESS=:8086 ``` ###### Configuration file [YAML](#yaml-10)[TOML](#toml-10)[JSON](#json-10) ```yml http-bind-address: ":8086" ``` ```toml http-bind-address = ":8086" ``` ```json { "http-bind-address": ":8086" } ``` ### http-idle-timeout Maximum duration the server should keep established connections alive while waiting for new requests. Set to `0` for no timeout. **Default:** `3m0s` | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--http-idle-timeout`|`INFLUXD_HTTP_IDLE_TIMEOUT`|`http-idle-timeout`| ###### influxd flag ```sh influxd --http-idle-timeout=3m0s ``` ###### Environment variable ```sh export INFLUXD_HTTP_IDLE_TIMEOUT=3m0s ``` ###### Configuration file [YAML](#yaml-11)[TOML](#toml-11)[JSON](#json-11) ```yml http-idle-timeout: 3m0s ``` ```toml http-idle-timeout = "3m0s" ``` ```json { "http-idle-timeout": "3m0s" } ``` ### http-read-header-timeout Maximum duration the server should try to read HTTP headers for new requests. Set to `0` for no timeout. **Default:** `10s` | influxd flag | Environment variable | Configuration key | |----------------------------|----------------------------------|--------------------------| |`--http-read-header-timeout`|`INFLUXD_HTTP_READ_HEADER_TIMEOUT`|`http-read-header-timeout`| ###### influxd flag ```sh influxd --http-read-header-timeout=10s ``` ###### Environment variable ```sh export INFLUXD_HTTP_READ_HEADER_TIMEOUT=10s ``` ###### Configuration file [YAML](#yaml-12)[TOML](#toml-12)[JSON](#json-12) ```yml http-read-header-timeout: 10s ``` ```toml http-read-header-timeout = "10s" ``` ```json { "http-read-header-timeout": "10s" } ``` ### http-read-timeout Maximum duration the server should try to read the entirety of new requests. Set to `0` for no timeout. **Default:** `0` > [!Note] > #### Set timeouts specific to your workload > > Although no `http-read-timeout` is set by default, we **strongly recommend**setting a timeout specific to your workload. > HTTP timeouts protect against large amounts of open connections that could > potentially hurt performance. | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--http-read-timeout`|`INFLUXD_HTTP_READ_TIMEOUT`|`http-read-timeout`| ###### influxd flag ```sh influxd --http-read-timeout=10s ``` ###### Environment variable ```sh export INFLUXD_HTTP_READ_TIMEOUT=10s ``` ###### Configuration file [YAML](#yaml-13)[TOML](#toml-13)[JSON](#json-13) ```yml http-read-timeout: 10s ``` ```toml http-read-timeout = "10s" ``` ```json { "http-read-timeout": "10s" } ``` ### http-user-query-bytes-enabled *Available in InfluxDB OSS v2.10 and later.* Enable per-user query response byte counting. When enabled, the `/metrics` endpoint exposes the `http_query_user_response_bytes` counter with the `user_id` and `endpoint` labels. For more information, see [HTTP API statistics](/influxdb/v2/reference/internals/metrics/#http-api-statistics). **Default:** `false` | influxd flag | Environment variable | Configuration key | |---------------------------------|---------------------------------------|-------------------------------| |`--http-user-query-bytes-enabled`|`INFLUXD_HTTP_USER_QUERY_BYTES_ENABLED`|`http-user-query-bytes-enabled`| ###### influxd flag ```sh influxd --http-user-query-bytes-enabled=true ``` ###### Environment variable ```sh export INFLUXD_HTTP_USER_QUERY_BYTES_ENABLED=true ``` ###### Configuration file [YAML](#yaml-14)[TOML](#toml-14)[JSON](#json-14) ```yml http-user-query-bytes-enabled: true ``` ```toml http-user-query-bytes-enabled = true ``` ```json { "http-user-query-bytes-enabled": true } ``` ### http-user-write-bytes-enabled *Available in InfluxDB OSS v2.10 and later.* Enable per-user write request byte counting. When enabled, the `/metrics` endpoint exposes the `http_write_user_request_bytes` counter with the `user_id` and `endpoint` labels. For more information, see [HTTP API statistics](/influxdb/v2/reference/internals/metrics/#http-api-statistics). InfluxDB doesn’t count requests that don’t have a valid user ID. In InfluxDB 1.x, these requests are counted as `(anonymous)`. **Default:** `false` | influxd flag | Environment variable | Configuration key | |---------------------------------|---------------------------------------|-------------------------------| |`--http-user-write-bytes-enabled`|`INFLUXD_HTTP_USER_WRITE_BYTES_ENABLED`|`http-user-write-bytes-enabled`| ###### influxd flag ```sh influxd --http-user-write-bytes-enabled=true ``` ###### Environment variable ```sh export INFLUXD_HTTP_USER_WRITE_BYTES_ENABLED=true ``` ###### Configuration file [YAML](#yaml-15)[TOML](#toml-15)[JSON](#json-15) ```yml http-user-write-bytes-enabled: true ``` ```toml http-user-write-bytes-enabled = true ``` ```json { "http-user-write-bytes-enabled": true } ``` ### http-write-timeout Maximum duration to wait before timing out writes of the response. It doesn’t let Handlers decide the duration on a per-request basis. The timeout is reset when a new request’s header is read. Set to `0` for no timeout. **Default:** `0` > [!Note] > #### Set timeouts specific to your workload > > Although no `http-write-timeout` is set by default, we **strongly recommend**setting a timeout specific to your workload. > HTTP timeouts protect against large amounts of open connections that could > potentially hurt performance. | influxd flag | Environment variable | Configuration key | |----------------------|----------------------------|--------------------| |`--http-write-timeout`|`INFLUXD_HTTP_WRITE_TIMEOUT`|`http-write-timeout`| ###### influxd flag ```sh influxd --http-write-timeout=10s ``` ###### Environment variable ```sh export INFLUXD_HTTP_WRITE_TIMEOUT=10s ``` ###### Configuration file [YAML](#yaml-16)[TOML](#toml-16)[JSON](#json-16) ```yml http-write-timeout: 10s ``` ```toml http-write-timeout = "10s" ``` ```json { "http-write-timeout": "10s" } ``` ### influxql-max-select-buckets Maximum number of group by time buckets a `SELECT` statement can create.`0` allows an unlimited number of buckets. **Default:** `0` | influxd flag | Environment variable | Configuration key | |-------------------------------|-------------------------------------|-----------------------------| |`--influxql-max-select-buckets`|`INFLUXD_INFLUXQL_MAX_SELECT_BUCKETS`|`influxql-max-select-buckets`| ###### influxd flag ```sh influxd --influxql-max-select-buckets=0 ``` ###### Environment variable ```sh export INFLUXD_INFLUXQL_MAX_SELECT_BUCKETS=0 ``` ###### Configuration file [YAML](#yaml-17)[TOML](#toml-17)[JSON](#json-17) ```yml influxql-max-select-buckets: 0 ``` ```toml influxql-max-select-buckets = 0 ``` ```json { "influxql-max-select-buckets": 0 } ``` ### influxql-max-select-point Maximum number of points a `SELECT` statement can process.`0` allows an unlimited number of points. InfluxDB checks the point count every second (so queries exceeding the maximum aren’t immediately aborted). **Default:** `0` | influxd flag | Environment variable | Configuration key | |-----------------------------|-----------------------------------|---------------------------| |`--influxql-max-select-point`|`INFLUXD_INFLUXQL_MAX_SELECT_POINT`|`influxql-max-select-point`| ###### influxd flag ```sh influxd --influxql-max-select-point=0 ``` ###### Environment variable ```sh export INFLUXD_INFLUXQL_MAX_SELECT_POINT=0 ``` ###### Configuration file [YAML](#yaml-18)[TOML](#toml-18)[JSON](#json-18) ```yml influxql-max-select-point: 0 ``` ```toml influxql-max-select-point = 0 ``` ```json { "influxql-max-select-point": 0 } ``` ### influxql-max-select-series Maximum number of series a `SELECT` statement can return.`0` allows an unlimited number of series. **Default:** `0` | influxd flag | Environment variable | Configuration key | |------------------------------|------------------------------------|----------------------------| |`--influxql-max-select-series`|`INFLUXD_INFLUXQL_MAX_SELECT_SERIES`|`influxql-max-select-series`| ###### influxd flag ```sh influxd --influxql-max-select-series=0 ``` ###### Environment variable ```sh export INFLUXD_INFLUXQL_MAX_SELECT_SERIES=0 ``` ###### Configuration file [YAML](#yaml-19)[TOML](#toml-19)[JSON](#json-19) ```yml influxql-max-select-series: 0 ``` ```toml influxql-max-select-series = 0 ``` ```json { "influxql-max-select-series": 0 } ``` ### influxql-max-time-range *Available in InfluxDB OSS v2.10 and later.* Maximum time range, as a duration, that an InfluxQL `SELECT` or `EXPLAIN` statement can query.`0` disables the limit. This option doesn’t apply to Flux queries. A query with no upper time bound is measured up to `now()`. A query with no lower time bound covers all time, so it exceeds any non-zero limit. If a statement exceeds the limit, InfluxDB returns an HTTP `200` response and reports the error for that statement in `results[].error`: ```json {"results":[{"statement_id":0,"error":"max-time-range limit exceeded: (1h59m59.999999999s/1h0m0s)"}]} ``` The error has the format `max-time-range limit exceeded: (/)`. Check `results[].error` in your client–the HTTP status code doesn’t indicate the error. The `influxd upgrade` command maps the InfluxDB 1.x `coordinator.max-time-range` option to this option. **Default:** `0` | influxd flag | Environment variable | Configuration key | |---------------------------|---------------------------------|-------------------------| |`--influxql-max-time-range`|`INFLUXD_INFLUXQL_MAX_TIME_RANGE`|`influxql-max-time-range`| ###### influxd flag ```sh influxd --influxql-max-time-range=72h ``` ###### Environment variable ```sh export INFLUXD_INFLUXQL_MAX_TIME_RANGE=72h ``` ###### Configuration file [YAML](#yaml-20)[TOML](#toml-20)[JSON](#json-20) ```yml influxql-max-time-range: 72h ``` ```toml influxql-max-time-range = "72h" ``` ```json { "influxql-max-time-range": "72h" } ``` ### instance-id Identifies edge nodes during replication, and prevents collisions if two edge nodes write the same `measurement,tagset`. | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--instance-id`|`INFLUXD_INSTANCE_ID`| `instance-id` | ###### influxd flag ```sh influxd --instance-id=:8086 ``` ###### Environment variable ```sh export INFLUXD_INSTANCE_ID=:8086 ``` ###### Configuration file [YAML](#yaml-21)[TOML](#toml-21)[JSON](#json-21) ```yml instance-id: ":8086" ``` ```toml instance-id = ":8086" ``` ```json { "instance-id": ":8086" } ``` ### log-level Log output level. InfluxDB outputs log entries with severity levels greater than or equal to the level specified. **Options:** `debug`, `info`, `error` **Default:** `info` |influxd flag |Environment variable|Configuration key| |-------------|--------------------|-----------------| |`--log-level`|`INFLUXD_LOG_LEVEL` | `log-level` | ###### influxd flag ```sh influxd --log-level=info ``` ###### Environment variable ```sh export INFLUXD_LOG_LEVEL=info ``` ###### Configuration file [YAML](#yaml-22)[TOML](#toml-22)[JSON](#json-22) ```yml log-level: info ``` ```toml log-level = "info" ``` ```json { "log-level": "info" } ``` ### metrics-disabled Disable the HTTP `/metrics` endpoint which exposes [internal InfluxDB metrics](/influxdb/v2/reference/internals/metrics/). **Default:** `false` | influxd flag | Environment variable |Configuration key | |--------------------|--------------------------|------------------| |`--metrics-disabled`|`INFLUXD_METRICS_DISABLED`|`metrics-disabled`| ###### influxd flag ```sh influxd --metrics-disabled ``` ###### Environment variable ```sh export INFLUXD_METRICS_DISABLED=true ``` ###### Configuration file [YAML](#yaml-23)[TOML](#toml-23)[JSON](#json-23) ```yml metrics-disabled: true ``` ```toml metrics-disabled = true ``` ```json { "metrics-disabled": true } ``` ### nats-max-payload-bytes `nats-max-payload-bytes` was **deprecated in InfluxDB 2.2** and no longer has any effect. Maximum number of bytes allowed in a NATS message payload. **Default:** `1048576` | influxd flag | Environment variable | Configuration key | |--------------------------|--------------------------------|------------------------| |`--nats-max-payload-bytes`|`INFLUXD_NATS_MAX_PAYLOAD_BYTES`|`nats-max-payload-bytes`| ###### influxd flag ```sh influxd --nats-max-payload-bytes=1048576 ``` ###### Environment variable ```sh export INFLUXD_NATS_MAX_PAYLOAD_BYTES=1048576 ``` ###### Configuration file [YAML](#yaml-24)[TOML](#toml-24)[JSON](#json-24) ```yml nats-max-payload-bytes: 1048576 ``` ```toml nats-max-payload-bytes = 1048576 ``` ```json { "nats-max-payload-bytes": 1048576 } ``` ### nats-port `nats-port` was **deprecated in InfluxDB 2.2** and no longer has any effect. Port for the NATS streaming server. `-1` selects a random port. **Default:** `-1` |influxd flag |Environment variable|Configuration key| |-------------|--------------------|-----------------| |`--nats-port`|`INFLUXD_NATS_PORT` | `nats-port` | ###### influxd flag ```sh influxd --nats-port=-1 ``` ###### Environment variable ```sh export INFLUXD_NATS_PORT=-1 ``` ###### Configuration file [YAML](#yaml-25)[TOML](#toml-25)[JSON](#json-25) ```yml nats-port: -1 ``` ```toml nats-port = -1 ``` ```json { "nats-port": -1 } ``` ### no-tasks Disable the task scheduler. If problematic tasks prevent InfluxDB from starting, use this option to start InfluxDB without scheduling or executing tasks. **Default:** `false` |influxd flag|Environment variable|Configuration key| |------------|--------------------|-----------------| |`--no-tasks`| `INFLUXD_NO_TASKS` | `no-tasks` | ###### influxd flag ```sh influxd --no-tasks ``` ###### Environment variable ```sh export INFLUXD_NO_TASKS=true ``` ###### Configuration file [YAML](#yaml-26)[TOML](#toml-26)[JSON](#json-26) ```yml no-tasks: true ``` ```toml no-tasks = true ``` ```json { "no-tasks": true } ``` ### overwrite-pid-file Overwrite the PID file specified by [pid-file](#pid-file) if it exists, instead of exiting with an error. **Default:** `false` | influxd flag | Environment variable | Configuration key | |----------------------|----------------------------|--------------------| |`--overwrite-pid-file`|`INFLUXD_OVERWRITE_PID_FILE`|`overwrite-pid-file`| ###### influxd flag ```sh influxd --overwrite-pid-file ``` ###### Environment variable ```sh export INFLUXD_OVERWRITE_PID_FILE=true ``` ###### Configuration file [YAML](#yaml-27)[TOML](#toml-27)[JSON](#json-27) ```yml overwrite-pid-file: true ``` ```toml overwrite-pid-file = true ``` ```json { "overwrite-pid-file": true } ``` ### pid-file Write the PID file to the specified path and remove it when InfluxDB stops. **Default:** `` |influxd flag|Environment variable|Configuration key| |------------|--------------------|-----------------| |`--pid-file`| `INFLUXD_PID_FILE` | `pid-file` | ###### influxd flag ```sh influxd --pid-file /path/to/pid-file ``` ###### Environment variable ```sh export INFLUXD_PID_FILE=/path/to/pid-file ``` ###### Configuration file [YAML](#yaml-28)[TOML](#toml-28)[JSON](#json-28) ```yml pid-file: /path/to/pid-file ``` ```toml pid-file = "/path/to/pid-file" ``` ```json { "pid-file": "/path/to/pid-file" } ``` ### pprof-disabled Disable the `/debug/pprof` HTTP endpoint. This endpoint provides runtime profiling data and can be helpful when debugging. **Default:** `false` | influxd flag | Environment variable |Configuration key| |------------------|------------------------|-----------------| |`--pprof-disabled`|`INFLUXD_PPROF_DISABLED`|`pprof-disabled` | ###### influxd flag ```sh influxd --pprof-disabled ``` ###### Environment variable ```sh export INFLUXD_PPROF_DISABLED=true ``` ###### Configuration file [YAML](#yaml-29)[TOML](#toml-29)[JSON](#json-29) ```yml pprof-disabled: true ``` ```toml pprof-disabled = true ``` ```json { "pprof-disabled": true } ``` ### query-concurrency Number of queries allowed to execute concurrently. Setting to `0` allows an unlimited number of concurrent queries. **Default:** `0` | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--query-concurrency`|`INFLUXD_QUERY_CONCURRENCY`|`query-concurrency`| ###### influxd flag ```sh influxd --query-concurrency=10 ``` ###### Environment variable ```sh export INFLUXD_QUERY_CONCURRENCY=10 ``` ###### Configuration file [YAML](#yaml-30)[TOML](#toml-30)[JSON](#json-30) ```yml query-concurrency: 10 ``` ```toml query-concurrency = 10 ``` ```json { "query-concurrency": 10 } ``` ### query-initial-memory-bytes Initial bytes of memory allocated for a query. **Default:** *equal to* [query-memory-bytes](#query-memory-bytes) | influxd flag | Environment variable | Configuration key | |------------------------------|------------------------------------|----------------------------| |`--query-initial-memory-bytes`|`INFLUXD_QUERY_INITIAL_MEMORY_BYTES`|`query-initial-memory-bytes`| ###### influxd flag ```sh influxd --query-initial-memory-bytes=10485760 ``` ###### Environment variable ```sh export INFLUXD_QUERY_INITIAL_MEMORY_BYTES=10485760 ``` ###### Configuration file [YAML](#yaml-31)[TOML](#toml-31)[JSON](#json-31) ```yml query-initial-memory-bytes: 10485760 ``` ```toml query-initial-memory-bytes = 10485760 ``` ```json { "query-initial-memory-bytes": 10485760 } ``` ### query-max-memory-bytes Maximum total bytes of memory allowed for queries. **Default:** *equal to* [query-concurrency](#query-concurrency) × [query-memory-bytes](#query-memory-bytes) | influxd flag | Environment variable | Configuration key | |--------------------------|--------------------------------|------------------------| |`--query-max-memory-bytes`|`INFLUXD_QUERY_MAX_MEMORY_BYTES`|`query-max-memory-bytes`| ###### influxd flag ```sh influxd --query-max-memory-bytes=104857600 ``` ###### Environment variable ```sh export INFLUXD_QUERY_MAX_MEMORY_BYTES=104857600 ``` ###### Configuration file [YAML](#yaml-32)[TOML](#toml-32)[JSON](#json-32) ```yml query-max-memory-bytes: 104857600 ``` ```toml query-max-memory-bytes = 104857600 ``` ```json { "query-max-memory-bytes": 104857600 } ``` ### query-memory-bytes Maximum bytes of memory allowed for a single query. **Default:** *unlimited* > [!Note] > Must be greater than or equal to [query-initial-memory-bytes](#query-initial-memory-bytes). | influxd flag | Environment variable | Configuration key | |----------------------|----------------------------|--------------------| |`--query-memory-bytes`|`INFLUXD_QUERY_MEMORY_BYTES`|`query-memory-bytes`| ###### influxd flag ```sh influxd --query-memory-bytes=10485760 ``` ###### Environment variable ```sh export INFLUXD_QUERY_MEMORY_BYTES=10485760 ``` ###### Configuration file [YAML](#yaml-33)[TOML](#toml-33)[JSON](#json-33) ```yml query-memory-bytes: 10485760 ``` ```toml query-memory-bytes = 10485760 ``` ```json { "query-memory-bytes": 10485760 } ``` ### query-queue-size Maximum number of queries allowed in execution queue. When queue limit is reached, new queries are rejected. Setting to `0` allows an unlimited number of queries in the queue. **Default:** `0` | influxd flag | Environment variable |Configuration key | |--------------------|--------------------------|------------------| |`--query-queue-size`|`INFLUXD_QUERY_QUEUE_SIZE`|`query-queue-size`| ###### influxd flag ```sh influxd --query-queue-size=10 ``` ###### Environment variable ```sh export INFLUXD_QUERY_QUEUE_SIZE=10 ``` ###### Configuration file [YAML](#yaml-34)[TOML](#toml-34)[JSON](#json-34) ```yml query-queue-size: 10 ``` ```toml query-queue-size = 10 ``` ```json { "query-queue-size": 10 } ``` ### reporting-disabled Disables sending telemetry data to InfluxData. The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides information about what data is collected and how InfluxData uses it. **Default:** `false` | influxd flag | Environment variable | Configuration key | |----------------------|----------------------------|--------------------| |`--reporting-disabled`|`INFLUXD_REPORTING_DISABLED`|`reporting-disabled`| ###### influxd flag ```sh influxd --reporting-disabled ``` ###### Environment variable ```sh export INFLUXD_REPORTING_DISABLED=true ``` ###### Configuration file [YAML](#yaml-35)[TOML](#toml-35)[JSON](#json-35) ```yml reporting-disabled: true ``` ```toml reporting-disabled = true ``` ```json { "reporting-disabled": true } ``` ### secret-store Specifies the data store for secrets such as passwords and tokens. Store secrets in either the InfluxDB [internal BoltDB](#bolt-path)or in [Vault](https://www.vaultproject.io/). **Options:** `bolt`, `vault` **Default:** `bolt` | influxd flag | Environment variable |Configuration key| |----------------|----------------------|-----------------| |`--secret-store`|`INFLUXD_SECRET_STORE`| `secret-store` | ###### influxd flag ```sh influxd --secret-store=bolt ``` ###### Environment variable ```sh export INFLUXD_SECRET_STORE=bolt ``` ###### Configuration file [YAML](#yaml-36)[TOML](#toml-36)[JSON](#json-36) ```yml secret-store: bolt ``` ```toml secret-store = "bolt" ``` ```json { "secret-store": "bolt" } ``` ### session-length Specifies the Time to Live (TTL) **in minutes** for newly created user sessions. **Default:** `60` | influxd flag | Environment variable |Configuration key| |------------------|------------------------|-----------------| |`--session-length`|`INFLUXD_SESSION_LENGTH`|`session-length` | ###### influxd flag ```sh influxd --session-length=60 ``` ###### Environment variable ```sh export INFLUXD_SESSION_LENGTH=60 ``` ###### Configuration file [YAML](#yaml-37)[TOML](#toml-37)[JSON](#json-37) ```yml session-length: 60 ``` ```toml session-length = 60 ``` ```json { "session-length": 60 } ``` ### session-renew-disabled Disables automatically extending a user’s session TTL on each request. By default, every request sets the session’s expiration time to five minutes from now. When disabled, sessions expire after the specified [session length](#session-length)and the user is redirected to the login page, even if recently active. **Default:** `false` | influxd flag | Environment variable | Configuration key | |--------------------------|--------------------------------|------------------------| |`--session-renew-disabled`|`INFLUXD_SESSION_RENEW_DISABLED`|`session-renew-disabled`| ###### influxd flag ```sh influxd --session-renew-disabled ``` ###### Environment variable ```sh export INFLUXD_SESSION_RENEW_DISABLED=true ``` ###### Configuration file [YAML](#yaml-38)[TOML](#toml-38)[JSON](#json-38) ```yml session-renew-disabled: true ``` ```toml session-renew-disabled = true ``` ```json { "session-renew-disabled": true } ``` ### sqlite-path Path to the SQLite database file. The SQLite database is used to store metadata for notebooks and annotations. **Default:** *`influxd.sqlite` in the same directory as the [bolt-path](#bolt-path).* | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--sqlite-path`|`INFLUXD_SQLITE_PATH`| `sqlite-path` | ###### influxd flag ```sh influxd --sqlite-path ~/.influxdbv2/influxd.sqlite ``` ###### Environment variable ```sh export INFLUXD_SQLITE_PATH=~/.influxdbv2/influxd.sqlite ``` ###### Configuration file [YAML](#yaml-39)[TOML](#toml-39)[JSON](#json-39) ```yml sqlite-path: ~/.influxdbv2/influxd.sqlite ``` ```toml sqlite-path = "~/.influxdbv2/influxd.sqlite" ``` ```json { "sqlite-path": "~/.influxdbv2/influxd.sqlite" } ``` ### startup-error-linger *Available in InfluxDB OSS v2.10 and later.* Duration to keep the `/health` and `/ready` endpoints serving after a failed startup before `influxd` exits. Use this window to retrieve the startup error from `/health` or `/ready`, for example, when a container orchestrator restarts `influxd` before you can read its logs. During the window, `/health` and `/ready` return `503` with the failing checks, and every other path returns `503` with `{"status":"starting"}`. After the window, `influxd` exits with the [exit code](/influxdb/v2/reference/cli/influxd/#exit-codes)for the failure. `0` exits immediately. The maximum is `30m`. Check messages can include file system paths and other configuration details. To restrict them to callers with operator permissions, see [`health-auth-mode`](#health-auth-mode). **Default:** `0` | influxd flag | Environment variable | Configuration key | |------------------------|------------------------------|----------------------| |`--startup-error-linger`|`INFLUXD_STARTUP_ERROR_LINGER`|`startup-error-linger`| ###### influxd flag ```sh influxd --startup-error-linger=5m ``` ###### Environment variable ```sh export INFLUXD_STARTUP_ERROR_LINGER=5m ``` ###### Configuration file [YAML](#yaml-40)[TOML](#toml-40)[JSON](#json-40) ```yml startup-error-linger: 5m ``` ```toml startup-error-linger = "5m" ``` ```json { "startup-error-linger": "5m" } ``` ### storage-cache-max-memory-size Maximum size (in bytes) a shard’s cache can reach before it starts rejecting writes. **Default:** `1073741824` | influxd flag | Environment variable | Configuration key | |---------------------------------|---------------------------------------|-------------------------------| |`--storage-cache-max-memory-size`|`INFLUXD_STORAGE_CACHE_MAX_MEMORY_SIZE`|`storage-cache-max-memory-size`| ###### influxd flag ```sh influxd --storage-cache-max-memory-size=1073741824 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_CACHE_MAX_MEMORY_SIZE=1073741824 ``` ###### Configuration file [YAML](#yaml-41)[TOML](#toml-41)[JSON](#json-41) ```yml storage-cache-max-memory-size: 1073741824 ``` ```toml storage-cache-max-memory-size = 1073741824 ``` ```json { "storage-cache-max-memory-size": 1073741824 } ``` ### storage-cache-snapshot-memory-size Size (in bytes) at which the storage engine will snapshot the cache and write it to a TSM file to make more memory available. **Default:** `26214400`) | influxd flag | Environment variable | Configuration key | |--------------------------------------|--------------------------------------------|------------------------------------| |`--storage-cache-snapshot-memory-size`|`INFLUXD_STORAGE_CACHE_SNAPSHOT_MEMORY_SIZE`|`storage-cache-snapshot-memory-size`| ###### influxd flag ```sh influxd --storage-cache-snapshot-memory-size=26214400 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_CACHE_SNAPSHOT_MEMORY_SIZE=26214400 ``` ###### Configuration file [YAML](#yaml-42)[TOML](#toml-42)[JSON](#json-42) ```yml storage-cache-snapshot-memory-size: 26214400 ``` ```toml storage-cache-snapshot-memory-size = 26214400 ``` ```json { "storage-cache-snapshot-memory-size": 26214400 } ``` ### storage-cache-snapshot-write-cold-duration Duration at which the storage engine will snapshot the cache and write it to a new TSM file if the shard hasn’t received writes or deletes. **Default:** `10m0s` | influxd flag | Environment variable | Configuration key | |----------------------------------------------|----------------------------------------------------|--------------------------------------------| |`--storage-cache-snapshot-write-cold-duration`|`INFLUXD_STORAGE_CACHE_SNAPSHOT_WRITE_COLD_DURATION`|`storage-cache-snapshot-write-cold-duration`| ###### influxd flag ```sh influxd --storage-cache-snapshot-write-cold-duration=10m0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_CACHE_SNAPSHOT_WRITE_COLD_DURATION=10m0s ``` ###### Configuration file [YAML](#yaml-43)[TOML](#toml-43)[JSON](#json-43) ```yml storage-cache-snapshot-write-cold-duration: 10m0s ``` ```toml storage-cache-snapshot-write-cold-duration = "10m0s" ``` ```json { "storage-cache-snapshot-write-cold-duration": "10m0s" } ``` ### storage-compact-full-write-cold-duration Duration at which the storage engine will compact all TSM files in a shard if it hasn’t received writes or deletes. **Default:** `4h0m0s` | influxd flag | Environment variable | Configuration key | |--------------------------------------------|--------------------------------------------------|------------------------------------------| |`--storage-compact-full-write-cold-duration`|`INFLUXD_STORAGE_COMPACT_FULL_WRITE_COLD_DURATION`|`storage-compact-full-write-cold-duration`| ###### influxd flag ```sh influxd --storage-compact-full-write-cold-duration=4h0m0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_COMPACT_FULL_WRITE_COLD_DURATION=4h0m0s ``` ###### Configuration file [YAML](#yaml-44)[TOML](#toml-44)[JSON](#json-44) ```yml storage-compact-full-write-cold-duration: 4h0m0s ``` ```toml storage-compact-full-write-cold-duration = "4h0m0s" ``` ```json { "storage-compact-full-write-cold-duration": "4h0m0s" } ``` ### storage-compact-throughput Sustained rate limit (in bytes per second) that TSM compactions can write to disk. In InfluxDB OSS v2.10 and later, this setting is independent of the burst limit ([`storage-compact-throughput-burst`](#storage-compact-throughput-burst)). If the burst limit is lower than the sustained limit, InfluxDB raises the burst limit to match the sustained limit. To verify the effective values, check the `Compaction settings` log entry at startup. In earlier versions, you can’t set this option with a flag, and the sustained and burst limits use the same value. To tune compaction write throughput in earlier versions, set `storage-compact-throughput-burst`. **Default:** `50331648` | influxd flag | Environment variable | Configuration key | |------------------------------|------------------------------------|----------------------------| |`--storage-compact-throughput`|`INFLUXD_STORAGE_COMPACT_THROUGHPUT`|`storage-compact-throughput`| ###### influxd flag ```sh influxd --storage-compact-throughput=50331648 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_COMPACT_THROUGHPUT=50331648 ``` ###### Configuration file [YAML](#yaml-45)[TOML](#toml-45)[JSON](#json-45) ```yml storage-compact-throughput: 50331648 ``` ```toml storage-compact-throughput = 50331648 ``` ```json { "storage-compact-throughput": 50331648 } ``` ### storage-compact-throughput-burst Maximum rate limit (in bytes per second) that TSM compactions can write to disk. In InfluxDB OSS v2.10 and later, this setting is independent of the sustained limit ([`storage-compact-throughput`](#storage-compact-throughput)). In earlier versions, this setting also controls the sustained compaction throughput. #### Scale compaction throughput If you scale to larger machines and faster storage, increase this value to let compactions keep up with ingest. If you set this too high, compactions can compete with writes and queries for disk I/O and hurt performance. To identify a compaction bottleneck, monitor the following: * `storage_compactions_queued` and `storage_compactions_active` from the `/metrics` endpoint * Disk I/O utilization and throughput from your OS or infrastructure metrics Example values: * `50331648` (default, about 48 MiB/s) * `100663296` (about 96 MiB/s) * `201326592` (about 192 MiB/s) **Default:** `50331648` | influxd flag | Environment variable | Configuration key | |------------------------------------|------------------------------------------|----------------------------------| |`--storage-compact-throughput-burst`|`INFLUXD_STORAGE_COMPACT_THROUGHPUT_BURST`|`storage-compact-throughput-burst`| ###### influxd flag ```sh influxd --storage-compact-throughput-burst=50331648 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_COMPACT_THROUGHPUT_BURST=50331648 ``` ###### Configuration file [YAML](#yaml-46)[TOML](#toml-46)[JSON](#json-46) ```yml storage-compact-throughput-burst: 50331648 ``` ```toml storage-compact-throughput-burst = 50331648 ``` ```json { "storage-compact-throughput-burst": 50331648 } ``` ### storage-max-concurrent-compactions Maximum number of full and level compactions that can run concurrently. A value of `0` results in 50% of `runtime.GOMAXPROCS(0)` used at runtime. Any number greater than zero limits compactions to that value.*This setting does not apply to cache snapshotting.* **Default:** `0` | influxd flag | Environment variable | Configuration key | |--------------------------------------|--------------------------------------------|------------------------------------| |`--storage-max-concurrent-compactions`|`INFLUXD_STORAGE_MAX_CONCURRENT_COMPACTIONS`|`storage-max-concurrent-compactions`| ###### influxd flag ```sh influxd --storage-max-concurrent-compactions=0 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_MAX_CONCURRENT_COMPACTIONS=0 ``` ###### Configuration file [YAML](#yaml-47)[TOML](#toml-47)[JSON](#json-47) ```yml storage-max-concurrent-compactions: 0 ``` ```toml storage-max-concurrent-compactions = 0 ``` ```json { "storage-max-concurrent-compactions": 0 } ``` ### storage-max-index-log-file-size Size (in bytes) at which an index write-ahead log (WAL) file will compact into an index file. Lower sizes will cause log files to be compacted more quickly and result in lower heap usage at the expense of write throughput. **Default:** `1048576` | influxd flag | Environment variable | Configuration key | |-----------------------------------|-----------------------------------------|---------------------------------| |`--storage-max-index-log-file-size`|`INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE`|`storage-max-index-log-file-size`| ###### influxd flag ```sh influxd --storage-max-index-log-file-size=1048576 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE=1048576 ``` ###### Configuration file [YAML](#yaml-48)[TOML](#toml-48)[JSON](#json-48) ```yml storage-max-index-log-file-size: 1048576 ``` ```toml storage-max-index-log-file-size = 1048576 ``` ```json { "storage-max-index-log-file-size": 1048576 } ``` ### storage-no-validate-field-size Skip field size validation on incoming write requests. **Default:** `false` | influxd flag | Environment variable | Configuration key | |----------------------------------|----------------------------------------|--------------------------------| |`--storage-no-validate-field-size`|`INFLUXD_STORAGE_NO_VALIDATE_FIELD_SIZE`|`storage-no-validate-field-size`| ###### influxd flag ```sh influxd --storage-no-validate-field-size ``` ###### Environment variable ```sh export INFLUXD_STORAGE_NO_VALIDATE_FIELD_SIZE=true ``` ###### Configuration file [YAML](#yaml-49)[TOML](#toml-49)[JSON](#json-49) ```yml storage-no-validate-field-size: true ``` ```toml storage-no-validate-field-size = true ``` ```json { "storage-no-validate-field-size": true } ``` ### storage-retention-check-interval Interval of retention policy enforcement checks. **Default:** `30m0s` | influxd flag | Environment variable | Configuration key | |------------------------------------|------------------------------------------|----------------------------------| |`--storage-retention-check-interval`|`INFLUXD_STORAGE_RETENTION_CHECK_INTERVAL`|`storage-retention-check-interval`| ###### influxd flag ```sh influxd --storage-retention-check-interval=30m0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_RETENTION_CHECK_INTERVAL=30m0s ``` ###### Configuration file [YAML](#yaml-50)[TOML](#toml-50)[JSON](#json-50) ```yml storage-retention-check-interval: 30m0s ``` ```toml storage-retention-check-interval = "30m0s" ``` ```json { "storage-retention-check-interval": "30m0s" } ``` ### storage-series-file-max-concurrent-snapshot-compactions Maximum number of snapshot compactions that can run concurrently across all series partitions in a database. **Default:** `0` | influxd flag | Environment variable | Configuration key | |-----------------------------------------------------------|-----------------------------------------------------------------|---------------------------------------------------------| |`--storage-series-file-max-concurrent-snapshot-compactions`|`INFLUXD_STORAGE_SERIES_FILE_MAX_CONCURRENT_SNAPSHOT_COMPACTIONS`|`storage-series-file-max-concurrent-snapshot-compactions`| ###### influxd flag ```sh influxd --storage-series-file-max-concurrent-snapshot-compactions=0 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_SERIES_FILE_MAX_CONCURRENT_SNAPSHOT_COMPACTIONS=0 ``` ###### Configuration file [YAML](#yaml-51)[TOML](#toml-51)[JSON](#json-51) ```yml storage-series-file-max-concurrent-snapshot-compactions: 0 ``` ```toml storage-series-file-max-concurrent-snapshot-compactions = 0 ``` ```json { "storage-series-file-max-concurrent-snapshot-compactions": 0 } ``` ### storage-series-id-set-cache-size Size of the internal cache used in the TSI index to store previously calculated series results. Cached results are returned quickly rather than needing to be recalculated when a subsequent query with the same tag key/value predicate is executed. Setting this value to `0` will disable the cache and may decrease query performance. **Default:** `100` > [!Note] > This value should only be increased if the set of regularly used tag key/value > predicates across all measurements for a database is larger than 100. > An increase in cache size may lead to an increase in heap usage. | influxd flag | Environment variable | Configuration key | |------------------------------------|------------------------------------------|----------------------------------| |`--storage-series-id-set-cache-size`|`INFLUXD_STORAGE_SERIES_ID_SET_CACHE_SIZE`|`storage-series-id-set-cache-size`| ###### influxd flag ```sh influxd --storage-series-id-set-cache-size=100 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_SERIES_ID_SET_CACHE_SIZE=100 ``` ###### Configuration file [YAML](#yaml-52)[TOML](#toml-52)[JSON](#json-52) ```yml storage-series-id-set-cache-size: 100 ``` ```toml storage-series-id-set-cache-size = 100 ``` ```json { "storage-series-id-set-cache-size": 100 } ``` ### storage-shard-precreator-advance-period The time before a shard group’s end-time that the successor shard group is created. **Default:** `30m0s` | influxd flag | Environment variable | Configuration key | |-------------------------------------------|-------------------------------------------------|-----------------------------------------| |`--storage-shard-precreator-advance-period`|`INFLUXD_STORAGE_SHARD_PRECREATOR_ADVANCE_PERIOD`|`storage-shard-precreator-advance-period`| ###### influxd flag ```sh influxd --storage-shard-precreator-advance-period=30m0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_SHARD_PRECREATOR_ADVANCE_PERIOD=30m0s ``` ###### Configuration file [YAML](#yaml-53)[TOML](#toml-53)[JSON](#json-53) ```yml storage-shard-precreator-advance-period: 30m0s ``` ```toml storage-shard-precreator-advance-period = "30m0s" ``` ```json { "storage-shard-precreator-advance-period": "30m0s" } ``` ### storage-shard-precreator-check-interval Interval of pre-create new shards check. **Default:** `10m0s` | influxd flag | Environment variable | Configuration key | |-------------------------------------------|-------------------------------------------------|-----------------------------------------| |`--storage-shard-precreator-check-interval`|`INFLUXD_STORAGE_SHARD_PRECREATOR_CHECK_INTERVAL`|`storage-shard-precreator-check-interval`| ###### influxd flag ```sh influxd --storage-shard-precreator-check-interval=10m0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_SHARD_PRECREATOR_CHECK_INTERVAL=10m0s ``` ###### Configuration file [YAML](#yaml-54)[TOML](#toml-54)[JSON](#json-54) ```yml storage-shard-precreator-check-interval: 10m0s ``` ```toml storage-shard-precreator-check-interval = "10m0s" ``` ```json { "storage-shard-precreator-check-interval": "10m0s" } ``` ### storage-tsm-use-madv-willneed Inform the kernel that InfluxDB intends to page in mmap’d sections of TSM files. **Default:** `false` | influxd flag | Environment variable | Configuration key | |---------------------------------|---------------------------------------|-------------------------------| |`--storage-tsm-use-madv-willneed`|`INFLUXD_STORAGE_TSM_USE_MADV_WILLNEED`|`storage-tsm-use-madv-willneed`| ###### influxd flag ```sh influxd --storage-tsm-use-madv-willneed ``` ###### Environment variable ```sh export INFLUXD_STORAGE_TSM_USE_MADV_WILLNEED=true ``` ###### Configuration file [YAML](#yaml-55)[TOML](#toml-55)[JSON](#json-55) ```yml storage-tsm-use-madv-willneed: true ``` ```toml storage-tsm-use-madv-willneed = true ``` ```json { "storage-tsm-use-madv-willneed": true } ``` ### storage-validate-keys Validate incoming writes to ensure keys have only valid unicode characters. **Default:** `false` | influxd flag | Environment variable | Configuration key | |-------------------------|-------------------------------|-----------------------| |`--storage-validate-keys`|`INFLUXD_STORAGE_VALIDATE_KEYS`|`storage-validate-keys`| ###### influxd flag ```sh influxd --storage-validate-keys ``` ###### Environment variable ```sh export INFLUXD_STORAGE_VALIDATE_KEYS=true ``` ###### Configuration file [YAML](#yaml-56)[TOML](#toml-56)[JSON](#json-56) ```yml storage-validate-keys: true ``` ```toml storage-validate-keys = true ``` ```json { "storage-validate-keys": true } ``` ### storage-wal-flush-on-shutdown Flush the WAL on shutdown. **Default:** `false` | influxd flag | Environment variable | Configuration key | |---------------------------------|---------------------------------------|-------------------------------| |`--storage-wal-flush-on-shutdown`|`INFLUXD_STORAGE_WAL_FLUSH_ON_SHUTDOWN`|`storage-wal-flush-on-shutdown`| If set, `influxd` flushes or snapshots all WALs prior to completing shutdown–`influxd` performs cache snapshots on shutdown, which results in the WAL files being written to TSM files and then deleted. This is useful in upgrade and downgrade scenarios to prevent WAL format compatibility issues. ###### influxd flag ```sh influxd --storage-wal-flush-on-shutdown ``` ###### Environment variable ```sh export INFLUXD_STORAGE_WAL_FLUSH_ON_SHUTDOWN=true ``` ###### Configuration file [YAML](#yaml-57)[TOML](#toml-57)[JSON](#json-57) ```yml storage-wal-flush-on-shutdown: true ``` ```toml storage-wal-flush-on-shutdown = true ``` ```json { "storage-wal-flush-on-shutdown": true } ``` ### storage-wal-fsync-delay Duration a write will wait before fsyncing. A duration greater than `0` batches multiple fsync calls. This is useful for slower disks or when WAL write contention is present. **Default:** `0s` | influxd flag | Environment variable | Configuration key | |---------------------------|---------------------------------|-------------------------| |`--storage-wal-fsync-delay`|`INFLUXD_STORAGE_WAL_FSYNC_DELAY`|`storage-wal-fsync-delay`| ###### influxd flag ```sh influxd --storage-wal-fsync-delay=0s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_WAL_FSYNC_DELAY=0s ``` ###### Configuration file [YAML](#yaml-58)[TOML](#toml-58)[JSON](#json-58) ```yml storage-wal-fsync-delay: 0s ``` ```toml storage-wal-fsync-delay = "0s" ``` ```json { "storage-wal-fsync-delay": "0s" } ``` ### storage-wal-max-concurrent-writes Maximum number writes to the WAL directory to attempt at the same time. **Default:** `0` *(number of processing units available × 2)* | influxd flag | Environment variable | Configuration key | |-------------------------------------|-------------------------------------------|-----------------------------------| |`--storage-wal-max-concurrent-writes`|`INFLUXD_STORAGE_WAL_MAX_CONCURRENT_WRITES`|`storage-wal-max-concurrent-writes`| ###### influxd flag ```sh influxd --storage-wal-max-concurrent-writes=0 ``` ###### Environment variable ```sh export INFLUXD_STORAGE_WAL_MAX_CONCURRENT_WRITES=0 ``` ###### Configuration file [YAML](#yaml-59)[TOML](#toml-59)[JSON](#json-59) ```yml storage-wal-max-concurrent-writes: 0 ``` ```toml storage-wal-max-concurrent-writes = 0 ``` ```json { "storage-wal-max-concurrent-writes": 0 } ``` ### storage-wal-max-write-delay Maximum amount of time a write request to the WAL directory will wait when the[maximum number of concurrent active writes to the WAL directory](#storage-wal-max-concurrent-writes)has been met. Set to `0` to disable the timeout. **Default:** `10m` | influxd flag | Environment variable | Configuration key | |-------------------------------|-------------------------------------|-----------------------------| |`--storage-wal-max-write-delay`|`INFLUXD_STORAGE_WAL_MAX_WRITE_DELAY`|`storage-wal-max-write-delay`| ###### influxd flag ```sh influxd --storage-wal-max-write-delay=10m ``` ###### Environment variable ```sh export INFLUXD_STORAGE_WAL_MAX_WRITE_DELAY=10m ``` ###### Configuration file [YAML](#yaml-60)[TOML](#toml-60)[JSON](#json-60) ```yml storage-wal-max-write-delay: 10m ``` ```toml storage-wal-max-write-delay = "10m" ``` ```json { "storage-wal-max-write-delay": "10m" } ``` ### storage-write-timeout Maximum amount of time the storage engine will process a write request before timing out. **Default:** `10s` | influxd flag | Environment variable | Configuration key | |-------------------------|-------------------------------|-----------------------| |`--storage-write-timeout`|`INFLUXD_STORAGE_WRITE_TIMEOUT`|`storage-write-timeout`| ###### influxd flag ```sh influxd --storage-write-timeout=10s ``` ###### Environment variable ```sh export INFLUXD_STORAGE_WRITE_TIMEOUT=10s ``` ###### Configuration file [YAML](#yaml-61)[TOML](#toml-61)[JSON](#json-61) ```yml storage-write-timeout: 10s ``` ```toml storage-write-timeout = "10s" ``` ```json { "storage-write-timeout": "10s" } ``` ### store Specifies the data store for REST resources. **Options:** `disk`, `memory` **Default:** `disk` > [!Note] > For backwards compatibility, this flag also acceptss `bolt` as a value. > When using `disk`, REST resources are stored on disk using the [bolt-path](#bolt-path) and [sqlite-path](#sqlite-path). > [!Note] > `memory` is meant for transient environments, such as testing environments, where > data persistence does not matter. > InfluxData does not recommend using `memory` in production. |influxd flag|Environment variable|Configuration key| |------------|--------------------|-----------------| | `--store` | `INFLUXD_STORE` | `store` | ###### influxd flag ```sh influxd --store=bolt ``` ###### Environment variable ```sh export INFLUXD_STORE=bolt ``` ###### Configuration file [YAML](#yaml-62)[TOML](#toml-62)[JSON](#json-62) ```yml store: bolt ``` ```toml store = "bolt" ``` ```json { "store": "bolt" } ``` ### strong-passwords Require passwords to have at least eight characters and include characters from at least three of the following four character classes: * uppercase (`A-Z`) * lowercase (`a-z`) * numbers (`0-9`) * special characters (`!@#$%^&*()_+`) | influxd flag | Environment variable |Configuration key | |--------------------|--------------------------|------------------| |`--strong-passwords`|`INFLUXD_STRONG_PASSWORDS`|`strong-passwords`| ###### influxd flag ```sh influxd --strong-passwords ``` ###### Environment variable ```sh export INFLUXD_STRONG_PASSWORDS=true ``` ###### Configuration file [YAML](#yaml-63)[TOML](#toml-63)[JSON](#json-63) ```yml strong-passwords: true ``` ```toml strong-passwords = true ``` ```json { "strong-passwords": true } ``` ### testing-always-allow-setup Ensures the `/api/v2/setup` endpoint always returns `true` to allow onboarding. This configuration option is primarily used in continuous integration tests. **Default:** `false` | influxd flag | Environment variable | Configuration key | |------------------------------|------------------------------------|----------------------------| |`--testing-always-allow-setup`|`INFLUXD_TESTING_ALWAYS_ALLOW_SETUP`|`testing-always-allow-setup`| ###### influxd flag ```sh influxd --testing-always-allow-setup ``` ###### Environment variable ```sh export INFLUXD_TESTING_ALWAYS_ALLOW_SETUP=true ``` ###### Configuration file [YAML](#yaml-64)[TOML](#toml-64)[JSON](#json-64) ```yml testing-always-allow-setup: true ``` ```toml testing-always-allow-setup = true ``` ```json { "testing-always-allow-setup": true } ``` ### tls-cert Path to TLS certificate file. Requires the [`tls-key`](#tls-key) to be set. *For more information, see [Enable TLS encryption](/influxdb/v2/admin/security/enable-tls/).* |influxd flag|Environment variable|Configuration key| |------------|--------------------|-----------------| |`--tls-cert`| `INFLUXD_TLS_CERT` | `tls-cert` | ###### influxd flag ```sh influxd --tls-cert=/path/to/influxdb.crt ``` ###### Environment variable ```sh export INFLUXD_TLS_CERT=/path/to/influxdb.crt ``` ###### Configuration file [YAML](#yaml-65)[TOML](#toml-65)[JSON](#json-65) ```yml tls-cert: /path/to/influxdb.crt ``` ```toml tls-cert = "/path/to/influxdb.crt" ``` ```json { "tls-cert": "/path/to/influxdb.crt" } ``` ### tls-key Path to TLS key file. Requires the [`tls-cert`](#tls-cert) to be set. *For more information, see [Enable TLS encryption](/influxdb/v2/admin/security/enable-tls/).* |influxd flag|Environment variable|Configuration key| |------------|--------------------|-----------------| |`--tls-key` | `INFLUXD_TLS_KEY` | `tls-key` | ###### influxd flag ```sh influxd --tls-key=/path/to/influxdb.key ``` ###### Environment variable ```sh export INFLUXD_TLS_KEY=/path/to/influxdb.key ``` ###### Configuration file [YAML](#yaml-66)[TOML](#toml-66)[JSON](#json-66) ```yml tls-key: /path/to/influxdb.key ``` ```toml tls-key = "/path/to/influxdb.key" ``` ```json { "tls-key": "/path/to/influxdb.key" } ``` ### tls-min-version Minimum accepted TLS version. **Default:** `1.2` | influxd flag | Environment variable |Configuration key| |-------------------|-------------------------|-----------------| |`--tls-min-version`|`INFLUXD_TLS_MIN_VERSION`|`tls-min-version`| ###### influxd flag ```sh influxd --tls-min-version=1.2 ``` ###### Environment variable ```sh export INFLUXD_TLS_MIN_VERSION=1.2 ``` ###### Configuration file [YAML](#yaml-67)[TOML](#toml-67)[JSON](#json-67) ```yml tls-min-version: "1.2" ``` ```toml tls-min-version = "1.2" ``` ```json { "tls-min-version": "1.2" } ``` ### tls-strict-ciphers Restrict accepted TLS ciphers to: * ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 * ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 * ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 * ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 * ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 * ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 **Default:** `false` | influxd flag | Environment variable | Configuration key | |----------------------|----------------------------|--------------------| |`--tls-strict-ciphers`|`INFLUXD_TLS_STRICT_CIPHERS`|`tls-strict-ciphers`| ###### influxd flag ```sh influxd --tls-strict-ciphers ``` ###### Environment variable ```sh export INFLUXD_TLS_STRICT_CIPHERS=true ``` ###### Configuration file [YAML](#yaml-68)[TOML](#toml-68)[JSON](#json-68) ```yml tls-strict-ciphers: true ``` ```toml tls-strict-ciphers = true ``` ```json { "tls-strict-ciphers": true } ``` ### tracing-type Enable tracing in InfluxDB and specifies the tracing type. Tracing is disabled by default. **Options:** `log`, `jaeger` | influxd flag | Environment variable |Configuration key| |----------------|----------------------|-----------------| |`--tracing-type`|`INFLUXD_TRACING_TYPE`| `tracing-type` | ###### influxd flag ```sh influxd --tracing-type=log ``` ###### Environment variable ```sh export INFLUXD_TRACING_TYPE=log ``` ###### Configuration file [YAML](#yaml-69)[TOML](#toml-69)[JSON](#json-69) ```yml tracing-type: log ``` ```toml tracing-type = "log" ``` ```json { "tracing-type": "log" } ``` ### ui-disabled Disable the InfluxDB user interface (UI). The UI is enabled by default. **Default:** `false` | influxd flag |Environment variable |Configuration key| |---------------|---------------------|-----------------| |`--ui-disabled`|`INFLUXD_UI_DISABLED`| `ui-disabled` | ###### influxd flag ```sh influxd --ui-disabled ``` ###### Environment variable ```sh export INFLUXD_UI_DISABLED=true ``` ###### Configuration file [YAML](#yaml-70)[TOML](#toml-70)[JSON](#json-70) ```yml ui-disabled: true ``` ```toml ui-disabled = true ``` ```json { "ui-disabled": true } ``` ### use-hashed-tokens Enable storing hashed API tokens on disk. Token hashing is **enabled by default in InfluxDB 2.9.0 and later**. In InfluxDB 2.8.0–2.8.x, token hashing was available but disabled by default. Storing hashed tokens increases security by storing API tokens as hashes on disk. When enabled, all unhashed tokens are converted to hashed tokens on every startup leaving no unhashed tokens on disk. Newly created tokens are also stored as hashes. Lost tokens must be replaced when token hashing is enabled because the hashing prevents them from being recovered. If token hashing is disabled after being enabled, any hashed tokens on disk remain as hashed tokens. Newly created tokens are stored unhashed when token hashing is disabled. Hashed tokens on disk remain valid and usable even with token hashing disabled. Hashed token support is available in versions 2.8.0 and newer. Downgrading to older versions is not recommended after enabling hashed tokens because the downgrade process deletes all stored hashed tokens. All hashed tokens must be replaced on a downgrade after hashed tokens are enabled. To opt out of the default and continue storing tokens unhashed (for example, to preserve compatibility with a possible downgrade to InfluxDB 2.7 or earlier), set `use-hashed-tokens` to `false`. **Default:** `true` *(in InfluxDB 2.9.0 and later; `false` in 2.8.x)* | influxd flag | Environment variable | Configuration key | |---------------------|---------------------------|-------------------| |`--use-hashed-tokens`|`INFLUXD_USE_HASHED_TOKENS`|`use-hashed-tokens`| ###### influxd flag ```sh # Disable token hashing (opt out of the 2.9.0 default) influxd --use-hashed-tokens=false ``` ###### Environment variable ```sh # Disable token hashing (opt out of the 2.9.0 default) export INFLUXD_USE_HASHED_TOKENS=false ``` ###### Configuration file [YAML](#yaml-71)[TOML](#toml-71)[JSON](#json-71) ```yml use-hashed-tokens: false ``` ```toml use-hashed-tokens = false ``` ```json { "use-hashed-tokens": false } ``` ### vault-addr Specifies the address of the Vault server expressed as a URL and port. For example: `https://127.0.0.1:8200/`. | influxd flag |Environment variable|Configuration key| |--------------|--------------------|-----------------| |`--vault-addr`| `VAULT_ADDR` | `vault-addr` | ###### influxd flag ```sh influxd --vault-addr=https://127.0.0.1:8200/ ``` ###### Environment variable ```sh export VAULT_ADDR=https://127.0.0.1:8200/ ``` ###### Configuration file [YAML](#yaml-72)[TOML](#toml-72)[JSON](#json-72) ```yml vault-addr: https://127.0.0.1:8200/ ``` ```toml vault-addr = "https://127.0.0.1:8200/" ``` ```json { "vault-addr": "https://127.0.0.1:8200/" } ``` ### vault-cacert Specifies the path to a PEM-encoded CA certificate file on the local disk. This file is used to verify the Vault server’s SSL certificate.**This setting takes precedence over the [`--vault-capath`](#vault-capath) setting.** | influxd flag |Environment variable|Configuration key| |----------------|--------------------|-----------------| |`--vault-cacert`| `VAULT_CACERT` | `vault-cacert` | ###### influxd flag ```sh influxd --vault-cacert=/path/to/ca.pem ``` ###### Environment variable ```sh export VAULT_CACERT=/path/to/ca.pem ``` ###### Configuration file [YAML](#yaml-73)[TOML](#toml-73)[JSON](#json-73) ```yml vault-cacert: /path/to/ca.pem ``` ```toml vault-cacert = "/path/to/ca.pem" ``` ```json { "vault-cacert": "/path/to/ca.pem" } ``` ### vault-capath Specifies the path to a directory of PEM-encoded CA certificate files on the local disk. These certificates are used to verify the Vault server’s SSL certificate. | influxd flag |Environment variable|Configuration key| |----------------|--------------------|-----------------| |`--vault-capath`| `VAULT_CAPATH` | `vault-capath` | ###### influxd flag ```sh influxd --vault-capath=/path/to/certs/ ``` ###### Environment variable ```sh export VAULT_CAPATH=/path/to/certs/ ``` ###### Configuration file [YAML](#yaml-74)[TOML](#toml-74)[JSON](#json-74) ```yml vault-capath: /path/to/certs/ ``` ```toml vault-capath = "/path/to/certs/" ``` ```json { "vault-capath": "/path/to/certs/" } ``` ### vault-client-cert Specifies the path to a PEM-encoded client certificate on the local disk. This file is used for TLS communication with the Vault server. | influxd flag |Environment variable| Configuration key | |---------------------|--------------------|-------------------| |`--vault-client-cert`|`VAULT_CLIENT_CERT` |`vault-client-cert`| ###### influxd flag ```sh influxd --vault-client-cert=/path/to/client_cert.pem ``` ###### Environment variable ```sh export VAULT_CLIENT_CERT=/path/to/client_cert.pem ``` ###### Configuration file [YAML](#yaml-75)[TOML](#toml-75)[JSON](#json-75) ```yml vault-client-cert: /path/to/client_cert.pem ``` ```toml vault-client-cert = "/path/to/client_cert.pem" ``` ```json { "vault-client-cert": "/path/to/client_cert.pem" } ``` ### vault-client-key Specifies the path to an unencrypted, PEM-encoded private key on disk which corresponds to the matching client certificate. | influxd flag |Environment variable|Configuration key | |--------------------|--------------------|------------------| |`--vault-client-key`| `VAULT_CLIENT_KEY` |`vault-client-key`| ###### influxd flag ```sh influxd --vault-client-key=/path/to/private_key.pem ``` ###### Environment variable ```sh export VAULT_CLIENT_KEY=/path/to/private_key.pem ``` ###### Configuration file [YAML](#yaml-76)[TOML](#toml-76)[JSON](#json-76) ```yml vault-client-key: /path/to/private_key.pem ``` ```toml vault-client-key = "/path/to/private_key.pem" ``` ```json { "vault-client-key": "/path/to/private_key.pem" } ``` ### vault-max-retries Specifies the maximum number of retries when encountering a 5xx error code. The default is 2 (for three attempts in total). Set this to 0 or less to disable retrying. **Default:** `2` | influxd flag |Environment variable| Configuration key | |---------------------|--------------------|-------------------| |`--vault-max-retries`|`VAULT_MAX_RETRIES` |`vault-max-retries`| ###### influxd flag ```sh influxd --vault-max-retries=2 ``` ###### Environment variable ```sh export VAULT_MAX_RETRIES=2 ``` ###### Configuration file [YAML](#yaml-77)[TOML](#toml-77)[JSON](#json-77) ```yml vault-max-retries: 2 ``` ```toml vault-max-retries = 2 ``` ```json { "vault-max-retries": 2 } ``` ### vault-client-timeout Specifies the Vault client timeout. **Default:** `60s` | influxd flag | Environment variable | Configuration key | |------------------------|----------------------|----------------------| |`--vault-client-timeout`|`VAULT_CLIENT_TIMEOUT`|`vault-client-timeout`| ###### influxd flag ```sh influxd --vault-client-timeout=60s ``` ###### Environment variable ```sh export VAULT_CLIENT_TIMEOUT=60s ``` ###### Configuration file [YAML](#yaml-78)[TOML](#toml-78)[JSON](#json-78) ```yml vault-client-timeout: 60s ``` ```toml vault-client-timeout = "60s" ``` ```json { "vault-client-timeout": "60s" } ``` ### vault-skip-verify Skip certificate verification when communicating with Vault.*Setting this variable voids [Vault’s security model](https://www.vaultproject.io/docs/internals/security.html)and is **not recommended**.* **Default:** `false` | influxd flag |Environment variable| Configuration key | |---------------------|--------------------|-------------------| |`--vault-skip-verify`|`VAULT_SKIP_VERIFY` |`vault-skip-verify`| ###### influxd flag ```sh influxd --vault-skip-verify ``` ###### Environment variable ```sh export VAULT_SKIP_VERIFY=true ``` ###### Configuration file [YAML](#yaml-79)[TOML](#toml-79)[JSON](#json-79) ```yml vault-skip-verify: true ``` ```toml vault-skip-verify = true ``` ```json { "vault-skip-verify": true } ``` ### vault-tls-server-name Specifies the name to use as the Server Name Indication (SNI) host when connecting via TLS. | influxd flag | Environment variable | Configuration key | |-------------------------|-----------------------|-----------------------| |`--vault-tls-server-name`|`VAULT_TLS_SERVER_NAME`|`vault-tls-server-name`| ###### influxd flag ```sh influxd --vault-tls-server-name=secure.example.com ``` ###### Environment variable ```sh export VAULT_TLS_SERVER_NAME=secure.example.com ``` ###### Configuration file [YAML](#yaml-80)[TOML](#toml-80)[JSON](#json-80) ```yml vault-tls-server-name: secure.example.com ``` ```toml vault-tls-server-name = "secure.example.com" ``` ```json { "vault-tls-server-name": "secure.example.com" } ``` ### vault-token Specifies the Vault token use when authenticating with Vault. | influxd flag |Environment variable|Configuration key| |---------------|--------------------|-----------------| |`--vault-token`| `VAULT_TOKEN` | `vault-token` | ###### influxd flag ```sh influxd --vault-token=exAmple-t0ken-958a-f490-c7fd0eda5e9e ``` ###### Environment variable ```sh export VAULT_TOKEN=exAmple-t0ken-958a-f490-c7fd0eda5e9e ``` ###### Configuration file [YAML](#yaml-81)[TOML](#toml-81)[JSON](#json-81) ```yml vault-token: exAmple-t0ken-958a-f490-c7fd0eda5e9e ``` ```toml vault-token = "exAmple-t0ken-958a-f490-c7fd0eda5e9e" ``` ```json { "vault-token": "exAmple-t0ken-958a-f490-c7fd0eda5e9e" } ``` #### Related * [influxd - InfluxDB service](/influxdb/v2/reference/cli/influxd/) | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --assets-path | INFLUXD_ASSETS_PATH | assets-path | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --bolt-path | INFLUXD_BOLT_PATH | bolt-path | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --e2e-testing | INFLUXD_E2E_TESTING | e2e-testing | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --engine-path | INFLUXD_ENGINE_PATH | engine-path | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --feature-flags | INFLUXD_FEATURE_FLAGS | feature-flags | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --flux-log-enabled | INFLUXD_FLUX_LOG_ENABLED | flux-log-enabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --hardening-enabled | INFLUXD_HARDENING_ENABLED | hardening-enabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --health-auth-mode | INFLUXD_HEALTH_AUTH_MODE | health-auth-mode | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-bind-address | INFLUXD_HTTP_BIND_ADDRESS | http-bind-address | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-idle-timeout | INFLUXD_HTTP_IDLE_TIMEOUT | http-idle-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-read-header-timeout | INFLUXD_HTTP_READ_HEADER_TIMEOUT | http-read-header-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-read-timeout | INFLUXD_HTTP_READ_TIMEOUT | http-read-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-user-query-bytes-enabled | INFLUXD_HTTP_USER_QUERY_BYTES_ENABLED | http-user-query-bytes-enabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-user-write-bytes-enabled | INFLUXD_HTTP_USER_WRITE_BYTES_ENABLED | http-user-write-bytes-enabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --http-write-timeout | INFLUXD_HTTP_WRITE_TIMEOUT | http-write-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --influxql-max-select-buckets | INFLUXD_INFLUXQL_MAX_SELECT_BUCKETS | influxql-max-select-buckets | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --influxql-max-select-point | INFLUXD_INFLUXQL_MAX_SELECT_POINT | influxql-max-select-point | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --influxql-max-select-series | INFLUXD_INFLUXQL_MAX_SELECT_SERIES | influxql-max-select-series | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --influxql-max-time-range | INFLUXD_INFLUXQL_MAX_TIME_RANGE | influxql-max-time-range | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --instance-id | INFLUXD_INSTANCE_ID | instance-id | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --log-level | INFLUXD_LOG_LEVEL | log-level | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --metrics-disabled | INFLUXD_METRICS_DISABLED | metrics-disabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --nats-max-payload-bytes | INFLUXD_NATS_MAX_PAYLOAD_BYTES | nats-max-payload-bytes | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --nats-port | INFLUXD_NATS_PORT | nats-port | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --no-tasks | INFLUXD_NO_TASKS | no-tasks | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --overwrite-pid-file | INFLUXD_OVERWRITE_PID_FILE | overwrite-pid-file | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --pid-file | INFLUXD_PID_FILE | pid-file | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --pprof-disabled | INFLUXD_PPROF_DISABLED | pprof-disabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --query-concurrency | INFLUXD_QUERY_CONCURRENCY | query-concurrency | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --query-initial-memory-bytes | INFLUXD_QUERY_INITIAL_MEMORY_BYTES | query-initial-memory-bytes | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --query-max-memory-bytes | INFLUXD_QUERY_MAX_MEMORY_BYTES | query-max-memory-bytes | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --query-memory-bytes | INFLUXD_QUERY_MEMORY_BYTES | query-memory-bytes | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --query-queue-size | INFLUXD_QUERY_QUEUE_SIZE | query-queue-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --reporting-disabled | INFLUXD_REPORTING_DISABLED | reporting-disabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --secret-store | INFLUXD_SECRET_STORE | secret-store | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --session-length | INFLUXD_SESSION_LENGTH | session-length | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --session-renew-disabled | INFLUXD_SESSION_RENEW_DISABLED | session-renew-disabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --sqlite-path | INFLUXD_SQLITE_PATH | sqlite-path | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --startup-error-linger | INFLUXD_STARTUP_ERROR_LINGER | startup-error-linger | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-cache-max-memory-size | INFLUXD_STORAGE_CACHE_MAX_MEMORY_SIZE | storage-cache-max-memory-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-cache-snapshot-memory-size | INFLUXD_STORAGE_CACHE_SNAPSHOT_MEMORY_SIZE | storage-cache-snapshot-memory-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-cache-snapshot-write-cold-duration | INFLUXD_STORAGE_CACHE_SNAPSHOT_WRITE_COLD_DURATION | storage-cache-snapshot-write-cold-duration | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-compact-full-write-cold-duration | INFLUXD_STORAGE_COMPACT_FULL_WRITE_COLD_DURATION | storage-compact-full-write-cold-duration | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-compact-throughput | INFLUXD_STORAGE_COMPACT_THROUGHPUT | storage-compact-throughput | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-compact-throughput-burst | INFLUXD_STORAGE_COMPACT_THROUGHPUT_BURST | storage-compact-throughput-burst | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-max-concurrent-compactions | INFLUXD_STORAGE_MAX_CONCURRENT_COMPACTIONS | storage-max-concurrent-compactions | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-max-index-log-file-size | INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE | storage-max-index-log-file-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-no-validate-field-size | INFLUXD_STORAGE_NO_VALIDATE_FIELD_SIZE | storage-no-validate-field-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-retention-check-interval | INFLUXD_STORAGE_RETENTION_CHECK_INTERVAL | storage-retention-check-interval | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-series-file-max-concurrent-snapshot-compactions | INFLUXD_STORAGE_SERIES_FILE_MAX_CONCURRENT_SNAPSHOT_COMPACTIONS | storage-series-file-max-concurrent-snapshot-compactions | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-series-id-set-cache-size | INFLUXD_STORAGE_SERIES_ID_SET_CACHE_SIZE | storage-series-id-set-cache-size | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-shard-precreator-advance-period | INFLUXD_STORAGE_SHARD_PRECREATOR_ADVANCE_PERIOD | storage-shard-precreator-advance-period | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-shard-precreator-check-interval | INFLUXD_STORAGE_SHARD_PRECREATOR_CHECK_INTERVAL | storage-shard-precreator-check-interval | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-tsm-use-madv-willneed | INFLUXD_STORAGE_TSM_USE_MADV_WILLNEED | storage-tsm-use-madv-willneed | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-validate-keys | INFLUXD_STORAGE_VALIDATE_KEYS | storage-validate-keys | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-wal-flush-on-shutdown | INFLUXD_STORAGE_WAL_FLUSH_ON_SHUTDOWN | storage-wal-flush-on-shutdown | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-wal-fsync-delay | INFLUXD_STORAGE_WAL_FSYNC_DELAY | storage-wal-fsync-delay | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-wal-max-concurrent-writes | INFLUXD_STORAGE_WAL_MAX_CONCURRENT_WRITES | storage-wal-max-concurrent-writes | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-wal-max-write-delay | INFLUXD_STORAGE_WAL_MAX_WRITE_DELAY | storage-wal-max-write-delay | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --storage-write-timeout | INFLUXD_STORAGE_WRITE_TIMEOUT | storage-write-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --store | INFLUXD_STORE | store | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --strong-passwords | INFLUXD_STRONG_PASSWORDS | strong-passwords | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --testing-always-allow-setup | INFLUXD_TESTING_ALWAYS_ALLOW_SETUP | testing-always-allow-setup | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --tls-cert | INFLUXD_TLS_CERT | tls-cert | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --tls-key | INFLUXD_TLS_KEY | tls-key | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --tls-min-version | INFLUXD_TLS_MIN_VERSION | tls-min-version | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --tls-strict-ciphers | INFLUXD_TLS_STRICT_CIPHERS | tls-strict-ciphers | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --tracing-type | INFLUXD_TRACING_TYPE | tracing-type | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --ui-disabled | INFLUXD_UI_DISABLED | ui-disabled | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --use-hashed-tokens | INFLUXD_USE_HASHED_TOKENS | use-hashed-tokens | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-addr | VAULT_ADDR | vault-addr | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-cacert | VAULT_CACERT | vault-cacert | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-capath | VAULT_CAPATH | vault-capath | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-client-cert | VAULT_CLIENT_CERT | vault-client-cert | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-client-key | VAULT_CLIENT_KEY | vault-client-key | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-max-retries | VAULT_MAX_RETRIES | vault-max-retries | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-client-timeout | VAULT_CLIENT_TIMEOUT | vault-client-timeout | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-skip-verify | VAULT_SKIP_VERIFY | vault-skip-verify | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-tls-server-name | VAULT_TLS_SERVER_NAME | vault-tls-server-name | | influxd flag | Environment variable | Configuration key | | --- | --- | --- | | influxd flag | Environment variable | Configuration key | | --vault-token | VAULT_TOKEN | vault-token | --- # Contribute to InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/reference/contributing/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To contribute to the InfluxDB OSS project, complete the following steps: 1. [Sign the InfluxData Contributor License Agreement (CLA)](#sign-influxdata-contributor-license-agreement-cla). 2. [Review contribution guidelines](#review-contribution-guidelines). 3. [Review the InfluxDB open source license](#review-open-source-license). ## Sign InfluxData Contributor License Agreement (CLA) Before contributing to the InfluxDB OSS project, you must complete and sign the [InfluxData Contributor License Agreement (CLA)](https://www.influxdata.com/legal/cla/), available on the InfluxData website. ## Review contribution guidelines To learn how you can contribute to the InfluxDB OSS project, see our [Contributing guidelines](https://github.com/influxdata/influxdb/blob/master/CONTRIBUTING.md) in the GitHub repository. ## Review open source license See information about our [open source MIT license for InfluxDB](https://github.com/influxdata/influxdb/blob/master/LICENSE) in GitHub. --- # Frequently asked questions Source: https://docs.influxdata.com/influxdb/v2/reference/faq/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ##### Account management * [How do I reset my password?](#how-do-i-reset-my-password) ##### InfluxDB service health * [Where can I see the current status of my InfluxDB instance?](#where-can-i-see-the-current-status-of-my-influxdb-instance) ##### Security * [What different types of API tokens exist?](#what-different-types-of-api-tokens-exist) * [Can I use InfluxDB with authentication disabled?](#can-i-use-influxdb-with-authentication-disabled) ##### Administration * [How can I identify my InfluxDB version?](#how-can-i-identify-my-influxdb-version) * [How can I identify the version of Flux I’m using in InfluxDB?](#how-can-i-identify-the-version-of-flux-im-using-in-influxdb) * [Where can I find InfluxDB logs?](#where-can-i-find-influxdb-logs) * [What is the relationship between shard group durations and retention periods?](#what-is-the-relationship-between-shard-group-durations-and-retention-periods) * [Why isn’t data dropped after I update a bucket’s retention period?](#why-isnt-data-dropped-after-i-update-a-buckets-retention-period) ##### Data types * [What are the minimum and maximum integers that InfluxDB can store?](#what-are-the-minimum-and-maximum-integers-that-influxdb-can-store) * [What are the minimum and maximum timestamps that InfluxDB can store?](#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store) * [Can I change a field’s data type?](#can-i-change-a-fields-data-type) * [How does InfluxDB handle field type discrepancies across shards?](#how-does-influxdb-handle-field-type-discrepancies-across-shards) ##### Writing data * [How do I write integer and unsigned integer field values?](#how-do-i-write-integer-and-unsigned-integer-field-values) * [How does InfluxDB handle duplicate points?](#how-does-influxdb-handle-duplicate-points) * [What newline character does the InfluxDB write API require?](#what-newline-character-does-the-influxdb-write-api-require) * [When should I single quote and when should I double quote when writing data?](#when-should-i-single-quote-and-when-should-i-double-quote-when-writing-data) * [Does the precision of the timestamp matter?](#does-the-precision-of-the-timestamp-matter) * [What are the configuration recommendations and schema guidelines for writing sparse, historical data?](#what-are-the-configuration-recommendations-and-schema-guidelines-for-writing-sparse-historical-data) ##### Querying data * [Flux](#flux) * [How do I structure fields as columns (like InfluxQL)?](#how-do-i-structure-fields-as-columns-like-influxql) * [How can I derive a state from multiple field values?](#how-can-i-derive-a-state-from-multiple-field-values) * [InfluxQL](#influxql) * [How do I use InfluxQL with InfluxDB v2.x?](#how-do-i-use-influxql-with-influxdb-v2x) * [How do I perform mathematical operations in an InfluxQL function?](#how-do-i-perform-mathematical-operations-in-an-influxql-function) * [Why does my query return epoch 0 as the timestamp?](#why-does-my-query-return-epoch-0-as-the-timestamp) * [Which InfluxQL functions support nesting?](#which-influxql-functions-support-nesting) * [What determines the time intervals returned by `GROUP BY time()` queries?](#what-determines-the-time-intervals-returned-by-group-by-time-queries) * [Why do my queries return no data or partial data?](#why-do-my-queries-return-no-data-or-partial-data) * [Why don’t my `GROUP BY time()` queries return timestamps that occur after `now()`?](#why-dont-my-group-by-time-queries-return-timestamps-that-occur-after-now) * [Can I perform mathematical operations against timestamps?](#can-i-perform-mathematical-operations-against-timestamps) * [Can I identify write precision from returned timestamps?](#can-i-identify-write-precision-from-returned-timestamps) * [When should I use single quote versus double quotes in a query?](#when-should-i-use-single-quote-versus-double-quotes-in-a-query) * [Why is my query with a `WHERE OR` time clause returning empty results?](#why-is-my-query-with-a-where-or-time-clause-returning-empty-results) * [Why does `fill(previous)` return empty results?](#why-does-fillprevious-return-empty-results) * [How do I query data with an identical tag key and field key?](#how-do-i-query-data-with-an-identical-tag-key-and-field-key) * [How do I query data across measurements?](#how-do-i-query-data-across-measurements) * [Does the order timestamps in a query matter?](#does-the-order-timestamps-in-a-query-matter) * [How do I query data by a tag with a null value?](#how-do-i-query-data-by-a-tag-with-a-null-value) ##### Deleting data * [Can I delete a field?](#can-i-delete-a-field) * [Can I delete a measurement?](#can-i-delete-a-measurement) * [Can I delete multiple measurements at the same time?](#can-i-delete-multiple-measurements-at-the-same-time) * [Do I need to verify that data is deleted?](#do-i-need-to-verify-that-data-is-deleted) ##### InfluxDB tasks * [How does retrying a task affect relative time ranges?](#how-does-retrying-a-task-affect-relative-time-ranges) ##### Series and series cardinality * [What is series cardinality?](#what-is-series-cardinality) * [Why does series cardinality matter?](#why-does-series-cardinality-matter) * [How do I remove series from the index?](#how-do-i-remove-series-from-the-index) ## Account management #### How do I reset my password? Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) and the[`influx user password` command](/influxdb/v2/reference/cli/influx/user/password/)command to update a user’s password. For more information, see[Change your password](/influxdb/v2/admin/users/change-password/). ## InfluxDB service health #### Where can I see the current status of my InfluxDB instance? InfluxDB 2.10 provides different ways to monitor its status: * The [`/health` API endpoint](/influxdb/v2/api/system-information-endpoints/) returns a JSON body with a summary of the current status of your InfluxDB instance. [](#view-example-health-summary) View example health summary ``` { "name": "influxdb", "message": "ready for queries and writes", "status": "pass", "checks": [], "version": "2.10.0", "commit": "xx00x0x000" } ``` * The [`/metrics` API endpoint](/influxdb/v2/api/system-information-endpoints/) provides internal InfluxDB metrics in Prometheus exposition format. Use [Telegraf](/telegraf/v1/),[InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/), or the Flux[`prometheus.scrape()` function](/flux/v0/stdlib/experimental/prometheus/scrape/)to scrape these metrics and store them in InfluxDB where you can monitor and alert on any anomalies. You can also use the [InfluxDB Open Source (OSS) Metrics template](https://github.com/influxdata/community-templates/tree/master/influxdb2_oss_metrics)quickly setup InfluxDB OSS monitoring. For more information, see [Monitor InfluxDB OSS using a template](/influxdb/v2/monitor-alert/templates/monitor/) ## Security #### What different types of API tokens exist? InfluxDB 2.10 supports the following token types: * Operator tokens * All Access tokens * Read/Write tokens For more information about each token type, see [Manage API tokens](/influxdb/v2/admin/tokens/). #### Can I use InfluxDB with authentication disabled? InfluxDB 2.10 enforces security best practices by requiring API requests to be authenticated. Authentication cannot be disabled. ## Administration #### How can I identify my InfluxDB version? Use one of the following methods to identify the version of InfluxDB OSS you’re using: * **Use the InfluxDB UI**: * On the user login page * In the right column of the main landing page * **Use the `influxd version` command** ``` $ influxd version InfluxDB 2.10.0 (git: x0x000xx0x) build_date: YYYY-MM-DDThh:mm:ssZ ``` * **Use the `/health` API endpoint**. The following example uses [`jq`](https://stedolan.github.io/jq/) to process the JSON body returned from the `/health` API endpoint and extract the InfluxDB version. You don’t have to process the JSON with `jq`. For an example of the JSON returned by the `/health` endpoint, see [View example health summary](#view-example-health-summary). ``` $ curl -s http://localhost:8086/health | jq -r '.version' 2.10.0 ``` #### How can I identify the version of Flux I’m using in InfluxDB? For information about what versions of Flux are packaged with official InfluxDB releases, see [Flux versions in InfluxDB](/flux/v0/influxdb-versions/). If using a custom build, use the following query to return the current version of Flux being used: ```js import "array" import "runtime" array.from(rows: [{version: runtime.version()}]) ``` For more information, see [Query the Flux version](/influxdb/cloud/query-data/flux/flux-version/). #### Where can I find InfluxDB logs? All InfluxDB logs are output by the `influxd` service. To store logs to a file, pipe the output of `influxd` to a file. For example: ``` influxd 2>~/path/to/influxd-errors.log ``` #### What is the relationship between shard group durations and retention periods? InfluxDB buckets store data in shard groups. A single shard group covers a specific time interval. InfluxDB determines that time interval by using the retention period of the bucket. The table below outlines the default relationship between the bucket retention period and the time interval of a shard group: | Bucket retention period |Default shard group duration| |---------------------------|----------------------------| | less than 2 days | 1h | |between 2 days and 6 months| 1d | | greater than 6 months | 7d | For more information, see [InfluxDB Shards and shard groups](/influxdb/v2/reference/internals/shards/). #### Why isn’t data dropped after I update a bucket’s retention period? Below are reasons why data may not be dropped immediately after updating the retention period of a bucket: * \*\*The retention enforcement service runs every 30 minutes (by default) \*\*. You may need to wait for the next retention enforcement cycle to run. * **InfluxDB drops shard groups, not individual points**. Shard groups cover a specific time interval assigned to the shard group on creation. The retention service will only delete a shard group when the entire time range covered by the shard group is beyond the bucket retention period. If the bucket’s new retention period is less than the old shard group duration and InfluxDB is currently writing data to the old, longer shard group, the the retention service will not drop old shard group until its assigned interval is fully expired. For more information, see [Data retention](/influxdb/v2/reference/internals/data-retention/). \ ## Data types #### What are the minimum and maximum integers that InfluxDB can store? InfluxDB stores all integers as signed 64bit integers. **Minimum integer**: `-9223372036854775808` **Maximum integer**: `9223372036854775807` Values close to but within those limits may lead to unexpected behavior. Some query operations convert 64bit integers to 64bit float values which can cause overflow issues. #### What are the minimum and maximum timestamps that InfluxDB can store? InfluxDB uses 64bit integers to represent Unix nanosecond timestamps. **Minimum timestamp**: `-9223372036854775806` or `1677-09-21T00:12:43.145224194Z` **Maximum timestamp**: `9223372036854775806` or `2262-04-11T23:47:16.854775806Z` Timestamps outside that range return a parsing error. #### Can I change a field’s data type? [Flux type-conversion functions](/flux/v0/function-types/#type-conversions) let you change a fields data type at query time. However, you cannot change the type of a field on disk. Below are some possible workarounds: * **Copy a field to a new field as a different type.**The example below does the following: * Queries the `example-string-field`. * Converts field values to booleans. * Changes the field name to `example-boolean-field`. * Writes the new field to the source bucket. ``` from(bucket: "example-bucket") |> range(start: -30d) |> filter(fn: (r) => r._measurement == "exampled-measurement") |> filter(fn: (r) => r._field == "example-string-field") |> toBool() |> set(key: "_field", value: "example-boolean-field") |> to(bucket: "example-bucket") ``` * **Copy a field to a new bucket as a different type.**The example below does the following: * Queries the `example-int-field` from the `example-bucket-1` bucket. * Converts field values to float values. * Changes the field name to `example-float-field`. * Writes the new field to the `example-bucket-2` bucket. ``` from(bucket: "example-bucket-1") |> range(start: -30d) |> filter(fn: (r) => r._measurement == "exampled-measurement") |> filter(fn: (r) => r._field == "example-int-field") |> toFloat() |> set(key: "_field", value: "example-float-field") |> to(bucket: "example-bucket-2") ``` #### How does InfluxDB handle field type discrepancies across shards? Field values can be floats, integers, strings, or Booleans. Field value types cannot differ within a[shard](/enterprise_influxdb/v1/concepts/glossary/#shard), but they can [differ](/enterprise_influxdb/v1/write_protocols/line_protocol_reference) across shards. The[`SELECT` statement](/enterprise_influxdb/v1/query_language/explore-data/#the-basic-select-statement)returns all field values **if** all values have the same type. If field value types differ across shards, InfluxDB first performs any applicable [cast](/enterprise_influxdb/v1/query_language/explore-data/#cast-operations)operations and then returns all values with the type that occurs first in the following list: float, integer, string, Boolean. If your data have field value type discrepancies, use the syntax`::` to query the different data types. #### Example The measurement `just_my_type` has a single field called `my_field`.`my_field` has four field values across four different shards, and each value has a different data type (float, integer, string, and Boolean). `SELECT *` returns only the float and integer field values. Note that InfluxDB casts the integer value to a float in the response. ``` SELECT * FROM just_my_type ## name: just_my_type time my_field 2016-06-03T15:45:00Z 9.87034 2016-06-03T16:45:00Z 7 ``` `SELECT :: [...]` returns all value types. InfluxDB outputs each value type in its own column with incremented column names. Where possible, InfluxDB casts field values to another type; it casts the integer `7` to a float in the first column, and it casts the float `9.879034` to an integer in the second column. InfluxDB cannot cast floats or integers to strings or Booleans. ``` SELECT "my_field"::float,"my_field"::integer,"my_field"::string,"my_field"::boolean FROM just_my_type ## name: just_my_type time my_field my_field_1 my_field_2 my_field_3 2016-06-03T15:45:00Z 9.87034 9 2016-06-03T16:45:00Z 7 7 2016-06-03T17:45:00Z a string 2016-06-03T18:45:00Z true ``` `SHOW FIELD KEYS` returns every data type, across every shard, associated with the field key. #### Example The measurement `just_my_type` has a single field called `my_field`.`my_field` has four field values across four different shards, and each value has a different data type (float, integer, string, and Boolean).`SHOW FIELD KEYS` returns all four data types: ```sql > SHOW FIELD KEYS name: just_my_type fieldKey fieldType -------- --------- my_field float my_field string my_field integer my_field boolean ``` ## Writing data #### How do I write integer and unsigned integer field values? In line protocol, identify **integers** with a trailing `i` and **unsigned integers**with a trailing `u`. Without these, numeric field values are parsed as floats. ```sh # Integer value=100i # Unsigned integer value=100u # Float value=100 ``` #### How does InfluxDB handle duplicate points? InfluxDB uniquely identifies a point by its **measurement**, **tag set**, and **timestamp**. If you submit a new point with the same measurement, tag set, and timestamp as an existing point, InfluxDB unions the old field with the new field set, and any ties go to the new field set. For more information, see [Handle duplicate data points](/influxdb/v2/write-data/best-practices/duplicate-points/). #### What newline character does the InfluxDB write API require? InfluxDB line protocol relies on line feed (`\n`, which is ASCII `0x0A`) to indicate the end of one line and the beginning of a new line. Files or data that use a newline character other than `\n` will result in errors similar to `bad timestamp` or `unable to parse`. > [!Note] > ##### Windows newlines > > Windows uses carriage return and line feed (`\r\n`) as the newline character which > will result in an error if you manually write line protocol on a Windows machine. > Strip out any carriage returns (`\r`) before submitting the line protocol to the > InfluxDB write API. #### When should I single quote and when should I double quote when writing data? Line protocol quote usage guidelines are provided in the[line protocol documentation](/influxdb/cloud/reference/syntax/line-protocol/#quotes). #### Does the precision of the timestamp matter? Yes. Timestamp precision affects ingest performance. The more precise the timestamp, the longer it takes to write the point. To maximize performance, use the coarsest possible timestamp precision when writing data to InfluxDB. However, if too coarse, you risk writing points from the same series with the same timestamp, which would be treated as[duplicate points](/influxdb/v2/write-data/best-practices/duplicate-points/). #### What are the configuration recommendations and schema guidelines for writing sparse, historical data? For sparse historical data, we recommend: * **Use a longer [shard group duration](/influxdb/v2/reference/internals/shards/#shard-group-duration)on the bucket you’re writing historical data to.**Historical shard group durations can and should cover several years. If your historical data spans many years, but your bucket’s shard group duration is 1 week, InfluxDB will create many shards, negatively affecting overall performance. * **Temporarily lower the[`storage-cache-snapshot-write-cold-duration` configuration setting](/influxdb/v2/reference/config-options/#storage-cache-snapshot-write-cold-duration)while ingesting historical data**. The default setting (`10m`) can cause the system cache all of your data for every shard. Temporarily lowering the `storage-cache-snapshot-write-cold-duration` setting to `10s` while you write the historical data makes the process more efficient. ## Querying data ### Flux #### How do I structure fields as columns (like InfluxQL)? A `SELECT` statement in InfluxQL returns data with a column for each queried tag and field. The Flux [`from()`](/flux/v0/stdlib/influxdata/influxdb/from/) function returns data with a column for each tag as well as a `_field` column that contains the field key. Each field is grouped into a different table. To structure each field as a column, use either [`pivot()`](/flux/v0/stdlib/universe/pivot/)or [`schema.fieldsAsCols()`](/flux/v0/stdlib/influxdata/influxdb/schema/fieldsascols/). [pivot()](#pivot)[schema.fieldsAsCols](#schemafieldsascols) ```js exampleData |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") ``` ```js import "influxdata/influxdb/schema" exampleData |> schema.fieldsAsCols() ``` ###### Example data returned by from() |\_measurement|sensor\_id|location |\_field| \_time |\_value| |-------------|----------|---------|-------|--------------------|-------| | machine | abc123 |station20| temp |2022-01-01T00:00:00Z| 150.1 | | machine | abc123 |station20| temp |2022-01-01T00:00:10Z| 152.8 | | machine | abc123 |station20| temp |2022-01-01T00:00:20Z| 153.3 | |\_measurement|sensor\_id|location |\_field| \_time |\_value| |-------------|----------|---------|-------|--------------------|-------| | machine | abc123 |station20| flow |2022-01-01T00:00:00Z| 12.2 | | machine | abc123 |station20| flow |2022-01-01T00:00:10Z| 14.9 | | machine | abc123 |station20| flow |2022-01-01T00:00:20Z| 16.1 | ###### Example pivoted data |\_measurement|sensor\_id|location | \_time |temp |flow| |-------------|----------|---------|--------------------|-----|----| | machine | abc123 |station20|2022-01-01T00:00:00Z|150.1|12.2| | machine | abc123 |station20|2022-01-01T00:00:10Z|152.8|14.9| | machine | abc123 |station20|2022-01-01T00:00:20Z|153.3|16.1| #### How can I derive a state from multiple field values? To compare multiple field values and derive a state: 1. Query all fields necessary to derive a state. 2. Use `pivot()` or `schema.fieldsAsCols()` to pivot fields into columns. 3. Use `map()` to iterate over each input row assign a new column value based on values in the field columns. The `fn` parameter of `map()` defines a functions that outputs a record for each input row. Use conditional logic to assign a state. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement") |> filter(fn: (r) => r._field == "field1" or r._field == "field2") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> map( fn: (r) => ({r with state: if r.field1 > 90 and r.field2 < 10 then "critical" else if r.field1 > 70 and r.field2 < 30 then "warning" else if r.field1 > 40 and r.field2 < 60 then "info" else "ok", }), ) ``` ### InfluxQL #### How do I use InfluxQL with InfluxDB v2.x? Using InfluxQL with InfluxDB 2.10 is made possible by the[v1 compatibility API](/influxdb/v2/reference/api/influxdb-1x/) which replicates the `/query` endpoint from InfluxDB 1.x. This allows all InfluxDB v1-compatible clients to work with InfluxDB 2.10. However, InfluxQL relies on a database and retention policy data model doesn’t exist in InfluxDB2.10, but has been replaced by [buckets](/influxdb/v2/reference/glossary/#bucket). InfluxDB 2.10 lets you map unique database and retention policy combinations used in InfluxQL to specific buckets using DBRP mappings. For detailed instructions on using InfluxQL with InfluxDB 2.10and configuring DBRP mapping, see [Query with InfluxQL](/influxdb/v2/query-data/influxql/). #### How do I perform mathematical operations in an InfluxQL function? InfluxQL does not support mathematical operations within functions. Use a [subquery](/influxdb/v1/query_language/explore-data/#subqueries) to perform the mathematical calculation. For example, InfluxQL does not support the following syntax: ```sql SELECT MEAN("dogs" - "cats") from "pet_daycare" ``` Instead, use a subquery to get the same result: ```sql SELECT MEAN("difference") FROM (SELECT "dogs" - "cat" AS "difference" FROM "pet_daycare") ``` #### Why does my query return epoch 0 as the timestamp? In InfluxQL, epoch 0 (`1970-01-01T00:00:00Z`) is often used as a null timestamp equivalent. If you request a query that has no timestamp to return, such as an aggregation function with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. #### Which InfluxQL functions support nesting? The following InfluxQL functions support nesting: * [`COUNT()`](/influxdb/v1/query_language/functions/#count) with [`DISTINCT()`](/influxdb/v1/query_language/functions/#distinct) * [`CUMULATIVE_SUM()`](/influxdb/v1/query_language/functions/#cumulative-sum) * [`DERIVATIVE()`](/influxdb/v1/query_language/functions/#derivative) * [`DIFFERENCE()`](/influxdb/v1/query_language/functions/#difference) * [`ELAPSED()`](/influxdb/v1/query_language/functions/#elapsed) * [`MOVING_AVERAGE()`](/influxdb/v1/query_language/functions/#moving-average) * [`NON_NEGATIVE_DERIVATIVE()`](/influxdb/v1/query_language/functions/#non-negative-derivative) * [`HOLT_WINTERS()`](/influxdb/v1/query_language/functions/#holt-winters) and [`HOLT_WINTERS_WITH_FIT()`](/influxdb/v1/query_language/functions/#holt-winters) For information on how to use subqueries as substitutes for nested functions, see[InfluxQL data exploration](/influxdb/v1/query_language/explore-data/#subqueries). #### What determines the time intervals returned by `GROUP BY time()` queries? The time intervals returned by `GROUP BY time()` queries conform to the InfluxDB database’s preset time windows or to the user-specified[offset interval](/influxdb/v1/query_language/explore-data/#advanced-group-by-time-syntax). ###### Preset time windows For example, the following query calculates the average value of `sunflowers` between 6:15pm and 7:45pm and groups those averages into one hour intervals: ```sql SELECT mean("sunflowers") FROM "flower_orders" WHERE time >= '2016-08-29T18:15:00Z' AND time <= '2016-08-29T19:45:00Z' GROUP BY time(1h) ``` InfluxQL uses the duration specified in the `GROUP BY time()` clause to partition data based on time. Preset time window boundaries fall on the duration unit specified. For example: |GROUP BY time() duration| Resulting window boundaries | |------------------------|----------------------------------------------| | 1s |00:00:00 - 00:00:01, 00:00:01 - 00:00:02, etc.| | 1m |00:00:00 - 00:01:00, 00:01:00 - 00:02:00, etc.| | 5m |00:00:00 - 00:05:00, 00:05:00 - 00:10:00, etc.| | 1h |00:00:00 - 01:00:00, 01:00:00 - 02:00:00, etc.| Although window boundaries may fall outside of the queried time range, only points within the queried time range are used in the calculation for each window. ###### Offset time windows As another example, the following query calculates the average value of`sunflowers` between 6:15pm and 7:45pm and groups those averages into one hour intervals. It offsets the InfluxDB database’s preset time windows by `15` minutes. ```sql SELECT mean("sunflowers") FROM "flower_orders" WHERE time >= '2016-08-29T18:15:00Z' AND time <= '2016-08-29T19:45:00Z' GROUP BY time(1h,15m) --- | offset interval ``` InfluxQL uses the duration and offset specified in the `GROUP BY time()` clause to partition data based on time. Time boundaries begin at the specified offset. For example: |GROUP BY time() duration and offset| Resulting window boundaries | |-----------------------------------|----------------------------------------------| | 1m,30s |00:30:00 - 01:30:00, 01:30:00 - 02:30:00, etc.| | 5m,15s |00:00:15 - 00:05:15, 00:05:15 - 00:10:15, etc.| | 1h,20m |00:20:00 - 01:20:00, 01:20:00 - 02:20:00, etc.| #### Why do my queries return no data or partial data? The most common reasons why your query returns no data or partial data: * [Querying the wrong retention policy](#querying-the-wrong-retention-policy) (no data returned) * [No field key in the SELECT clause](#no-field-key-in-the-select-clause) (no data returned) * [SELECT query includes `GROUP BY time()`](#select-query-includes-group-by-time) (partial data before `now()` returned) * [Tag and field key with the same name](#tag-and-field-key-with-the-same-name) ##### Querying the wrong retention policy InfluxDB automatically queries data in a database’s default retention policy (configured as part of a [DBRP mapping](/influxdb/v2/query-data/influxql/)). If your data is associated another retention policy, you must specify the correct retention policy to get results. ##### No field key in the SELECT clause An InfluxQL query requires at least one **field key** in the `SELECT` clause. If the `SELECT` clause includes only **tag keys**, the query returns an empty response. For more information, see[InfluxQL Data exploration](/influxdb/v1/query_language/explore-data/#common-issues-with-the-select-statement). ##### SELECT query includes `GROUP BY time()` If your `SELECT` query includes a [`GROUP BY time()` clause](/influxdb/v1/query_language/explore-data/#group-by-time-intervals), only data points between `1677-09-21 00:12:43.145224194` and[`now()`](/influxdb/v1/concepts/glossary/#now) are returned. If any of your data points occur after `now()`, specify[an alternative upper bound](/influxdb/v1/query_language/explore-data/#time-syntax)in your time interval. ##### Tag and field key with the same name Avoid using the same name for a tag and field key. If you inadvertently add the same name for a tag and field key, and then query both together, the query results show the second key queried (tag or field) appended with `_1`. To query a tag or field key appended with `_1`, you **must drop** the appended `_1` **and include** the syntax `::tag` or `::field`. For example: ```sql -- Query duplicate keys using the correct syntax SELECT "leaves"::tag, "leaves"::field FROM db.rp."grape" name: grape time leaves leaves_1 ---- -------- ---------- 1574128162128468000 species 6.00 1574128238044155000 5.00 ``` #### Why don’t my `GROUP BY time()` queries return timestamps that occur after `now()`? `SELECT` statements without a time range defined in the `WHERE` clause have a default time range of `1677-09-21 00:12:43.145224194` to `2262-04-11T23:47:16.854775806Z` UTC. For `SELECT` statements that don’t specify a time range but have a[`GROUP BY time()` clause](/influxdb/v1/query_language/explore-data/#group-by-time-intervals), the default time range is `1677-09-21 00:12:43.145224194` UTC to [`now()`](/influxdb/v2/reference/glossary/#now). To query data with timestamps that occur after `now()`, `SELECT` statements with a `GROUP BY time()` clause must provide an alternative **upper** bound in the[`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/). For example: ```sql SELECT MEAN("boards") FROM "hillvalley" WHERE time >= '2022-01-01T00:00:00Z' AND time <= now() + 10d GROUP BY time(12m) fill(none) ``` Note that the `WHERE` clause must provide an alternative **upper** bound to override the default `now()` upper bound. The following query merely resets the lower bound to `now()` such that the query’s time range is between`now()` and `now()`: ```sql SELECT MEAN("boards") FROM "hillvalley" WHERE time >= now() GROUP BY time(12m) fill(none) ``` For for more on time syntax in queries, see [InfluxQL data Exploration](/influxdb/v1/query_language/explore-data/#time-syntax). #### Can I perform mathematical operations against timestamps? InfluxQL does not support mathematical operators against timestamp values. Most time calculations must be carried out by the client receiving the query results. There is limited support for using InfluxQL functions against timestamp values. The [ELAPSED()](/influxdb/v1/query_language/functions/#elapsed)function returns the difference between subsequent timestamps in a single field. #### Can I identify write precision from returned timestamps? InfluxDB stores all timestamps as nanosecond values, regardless of the write precision supplied. InfluxQL silently drops trailing zeros from timestamps which obscures the initial write precision. Because InfluxDB silently drops trailing zeros on returned timestamps, the write precision is not recognizable in the returned timestamps. #### When should I use single quote versus double quotes in a query? Follow these general rules for quotes in InfluxQL queries: ###### Single quotes * Use to quote literal string values, like tag values. * Do **not** use on identifiers like database names, retention policy names, user names, measurement names, tag keys, and field keys. * Use on date-time strings. ###### Double quotes * Use on identifiers that start with a digit, contain characters other than `[A-z,0-9,_]`, or that are an [InfluxQL keyword](/influxdb/v1/query_language/spec/#keywords). We generally recommend using double quotes on all identifiers, even if they don’t meet these criteria. * Do **not** use on date-time strings. ```sql -- Correctly quote usage SELECT bikes_available FROM bikes WHERE station_id='9' SELECT "bikes_available" FROM "bikes" WHERE "station_id"='9' SELECT MIN("avgrq-sz") AS "min_avgrq-sz" FROM telegraf SELECT * from "cr@zy" where "p^e"='2' SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-08-18T23:00:01.232000000Z' AND time < '2015-09-19' -- Incorrect quote usage SELECT 'bikes_available' FROM 'bikes' WHERE 'station_id'="9" SELECT * from cr@zy where p^e='2' SELECT "water_level" FROM "h2o_feet" WHERE time > "2015-08-18T23:00:01.232000000Z" AND time < "2015-09-19" ``` #### Why is my query with a `WHERE OR` time clause returning empty results? InfluxQL does not support using `OR` in the `WHERE` clause to specify multiple time ranges and returns an empty response if multiple are specified. For example, the following query will return an empty response: ```sql SELECT * FROM "absolutismus" WHERE time = '2016-07-31T20:07:00Z' OR time = '2016-07-31T23:07:17Z' ``` #### Why does `fill(previous)` return empty results? `fill(previous)` doesn’t fill a null value if there is no previous value inside the queried time range. #### How do I query data with an identical tag key and field key? Use the `::` syntax to specify if the key is a field key or tag key. For example: ```sql SELECT * FROM "candied" WHERE "almonds"::field > 51 SELECT * FROM "candied" WHERE "almonds"::tag='true' ``` #### How do I query data across measurements? InfluxQL does not support querying multiple measurements All data must be under a single measurement to query it together. To perform cross-measurement queries,[use Flux](/influxdb/v2/reference/syntax/flux/flux-vs-influxql/#math-across-measurements). #### Does the order timestamps in a query matter? No, it doesn’t. There is a only a *negligible* difference between the following queries: ```sql SELECT ... FROM ... WHERE time > 'timestamp1' AND time < 'timestamp2' SELECT ... FROM ... WHERE time < 'timestamp2' AND time > 'timestamp1' ``` #### How do I query data by a tag with a null value? In your `WHERE` clause, specify an empty or null tag value with `''`. For example: ```sql SELECT * FROM "vases" WHERE priceless='' ``` ## Deleting data #### Can I delete a field? No. InfluxDB 2.10 does not support deleting data by field. #### Can I delete a measurement? Yes. InfluxDB 2.10 supports deleting data by measurement. Use the `_measurement` label in your [delete predicate](/influxdb/v2/reference/syntax/delete-predicate/)to identify the measurement to delete. ```js _measurement == "example-measurement" ``` #### Can I delete multiple measurements at the same time? No. InfluxDB 2.10 does not support deleting multiple measurements in a single delete request. To delete multiple measurements, [issue a delete request](/influxdb/v2/write-data/delete-data/)for each measurement. #### Do I need to verify that data is deleted? It is not necessary to verify delete operations once they have been submitted to the queue. The `/api/v2/delete` endpoint returns a 204 response when the delete request has been added to the queue. If you wish to verify a delete has occurred, try to query the deleted data. If the query returns results, the data has not been fully deleted. ## InfluxDB tasks #### How does retrying a task affect relative time ranges? When you retry a task that uses relative time ranges, it will query the original time range of the task execution (run). Whenever a task executes, InfluxDB sets the [`now` option ](/flux/v0/stdlib/universe/#options)in the task to the scheduled execution time of the task. When using [`range()`](/flux/v0/stdlib/universe/range/)or other functions that support relative duration values, these duration values are relative to [`now()`](/flux/v0/stdlib/universe/now/), which returns the value of the `now` option. Every task run has a unique `now` option based on the time the run was scheduled to execute. ## Series and series cardinality #### What is series cardinality? [Series cardinality](/influxdb/v2/reference/glossary/#series-cardinality) is the total number of unique **measurement** and **tag set** combinations (series) stored on disk and indexed in memory. #### Why does series cardinality matter? InfluxDB maintains an in-memory index of every [series](/influxdb/v2/reference/glossary/#series). As the number of unique series grows, so does the memory usage. High series cardinality can force the host operating system to kill the InfluxDB process with an out of memory (OOM) exception. Use [`influxdb.cardinality()`](/flux/v0/stdlib/influxdata/influxdb/cardinality/) in Flux or [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality)in InfluxQL to measure the series cardinality in a bucket. See [Resolve high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/)for information about reducing series cardinality. #### How do I remove series from the index? To remove a series from an index: 1. Use the **`influx` CLI** or **InfluxDB 2.10 API** to delete points associated with the series. See [Delete data](/influxdb/v2/write-data/delete-data/)for more information. 2. Use the [`influxd inspect build-tsi` tool](/influxdb/v2/reference/cli/influxd/inspect/build-tsi/)to rebuild your index. | Bucket retention period | Default shard group duration | | --- | --- | | Bucket retention period | Default shard group duration | | less than 2 days | 1h | | between 2 days and 6 months | 1d | | greater than 6 months | 7d | | _measurement | sensor_id | location | _field | _time | _value | | --- | --- | --- | --- | --- | --- | | _measurement | sensor_id | location | _field | _time | _value | | machine | abc123 | station20 | temp | 2022-01-01T00:00:00Z | 150.1 | | machine | abc123 | station20 | temp | 2022-01-01T00:00:10Z | 152.8 | | machine | abc123 | station20 | temp | 2022-01-01T00:00:20Z | 153.3 | | _measurement | sensor_id | location | _field | _time | _value | | --- | --- | --- | --- | --- | --- | | _measurement | sensor_id | location | _field | _time | _value | | machine | abc123 | station20 | flow | 2022-01-01T00:00:00Z | 12.2 | | machine | abc123 | station20 | flow | 2022-01-01T00:00:10Z | 14.9 | | machine | abc123 | station20 | flow | 2022-01-01T00:00:20Z | 16.1 | | _measurement | sensor_id | location | _time | temp | flow | | --- | --- | --- | --- | --- | --- | | _measurement | sensor_id | location | _time | temp | flow | | machine | abc123 | station20 | 2022-01-01T00:00:00Z | 150.1 | 12.2 | | machine | abc123 | station20 | 2022-01-01T00:00:10Z | 152.8 | 14.9 | | machine | abc123 | station20 | 2022-01-01T00:00:20Z | 153.3 | 16.1 | | GROUP BY time() duration | Resulting window boundaries | | --- | --- | | GROUP BY time() duration | Resulting window boundaries | | 1s | 00:00:00 - 00:00:01, 00:00:01 - 00:00:02, etc. | | 1m | 00:00:00 - 00:01:00, 00:01:00 - 00:02:00, etc. | | 5m | 00:00:00 - 00:05:00, 00:05:00 - 00:10:00, etc. | | 1h | 00:00:00 - 01:00:00, 01:00:00 - 02:00:00, etc. | | GROUP BY time() duration and offset | Resulting window boundaries | | --- | --- | | GROUP BY time() duration and offset | Resulting window boundaries | | 1m,30s | 00:30:00 - 01:30:00, 01:30:00 - 02:30:00, etc. | | 5m,15s | 00:00:15 - 00:05:15, 00:05:15 - 00:10:15, etc. | | 1h,20m | 00:20:00 - 01:20:00, 01:20:00 - 02:20:00, etc. | --- # Glossary Source: https://docs.influxdata.com/influxdb/v2/reference/glossary/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [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 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 [Flux aggregate functions](/flux/v0/function-types#aggregates). Related entries: [function](#function), [selector](#selector), [transformation](#transformation) B ---------- ### bar graph A visual representation in the InfluxDB user interface used to compare variables (bars) and plot categorical data. A bar graph has spaces between bars, can be sorted in any order, and bars in the graph typically have the same width. Related entries: [histogram](#histogram) ### 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](/influxdb/v2/reference/syntax/line-protocol/), [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. ### block In Flux, a block is a possibly empty sequence of statements within matching braces (`{ }`). Two types of blocks exist in Flux: * Explicit blocks in the source code, for example: ``` Block = "{" StatementList "} StatementList = { Statement } ``` * Implicit blocks, including: * Universe: Encompasses all Flux source text. * Package: Each package includes a package block that contains Flux source text for the package. * File: Each file has a file block containing Flux source text in the file. * Function: Each function literal has a function block with Flux source text (even if not explicitly declared). Related entries: [implicit block](#implicit-block), [explicit block](#explicit-block) ### 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). In [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), columns that contain boolean values are annotated with the `boolean` datatype. ### bucket A bucket is a named location where time series data is stored. All buckets have a [retention period](#retention-period). A bucket belongs to an organization. ### bucket schema In InfluxDB Cloud, an explicit bucket schema lets you strictly enforce the data that can be written into one or more measurements in a bucket by defining the column names, tags, fields, and data types allowed for each measurement. By default, buckets in InfluxDB 2.10 have an `implicit` schema that lets you write data without restrictions on columns, fields, or data types. Learn how to [manage bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema/) in InfluxDB Cloud. Related entries: [data type](#data-type), [field](#field), [measurement](#measurement) C ---------- ### check Checks are part of queries used in monitoring to read input data and assign a [status](#check-status) (`_level`) based on specified conditions. For example: ``` monitor.check( crit: (r) => r._value > 90.0, warn: (r) => r._value > 80.0, info: (r) => r._value > 60.0, ok: (r) => r._value <= 20.0, messageFn: (r) => "The current level is ${r._level}", ) ``` This check gives rows with a `_value` greater than 90.0 a crit `_level`; rows greater than 80.0 get a warn `_level`, and so on. Learn how to [create a check](/influxdb/v2/monitor-alert/checks/create/). Related entries: [check status](#check-status), [notification rule](#notification-rule), [notification endpoint](#notification-endpoint) ### check status A [check](#check) gets one of the following statuses (`_level`): `crit`, `info`, `warn`, or `ok`. Check statuses are written to a status measurement in the `_monitoring` bucket. Related entries: [check](#check), [notification rule](#notification-rule), [notification endpoint](#notification-endpoint) ### 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 record. Each record consists of one or more fields, separated by commas. CSV file format is not fully standardized. InfluxData uses annotated CSV (comma-separated values) format to encode HTTP responses and results returned to the Flux csv.from() function. For more detail, see [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/). ### co-monitoring dashboard The prebuilt co-monitoring dashboard displays details of your instance based on metrics from Telegraf, allowing you to monitor overall performance. ### collect Collect and write time series data to InfluxDB using line protocol, Telegraf or InfluxDB scrapers, the InfluxDB v2 API, influx command line interface (CLI),the InfluxDB user interface (UI), and 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 will sleep 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 (indexed) and fields sets. The only required column is *time*, which stores timestamps and is included in all InfluxDB tables. ### comment Use comments with Flux statements to describe your functions. ### common log format (CLF) A standardized text file format used by the InfluxDB web 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 the predecessor to tasks in InfluxDB 2.10. Continuous queries run automatically and periodically on a database. Related entries: [function](#function) D ---------- ### daemon A background process that runs without user input. ### dashboard InfluxDB dashboards visualize time series data. Use dashboards to query and graph data. ### dashboard variable Dashboard template variables define components of a cell query. Dashboard variables make is easier to interact with and explore your databoard data. Use the InfluxDB user interface (UI) to add predefined template variables or customize your own template variables. ### Data Explorer Use the Data Explorer in the InfluxDB user interface (UI) to view, add, or delete variables and functions manually or using the Script Editor. ### 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. Flux uses a data model built from basic data types: tables, records, columns and streams. ### data service Stores time series data and handles writes and queries. ### data source A source of data that InfluxDB collects or queries data from. Examples include InfluxDB buckets, Prometheus, Postgres, MySQL, and InfluxDB clients. Related entries: [bucket](#bucket) ### 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: | Data type | Alias/annotation | |----------------|------------------| | string | | | boolean | | | float | double | | integer | int, long | |unsigned integer|uint, unsignedLong| | time | dateTime | For more information about different data types, see: * [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) * [extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/#datatype) * [line protocol](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format) * [InfluxQL](/influxdb/v1/query_language/spec/#literals) * [Flux](/influxdb/v2/reference/flux/language/types/) * [InfluxDB](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format) #### database In InfluxDB 1.x, a database represented a logical container for users, retention policies, continuous queries, and time series data. The InfluxDB 2.x equivalent of this concept is an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket). Related entries: [continuous query](#continuous-query-cq), [retention policy](#retention-policy-rp), [user](#user) ### date-time InfluxDB stores the date-time format for each data point in a timestamp with nanosecond-precision Unix time. Specifying a timestamp is options. 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 policies are set using durations. Data older than the duration is automatically dropped from the database. E ---------- ### event Metrics gathered at irregular time intervals. ### explicit block In Flux, an explicit block is a possibly empty sequence of statements within matching braces (`{ }`) that is defined in the source code, for example: ``` Block = "{" StatementList "} StatementList = { Statement } ``` Related entries: [implicit block](#implicit-block), [block](#block) ### expression A combination of one or more constants, variables, operators, and functions. F ---------- ### field The key-value pair in InfluxDB’s data structure that records metadata and the actual data value. Fields are required in InfluxDB’s data structure and they are not indexed - queries on field values scan all points that match the specified time range and, as a result, are not performant relative to tags. *Query tip:* Compare fields to tags; tags are indexed. 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 and they store metadata. Related entries: [field](#field), [field set](#field-set), [field value](#field-value), [tag key](#tag-key) ### field set The collection of field keys and field values on a point. 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, or booleans. A field value is always associated with a timestamp. Field values are not indexed - queries on field values scan all points that match the specified time range and, as a result, are not performant. *Query tip:* Compare field values to tag values; tag values are indexed. Related entries: [field](#field), [field key](#field-key), [field set](#field-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. Related entries: [block](#block) ### 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. In [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), columns that contain float values are annotated with the `double` datatype. ### 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 will sleep 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) ### Flux A lightweight scripting language for querying databases (like InfluxDB) and working with data. ### function Flux functions aggregate, select, and transform time series data. For a complete list of Flux functions, see [Flux functions](/flux/v0/stdlib/all-functions/). Related entries: [aggregate](#aggregate), [selector](#selector), [transformation](#transformation) ### function block In Flux, each file has a file block containing all Flux source text in that file. Each function literal has its own function block even if not explicitly declared. G ---------- ### gauge A type of visualization that displays the single most recent value for a time series. A gauge typically displays one or more measures from a single row, and is not designed to display multiple rows of data. Elements include a range, major and minor tick marks (within the range), and a pointer (needle) indicating the single most recent value. ### graph A diagram that visually depicts the relation between variable quantities measured along specified axes. ### group key Group keys determine the schema and contents of tables in Flux output. A group key is a list of columns for which every row in the table has the same value. Columns with unique values in each row are not part of the group key. ### 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 task names, bucket names, field keys, measurement names, tag keys, and user names. For examples and rules, see [Flux language lexical elements](/flux/v0/spec/lexical-elements/#identifiers). Related entries:[bucket](#bucket)[field key](#field-key),[measurement](#measurement), [tag key](#tag-key),[user](#user) ### implicit block In Flux, an implicit block is a possibly empty sequence of statements within matching braces ({ }) that includes the following types: * Universe: Encompasses all Flux source text. * Package: Each package includes a package block that contains Flux source text for the package. * File: Each file has a file block containing Flux source text in the file. * Function: Each function literal has a function block with Flux source text (even if not explicitly declared). Related entries: [explicit block](#explicit-block), [block](#block) ### influx `influx` is a command line interface (CLI) that interacts with the InfluxDB daemon (influxd). ### influxd `influxd` is the InfluxDB daemon that runs the InfluxDB server and other required processes. ### InfluxDB An open source time series database (TSDB) developed by InfluxData. Written in Go and 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. ### InfluxDB UI The graphical web interface provided by InfluxDB for visualizing data and managing InfluxDB functionality. ### InfluxQL The SQL-like query language used to query data in InfluxDB 1.x. The preferred method for querying data in InfluxDB 2.10 is the [Flux](#flux) language. ### 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. In order to activate an input plugin, it needs to be enabled and configured in Telegraf’s configuration file. Related entries: [aggregator plugin](#aggregator-plugin), [collection interval](#collection-interval), [output plugin](#output-plugin), [processor plugin](#processor-plugin) ### instance An entity comprising data on a server (or virtual server in cloud computing). ### instance owner A type of admin role for a user. Instance owners have read/write permissions for all resources within the instance. ### integer A whole number that is positive, negative, or zero (`0`, `-5`, `143`). InfluxDB supports 64-bit integers (minimum: `-9223372036854775808`, maximum: `9223372036854775807`). In [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), columns that contain integers are annotated with the `long` datatype. Related entries: [unsigned integer](#unsigned-integer) 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 an identifier. See a list of [Flux keywords](/flux/v0/spec/lexical-elements/#keywords). L ---------- ### literal A literal is value in an expression, a number, character, string, function, record, or array. Literal values are interpreted as defined. See examples of [Flux literals](/flux/v0/spec/expressions/#examples-of-function-literals). ### 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. The InfluxDB 2.10 user interface (UI) can be used to view log history and data. ### Line protocol (LP) The text based format for writing points to InfluxDB. See [line protocol](/influxdb/v2/reference/syntax/line-protocol/). M ---------- ### measurement The part of InfluxDB’s structure that describes the data stored in the associated fields. Measurements are strings. Related entries: [field](#field), [series](#series), [table](#table) ### member A user in an organization. ### 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. The Flux data model includes [Missing values (null)](/flux/v0/spec/data-model/#missing-values-null). N ---------- ### node An independent `influxd` process. Related entries: [server](#server) ### notification endpoint The notification endpoint specifies the Slack or PagerDuty endpoint to send a notification and contains configuration details for connecting to the endpoint. Learn how to [create a notification endpoint](/influxdb/v2/monitor-alert/notification-endpoints/create). Related entries: [check](#check), [notification rule](#notification-rule) ### notification rule A notification rule specifies a status level (and tags) to alert on, the notification message to send for the specified status level (or change in status level), and the interval or schedule you want to check the status level (and tags). If conditions are met, the notification rule sends a message to the [notification endpoint](#notification-endpoint) and stores a receipt in a notification measurement in the `_monitoring` bucket. For example, a notification rule may specify a message to send to a Slack endpoint when a status level is critical (`crit`). Learn how to [create a notification rule](/influxdb/v2/monitor-alert/notification-rules/create). Related entries: [check](#check), [notification endpoint](#notification-endpoint) ### now() The local server’s nanosecond timestamp. Related entries: [timestamp](#timestamp) ### null A data type that represents a missing or unknown value. Denoted by the null value. O ---------- ### operator A symbol that usually represents an action or process. For example: `+`, `-`, `>`. ### operand The object or value on either side of an operator. ### option Represents a storage location for any value of a specified type. Mutable, can hold different values during its lifetime. See built-in Flux [options](/flux/v0/spec/options/). ### option assignment An option assignment binds an identifier to an option. Learn about the [option assignment](/flux/v0/spec/assignment-scope/#option-assignment) in Flux. ### organization A workspace for a group of users. All dashboards, tasks, buckets, members, and so on, belong to an organization. ### owner A type of role for a user. Owners have read/write permissions. Users can have owner roles for bucket and organization 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 functions. ### 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. ### pipe-forward operator An operator (`|>`) used in Flux to chain operations together. Specifies the output from a function is input to next function. ### point In InfluxDB, a point represents a single data record, similar to a row in a SQL database table. Each point: * has a measurement, a tag set, a field key, a field value, and a timestamp; * is uniquely identified by its series and timestamp. In a 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) ### 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), [timestamp](#timestamp) ### 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. ### predicate function A Flux predicate function is an anonymous function that returns `true` or `false`based on one or more [predicate expressions](#predicate-expression). ###### Example predicate function ```js (r) => r.foo == "bar" and r.baz != "quz" ``` ### 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. In Flux, you can process data with [InfluxDB tasks](/influxdb/v2/process-data/get-started/). ### 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 or InfluxDB using InfluxDB scrapers. Collect data from any accessible endpoint that provides data in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). Q ---------- ### query A Flux script that returns time series data, including [tags](#tag) and [timestamps](#timestamp). See [Query data in InfluxDB](/influxdb/v2/query-data/). R ---------- ### REPL A Read-Eval-Print Loop (REPL) is an interactive programming environment where you type a command and immediately see the result. See [Flux REPL](/influxdb/v2/tools/flux-repl/) for information on building and using the REPL. ### record A tuple of named values represented using a record type. ### 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 bucket. Field type conflicts are a common cause of rejected points. ### retention period The [duration](#duration) of time that a bucket retains data. InfluxDB drops points with timestamps older than their bucket’s retention period. The minimum retention period is **one hour**. Related entries: [bucket](#bucket), [shard group duration](#shard-group-duration) ### retention policy (RP) Retention policy is an InfluxDB 1.x concept that represents the duration of time that each data point in the retention policy persists. The InfluxDB 2.x equivalent is [retention period](#retention-period). For more information about retention policies, see the[latest 1.x documentation](/influxdb/v1/concepts/glossary/#retention-policy-rp). 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`). Flux and InfluxDB clients return query results with RFC3339 timestamps. 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) S ---------- ### schema How data is organized in InfluxDB. The fundamentals of the InfluxDB schema are buckets (which include retention policies), series, measurements, tag keys, tag values, and field keys. Related entries: [bucket](#bucket), [field key](#field-key), [measurement](#measurement), [series](#series), [tag key](#tag-key), [tag value](#tag-value) ### scrape InfluxDB scrapes data from specified targets at regular intervals and writes the data to an InfluxDB bucket. Data can be scraped from any accessible endpoint that provides data in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). ### secret Secrets are key-value pairs that contain information you want to control access to, such as API keys, passwords, or certificates. ### selector A Flux function that returns a single point from the range of specified points. See [Flux selector functions](/flux/v0/stdlib/universe/) for a complete list of available selector functions. Related entries: [aggregate](#aggregate), [function](#function), [transformation](#transformation) ### series A collection of timestamps and field values that share a common series key ( measurement and tag set ). Related entries: [field set](#field-set), [measurement](#measurement), [series key](#series-key), [tag set](#tag-set) ### series cardinality The number of unique measurement, tag set, and field key combinations in an InfluxDB bucket. For example, assume that an InfluxDB bucket has one measurement. The single measurement has two tag keys: `email` and `status`. If the data contains three different `email` values, and each email address is associated with two different `status` values, 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, this calculation may overestimate series cardinality because of the presence of *dependent tags*–tags scoped by another tag. Dependent tags do not increase series cardinality. Adding the tag `firstname` to the preceding example would not increase the series cardinality to `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 | ##### Query for cardinality: * **Flux:** [influxdb.cardinality()](/flux/v0/stdlib/influxdb/cardinality/) * **InfluxQL:** [SHOW CARDINALITY](/influxdb/v1/query_language/spec/#show-cardinality) Related entries: [field key](#field-key),[measurement](#measurement), [tag key](#tag-key), [tag set](#tag-set) ### series file A file created and used by the **InfluxDB OSS storage engine**that contains a set of all series keys across the entire database. ### series key A series key identifies a particular series by measurement, tag set, and field key. For example: ``` # measurement, tag set, field key h2o_level, location=santa_monica, h2o_feet ``` Related entries: [series](#series) ### server A computer, virtual or physical, running InfluxDB. Related entries: [node](#node) ### 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) ### shard A shard contains encoded and compressed data for a specific set of [series](#series). A shard consists of one or more [TSM files](#tsm-time-structured-merge-tree) on disk. All points in a series in a given shard group are stored in the same shard (TSM file) on disk. A shard belongs to a single [shard group](#shard-group). For more information, see [Shards and shard groups (OSS)](/influxdb/v2/reference/internals/shards/). Related entries: [series](#series), [shard group duration](#shard-group-duration),[shard group](#shard-group), [tsm](#tsm-time-structured-merge-tree) ### shard group Shard groups are logical containers for shards organized by [bucket](#bucket). Every bucket with data has at least one shard group. A shard group contains all shards with data for the time interval covered by the shard group. The interval spanned by each shard group is the [shard group duration](#shard-group-duration). For more information, see [Shards and shard groups (OSS)](/influxdb/v2/reference/internals/shards/). Related entries: [bucket](#bucket), [retention period](#retention-period),[series](#series), [shard](#shard), [shard group duration](#shard-group-duration) ### shard group duration The duration of time or interval that each [shard group](#shard-group) covers. Set the `shard-group-duration` for each [bucket](#bucket). For more information, see: * [Shards and shard groups (OSS)](/influxdb/v2/reference/internals/shards/) * [Manage buckets](/influxdb/v2/admin/buckets/) ### Single Stat A visualization that displays the numeric value of the most recent point in a table (or series) returned by a query. ### Snappy compression InfluxDB uses snappy compression to compress batches of points. To improve space and disk IO efficiency, each batch is compressed before being written to disk. ### step-plot A data visualization that displays time series data in a staircase graph. Generate a step-plot using the step [interpolation option for line graphs](/influxdb/v2/visualize-data/visualization-types/graph/#options). ### stream Flux processes streams of data. A stream includes a series of tables over a sequence of time intervals. ### string A data type used to represent text. In [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), columns that contain string values are annotated with the `string` datatype. T ---------- ### TCP InfluxDB uses Transmission Control Protocol (TCP) port 8086 for client-server communication over the InfluxDB HTTP API. ### table Flux processes a series of tables for a specified time series. These tables in sequence result in a stream of data. Related entries: [measurement](#measurement) ### 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; tags are indexed so queries on tags are performant.*Query tip:* Compare tags to fields; fields are not indexed. 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. Tag keys are indexed so queries on tag keys are processed quickly. *Query tip:* Compare tag keys to field keys. Field keys are not indexed. 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), [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. Tag values are indexed so queries on tag values are processed quickly. Related entries: [tag](#tag), [tag key](#tag-key), [tag set](#tag-set) ### task A scheduled Flux query that runs periodically and may store results in a specified measurement. Examples include downsampling and batch jobs. For more information, see [Process Data with InfluxDB tasks](/influxdb/v2/process-data/). Related entries: [function](#function) ### technical preview A new feature released to gather feedback from customers and the InfluxDB community. Send feedback to InfluxData via [Community Slack](https://app.slack.com/client/TH8RGQX5Z) or our [Community Site](https://community.influxdata.com/). ### Telegraf A plugin-driven agent that collects, processes, aggregates, and writes metrics. Related entries: [Automatically configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/), [Manually configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/manual-config/), [Telegraf plugins](/telegraf/v1/plugins//), [Use Telegraf to collect data](/influxdb/v2/write-data/no-code/use-telegraf/), [View a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/view/) ### 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. In InfluxDB, a timestamp is a nanosecond-scale [unix timestamp](#unix-timestamp) in UTC. To specify time when writing data, see [Elements of line protocol](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol). To specify time when querying data, see [Query InfluxDB with Flux](/influxdb/v2/query-data/get-started/query-influxdb/#2-specify-a-time-range). Related entries: [point](#point), [precision](#precision), [RFC3339 timestamp](#rfc3339-timestamp), [unix timestamp](#unix-timestamp), ### token Tokens (or API tokens) verify user and organization permissions in InfluxDB. There are different types of API tokens: * **Operator token:** grants full read and write access to all resources in **all organizations in InfluxDB OSS 2.x**. *InfluxDB Cloud does not support Operator tokens.* * **All Access token:** grants full read and write access to all resources in an organization. * **Read/Write token:** grants read or write access to specific resources in an organization. Related entries: [Create a token](/influxdb/v2/admin/tokens/create-token/). ### tracing By default, tracing is disabled in InfluxDB OSS. To enable tracing or set other InfluxDB OSS configuration options, see [InfluxDB OSS configuration options](/influxdb/v2/reference/config-options/). ### transformation An InfluxQL function that returns a value or a set of values calculated from specified points, but does not return an aggregated value across those points. See [InfluxQL functions](/influxdb/v1/query_language/functions/#transformations) for a complete list of the available and upcoming aggregations. Related entries: [aggregate](#aggregate), [function](#function), [selector](#selector) ### TSI (Time Series Index) TSI uses the operating system’s page cache to pull frequently accessed data into memory and keep infrequently accessed data on disk. ### TSL The Time Series Logs (TSL) extension (`.tsl`) identifies Time Series Index (TSI) log files, generated by the tsi1 engine. ### TSM (Time Structured Merge tree) A data storage format that allows greater compaction and higher write and read throughput than B+ or LSM tree implementations. For more information, see [Storage engine](/influxdb/v1/concepts/storage_engine/). Related entries: [TSI](#tsi-time-series-index) 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. ### universe block An implicit block that encompasses all Flux source text in a universe block. ### 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](/influxdb/v2/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`). In [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), columns that contain integers are annotated with the `unsignedLong` datatype. Related entries: [integer](#integer) ### user InfluxDB users are granted permission to access to InfluxDB. Users are added as a member of an organization and are given a unique API token. 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. In Flux, the variable assignment creates a variable bound to an identifier and gives it a type and value. A variable keeps the same type and value for the remainder of its lifetime. An identifier assigned to a variable in a block cannot be reassigned in the same block. W ---------- ### windowing Grouping data based on specified time intervals. For information about how to window in Flux, see [Window and aggregate data with Flux](/influxdb/v2/query-data/flux/window-aggregate/). [glossary](/influxdb/v2/tags/glossary/) | Data type | Alias/annotation | | --- | --- | | Data type | Alias/annotation | | string | | | boolean | | | float | double | | integer | int, long | | unsigned integer | uint, unsignedLong | | time | dateTime | | 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 | --- # InfluxDB internals Source: https://docs.influxdata.com/influxdb/v2/reference/internals/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ### [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/) An overview of the InfluxDB storage engine architecture. ### [InfluxDB file system layout](/influxdb/v2/reference/internals/file-system-layout/) The InfluxDB file system layout depends on the operating system, package manager, or containerization platform used to install InfluxDB. ### [Data retention in InfluxDB](/influxdb/v2/reference/internals/data-retention/) The InfluxDB retention service checks for and removes data with timestamps beyond the defined retention period of the bucket the data is stored in. ### [InfluxDB runtime](/influxdb/v2/reference/internals/runtime/) Learn how to collect Go runtime profiling and tracing information to help with InfluxDB performance analysis and debugging. ### [InfluxDB shards and shard groups](/influxdb/v2/reference/internals/shards/) Learn the relationships between buckets, shards, and shard groups. InfluxDB organizes time series data into **shards** when storing data to disk. Shards are grouped into **shard groups**. ### [InfluxDB system buckets](/influxdb/v2/reference/internals/system-buckets/) InfluxDB system buckets contain time series data used by and generated from the InfluxDB monitoring and alerting system and the task engine. ### [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/) Get metrics about the workload performance of an InfluxDB OSS instance. --- # Data retention in InfluxDB Source: https://docs.influxdata.com/influxdb/v2/reference/internals/data-retention/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **InfluxDB retention enforcement service** checks for and removes data with timestamps beyond the defined retention period of the[bucket](/influxdb/v2/reference/glossary/#bucket) the data is stored in. This service is designed to automatically delete “expired” data and optimize disk usage without any user intervention. By default, the retention enforcement service runs every 30 minutes. You can configure this interval with the[`storage-retention-check-interval`](/influxdb/v2/reference/config-options/#storage-retention-check-interval)configuration option. * [Bucket retention period](#bucket-retention-period) * [Shard group duration](#shard-group-duration) * [When does data actually get deleted?](#when-does-data-actually-get-deleted) ## Bucket retention period A **bucket retention period** is the [duration](/influxdb/v2/reference/glossary/#duration)of time that a bucket retains data. You can specify the retention period when you [create](/influxdb/v2/admin/buckets/create-bucket/) or [update](/influxdb/v2/admin/buckets/update-bucket/) a bucket. Retention periods can be infinite or as short as an hour.[Points](/influxdb/v2/reference/glossary/#point)in a bucket with timestamps beyond the defined retention period (relative to now) are *eligible* for deletion. ## Shard group duration InfluxDB stores data on disk in [shards](/influxdb/v2/reference/glossary/#shard). Each shard belongs to a shard group and each shard group has a shard group duration. The **shard group duration** defines the duration of time that each shard in the shard group covers. Each shard contains only points with timestamps in a specific time range defined by the shard group duration. By default, shard group durations are set automatically based on the bucket retention period, but can also be explicitly defined when creating or updating a bucket. *For more information, see [InfluxDB shard group duration](/influxdb/v2/reference/internals/shards/#shard-group-duration).* > [!Note] > #### View bucket retention periods and shard group durations > > Use the [`influx bucket list` command](/influxdb/v2/reference/cli/influx/bucket/list/)to view the retention period and shard group duration of buckets in your organization. ## When does data actually get deleted? The InfluxDB retention enforcement service runs at regular intervals and deletes[shard groups](/influxdb/v2/reference/internals/shards/#shard-groups), not individual points. The service will only delete a shard group when the entire time range covered by the shard group is beyond the bucket retention period. > [!Note] > #### Data is queryable until deleted > > Even though data may be older than the specified bucket retention period, > it is queryable until removed by the retention enforcement service. To calculate the possible time data will persist before being deleted: * **minimum**: `bucket-retention-period` * **maximum** `bucket-retention-period + shard-group-duration` For example, if your bucket retention period is three days (`3d`) and your shard group duration is one day (`1d`), the retention enforcement service deletes all shard groups with data that is **three to four days old** the next time the service runs. 4d 3d 2d 1d 0d Shard group Shard Shard group Shard Shard group Shard Shard group Shard Deleted 3d retention period #### Related * [Create a bucket](/influxdb/v2/admin/buckets/create-bucket/) * [InfluxDB shards and shard groups](/influxdb/v2/reference/internals/shards/) * [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/) * [Manage InfluxDB internal systems](/influxdb/v2/admin/internals/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # InfluxDB file system layout Source: https://docs.influxdata.com/influxdb/v2/reference/internals/file-system-layout/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB file system layout depends on the operating system, installation method, or containerization platform used to install InfluxDB. * [InfluxDB file structure](#influxdb-file-structure) * [Engine path](#engine-path) * [Bolt path](#bolt-path) * [SQLite path](#sqlite-path) * [Configs path](#configs-path) * [InfluxDB configuration files](#influxdb-configuration-files) * [File system layout](#file-system-layout) * [Installed as a standalone binary](#installed-as-a-standalone-binary) * [Installed as a package](#installed-as-a-package) * [Docker Hub](#docker-hub) * [Quay.io](#quayio) ## InfluxDB file structure The InfluxDB file structure includes the following: ### Engine path Directory path to the [storage engine](/influxdb/v2/reference/internals/storage-engine/), where InfluxDB stores time series data, includes the following directories: * **data**: Stores time-structured merge tree (TSM) files. For more information about the structure of the `data` directory, see[TSM directories and files layout](#tsm-directories-and-files-layout). * **replicationq**: Store the replication queue for the [InfluxDB replication service](/influxdb/v2/write-data/replication/). * **wal**: Stores write-ahead log (WAL) files. For more information about the structure of the `wal` directory, see[WAL directories and files layout](#wal-directories-and-files-layout). To customize this path, use the [engine-path](/influxdb/v2/reference/config-options/#engine-path)configuration option. ### Bolt path File path to the [Boltdb](https://github.com/boltdb/bolt) database, a file-based key-value store for non-time series data, such as InfluxDB users, dashboards, and tasks. To customize this path, use the [bolt-path](/influxdb/v2/reference/config-options/#bolt-path)configuration option. ### SQLite path File path to the [SQLite](https://www.sqlite.org/) database, an SQL database for non-time series data, such as InfluxDB notebooks and annotations. To customize this path, use the [sqlite-path](/influxdb/v2/reference/config-options/#sqlite-path) configuration option. ### Configs path File path to [`influx` CLI connection configurations](/influxdb/v2/reference/cli/influx/config/) (configs). To use a custom path, pass the `--configs-path` flag with `influx` CLI commands. ### InfluxDB configuration files Some operating systems and package managers store a default InfluxDB (`influxd`) configuration file on disk. For more information about using InfluxDB configuration files, see[Configuration options](/influxdb/v2/reference/config-options/). ## File system layout [macOS](#macos)[Linux](#linux)[Windows](#windows)[Docker](#docker)[Kubernetes](#kubernetes) #### macOS default paths | Path | Default | |-----------------------------|------------------------------| | [Engine path](#engine-path) | `~/.influxdbv2/engine/` | | [Bolt path](#bolt-path) | `~/.influxdbv2/influxd.bolt` | | [SQLite path](#sqlite-path) |`~/.influxdbv2/influxd.sqlite`| |[Configs path](#configs-path)| `~/.influxdbv2/configs` | #### macOS file system overview * \~/.influxdbv2/ * engine/ * data/ * *TSM directories and files* * wal/ * *WAL directories and files* * configs * influxd.bolt * influxd.sqlite When installing InfluxDB on Linux, you can download and install the `influxd` binary, or you can use a package manager. Which installation method you use determines the file system layout. * [InfluxDB file structure](#influxdb-file-structure) * [File system layout](#file-system-layout) * [Installed as a standalone binary](#installed-as-a-standalone-binary) * [Installed as a package](#installed-as-a-package) * [Docker Hub](#docker-hub) * [Quay.io](#quayio) ### Installed as a standalone binary #### Linux default paths (standalone binary) | Path | Default | |-----------------------------|------------------------------| | [Engine path](#engine-path) | `~/.influxdbv2/engine/` | | [Bolt path](#bolt-path) | `~/.influxdbv2/influxd.bolt` | | [SQLite path](#sqlite-path) |`~/.influxdbv2/influxd.sqlite`| |[Configs path](#configs-path)| `~/.influxdbv2/configs` | #### Linux file system overview (standalone binary) * \~/.influxdbv2/ * engine/ * data/ * *TSM directories and files* * wal/ * *WAL directories and files* * configs * influxd.bolt * influxd.sqlite ### Installed as a package InfluxDB 2.10 supports **.deb-** and **.rpm-based** Linux package managers. The file system layout is the same with each. #### Linux default paths (package) | Path | Default | |---------------------------------------------------------|----------------------------------| | [Engine path](#engine-path) | `/var/lib/influxdb/engine/` | | [Bolt path](#bolt-path) | `/var/lib/influxdb/influxd.bolt` | | [SQLite path](#sqlite-path) |`/var/lib/influxdb/influxd.sqlite`| | [Configs path](#configs-path) | `/var/lib/influxdb/configs` | |[Default config file path](#influxdb-configuration-files)| `/etc/influxdb/config.toml` | #### Linux file system overview (package) * /var/lib/influxdb/ * engine/ * data/ * *TSM directories and files* * wal/ * *WAL directories and files* * configs * influxd.bolt * influxd.sqlite * /etc/influxdb/ * config.toml *(influxd configuration file)* #### Windows default paths | Path | Default | |-----------------------------|------------------------------------------| | [Engine path](#engine-path) | `%USERPROFILE%\.influxdbv2\engine\` | | [Bolt path](#bolt-path) | `%USERPROFILE%\.influxdbv2\influxd.bolt` | | [SQLite path](#sqlite-path) |`%USERPROFILE%\.influxdbv2\influxd.sqlite`| |[Configs path](#configs-path)| `%USERPROFILE%\.influxdbv2\configs` | #### Windows file system overview * %USERPROFILE%\\.influxdbv2\\ * engine\\ * data\\ * *TSM directories and files* * wal\\ * *WAL directories and files* * configs * influxd.bolt * influxd.sqlite InfluxDB Docker images are available from both [Docker Hub](https://hub.docker.com/_/influxdb)and [Quay.io](https://quay.io/repository/influxdb/influxdb?tab=tags). Each has a unique InfluxDB file system layout. * [Docker Hub](#docker-hub) * [Quay.io](#quayio) ### Docker Hub > [!Note] > For InfluxDB v2, the InfluxDB Docker Hub image uses `/var/lib/influxdb2` instead of `/var/lib/influxdb`so you can easily mount separate volumes for InfluxDB 1.x and 2.x data during the[upgrade process](/influxdb/v2/upgrade/v1-to-v2/docker/). #### Docker Hub default paths | Path | Default | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Engine path](#engine-path) | `/var/lib/influxdb2/engine/` | | [Bolt path](#bolt-path) | `/var/lib/influxdb2/influxd.bolt` | | [SQLite path](#sqlite-path) | `/var/lib/influxdb2/influxd.sqlite` | |[Configs path](#configs-path)|`/etc/influxdb2/influx-configs` if InfluxDB is set up using automated `setup` mode or `influx setup` from within the container; `/etc/influxdb2/configs` otherwise.| #### Docker Hub file system overview * /var/lib/influxdb2/ * engine/ * data/ * *TSM directories and files* * wal/ * *WAL directories and files* * influxd.bolt * influxd.sqlite * /etc/influxdb2/ * configs * influx-configs ### Quay.io #### Quay default paths | Path | Default | |-----------------------------|----------------------------------| | [Engine path](#engine-path) | `/root/.influxdbv2/engine/` | | [Bolt path](#bolt-path) | `/root/.influxdbv2/influxd.bolt` | | [SQLite path](#sqlite-path) |`/root/.influxdbv2/influxd.sqlite`| |[Configs path](#configs-path)| `/root/.influxdbv2/configs` | #### Quay file system overview * /root/.influxdbv2/ * engine/ * data/ * *TSM directories and files* * wal/ * *WAL directories and files* * configs * influxd.bolt * influxd.sqlite #### Kubernetes default paths | Path | Default | |-----------------------------|-----------------------------------| | [Engine path](#engine-path) | `/var/lib/influxdb2/engine/` | | [Bolt path](#bolt-path) | `/var/lib/influxdb2/influxd.bolt` | | [SQLite path](#sqlite-path) |`/var/lib/influxdb2/influxd.sqlite`| |[Configs path](#configs-path)| `/etc/influxdb2/configs` | #### Kubernetes file system overview * /var/lib/influxdb2/ * engine/ * data/ * *TSM directories and files*[+](#tsm-directories-and-files-layout) * wal/ * *WAL directories and files* * influxd.bolt * influxd.sqlite * /etc/influxdb2/ * configs #### TSM directories and files layout TSM directories and files are stored in the `data` directory inside the [engine path](#engine-path). The diagram below is **relative to the [engine path](#file-system-layout)**. * …/data/ * 000xX00xxXx000x0/ *(bucket ID)* * \_series/ *(series directory)* * 00/ *(internal shard index)* * 0000 *(internal shard index file)* * autogen * 0123/ *(shard ID)* * index *(index directory)* * L0-00000001.tsl *(write-ahead log for the TSI index)* * L0-00000001.tsi *(series index)* * MANIFEST *(index manifest)* #### WAL directories and files layout WAL directories and files are stored in the `data` directory inside the [engine path](#engine-path). The diagram below is **relative to the [engine path](#file-system-layout)**. * …/wal/ * 000xX00xxXx000x0/ *(bucket ID)* * autogen/ * 0123/ *(shard ID)* * \_01234.wal *(WAL file)* #### Related * [Manage InfluxDB internal systems](/influxdb/v2/admin/internals/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) | Path | Default | | --- | --- | | Path | Default | | Engine path | ~/.influxdbv2/engine/ | | Bolt path | ~/.influxdbv2/influxd.bolt | | SQLite path | ~/.influxdbv2/influxd.sqlite | | Configs path | ~/.influxdbv2/configs | | Path | Default | | --- | --- | | Path | Default | | Engine path | ~/.influxdbv2/engine/ | | Bolt path | ~/.influxdbv2/influxd.bolt | | SQLite path | ~/.influxdbv2/influxd.sqlite | | Configs path | ~/.influxdbv2/configs | | Path | Default | | --- | --- | | Path | Default | | Engine path | /var/lib/influxdb/engine/ | | Bolt path | /var/lib/influxdb/influxd.bolt | | SQLite path | /var/lib/influxdb/influxd.sqlite | | Configs path | /var/lib/influxdb/configs | | Default config file path | /etc/influxdb/config.toml | | Path | Default | | --- | --- | | Path | Default | | Engine path | %USERPROFILE%\.influxdbv2\engine\ | | Bolt path | %USERPROFILE%\.influxdbv2\influxd.bolt | | SQLite path | %USERPROFILE%\.influxdbv2\influxd.sqlite | | Configs path | %USERPROFILE%\.influxdbv2\configs | | Path | Default | | --- | --- | | Path | Default | | Engine path | /var/lib/influxdb2/engine/ | | Bolt path | /var/lib/influxdb2/influxd.bolt | | SQLite path | /var/lib/influxdb2/influxd.sqlite | | Configs path | /etc/influxdb2/influx-configs if InfluxDB is set up using automated setup mode or influx setup from within the container; /etc/influxdb2/configs otherwise. | | Path | Default | | --- | --- | | Path | Default | | Engine path | /root/.influxdbv2/engine/ | | Bolt path | /root/.influxdbv2/influxd.bolt | | SQLite path | /root/.influxdbv2/influxd.sqlite | | Configs path | /root/.influxdbv2/configs | | Path | Default | | --- | --- | | Path | Default | | Engine path | /var/lib/influxdb2/engine/ | | Bolt path | /var/lib/influxdb2/influxd.bolt | | SQLite path | /var/lib/influxdb2/influxd.sqlite | | Configs path | /etc/influxdb2/configs | --- # InfluxDB OSS metrics Source: https://docs.influxdata.com/influxdb/v2/reference/internals/metrics/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Get metrics about the workload performance of an InfluxDB OSS instance. InfluxDB OSS exposes a `/metrics` endpoint that returns performance, resource, and usage metrics formatted in the [Prometheus plain-text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats). ``` GET http://localhost:8086/metrics ``` Metrics contain a name, an optional set of key-value pairs, and a value. The following descriptors precede each metric: * `HELP`: description of the metric * `TYPE`: [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, `gauge`, `histogram`, or `summary`) #### Example ```text # HELP go_info Information about the Go environment. # TYPE go_info gauge go_info{version="go1.17"} 1 # HELP go_memstats_alloc_bytes Number of bytes allocated and still in use. # TYPE go_memstats_alloc_bytes gauge go_memstats_alloc_bytes 2.27988488e+08 # HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. # TYPE go_memstats_alloc_bytes_total counter go_memstats_alloc_bytes_total 9.68016566648e+11 ``` The InfluxDB `/metrics` endpoint returns metrics associated with the following categories: * [Boltdb](#boltdb-statistics) * [Go runtime](#go-runtime-statistics) * [HTTP API](#http-api-statistics) * [InfluxDB objects and queries](#influxdb-object-and-query-statistics) * [QC (query controller)](#qc-query-controller-statistics) * [InfluxDB services](#influxdb-service-statistics) * [InfluxDB storage](#influxdb-storage-statistics) * [InfluxDB tasks](#influxdb-task-statistics) ## Boltdb statistics ### Reads total Total number of boltdb reads. #### Example ```text # HELP boltdb_reads_total Total number of boltdb reads # TYPE boltdb_reads_total counter boltdb_reads_total 75129 ``` ### Writes total Total number of boltdb writes. #### Example ```text # HELP boltdb_writes_total Total number of boltdb writes # TYPE boltdb_writes_total counter boltdb_writes_total 201591 ``` ## Go runtime statistics For more detail about Go runtime statistics, see the following: * [Go diagostics documentation](https://go.dev/doc/diagnostics) * [Go mstats](https://github.com/golang/go/blob/master/src/runtime/mstats.go) ### GC (garbage collection) duration seconds Summary of the pause duration of garbage collection cycles. #### Example ``` # HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles. # TYPE go_gc_duration_seconds summary ## go_gc_duration_seconds{quantile="0"} 5.1467e-05 ``` ### Goroutines Number of goroutines that currently exist. #### Example ```text # HELP go_goroutines Number of goroutines that currently exist. # TYPE go_goroutines gauge go_goroutines 1566 ``` ### Info Information about the Go environment. #### Example ```text # HELP go_info Information about the Go environment. # TYPE go_info gauge go_info{version="go1.17"} 1 ``` ### Memory allocated bytes Number of bytes allocated and still in use. #### Example ```text # HELP go_memstats_alloc_bytes Number of bytes allocated and still in use. # TYPE go_memstats_alloc_bytes gauge go_memstats_alloc_bytes 2.27988488e+08 ``` ### Memory allocated bytes total Total number of bytes allocated, even if freed. #### Example ```text # HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. # TYPE go_memstats_alloc_bytes_total counter go_memstats_alloc_bytes_total 9.68016566648e+11 ``` ### Memory bucket hash system bytes Number of bytes used by the profiling bucket hash table. #### Example ```text # HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. # TYPE go_memstats_buck_hash_sys_bytes gauge go_memstats_buck_hash_sys_bytes 1.0067613e+07 ``` ### Memory frees total Total number of frees. #### Example ```text # HELP go_memstats_frees_total Total number of frees. # TYPE go_memstats_frees_total counter go_memstats_frees_total 1.3774541795e+10 ``` ### Memory GC (garbage collection) CPU fraction Fraction of this program’s available CPU time used by the GC since the program started. #### Example ```text # HELP go_memstats_gc_cpu_fraction The fraction of this program's available CPU time used by the GC since the program started. # TYPE go_memstats_gc_cpu_fraction gauge go_memstats_gc_cpu_fraction 0.011634918451016558 ``` ### Memory GC (garbage collection) system bytes Number of bytes used for garbage collection system metadata. #### Example ```text # HELP go_memstats_gc_sys_bytes Number of bytes used for garbage collection system metadata. # TYPE go_memstats_gc_sys_bytes gauge go_memstats_gc_sys_bytes 4.63048016e+08 ``` ### Memory heap allocated bytes Number of heap bytes allocated and still in use. #### Example ```text # HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and still in use. # TYPE go_memstats_heap_alloc_bytes gauge go_memstats_heap_alloc_bytes 2.27988488e+08 ``` ### Memory heap idle bytes Number of heap bytes waiting to be used. #### Example ```text # HELP go_memstats_heap_idle_bytes Number of heap bytes waiting to be used. # TYPE go_memstats_heap_idle_bytes gauge go_memstats_heap_idle_bytes 1.0918273024e+10 ``` ### Memory heap in use bytes Number of heap bytes that are in use. #### Example ```text # HELP go_memstats_heap_inuse_bytes Number of heap bytes that are in use. # TYPE go_memstats_heap_inuse_bytes gauge go_memstats_heap_inuse_bytes 3.5975168e+08 ``` ### Memory heap objects Number of allocated objects.*Allocated* heap objects include all reachable objects, as well as unreachable objects that the garbage collector has not yet freed. #### Example ```text # HELP go_memstats_heap_objects Number of allocated objects. # TYPE go_memstats_heap_objects gauge go_memstats_heap_objects 2.404017e+06 ``` ### Memory heap released bytes Number of heap bytes released to the OS. #### Example ```text # HELP go_memstats_heap_released_bytes Number of heap bytes released to OS. # TYPE go_memstats_heap_released_bytes gauge go_memstats_heap_released_bytes 2.095038464e+09 ``` ### Memory heap system bytes Number of heap bytes obtained from the system. #### Example ```text # HELP go_memstats_heap_sys_bytes Number of heap bytes obtained from system. # TYPE go_memstats_heap_sys_bytes gauge go_memstats_heap_sys_bytes 1.1278024704e+10 ``` ### Memory last GC (garbage collection) time seconds Number of seconds since 1970 of the last garbage collection. #### Example ```text # HELP go_memstats_last_gc_time_seconds Number of seconds since 1970 of last garbage collection. # TYPE go_memstats_last_gc_time_seconds gauge go_memstats_last_gc_time_seconds 1.64217120199452e+09 ``` ### Memory lookups total Total number of pointer lookups. #### Example ```text # HELP go_memstats_lookups_total Total number of pointer lookups. # TYPE go_memstats_lookups_total counter go_memstats_lookups_total 0 ``` ### Memory allocations total Cumulative count of heap objects allocated. #### Example ```text # HELP go_memstats_mallocs_total Total number of mallocs. # TYPE go_memstats_mallocs_total counter go_memstats_mallocs_total 1.3776945812e+10 ``` ### Memory mcache in use bytes Number of bytes in use by mcache structures. #### Example ```text # HELP go_memstats_mcache_inuse_bytes Number of bytes in use by mcache structures. # TYPE go_memstats_mcache_inuse_bytes gauge go_memstats_mcache_inuse_bytes 9600 ``` ### Memory mcache system bytes Number of bytes used for mcache structures obtained from system. #### Example ```text # HELP go_memstats_mcache_sys_bytes Number of bytes used for mcache structures obtained from system. # TYPE go_memstats_mcache_sys_bytes gauge go_memstats_mcache_sys_bytes 16384 ``` ### Memory mspan in use bytes Number of bytes of allocated mspan structures. #### Example ```text # HELP go_memstats_mspan_inuse_bytes Number of bytes in use by mspan structures. # TYPE go_memstats_mspan_inuse_bytes gauge go_memstats_mspan_inuse_bytes 4.199e+06 ``` ### Memory mspan system bytes Bytes of memory obtained from the OS for mspan structures. #### Example ```text # HELP go_memstats_mspan_sys_bytes Number of bytes used for mspan structures obtained from system. # TYPE go_memstats_mspan_sys_bytes gauge go_memstats_mspan_sys_bytes 1.65609472e+08 ``` ### Memory next GC (garbage collection) bytes Number of heap bytes when next garbage collection will take place. #### Example ```text # HELP go_memstats_next_gc_bytes Number of heap bytes when next garbage collection will take place. # TYPE go_memstats_next_gc_bytes gauge go_memstats_next_gc_bytes 4.45628016e+08 ``` ### Memory other system bytes Number of bytes used for other system allocations. #### Example ```text # HELP go_memstats_other_sys_bytes Number of bytes used for other system allocations. # TYPE go_memstats_other_sys_bytes gauge go_memstats_other_sys_bytes 8.1917722e+07 ``` ### Memory stack in use bytes Number of bytes in use by the stack allocator. #### Example ```text # HELP go_memstats_stack_inuse_bytes Number of bytes in use by the stack allocator. # TYPE go_memstats_stack_inuse_bytes gauge go_memstats_stack_inuse_bytes 8.84736e+06 ``` ### Memory stack system bytes Number of bytes obtained from system for stack allocator. #### Example ```text # HELP go_memstats_stack_sys_bytes Number of bytes obtained from system for stack allocator. # TYPE go_memstats_stack_sys_bytes gauge go_memstats_stack_sys_bytes 8.84736e+06 ``` ### Memory system bytes Number of bytes obtained from system. #### Example ```text # HELP go_memstats_sys_bytes Number of bytes obtained from system. # TYPE go_memstats_sys_bytes gauge go_memstats_sys_bytes 1.2007531271e+10 ``` ### Threads Number of OS threads created. #### Example ```text # HELP go_threads Number of OS threads created. # TYPE go_threads gauge go_threads 27 ``` ## HTTP API statistics ### API request duration seconds How long InfluxDB took to respond to the HTTP request. #### Example ``` # HELP http_api_request_duration_seconds Time taken to respond to HTTP request # TYPE http_api_request_duration_seconds histogram ## http_api_request_duration_seconds_bucket{handler="platform",method="DELETE",path="/api/v2/authorizations/:id",response_code="204",status="2XX",user_agent="Chrome",le="0.005"} 0 ``` ### API requests total Number of HTTP requests received. #### Example ``` # HELP http_api_requests_total Number of http requests received # TYPE http_api_requests_total counter ## http_api_requests_total{handler="platform",method="DELETE",path="/api/v2/authorizations/:id",response_code="204",status="2XX",user_agent="Chrome"} 1 ``` ### Query request bytes Count of bytes received. In InfluxDB OSS v2.10 and later, the `http_query_request_count`, `http_query_request_bytes`, and `http_query_response_bytes` metrics include the legacy `/query` endpoint. #### Example ```text # HELP http_query_request_bytes Count of bytes received # TYPE http_query_request_bytes counter http_query_request_bytes{endpoint="/api/v2/query",org_id="48c88459ee424a04",status="200"} 727 ``` ### Query request count Total number of query requests. #### Example ```text # HELP http_query_request_count Total number of query requests # TYPE http_query_request_count counter http_query_request_count{endpoint="/api/v2/query",org_id="48c88459ee424a04",status="200"} 2 ``` ### Query response bytes Count of bytes returned by the query endpoint. #### Example ```text # HELP http_query_response_bytes Count of bytes returned # TYPE http_query_response_bytes counter http_query_response_bytes{endpoint="/api/v2/query",org_id="48c88459ee424a04",status="200"} 103 ``` ### Query user response bytes Available in InfluxDB OSS v2.10 and later. The `http_query_user_response_bytes` counter: total number of bytes returned in query responses, by user and endpoint. InfluxDB exposes this counter only when you enable [`http-user-query-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled). Labels: `user_id`, `endpoint` ### Write user request bytes Available in InfluxDB OSS v2.10 and later. The `http_write_user_request_bytes` counter: total number of bytes in write requests, by user and endpoint. InfluxDB exposes this counter only when you enable [`http-user-write-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled). InfluxDB doesn’t count requests that don’t have a valid user ID. Labels: `user_id`, `endpoint` ## InfluxDB object and query statistics ### Buckets total Total number of buckets on the server. #### Example ```text # HELP influxdb_buckets_total Number of total buckets on the server # TYPE influxdb_buckets_total counter influxdb_buckets_total 9 ``` ### Dashboards total Total number of dashboards on the server. #### Example ```text # HELP influxdb_dashboards_total Number of total dashboards on the server # TYPE influxdb_dashboards_total counter influxdb_dashboards_total 2 ``` ### Info Information about the InfluxDB environment. #### Example ```text # HELP influxdb_info Information about the influxdb environment. # TYPE influxdb_info gauge influxdb_info{arch="amd64",build_date="2021-12-28T22:12:40Z",commit="657e1839de",cpus="8",os="darwin",version="v2.1.1"} 1 ``` ### Organizations total Total number of organizations on the server. #### Example ```text # HELP influxdb_organizations_total Number of total organizations on the server # TYPE influxdb_organizations_total counter influxdb_organizations_total 2 ``` ### Replications total Total number of replication configurations on the server #### Example ```text # HELP influxdb_replications_total Number of total replication configurations on the server # TYPE influxdb_replications_total counter influxdb_replications_total 1 ``` ### Scrapers total Total number of scrapers on the server. #### Example ```text # HELP influxdb_scrapers_total Number of total scrapers on the server # TYPE influxdb_scrapers_total counter influxdb_scrapers_total 0 ``` ### Telegrafs total Total number of Telegraf configurations on the server. #### Example ```text # HELP influxdb_telegrafs_total Number of total telegraf configurations on the server # TYPE influxdb_telegrafs_total counter influxdb_telegrafs_total 0 ``` ### Token services total Total number of API tokens on the server. #### Example ```text # HELP influxdb_tokens_total Number of total tokens on the server # TYPE influxdb_tokens_total counter influxdb_tokens_total 23 ``` ### Uptime seconds InfluxDB process uptime in seconds. #### Example ```text # HELP influxdb_uptime_seconds influxdb process uptime in seconds # TYPE influxdb_uptime_seconds gauge influxdb_uptime_seconds{id="077238f9ca108000"} 343354.914499305 ``` ### Users total Total number of users on the server. #### Example ```text # HELP influxdb_users_total Number of total users on the server # TYPE influxdb_users_total counter influxdb_users_total 84 ``` ## QC (query controller) statistics ### All active Number of queries in all states. #### Example ``` # HELP qc_all_active Number of queries in all states # TYPE qc_all_active gauge ## qc_all_active{org="48c88459ee424a04"} 0 ``` ### All duration seconds Total time spent in all query states. #### Example ``` # HELP qc_all_duration_seconds Histogram of total times spent in all query states # TYPE qc_all_duration_seconds histogram ## qc_all_duration_seconds_bucket{org="48c88459ee424a04",le="0.001"} 0 ``` ### Compiling active Number of queries actively compiling. #### Example ``` # HELP qc_compiling_active Number of queries actively compiling # TYPE qc_compiling_active gauge ## qc_compiling_active{compiler_type="ast",org="ed32b47572a0137b"} 0 ``` ### Compiling duration seconds Histogram of times spent compiling queries. #### Example ``` # HELP qc_compiling_duration_seconds Histogram of times spent compiling queries # TYPE qc_compiling_duration_seconds histogram ## qc_compiling_duration_seconds_bucket{compiler_type="ast",org="ed32b47572a0137b",le="0.001"} 999 ``` ### Executing active Number of queries actively executing. #### Example ``` # HELP qc_executing_active Number of queries actively executing # TYPE qc_executing_active gauge ## qc_executing_active{org="48c88459ee424a04"} 0 ``` ### Executing duration seconds Histogram of times spent executing queries. #### Example ``` # HELP qc_executing_duration_seconds Histogram of times spent executing queries # TYPE qc_executing_duration_seconds histogram ## qc_executing_duration_seconds_bucket{org="48c88459ee424a04",le="0.001"} 0 ``` ### Memory unused bytes Free memory as seen by the internal memory manager. #### Example ``` # HELP qc_memory_unused_bytes The free memory as seen by the internal memory manager # TYPE qc_memory_unused_bytes gauge ## qc_memory_unused_bytes{org="48c88459ee424a04"} 0 ``` ### Queueing active Number of queries actively queueing. #### Example ``` # HELP qc_queueing_active Number of queries actively queueing # TYPE qc_queueing_active gauge ## qc_queueing_active{org="48c88459ee424a04"} 0 ``` ### Queueing duration seconds Histogram of times spent queueing queries. #### Example ``` # HELP qc_queueing_duration_seconds Histogram of times spent queueing queries # TYPE qc_queueing_duration_seconds histogram ## qc_queueing_duration_seconds_bucket{org="48c88459ee424a04",le="0.001"} 2 ``` ### Requests total Count of the query requests. #### Example ``` # HELP qc_requests_total Count of the query requests # TYPE qc_requests_total counter ## qc_requests_total{org="48c88459ee424a04",result="success"} 2 ``` ### Read request duration Histogram of times spent in read requests. #### Example ``` # HELP query_influxdb_source_read_request_duration_seconds Histogram of times spent in read requests # TYPE query_influxdb_source_read_request_duration_seconds histogram ## query_influxdb_source_read_request_duration_seconds_bucket{op="readTagKeys",org="48c88459ee424a04",le="0.001"} 0 ``` ## InfluxDB service statistics ### Bucket service new call total Number of calls to the bucket creation service. #### Example ``` # HELP service_bucket_new_call_total Number of calls # TYPE service_bucket_new_call_total counter ## service_bucket_new_call_total{method="find_bucket"} 6177 ``` ### Bucket service new duration Duration of calls to the bucket creation service. #### Example ``` # HELP service_bucket_new_duration Duration of calls # TYPE service_bucket_new_duration histogram ## service_bucket_new_duration_bucket{method="find_bucket",le="0.005"} 5876 ``` ### Bucket service new error total Number of errors encountered by the bucket creation service. #### Example ```text # HELP service_bucket_new_error_total Number of errors encountered # TYPE service_bucket_new_error_total counter service_bucket_new_error_total{code="not found",method="find_bucket_by_id"} 76 ``` ### Onboard service new call total Number of calls to the onboarding service. #### Example ```text # HELP service_onboard_new_call_total Number of calls # TYPE service_onboard_new_call_total counter service_onboard_new_call_total{method="is_onboarding"} 11 ``` ### Onboard service new duration Duration of calls to the onboarding service. #### Example ``` # HELP service_onboard_new_duration Duration of calls # TYPE service_onboard_new_duration histogram ## service_onboard_new_duration_bucket{method="is_onboarding",le="0.005"} 11 ``` ### Organization service call total Number of calls to the organization service. #### Example ```text # HELP service_org_call_total Number of calls # TYPE service_org_call_total counter service_org_call_total{method="find_labels_for_resource"} 10 ``` ### Organization service duration Duration of calls to the organization service. #### Example ``` # HELP service_org_duration Duration of calls # TYPE service_org_duration histogram ## service_org_duration_bucket{method="find_labels_for_resource",le="0.005"} 10 ``` ### Organization service new call total Number of calls to the organization creation service. #### Example ``` # HELP service_org_new_call_total Number of calls # TYPE service_org_new_call_total counter ## service_org_new_call_total{method="find_org"} 1572 ``` ### Organization service new duration Duration of calls to the organization creation service. #### Example ``` # HELP service_org_new_duration Duration of calls # TYPE service_org_new_duration histogram ## service_org_new_duration_bucket{method="find_org",le="0.005"} 1475 ``` ### Organization service new error total Number of errors encountered by the organization creation service. #### Example ```text # HELP service_org_new_error_total Number of errors encountered # TYPE service_org_new_error_total counter service_org_new_error_total{code="not found",method="find_orgs"} 1 ``` ### Password service new call total Number of calls to the password creation service. #### Example ```text # HELP service_password_new_call_total Number of calls # TYPE service_password_new_call_total counter service_password_new_call_total{method="compare_password"} 4 ``` ### Password service new duration Duration of calls to the password creation service. #### Example ``` # HELP service_password_new_duration Duration of calls # TYPE service_password_new_duration histogram ## service_password_new_duration_bucket{method="compare_password",le="0.005"} 0 ``` ### Password service new error total Number of errors encountered by the password creation service. #### Example ```text # HELP service_password_new_error_total Number of errors encountered # TYPE service_password_new_error_total counter service_password_new_error_total{code="forbidden",method="compare_password"} 1 ``` ### Pkger service call total Number of calls to the `pkger` service. #### Example ```text # HELP service_pkger_call_total Number of calls # TYPE service_pkger_call_total counter service_pkger_call_total{method="export"} 3 ``` ### Pkger service duration Duration of calls to the `pkger` service. #### Example ``` # HELP service_pkger_duration Duration of calls # TYPE service_pkger_duration histogram ## service_pkger_duration_bucket{method="export",le="0.005"} 0 ``` ### Pkger service template export Metrics for exported resources. #### Example ```text # HELP service_pkger_template_export Metrics for resources being exported # TYPE service_pkger_template_export counter service_pkger_template_export{buckets="0",by_stack="false",checks="0",dashboards="0",endpoints="0",label_mappings="0",labels="0",method="export",num_org_ids="1",rules="0",tasks="0",telegraf_configs="0",variables="0"} 3 ``` ### Replication service call total Number of calls to the replication service. #### Example ```text # HELP service_replication_call_total Number of calls # TYPE service_replication_call_total counter service_replication_call_total{method="find_replications"} 1 ``` ### Replication service call duration Duration of calls to the replication service. #### Example ```text # HELP service_replication_duration Duration of calls # TYPE service_replication_duration histogram service_replication_duration_bucket{method="create_replication",le="0.005"} 0 service_replication_duration_bucket{method="find_replications",le="0.005"} 1 ``` ### Replication queue total points queued Sum of all points that have been successfully added to the replication stream queue. #### Example ```text # HELP replications_queue_total_points_queued Sum of all points # TYPE replications_queue_total_points_queued Counter replications_queue_total_points_queued ``` ### Replications queue total bytes queued Sum of all bytes that have been successfully added to the replication stream queue. #### Example ```text # HELP replications_queue_total_bytes_queued Sum of all bytes that have been successfully added to the replication stream queue # TYPE replications_queue_total_bytes_queued counter replications_queue_total_bytes_queued{replicationID="0cd2cd54e9fe9000"} 289 ``` ### Replications queue current bytes queued Current number of bytes in the replication stream queue remaining to be processed. #### Example ```text # HELP replications_queue_current_bytes_queued Current number of bytes in the replication stream queue remaining to be processed # TYPE replications_queue_current_bytes_queued gauge replications_queue_current_bytes_queued{replicationID="0cd2cd54e9fe9000"} 297 ``` ### Replications queue remote write errors Error codes returned from attempted remote writes. #### Example ```text # HELP replications_queue_remote_write_errors Error codes returned from attempted remote writes # TYPE replications_queue_remote_write_errors counter replications_queue_remote_write_errors{code="404",replicationID="0cd2cd54e9fe9000"} 11 ``` ### Replications queue remote write bytes sent Bytes of data successfully sent to the remote by the replication stream. #### Example ```text # HELP replications_queue_remote_write_bytes_sent Bytes of data successfully sent to the remote by the replication stream # TYPE replications_queue_remote_write_bytes_sent counter replications_queue_remote_write_bytes_sent{...} ``` ### Replications queue Bytes of data dropped due to remote write failures. #### Example ```text # HELP replications_queue_remote_write_bytes_dropped Bytes of data dropped due to remote write failures # TYPE replications_queue_remote_write_bytes_dropped counter replications_queue_remote_write_bytes_dropped{...} ``` ### Replications queue Sum of all points that could not be added to the local replication queue. #### Example ```text # HELP replications_queue_points_failed_to_queue # TYPE replications_queue_points_failed_to_queue replications_queue_points_failed_to_queue{...} ``` ### Replications queue Sum of all bytes that could not be added to the local replication queue. #### Example ```text # HELP replications_queue_bytes_failed_to_queue Sum of all bytes that could not be added to the local replication queue # TYPE replications_queue_bytes_failed_to_queue counter replications_queue_bytes_failed_to_queue{...} ``` ### Session service call total Number of calls to the session service. #### Example ``` # HELP service_session_call_total Number of calls # TYPE service_session_call_total counter ## service_session_call_total{method="create_session"} 3 ``` ### Session service duration Duration of calls to the session service. #### Example ``` # HELP service_session_duration Duration of calls # TYPE service_session_duration histogram ## service_session_duration_bucket{method="create_session",le="0.005"} 3 ``` ### Session service error total Number of errors encountered by the session service. #### Example ```text # HELP service_session_error_total Number of errors encountered # TYPE service_session_error_total counter service_session_error_total{code="not found",method="find_session"} 4 ``` ### Token service call total Number of calls to the token service. #### Example ``` # HELP service_token_call_total Number of calls # TYPE service_token_call_total counter ## service_token_call_total{method="delete_authorization"} 3 ``` ### Token service duration Duration of calls to the token service. #### Example ``` # HELP service_token_duration Duration of calls # TYPE service_token_duration histogram ## service_token_duration_bucket{method="delete_authorization",le="0.005"} 1 ``` ### Token service error total Number of errors encountered by the token service. #### Example ```text # HELP service_token_error_total Number of errors encountered # TYPE service_token_error_total counter service_token_error_total{code="not found",method="delete_authorization"} 1 ``` ### URM new call total Number of calls to the URM (unified resource management) creation service. #### Example ```text # HELP service_urm_new_call_total Number of calls # TYPE service_urm_new_call_total counter service_urm_new_call_total{method="find_urms"} 6451 ``` ### urm new duration Duration of calls to the URM creation service. #### Example ``` # HELP service_urm_new_duration Duration of calls # TYPE service_urm_new_duration histogram ## service_urm_new_duration_bucket{method="find_urms",le="0.005"} 6198 ``` ### User new call total Number of calls to the user creation service. #### Example ``` # HELP service_user_new_call_total Number of calls # TYPE service_user_new_call_total counter ## service_user_new_call_total{method="find_permission_for_user"} 4806 ``` ### User new duration Duration of calls to the user creation service. #### Example ``` # HELP service_user_new_duration Duration of calls # TYPE service_user_new_duration histogram ## service_user_new_duration_bucket{method="find_permission_for_user",le="0.005"} 4039 ``` ## InfluxDB storage statistics To learn how InfluxDB writes, stores, and caches data, see [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/). ### Bucket measurement number Number of measurements in a bucket. #### Example ``` # HELP storage_bucket_measurement_num Gauge of measurement cardinality per bucket # TYPE storage_bucket_measurement_num gauge ## storage_bucket_measurement_num{bucket="0c3dd7d2d97f4b23"} 4 ``` ### Bucket series number Number of series in a bucket. #### Example ``` # HELP storage_bucket_series_num Gauge of series cardinality per bucket # TYPE storage_bucket_series_num gauge ## storage_bucket_series_num{bucket="0c3dd7d2d97f4b23"} 38 ``` ### Cache disk bytes Size (in bytes) of the most recent [snapshot](/influxdb/v2/reference/internals/storage-engine/#cache). #### Example ``` # HELP storage_cache_disk_bytes Gauge of size of most recent snapshot # TYPE storage_cache_disk_bytes gauge ## storage_cache_disk_bytes{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Cache in use bytes Current memory consumption (in bytes) of the [cache](/influxdb/v2/reference/internals/storage-engine/#cache). #### Example ``` # HELP storage_cache_inuse_bytes Gauge of current memory consumption of cache # TYPE storage_cache_inuse_bytes gauge ## storage_cache_inuse_bytes{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Cache latest snapshot [Unix time](/influxdb/v2/reference/glossary/#unix-timestamp) of the most recent [snapshot](/influxdb/v2/reference/internals/storage-engine/#cache). #### Example ``` # HELP storage_cache_latest_snapshot Unix time of most recent snapshot # TYPE storage_cache_latest_snapshot gauge ## storage_cache_latest_snapshot{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 1.644269658196893e+09 ``` ### Cache writes with dropped points Cumulative number of [cached](/influxdb/v2/reference/internals/storage-engine/#cache) writes that had [rejected points](/influxdb/v2/reference/glossary/#rejected-points). Writes with rejected points also increment the [write errors counter (`storage_cache_writes_err`)](#cache-writes-failed). #### Example ``` # HELP storage_cache_writes_dropped Counter of writes to cache with some dropped points # TYPE storage_cache_writes_dropped counter ## storage_cache_writes_dropped{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Cache writes failed Cumulative number of [cached](/influxdb/v2/reference/internals/storage-engine/#cache) writes that [failed](/influxdb/v2/write-data/troubleshoot/#troubleshoot-failures), inclusive of [cache writes with dropped points (`storage_cache_writes_dropped`)](#cache-writes-with-dropped-points). #### Example ``` # HELP storage_cache_writes_err Counter of failed writes to cache # TYPE storage_cache_writes_err counter ## storage_cache_writes_err{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Cache writes total Cumulative number of writes to [cache](/influxdb/v2/reference/internals/storage-engine/#cache). #### Example ``` # HELP storage_cache_writes_total Counter of all writes to cache # TYPE storage_cache_writes_total counter ## storage_cache_writes_total{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Compactions active Currently running [TSM](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm) compactions (by level). #### Example ``` # HELP storage_compactions_active Gauge of compactions (by level) currently running # TYPE storage_compactions_active gauge ## storage_compactions_active{bucket="ec3f82d1de90eddf",engine="tsm1",id="565",level="1",path="/Users/me/.influxdbv2/engine/data/ec3f82d1de90eddf/autogen/565",walPath="/Users/me/.influxdbv2/engine/wal/ec3f82d1de90eddf/autogen/565"} 0 ``` ### Compactions since startup [TSM](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm) compactions (by level) since startup. #### Example ``` # HELP storage_compactions_duration_seconds Histogram of compactions by level since startup # TYPE storage_compactions_duration_seconds histogram storage_compactions_duration_seconds_bucket{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567",le="60"} 1 storage_compactions_duration_seconds_bucket{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567",le="600"} 1 storage_compactions_duration_seconds_bucket{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567",le="6000"} 1 storage_compactions_duration_seconds_bucket{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567",le="+Inf"} 1 storage_compactions_duration_seconds_sum{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567"} 0.167250668 ## storage_compactions_duration_seconds_count{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="cache",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567"} 1 ``` ### Compactions failed Failed [TSM](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm) compactions (by level). #### Example ``` # HELP storage_compactions_failed Counter of TSM compactions (by level) that have failed due to error # TYPE storage_compactions_failed counter ## storage_compactions_failed{bucket="ec3f82d1de90eddf",engine="tsm1",id="565",level="1",path="/Users/me/.influxdbv2/engine/data/ec3f82d1de90eddf/autogen/565",walPath="/Users/me/.influxdbv2/engine/wal/ec3f82d1de90eddf/autogen/565"} 0 ``` ### Compactions queued Queued [TSM](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm) compactions (by level). #### Example ``` # HELP storage_compactions_queued Counter of TSM compactions (by level) that are currently queued # TYPE storage_compactions_queued gauge ## storage_compactions_queued{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="567",level="1",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/567",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/567"} 0 ``` ### Retention check duration Retention policy check duration (in seconds). #### Example ``` # HELP storage_retention_check_duration Histogram of duration of retention check (in seconds) # TYPE storage_retention_check_duration histogram storage_retention_check_duration_bucket{le="0.005"} 1 storage_retention_check_duration_bucket{le="0.01"} 1 storage_retention_check_duration_bucket{le="0.025"} 1 storage_retention_check_duration_bucket{le="0.05"} 1 storage_retention_check_duration_bucket{le="0.1"} 1 storage_retention_check_duration_bucket{le="0.25"} 1 storage_retention_check_duration_bucket{le="0.5"} 1 storage_retention_check_duration_bucket{le="1"} 1 storage_retention_check_duration_bucket{le="2.5"} 1 storage_retention_check_duration_bucket{le="5"} 1 storage_retention_check_duration_bucket{le="10"} 1 storage_retention_check_duration_bucket{le="+Inf"} 1 storage_retention_check_duration_sum 0.000351857 ## storage_retention_check_duration_count 1 ``` ### Shard disk size Disk size (in bytes) of the [shard](/influxdb/v2/reference/internals/shards/). #### Example ``` # HELP storage_shard_disk_size Gauge of the disk size for the shard # TYPE storage_shard_disk_size gauge ## storage_shard_disk_size{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 4.188743e+06 ``` ### Shard fields created Number of [shard](/influxdb/v2/reference/internals/shards/) fields created. #### Example ``` # HELP storage_shard_fields_created Counter of the number of fields created # TYPE storage_shard_fields_created counter ## storage_shard_fields_created{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Shard series Number of series in the [shard](/influxdb/v2/reference/internals/shards/) index. #### Example ``` # HELP storage_shard_series Gauge of the number of series in the shard index # TYPE storage_shard_series gauge ## storage_shard_series{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 38 ``` ### Shard writes Number of [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests. #### Example ``` # HELP storage_shard_write_count Count of the number of write requests # TYPE storage_shard_write_count counter ## storage_shard_write_count{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Shard dropped points Number of [rejected points](/influxdb/v2/reference/glossary/#rejected-points) in [shard writes](/influxdb/v2/reference/internals/shards/#shard-writes). #### Example ``` # HELP storage_shard_write_dropped_sum Counter of the number of points dropped # TYPE storage_shard_write_dropped_sum counter ## storage_shard_write_dropped_sum{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Shard writes with errors Number of [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests with errors. #### Example ``` # HELP storage_shard_write_err_count Count of the number of write requests with errors # TYPE storage_shard_write_err_count counter ## storage_shard_write_err_count{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Points in shard writes with errors Number of points in [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests with errors. #### Example ``` # HELP storage_shard_write_err_sum Counter of the number of points for write requests with errors # TYPE storage_shard_write_err_sum counter ## storage_shard_write_err_sum{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Points in shard writes Number of points in [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests. #### Example ``` # HELP storage_shard_write_sum Counter of the number of points for write requests # TYPE storage_shard_write_sum counter ## storage_shard_write_sum{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ### Shard data size Gauge of the data size (in bytes) for each [shard](/influxdb/v2/reference/internals/shards/). #### Example ``` # HELP storage_tsm_files_disk_bytes Gauge of data size in bytes for each shard # TYPE storage_tsm_files_disk_bytes gauge ## storage_tsm_files_disk_bytes{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 4.188743e+06 ``` ### Shard files Number of files per [shard](/influxdb/v2/reference/internals/shards/). #### Example ``` # HELP storage_tsm_files_total Gauge of number of files per shard # TYPE storage_tsm_files_total gauge ## storage_tsm_files_total{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 1 ``` ### WAL size [WAL](/influxdb/v2/reference/internals/storage-engine/#write-ahead-log-wal) size (in bytes). #### Example ``` # HELP storage_wal_size Gauge of size of WAL in bytes # TYPE storage_wal_size gauge ## storage_wal_size{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ## WAL write attempts Cumulative number of write attempts to the [WAL](/influxdb/v2/reference/internals/storage-engine/#write-ahead-log-wal). #### Example ``` # HELP storage_wal_writes Number of write attempts to the WAL # TYPE storage_wal_writes counter ## storage_wal_writes{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ## WAL failed write attempts Cumulative number of failed write attempts to the [WAL](/influxdb/v2/reference/internals/storage-engine/#write-ahead-log-wal). #### Example ``` # HELP storage_wal_writes_err Number of failed write attempts to the WAL # TYPE storage_wal_writes_err counter ## storage_wal_writes_err{bucket="0c3dd7d2d97f4b23",engine="tsm1",id="561",path="/Users/me/.influxdbv2/engine/data/0c3dd7d2d97f4b23/autogen/561",walPath="/Users/me/.influxdbv2/engine/wal/0c3dd7d2d97f4b23/autogen/561"} 0 ``` ## Points dropped due to partial writes Number of points dropped due to partial writes. #### Example ``` # HELP storage_writer_dropped_points Histogram of number of points dropped due to partial writes # TYPE storage_writer_dropped_points histogram storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="10"} 0 storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="100"} 0 storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="1000"} 0 storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="10000"} 0 storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="100000"} 0 storage_writer_dropped_points_bucket{path="/Users/me/.influxdbv2/engine",le="+Inf"} 0 storage_writer_dropped_points_sum{path="/Users/me/.influxdbv2/engine"} 0 ## storage_writer_dropped_points_count{path="/Users/me/.influxdbv2/engine"} 0 ``` ## Points in shard write requests with errors Number of points in [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests with errors. #### Example ``` # HELP storage_writer_err_points Histogram of number of points in errored shard write requests # TYPE storage_writer_err_points histogram storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="10"} 0 storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="100"} 0 storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="1000"} 0 storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="10000"} 0 storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="100000"} 0 storage_writer_err_points_bucket{path="/Users/me/.influxdbv2/engine",le="+Inf"} 0 storage_writer_err_points_sum{path="/Users/me/.influxdbv2/engine"} 0 ## storage_writer_err_points_count{path="/Users/me/.influxdbv2/engine"} 0 ``` ## Points in successful shard write requests Number of points in successful [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) requests. #### Example ``` # HELP storage_writer_ok_points Histogram of number of points in successful shard write requests # TYPE storage_writer_ok_points histogram storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="10"} 6 storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="100"} 6 storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="1000"} 8 storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="10000"} 20 storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="100000"} 24 storage_writer_ok_points_bucket{path="/Users/me/.influxdbv2/engine",le="+Inf"} 24 storage_writer_ok_points_sum{path="/Users/me/.influxdbv2/engine"} 125787 ## storage_writer_ok_points_count{path="/Users/me/.influxdbv2/engine"} 24 ``` ## Points in write requests Number of points in write requests. #### Example ``` # HELP storage_writer_req_points Histogram of number of points requested to be written # TYPE storage_writer_req_points histogram storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="10"} 6 storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="100"} 6 storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="1000"} 6 storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="10000"} 14 storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="100000"} 18 storage_writer_req_points_bucket{path="/Users/me/.influxdbv2/engine",le="+Inf"} 18 storage_writer_req_points_sum{path="/Users/me/.influxdbv2/engine"} 125787 ## storage_writer_req_points_count{path="/Users/me/.influxdbv2/engine"} 18 ``` ## Shard write request timeouts Cumulative number of [shard write](/influxdb/v2/reference/internals/shards/#shard-writes) request timeouts. #### Example ``` # HELP storage_writer_timeouts Number of shard write request timeouts # TYPE storage_writer_timeouts counter ## storage_writer_timeouts{path="/Users/me/.influxdbv2/engine"} 0 ``` ## InfluxDB task statistics ### Task executor errors Number of errors thrown by the executor with the type of error (ex. Invalid, Internal, etc.) #### Example ``` # HELP task_executor_errors_counter The number of errors thrown by the executor with the type of error (ex. Invalid, Internal, etc.) # TYPE task_executor_errors_counter counter ## task_executor_errors_counter{errorType="internal error",task_type="system"} 1183 ``` ### Task executor promise queue usage Percent of the promise queue that is currently full. #### Example ```text # HELP task_executor_promise_queue_usage Percent of the promise queue that is currently full # TYPE task_executor_promise_queue_usage gauge task_executor_promise_queue_usage 0 ``` ### Task executor run duration Duration (in seconds) between a task run starting and finishing. #### Example ``` # HELP task_executor_run_duration The duration in seconds between a run starting and finishing. # TYPE task_executor_run_duration summary task_executor_run_duration{taskID="08017725990f6000",task_type="",quantile="0.5"} 0.865043855 task_executor_run_duration{taskID="08017725990f6000",task_type="",quantile="0.9"} 0.865043855 task_executor_run_duration{taskID="08017725990f6000",task_type="",quantile="0.99"} 0.865043855 task_executor_run_duration_sum{taskID="08017725990f6000",task_type=""} 1.524920552 ## task_executor_run_duration_count{taskID="08017725990f6000",task_type=""} 2 ``` ### Task executor run latency seconds Latency between the task run’s scheduled start time and the execution time, by task type. #### Example ``` # HELP task_executor_run_latency_seconds Records the latency between the time the run was due to run and the time the task started execution, by task type # TYPE task_executor_run_latency_seconds histogram task_executor_run_latency_seconds_bucket{task_type="system",le="0.005"} 0 task_executor_run_latency_seconds_bucket{task_type="system",le="0.01"} 0 task_executor_run_latency_seconds_bucket{task_type="system",le="0.025"} 0 task_executor_run_latency_seconds_bucket{task_type="system",le="0.05"} 0 task_executor_run_latency_seconds_bucket{task_type="system",le="0.1"} 0 task_executor_run_latency_seconds_bucket{task_type="system",le="0.25"} 2 task_executor_run_latency_seconds_bucket{task_type="system",le="0.5"} 6 task_executor_run_latency_seconds_bucket{task_type="system",le="1"} 6 task_executor_run_latency_seconds_bucket{task_type="system",le="2.5"} 6 task_executor_run_latency_seconds_bucket{task_type="system",le="5"} 6 task_executor_run_latency_seconds_bucket{task_type="system",le="10"} 6 task_executor_run_latency_seconds_bucket{task_type="system",le="+Inf"} 6 task_executor_run_latency_seconds_sum{task_type="system"} 2.237636 ## task_executor_run_latency_seconds_count{task_type="system"} 6 ``` ### Task executor run queue delta Duration (in seconds) between the task run’s scheduled start time and the execution time. #### Example ``` # HELP task_executor_run_queue_delta The duration in seconds between a run being due to start and actually starting. # TYPE task_executor_run_queue_delta summary task_executor_run_queue_delta{taskID="08017725990f6000",task_type="",quantile="0.5"} 0.324742 task_executor_run_queue_delta{taskID="08017725990f6000",task_type="",quantile="0.9"} 0.324742 task_executor_run_queue_delta{taskID="08017725990f6000",task_type="",quantile="0.99"} 0.324742 task_executor_run_queue_delta_sum{taskID="08017725990f6000",task_type=""} 0.674875 ## task_executor_run_queue_delta_count{taskID="08017725990f6000",task_type=""} 2 ``` ### Task executor total runs active Number of workers currently running tasks. #### Example ```text # HELP task_executor_total_runs_active Total number of workers currently running tasks # TYPE task_executor_total_runs_active gauge task_executor_total_runs_active 0 ``` ### Task executor total runs complete Number of task runs completed across all tasks, split out by success or failure. #### Example ``` # HELP task_executor_total_runs_complete Total number of runs completed across all tasks, split out by success or failure. # TYPE task_executor_total_runs_complete counter task_executor_total_runs_complete{status="failed",task_type="system"} 1384 ## task_executor_total_runs_complete{status="success",task_type="system"} 6 ``` ### Task executor workers busy Percent of total available workers that are currently busy. #### Example ```text # HELP task_executor_workers_busy Percent of total available workers that are currently busy # TYPE task_executor_workers_busy gauge task_executor_workers_busy 0 ``` ### Task scheduler current execution Number of tasks currently being executed. #### Example ```text # HELP task_scheduler_current_execution Number of tasks currently being executed # TYPE task_scheduler_current_execution gauge task_scheduler_current_execution 128 ``` ### Task scheduler execute delta Duration (in seconds) between a task run starting and finishing. #### Example ``` # HELP task_scheduler_execute_delta The duration in seconds between a run starting and finishing. # TYPE task_scheduler_execute_delta summary ## task_scheduler_execute_delta{quantile="0.5"} NaN ``` ### Task scheduler schedule delay Summary of the delay between when a task is scheduled to run and when it is told to execute. #### Example ``` # HELP task_scheduler_schedule_delay The duration between when a Item should be scheduled and when it is told to execute. # TYPE task_scheduler_schedule_delay summary task_scheduler_schedule_delay{quantile="0.5"} 120.001036 task_scheduler_schedule_delay{quantile="0.9"} 120.001074 task_scheduler_schedule_delay{quantile="0.99"} 120.001074 task_scheduler_schedule_delay_sum 720.0033010000001 ## task_scheduler_schedule_delay_count 6 ``` ### Task scheduler total execute failure Number of times a scheduled task execution has failed. #### Example ```text # HELP task_scheduler_total_execute_failure Total number of times an execution has failed. # TYPE task_scheduler_total_execute_failure counter task_scheduler_total_execute_failure 0 ``` ### Task scheduler total execution calls Number of scheduled executions across all tasks. #### Example ```text # HELP task_scheduler_total_execution_calls Total number of executions across all tasks. # TYPE task_scheduler_total_execution_calls counter task_scheduler_total_execution_calls 4806 ``` ### Task scheduler total release calls Number of release requests. #### Example ```text # HELP task_scheduler_total_release_calls Total number of release requests. # TYPE task_scheduler_total_release_calls counter task_scheduler_total_release_calls 0 ``` ### Task scheduler total schedule calls Number of schedule requests. #### Example ```text # HELP task_scheduler_total_schedule_calls Total number of schedule requests. # TYPE task_scheduler_total_schedule_calls counter task_scheduler_total_schedule_calls 6 ``` ### Task scheduler total schedule fails Number of schedule requests that fail to schedule. #### Example ```text # HELP task_scheduler_total_schedule_fails Total number of schedule requests that fail to schedule. # TYPE task_scheduler_total_schedule_fails counter task_scheduler_total_schedule_fails 0 ``` [cpu](/influxdb/v2/tags/cpu/)[memory](/influxdb/v2/tags/memory/)[metrics](/influxdb/v2/tags/metrics/)[performance](/influxdb/v2/tags/performance/)[Prometheus](/influxdb/v2/tags/prometheus/)[storage](/influxdb/v2/tags/storage/)[usage](/influxdb/v2/tags/usage/) --- # InfluxDB runtime Source: https://docs.influxdata.com/influxdb/v2/reference/internals/runtime/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB provides Go runtime profiles, trace, and other information useful for analyzing and debugging the server runtime execution. * [Overview of Go runtime profiles](#overview-of-go-runtime-profiles) * [Analyze Go runtime profiles](#analyze-go-runtime-profiles) * [Analyze the Go runtime trace](#analyze-the-go-runtime-trace) * [View the command line that invoked InfluxDB](#view-the-command-line-that-invoked-influxdb) * [View runtime configuration](#view-runtime-configuration) ## Overview of Go runtime profiles A **Go runtime profile** is a collection of stack traces showing call sequences that led to instances of a particular event. InfluxDB provides profile data for the following events: * blocks * CPU usage * memory allocation * mutual exclusion (mutex) * OS thread creation When you send a profile request to InfluxDB, the [Golang runtime pprof package](https://pkg.go.dev/runtime/pprof) samples the events on the runtime to collect stack traces and statistics (e.g., number of bytes of memory for heap allocation events). For some profiles, you can set the number of seconds that InfluxDB will collect profile data. Once data collection is complete, InfluxDB returns the profile data. The default response format is a compressed protocol buffer in[profile.proto](https://github.com/google/pprof/blob/master/proto/profile.proto) format. **profile.proto** files are compatible with the [pprof](https://github.com/google/pprof) and [`go tool pprof`](https://go.dev/blog/pprof) analysis tools. For some profiles, InfluxDB provides an alternative human-readable plain text format with comments that translate to function calls and line numbers, but the `pprof` tools and **profile.proto** format offer the following advantages: * Read profiles from disk or HTTP. * Aggregate and compare multiple profiles of the same type. * Analyze and filter profile data. * Generate visualizations and reports. ## Analyze Go runtime profiles Use the `/debug/pprof` InfluxDB endpoints to download all the profiles at once or request them individually. * [Get all runtime profiles](#get-all-runtime-profiles) * [Profile all memory allocations](#profile-all-memory-allocations) * [Profile blocking operations](#profile-blocking-operations) * [Profile CPU](#profile-cpu) * [Profile goroutines](#profile-goroutines) * [Profile heap memory allocations](#profile-heap-memory-allocations) * [Profile mutual exclusions](#profile-mutual-exclusions-mutexes) * [Profile thread creation](#profile-thread-creation) ### Get all runtime profiles To download all runtime profiles at once, use an HTTP client to send a `GET` request to the `/debug/pprof/all` endpoint. `go tool pprof` can’t fetch profiles directly from `/debug/pprof/all`. ``` GET http://localhost:8086/debug/pprof/all ``` InfluxDB returns a gzipped tar file that contains the following profiles in the **profile.proto** format: * `profiles/allocs.pb.gz`: [profile all memory allocations](#profile-all-memory-allocations) * `profiles/block.pb.gz`: [profile blocking operations](#profile-blocking-operations) * `profiles/cpu.pb.gz`: *(Optional)* [profile CPU](#profile-cpu). * `profiles/goroutine.pb.gz`: [profile goroutines](#profile-goroutines) * `profiles/heap.pb.gz`: [profile heap memory allocations](#profile-heap-memory-allocations) * `profiles/mutex.pb.gz`: [profile mutual exclusions](#profile-mutual-exclusions-mutexes) * `profiles/threadcreate.pb.gz`: [profile thread creation](#profile-thread-creation) | Option | Include by | |-----------|--------------------------------------------------------------------------------------------------------------------------| |Profile CPU|Pass a [duration of seconds](/influxdb/v2/reference/glossary/#duration) with the `cpu` query parameter in your request URL| Use an HTTP client like `curl` or `wget` to download profiles from `/debug/pprof/all`. #### Example ```sh # Use `curl` to download a `.tar.gz` of all profiles after 10 seconds of CPU sampling. # Use `tar` to extract the profiles folder. curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz # Analyze an extracted profile. go tool pprof profiles/heap.pb.gz ``` ### Profile all memory allocations Profiles memory allocations and sets the default profile display to **alloc\_space**, the total number of bytes allocated since the program began (including garbage-collected bytes). ``` GET http://localhost:8086/debug/pprof/allocs ``` | Option | Include by | |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | Seconds to sample |Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| |Output plain text (mutually exclusive with `seconds`)| Pass `1` with the `debug` query parameter in your request URL | ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/allocs # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N memory allocations. (pprof) top10 ``` ### Profile blocking operations Profiles operations that led to blocking on synchronization primitives and caused Go to suspend goroutine’s execution. ``` GET http://localhost:8086/debug/pprof/block ``` | Option | Include by | |-----------------|-------------------------------------------------------------| |Output plain text|Pass `1` with the `debug` query parameter in your request URL| ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/block # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N entries. (pprof) top10 ``` ### Profile CPU Profiles program counters sampled from the execution stack. To download the profile, use an HTTP client to send a `GET` request to the `/debug/pprof/profile` endpoint. `go tool pprof` can’t fetch the CPU profile directly. ``` GET http://localhost:8086/debug/pprof/profile ``` | Option | Include by | |--------------------------------|------------------------------------------------------------------------------------------------------------------------------------| |Seconds to sample (default `30`)|Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| Use an HTTP client like `curl` or `wget` to download the profile. #### Example ```sh # Get the profile. curl http://localhost:8086/debug/pprof/profile -o cpu # Analyze the profile in interactive mode. go tool pprof ./cpu # At the prompt, get the top N functions most often running # or waiting during the sample period. (pprof) top10 ``` Use the `seconds` query parameter to control the sampling duration. > [!Note] > `/debug/pprof/profile?seconds=SECONDS` returns the same CPU profile as `/debug/pprof/all?cpu=DURATION`. #### Example ```sh # Get the CPU profile after 10 seconds of sampling. curl "http://localhost:8086/debug/pprof/profile?seconds=10" -o cpu # Get all profiles after 10 seconds of CPU sampling. curl "http://localhost:8086/debug/pprof/all?cpu=10s" -o all.tar.gz ``` ### Profile goroutines Profiles all current goroutines. ``` GET http://localhost:8086/debug/pprof/goroutine ``` | Option | Include by | |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | Seconds to sample |Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| |Output plain text (mutually exclusive with `seconds`)| Pass `1` with the `debug` query parameter in your request URL | #### Example ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/goroutine # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N entries. (pprof) top10 ``` ### Profile heap memory allocations Profiles heap, or memory allocations for live objects. ``` GET http://localhost:8086/debug/pprof/heap ``` | Option | Include by | |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | Run garbage control before sampling | Pass `1` with the `gc` query parameter in your request URL | | Seconds to sample |Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| |Output plain text (mutually exclusive with `seconds`)| Pass `1` with the `debug` query parameter in your request URL | #### Example ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/heap # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N memory-intensive nodes. (pprof) top10 # pprof displays the list: # Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total # Dropped 895 nodes (cum <= 0.83MB) # Showing top 10 nodes out of 143 ``` ### Profile mutual exclusions (mutexes) Profiles holders of contended mutual exclusions (mutexes). ``` GET http://localhost:8086/debug/pprof/mutex ``` | Option | Include by | |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | Seconds to sample |Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| |Output plain text (mutually exclusive with `seconds`)| Pass `1` with the `debug` query parameter in your request URL | #### Example ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/mutex # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N entries. (pprof) top10 ``` ### Profile thread creation Profiles operations that led to the creation of OS threads. ``` GET http://localhost:8086/debug/pprof/threadcreate ``` | Option | Include by | |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | Seconds to sample |Pass an [unsigned integer](/influxdb/v2/reference/glossary/#unsigned-integer) with the `seconds` query parameter in your request URL| |Output plain text (mutually exclusive with `seconds`)| Pass `1` with the `debug` query parameter in your request URL | #### Example ```sh # Analyze the profile in interactive mode. go tool pprof http://localhost:8086/debug/pprof/threadcreate # `pprof` returns the following prompt: # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) # At the prompt, get the top N entries. (pprof) top10 ``` ## Analyze the Go runtime trace To trace execution events for InfluxDB, use the `/debug/pprof/trace`endpoint with `go tool trace`. ``` GET http://localhost:8086/debug/pprof/trace ``` #### Example ```sh # Download the trace file. curl http://localhost:8086/debug/pprof/trace -o trace.out # Analyze the trace. go tool trace ./trace.out ``` #### Generate a pprof-like profile from trace You can use `go tool trace` to generate *pprof-like* profiles from a trace file and then analyze them with `go tool pprof`. #### Example ```sh # Generate a profile from the downloaded trace file. go tool trace -pprof=PROFILE_TYPE ./trace.out > PROFILE_TYPE.pprof ``` Replace *`PROFILE_TYPE`* with one of the following [Golang profile types](https://pkg.go.dev/cmd/trace): * `net`: network blocking profile * `sync`: synchronization blocking profile * `syscall`: syscall blocking profile * `sched`: scheduler latency profile ## View the command line that invoked InfluxDB To view the command, arguments, and command-line variables that invoked InfluxDB, use the `/debug/pprof/cmdline` endpoint. ``` GET http://localhost:8086/debug/pprof/cmdline ``` `/debug/pprof/cmdline` returns the command line invocation in plain text. ## View runtime configuration In InfluxDB v2.3+, you can view your active runtime configuration, including flags and environment variables. See how to [view your runtime server configuration](/influxdb/v2/reference/config-options/#view-your-runtime-server-configuration). | Option | Include by | | --- | --- | | Option | Include by | | Profile CPU | Pass a duration of seconds with the cpu query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Seconds to sample | Pass an unsigned integer with the seconds query parameter in your request URL | | Output plain text (mutually exclusive with seconds ) | Pass 1 with the debug query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Output plain text | Pass 1 with the debug query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Seconds to sample (default 30 ) | Pass an unsigned integer with the seconds query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Seconds to sample | Pass an unsigned integer with the seconds query parameter in your request URL | | Output plain text (mutually exclusive with seconds ) | Pass 1 with the debug query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Run garbage control before sampling | Pass 1 with the gc query parameter in your request URL | | Seconds to sample | Pass an unsigned integer with the seconds query parameter in your request URL | | Output plain text (mutually exclusive with seconds ) | Pass 1 with the debug query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Seconds to sample | Pass an unsigned integer with the seconds query parameter in your request URL | | Output plain text (mutually exclusive with seconds ) | Pass 1 with the debug query parameter in your request URL | | Option | Include by | | --- | --- | | Option | Include by | | Seconds to sample | Pass an unsigned integer with the seconds query parameter in your request URL | | Output plain text (mutually exclusive with seconds ) | Pass 1 with the debug query parameter in your request URL | --- # InfluxDB shards and shard groups Source: https://docs.influxdata.com/influxdb/v2/reference/internals/shards/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB organizes time series data into **shards** when storing data to disk. Shards are grouped into **shard groups**. Learn the relationships between buckets, shards, and shard groups. * [Shards](#shards) * [Shard groups](#shard-groups) * [Shard group duration](#shard-group-duration) * [Shard group diagram](#shard-group-diagram) * [Shard life cycle](#shard-life-cycle) * [Shard precreation](#shard-precreation) * [Shard writes](#shard-writes) * [Shard compaction](#shard-compaction) * [Shard deletion](#shard-deletion) ## Shards A shard contains encoded and compressed time series data for a given time range defined by the [shard group duration](#shard-group-duration). All points in a [series](/influxdb/v2/reference/glossary/#series) within the specified shard group duration are stored in the same shard. A single shard contains multiple series, one or more [TSM files](/influxdb/v2/reference/glossary/#tsm-time-structured-merge-tree) on disk, and belongs to a [shard group](#shard-groups). ## Shard groups A shard group belongs to an InfluxDB [bucket](/influxdb/v2/reference/glossary/#bucket) and contains time series data for a specific time range defined by the [shard group duration](#shard-group-duration). > [!Note] > In **InfluxDB OSS**, a shard group typically contains only a single shard. > In an **InfluxDB Enterprise 1.x cluster**, shard groups contain multiple shards > distributed across multiple data nodes. ### Shard group duration The **shard group duration** specifies the time range for each shard group and determines how often to create a new shard group. By default, InfluxDB sets the shard group duration according to the [retention period](/influxdb/v2/reference/glossary/#retention-period)of the bucket: | Bucket retention period |Default shard group duration| |---------------------------|----------------------------| | less than 2 days | 1h | |between 2 days and 6 months| 1d | | greater than 6 months | 7d | ##### Shard group duration configuration options To configure a custom bucket shard group duration, use the `--shard-group-duration`flag with the [`influx bucket create`](/influxdb/v2/reference/cli/influx/bucket/create/#create-a-bucket-with-a-custom-shard-group-duration)and [`influx bucket update`](/influxdb/v2/reference/cli/influx/bucket/update//#update-the-shard-group-duration-of-a-bucket) commands. > [!Note] > Shard group durations must be shorter than the bucket’s retention period. To view your bucket’s shard group duration, use the[`influx bucket list` command](/influxdb/v2/reference/cli/influx/bucket/list/). ### Shard group diagram The following diagram represents a **bucket** with a **4d retention period**and a **1d shard group duration**: 0d 1d 2d 3d 4d Shard group Shard Shard group Shard Shard group Shard Shard group Shard ## Shard life cycle ### Shard precreation The InfluxDB **shard precreation service** pre-creates shards with future start and end times for each shard group based on the shard group duration. The precreator service does not pre-create shards for past time ranges. When backfilling historical data, InfluxDB creates shards for past time ranges as needed, resulting in temporarily lower write throughput. ##### Shard precreation-related configuration settings * [`storage-shard-precreator-advance-period`](/influxdb/v2/reference/config-options/#storage-shard-precreator-advance-period) * [`storage-shard-precreator-check-interval`](/influxdb/v2/reference/config-options/#storage-shard-precreator-check-interval) ### Shard writes InfluxDB writes time series data to un-compacted or “hot” shards. When a shard is no longer actively written to, InfluxDB [compacts](#shard-compaction) shard data, resulting in a “cold” shard. Typically, InfluxDB writes data to the most recent shard group, but when backfilling historical data, InfluxDB writes to older shards that must first be un-compacted. When the backfill is complete, InfluxDB re-compacts the older shards. ### Shard compaction InfluxDB compacts shards at regular intervals to compress time series data and optimize disk usage. When compactions are enabled, InfluxDB checks to see whether shard compactions are needed every second. If there haven’t been writes during the `compact-full-write-cold-duration` period (by default, `4h`), InfluxDB compacts all TSM files. Otherwise, InfluxDB groups TSM files into compaction levels (determined by the number of times the file have been compacted), and attempts to combine files and compress them more efficiently. InfluxDB uses the following four compaction levels: * **Level 0 (L0):** The log file (`LogFile`) is considered level 0 (L0). Once this file exceeds a `5MB` threshold, InfluxDB creates a new active log file, and the previous one begins compacting into an `IndexFile`. This first index file is at level 1 (L1). * **Level 1 (L1):** InfluxDB flushes all newly written data held in an in-memory cache to disk into an `IndexFile`. * **Level 2 (L2):** InfluxDB compacts up to eight L1-compacted files into one or more L2 files by combining multiple blocks containing the same series into fewer blocks in one or more new files. * **Level 3 (L3):** InfluxDB iterates over L2-compacted file blocks (over a certain size) and combines multiple blocks containing the same series into one block in a new file. * **Level 4 (L4):** **Full compaction** InfluxDB iterates over L3-compacted file blocks and combines multiple blocks containing the same series into one block in a new file. InfluxDB schedules compactions preferentially, using the following guidelines: * The lower the level (fewer times the file has been compacted), the more weight is given to compacting the file. * The more compactible files in a level, the higher the priority given to compacting that level. If the number of files in each level is equal, lower levels are compacted first. * If a higher level has more candidates for compaction, it may be compacted before a lower level. InfluxDB multiplies the number of collection groups (collections of files to compact into a single next-generation file) by a specified weight (0.4, 0.3, 0.2, and 0.1) per level, to determine the compaction priority. ##### Shard compaction-related configuration settings The following configuration settings are especially beneficial for systems with irregular loads, because they limit compactions during periods of high usage, and let compactions catch up during periods of lower load: * [`storage-compact-full-write-cold-duration`](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration) * [`storage-compact-throughput`](/influxdb/v2/reference/config-options/#storage-compact-throughput) * [`storage-compact-throughput-burst`](/influxdb/v2/reference/config-options/#storage-compact-throughput-burst) * [`storage-max-concurrent-compactions`](/influxdb/v2/reference/config-options/#storage-max-concurrent-compactions) * [`storage-max-index-log-file-size`](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size) * [`storage-series-file-max-concurrent-snapshot-compactions`](/influxdb/v2/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) In InfluxDB OSS v2.10 and later, `storage-compact-throughput` sets the sustained compaction throughput and `storage-compact-throughput-burst` sets the burst compaction throughput. If the burst value is lower than the sustained value, InfluxDB raises the burst value to match. In earlier versions, `storage-compact-throughput-burst` controls both values. Use these settings to scale compaction write throughput as you scale CPU and disk. In systems with stable loads, if compactions interfere with other operations, typically, the system is undersized for its load, and configuration changes won’t help much. ## Shard deletion The InfluxDB **retention enforcement service** routinely checks for shard groups older than their bucket’s retention period. Once the start time of a shard group is beyond the bucket’s retention period, InfluxDB deletes the shard group and associated shards and TSM files. In buckets with an infinite retention period, shards remain on disk indefinitely. > [!Note] > #### InfluxDB only deletes cold shards > > InfluxDB only deletes **cold** shards. > If backfilling data beyond a bucket’s retention period, the backfilled data will > remain on disk until the following occurs: > > 1. The shard returns to a cold state. > 2. The retention enforcement service deletes the shard group. ##### Retention enforcement-related configuration settings * [`storage-retention-check-interval`](/influxdb/v2/reference/config-options/#storage-retention-check-interval) #### Related * [InfluxDB storage engine](/influxdb/v2/reference/internals/storage-engine/) * [Manage buckets](/influxdb/v2/admin/buckets/) * [influx bucket](/influxdb/v2/reference/cli/influx/bucket/) * [Manage InfluxDB internal systems](/influxdb/v2/admin/internals/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) | Bucket retention period | Default shard group duration | | --- | --- | | Bucket retention period | Default shard group duration | | less than 2 days | 1h | | between 2 days and 6 months | 1d | | greater than 6 months | 7d | --- # InfluxDB storage engine Source: https://docs.influxdata.com/influxdb/v2/reference/internals/storage-engine/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB storage engine ensures that: * Data is safely written to disk * Queried data is returned complete and correct * Data is accurate (first) and performant (second) This document outlines the internal workings of the storage engine. This information is presented both as a reference and to aid those looking to maximize performance. The storage engine includes the following components: * [Write Ahead Log (WAL)](#write-ahead-log-wal) * [Cache](#cache) * [Time-Structured Merge Tree (TSM)](#time-structured-merge-tree-tsm) * [Time Series Index (TSI)](#time-series-index-tsi) ## Writing data from API to disk The storage engine handles data from the point an API write request is received through writing data to the physical disk. Data is written to InfluxDB using [line protocol](/influxdb/v2/reference/syntax/line-protocol/) sent via HTTP POST request to the `/api/v2/write` endpoint or the [`/write` 1.x compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/). Batches of [points](/influxdb/v2/reference/glossary/#point) are sent to InfluxDB, compressed, and written to a WAL for immediate durability. Points are also written to an in-memory cache and become immediately queryable. The in-memory cache is periodically written to disk in the form of [TSM](#time-structured-merge-tree-tsm) files. As TSM files accumulate, the storage engine combines and compacts accumulated them into higher level TSM files. > [!Note] > While points can be sent individually, for efficiency, most applications send points in batches. > Points in a POST body can be from an arbitrary number of series, measurements, and tag sets. > Points in a batch do not have to be from the same measurement or tagset. ## Write Ahead Log (WAL) The **Write Ahead Log** (WAL) retains InfluxDB data when the storage engine restarts. The WAL ensures data is durable in case of an unexpected failure. When the storage engine receives a write request, the following steps occur: 1. The write request is appended to the end of the WAL file. 2. Data is written to disk using `fsync()`. 3. The in-memory cache is updated. 4. When data is successfully written to disk, a response confirms the write request was successful. `fsync()` takes the file and pushes pending writes all the way to the disk. As a system call, `fsync()` has a kernel context switch that’s computationally expensive, but guarantees that data is safe on disk. When the storage engine restarts, the WAL file is read back into the in-memory database. InfluxDB then answers requests to the `/read` endpoint. ## Cache The **cache** is an in-memory copy of data points currently stored in the WAL. The [WAL](#write-ahead-log-wal) and cache are separate entities and do not interact with each other. The storage engine coordinates writes to both. The cache: * Organizes points by key (measurement, tag set, and unique field). Each field is stored in its own time-ordered range. * Stores uncompressed data. * Gets updates from the WAL each time the storage engine restarts. The cache is queried at runtime and merged with the data stored in TSM files. * Uses a maximum `maxSize` bytes of memory. Cache snapshots are cache objects currently being written to TSM files. They’re kept in memory while flushing so they can be queried along with the cache. Queries to the storage engine merge data from the cache with data from the TSM files. Queries execute on a copy of the data that is made from the cache at query processing time. This way writes that come in while a query is running do not affect the result. Deletes sent to the cache clear the specified key or time range for a specified key. ## Time-Structured Merge Tree (TSM) To efficiently compact and store data, the storage engine groups field values by series key, and then orders those field values by time. (A [series key](/influxdb/v2/reference/glossary/#series-key) is defined by measurement, tag key and value, and field key.) The storage engine uses a **Time-Structured Merge Tree** (TSM) data format. TSM files store compressed series data in a columnar format. To improve efficiency, the storage engine only stores differences (or *deltas*) between values in a series. Column-oriented storage lets the engine read by series key and omit extraneous data. After fields are stored safely in TSM files, the WAL is truncated and the cache is cleared. The **compaction** process creates read-optimized TSM files. The TSM compaction code is quite complex. However, the high-level goal is quite simple: organize values for a series together into long runs to best optimize compression and scanning queries. For more information on the TSM engine, watch the video below: ## Time Series Index (TSI) As data cardinality (the number of series) grows, queries read more series keys and become slower. The **Time Series Index** ensures queries remain fast as data cardinality grows. The TSI stores series keys grouped by measurement, tag, and field. This allows the database to answer two questions well: * What measurements, tags, fields exist? (This happens in meta queries.) * Given a measurement, tags, and fields, what series keys exist? #### Related * [InfluxDB TSM Engine](/resources/videos/tsm-engine/) * [Manage InfluxDB internal systems](/influxdb/v2/admin/internals/) [storage](/influxdb/v2/tags/storage/)[internals](/influxdb/v2/tags/internals/) --- # InfluxDB system buckets Source: https://docs.influxdata.com/influxdb/v2/reference/internals/system-buckets/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB system buckets contain time series data used by and generated from the InfluxDB monitoring and alerting system and the task engine. Each InfluxDB organization includes the following system buckets: * [\_monitoring](#_monitoring-system-bucket) * [\_tasks](#_tasks-system-bucket) > [!Note] > The system bucket schemas below reference **InfluxDB data elements**. > For more information, see [InfluxDB key concepts](/influxdb/v2/reference/key-concepts/data-elements/). ## \_monitoring system bucket The `_monitoring` system bucket stores InfluxDB data used to[monitor data and send alerts](/influxdb/v2/monitor-alert/). **Data retention:** 7 days ### \_monitoring bucket schema * **statuses** *(measurement)* * **tags:** * **\_check\_id:** check ID * **\_check\_name:** check name * **\_level:** level evaluated by the check (ok, info, warn, or crit) * **\_source\_measurement:** original measurement queried by the check * **\_type:** check type (threshold or deadman) * *other tags inherited from queried data or added in the check configuration* * **fields:** * **\_message:** message generated by the check * **\_source\_timestamp:** original timestamp of the queried data * *other fields inherited from queried data* * **notifications** *(measurement)* * **tags:** * **\_check\_id:** check ID that triggered the notification * **\_check\_name:** check name that triggered the notification * **\_level:** check-evaluated level that triggered the notification (ok, info, warn, or crit) * **\_notification\_endpoint\_id:** notification endpoint ID * **\_notification\_endpoint\_name:** notification endpoint name * **\_notification\_rule\_id:** notification rule ID * **\_notification\_rule\_name:** notification rule name * **\_sent:** sent status (true or false) * **\_source\_measurement:** original measurement queried by the check * **\_type:** check type (threshold or deadman) * *other tags inherited from queried data or added in the check configuration* * **fields:** * **\_message:** message generated by the check * **\_source\_timestamp:** original timestamp of the queried data * **\_status\_timestamp:** timestamp when the status (`_level`) was evaluated * *other fields inherited from queried data* * ## \_tasks system bucket The `_tasks` system bucket stores data related to [InfluxDB task](/influxdb/v2/process-data/) executions. **Data retention:** 3 days ### \_tasks bucket schema *A **task run** refers to a single task execution.* * **runs** *(measurement)* * **tags:** * **status:** task run status (success or failed) * **taskID:** task ID * **fields:** * **finishedAt:** timestamp when the task run finished * **logs:** log output from the task run * **requestedAt:** timestamp when the task run was requested * **runID** task run ID * **scheduledFor:** timestamp the task run was scheduled for * **startedAt:** timestamp when the task run started #### Related * [Monitor data and send alerts](/influxdb/v2/monitor-alert/) * [Process data with InfluxDB tasks](/influxdb/v2/process-data/) * [monitor.check() function](/flux/v0/stdlib/influxdata/influxdb/monitor/check/) * [monitor.deadman() function](/flux/v0/stdlib/influxdata/influxdb/monitor/deadman/) * [monitor.from() function](/flux/v0/stdlib/influxdata/influxdb/monitor/from/) * [monitor.logs() function](/flux/v0/stdlib/influxdata/influxdb/monitor/logs/) * [monitor.notify() function](/flux/v0/stdlib/influxdata/influxdb/monitor/notify/) [buckets](/influxdb/v2/tags/buckets/) --- # InfluxDB key concepts Source: https://docs.influxdata.com/influxdb/v2/reference/key-concepts/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Before working with InfluxDB 2.10, it’s helpful to learn a few key concepts. Browse the topics and videos below to learn more. ### [InfluxDB data elements](/influxdb/v2/reference/key-concepts/data-elements/) InfluxDB structures data using elements such as timestamps, field keys, field values, tags, etc. ### [InfluxDB data schema](/influxdb/v2/reference/key-concepts/data-schema/) InfluxDB uses a tabular data schema for displaying raw data in Data Explorer and for returning query results in annotated CSV syntax. ### [InfluxDB design principles](/influxdb/v2/reference/key-concepts/design-principles/) Principles and tradeoffs related to InfluxDB design. [key concepts](/influxdb/v2/tags/key-concepts/) --- # InfluxDB data elements Source: https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-elements/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB 2.10 includes the following data elements: * [Timestamp](#timestamp) * [Measurement](#measurement) * [Fields](#fields) * [Field key](#field-key) * [Field value](#field-value) * [Field set](#field-set) * [Tags](#tags) * [Tag key](#tag-key) * [Tag value](#tag-value) * [Tag set](#tag-set) * [Series](#series) * [Point](#point) * [Bucket](#bucket) * [Organization](#organization) The following sample data represents time series records stored in InfluxDB and is used to illustrate data elements concepts.*Hover over highlighted terms to get acquainted with InfluxDB terminology and layout.*[]() **bucket:** `my_bucket` | \_time |\_measurement|location|scientist|\_field|\_value| |--------------------|-------------|--------|---------|-------|-------| |2019-08-18T00:00:00Z| census |klamath |anderson | bees | 23 | |2019-08-18T00:00:00Z| census |portland| mullen | ants | 30 | |2019-08-18T00:06:00Z| census |klamath |anderson | bees | 28 | |2019-08-18T00:06:00Z| census |portland| mullen | ants | 32 | ## Timestamp All data stored in InfluxDB has a `_time` column that stores timestamps. On disk, timestamps are stored in epoch nanosecond format. InfluxDB formats timestamps show the date and time in [RFC3339](/influxdb/v2/reference/glossary/#rfc3339-timestamp) UTC associated with data. Timestamp precision is important when you write data. ## Measurement The `_measurement` column shows the name of the measurement `census`. Measurement names are strings. A measurement acts as a container for tags, fields, and timestamps. Use a measurement name that describes your data. The name `census` tells us that the field values record the number of `bees` and `ants`. ## Fields A field includes a field key stored in the `_field` column and a field value stored in the `_value` column. ### Field key A field key is a string that represents the name of the field. In the preceding [sample data](#sample-data), `bees` and `ants` are field keys. ### Field value A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the sample data show the number of `bees` at specified times: `23`, and `28` and the number of `ants` at a specified time: `30` and `32`. ### Field set A field set is a collection of field key-value pairs associated with a timestamp. The [sample data](#sample-data) includes the following field sets: ```text census bees=23i,ants=30i 1566086400000000000 census bees=28i,ants=32i 1566086760000000000 ----------------- Field set ``` > [!Note] > #### Fields aren’t indexed > > Fields are required in InfluxDB data and are not indexed. > Queries that filter field values must scan all field values to match query conditions. > As a result, queries on tags are more performant than queries on fields. > > See how to [use tags and fields](/influxdb/v2/write-data/best-practices/schema-design/#use-tags-and-fields) to make your schema easier to query. ## Tags The columns in the sample data, `location` and `scientist`, are tags. Tags include tag keys and tag values that are stored as strings and metadata. ### Tag key The tag keys in the sample data are `location` and `scientist`.*For information about tag key requirements, see [Line protocol – Tag set](/influxdb/v2/reference/syntax/line-protocol/#tag-set).* ### Tag value The tag key `location` has two tag values: `klamath` and `portland`. The tag key `scientist` also has two tag values: `anderson` and `mullen`.*For information about tag value requirements, see [Line protocol – Tag set](/influxdb/v2/reference/syntax/line-protocol/#tag-set).* ### Tag set The collection of tag key-value pairs make up a tag set. The sample data includes the following four tag sets: ```bash location = klamath, scientist = anderson location = portland, scientist = anderson location = klamath, scientist = mullen location = portland, scientist = mullen ``` > [!Note] > #### Tags are indexed > > Tags are optional. > You don’t need tags in your data structure, but it’s typically a good idea to include them. > Because InfluxDB indexes tags, the query engine doesn’t need to scan every record in a bucket to locate a tag value. > See how to [use tags to improve query performance](/influxdb/v2/write-data/best-practices/schema-design/#use-tags-to-improve-query-performance). ### Why your schema matters How you structure measurements, fields, and tags in your data can make queries easier to write and more performant. Good [schema design](/influxdb/v2/write-data/best-practices/schema-design) can prevent [high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/), resulting in better performing queries. ## Series Now that you’re familiar with measurements, field sets, and tag sets, it’s time to discuss series keys and series. In InfluxDB OSS (TSM), a [series key](/influxdb/v2/reference/glossary/#series-key) is a unique combination of measurement and tag set. For example, the [sample data](#sample-data) includes two unique series keys: |measurement| tag set | |-----------|-----------------------------------| | census |location=klamath,scientist=anderson| | census |location=portland,scientist=mullen | A *series* includes timestamps and field values for a given series key–for example, the sample data contains the following series key and corresponding series: ### Sample data series * census,location=klamath,scientist=anderson * 2019-08-18T00:00:00Z 23 * 2019-08-18T00:06:00Z 28 Understanding the concept of a series is essential when [designing your schema](/influxdb/v2/write-data/best-practices/schema-design/) and working with your data in InfluxDB. ## Point A **point** includes the series key, a field value, and a timestamp–for example, a single point from the [sample data](#sample-data): `2019-08-18T00:00:00Z census ants 30 portland mullen` ## Bucket All InfluxDB data is stored in a bucket. A **bucket** combines the concept of a database and a retention period (the duration of time that each data point persists). A bucket belongs to an organization. For more information about buckets, see [Manage buckets](/influxdb/v2/admin/buckets/). ## Organization An InfluxDB **organization** is a workspace for a group of [users](/influxdb/v2/admin/users/). All [dashboards](/influxdb/v2/visualize-data/dashboards/), [tasks](/influxdb/v2/process-data/), buckets, and users belong to an organization. For more information about organizations, see [Manage organizations](/influxdb/v2/admin/organizations/). If you’re new to using InfluxDB, see how to [get started](/influxdb/v2/get-started) writing and querying data. For an overview of how these elements interconnect within InfluxDB’s data model, watch the following video: #### Related * [Building Blocks of the InfluxDB Data Model](/resources/videos/data-model-building-blocks/) * [Resolve high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/) * [InfluxDB schema design](/influxdb/v2/write-data/best-practices/schema-design/) [key concepts](/influxdb/v2/tags/key-concepts/)[schema](/influxdb/v2/tags/schema/) | _time | _measurement | location | scientist | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | location | scientist | _field | _value | | 2019-08-18T00:00:00Z | census | klamath | anderson | bees | 23 | | 2019-08-18T00:00:00Z | census | portland | mullen | ants | 30 | | 2019-08-18T00:06:00Z | census | klamath | anderson | bees | 28 | | 2019-08-18T00:06:00Z | census | portland | mullen | ants | 32 | | measurement | tag set | | --- | --- | | measurement | tag set | | census | location=klamath,scientist=anderson | | census | location=portland,scientist=mullen | --- # InfluxDB data schema Source: https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-schema/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB [data elements](/influxdb/v2/reference/key-concepts/data-elements/) are stored in **time-structured merge tree (TSM)** and **time series index (TSI)** files to efficiently compact stored data. InfluxDB also provides a **tabular data schema** that includes the following: * [Annotation rows](#annotation-rows) * [Header row](#header-row) * [Data rows](#data-rows) * [Other columns](#other-columns) * [Group keys](#group-keys) The **tabular data schema is used for the following**: * To [view raw data](/influxdb/v2/query-data/execute-queries/data-explorer/#view-raw-data) when [exploring metrics with InfluxDB](/influxdb/v2/visualize-data/explore-metrics) * To return query results in [annotated CSV syntax](/influxdb/v2/reference/syntax/annotated-csv/) ## Annotation rows Annotation rows describe column properties, for example: * `#group` * `#datatype` * `#default` ## Header row The header row defines column labels that describe data in each column, for example: * `table` * `_time` * `_value` * `_field` * `_measurement` * tag key names (without underscore prefix): `tag-1`, `tag-2` ## Data rows Each data row contains the data specified in the header row for one [point](/influxdb/v2/reference/glossary/#point). ## Other columns In addition to the columns in each data row (specified in the header row), the following columns are optional: * `annotation` * `result` * `table` ## Group keys Determine the contents of output tables in Flux by grouping records that share common values in specified columns. Learn more about [grouping your data with Flux](/influxdb/v2/query-data/flux/group-data/). [key concepts](/influxdb/v2/tags/key-concepts/) --- # InfluxDB design principles Source: https://docs.influxdata.com/influxdb/v2/reference/key-concepts/design-principles/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB implements optimal design principles for time series data. Some of these design principles may have associated tradeoffs in performance. * [Time-ordered data](#time-ordered-data) * [Strict update and delete permissions](#strict-update-and-delete-permissions) * [Handle read and write queries first](#handle-read-and-write-queries-first) * [Schemaless design](#schemaless-design) * [Datasets over individual points](#datasets-over-individual-points) * [Duplicate data](#duplicate-data) ## Time-ordered data To improve performance, data is written in time-ascending order. ## Strict update and delete permissions To increase query and write performance, InfluxDB tightly restricts **update** and **delete** permissions. Time series data is predominantly new data that is never updated. Deletes generally only affect data that isn’t being written to, and contentious updates never occur. ## Handle read and write queries first InfluxDB prioritizes read and write requests over strong consistency. InfluxDB returns results when a query is executed. Any transactions that affect the queried data are processed subsequently to ensure that data is eventually consistent. Therefore, if the ingest rate is high (multiple writes per ms), query results may not include the most recent data. ## Schemaless design InfluxDB uses a schemaless design to better manage discontinuous data. Time series data are often ephemeral, meaning the data appears for a few hours and then goes away. For example, a new host that gets started and reports for a while and then gets shut down. ## Datasets over individual points Because the data set is more important than an individual point, InfluxDB implements powerful tools to aggregate data and handle large data sets. Points are differentiated by timestamp and series, so don’t have IDs in the traditional sense. ## Duplicate data To simplify conflict resolution and increase write performance, InfluxDB assumes data sent multiple times is duplicate data. Identical points aren’t stored twice. If a new field value is submitted for a point, InfluxDB updates the point with the most recent field value. In rare circumstances, data may be overwritten. Learn more about [duplicate points](/influxdb/v2/write-data/best-practices/duplicate-points/). [key concepts](/influxdb/v2/tags/key-concepts/)[design principles](/influxdb/v2/tags/design-principles/) --- # Prometheus metric parsing formats Source: https://docs.influxdata.com/influxdb/v2/reference/prometheus-metrics/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Prometheus-formatted metrics](https://prometheus.io/docs/concepts/data_model/)are parsed and written to InfluxDB in one of two formats, depending on the scraping tool used: * [Metric version 1](#metric-version-1) * [Metric version 2](#metric-version-2) #### Scraping tools and parsing format | Scraping tool | InfluxDB Metric version | |-----------------------------------------------------------------------------|-----------------------------------------------------| | [Telegraf Prometheus plugin](/telegraf/v1/plugins/#input-prometheus) |*Determined by `metric_version` configuration option*| | [InfluxDB scraper](/influxdb/v2/write-data/no-code/scrape-data/) | 1 | |Flux [`prometheus.scrape()`](/flux/v0/stdlib/experimental/prometheus/scrape/)| 2 | ## Metric version 1 * **\_time**: timestamp * **\_measurement**: [Prometheus metric name](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)*(`_bucket`, `_sum`, and `_count` are trimmed from histogram and summary metric names)* * **\_field**: *depends on the [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/)* * Counter: `counter` * Gauge: `gauge` * Histogram: *histogram bucket upper limits*, `count`, `sum` * Summary: *summary quantiles*, `count`, `sum` * **\_value**: [Prometheus metric value](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) * **tags**: A tag for each [Prometheus label](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)*(except for histogram bucket upper limits (`le`) or summary quantiles (`quantile`))*. The label name is the tag key and the label value is the tag value. ### Example Prometheus query results The following are example Prometheus metrics scraped from the **InfluxDB OSS 2.x `/metrics`** endpoint: ```sh # HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. # TYPE go_memstats_alloc_bytes_total counter go_memstats_alloc_bytes_total 1.42276424e+09 # HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. # TYPE go_memstats_buck_hash_sys_bytes gauge go_memstats_buck_hash_sys_bytes 5.259247e+06 # HELP task_executor_run_latency_seconds Records the latency between the time the run was due to run and the time the task started execution, by task type # TYPE task_executor_run_latency_seconds histogram task_executor_run_latency_seconds_bucket{task_type="system",le="0.25"} 4413 task_executor_run_latency_seconds_bucket{task_type="system",le="0.5"} 11901 task_executor_run_latency_seconds_bucket{task_type="system",le="1"} 12565 task_executor_run_latency_seconds_bucket{task_type="system",le="2.5"} 12823 task_executor_run_latency_seconds_bucket{task_type="system",le="5"} 12844 task_executor_run_latency_seconds_bucket{task_type="system",le="10"} 12864 task_executor_run_latency_seconds_bucket{task_type="system",le="+Inf"} 74429 task_executor_run_latency_seconds_sum{task_type="system"} 4.256783538679698e+11 task_executor_run_latency_seconds_count{task_type="system"} 74429 # HELP task_executor_run_duration The duration in seconds between a run starting and finishing. # TYPE task_executor_run_duration summary task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.5"} 5.178160855 task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.9"} 5.178160855 task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.99"} 5.178160855 task_executor_run_duration_sum{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 2121.9758301650004 task_executor_run_duration_count{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 570 ``` #### Resulting line protocol ``` go_memstats_alloc_bytes_total counter=1.42276424e+09 go_memstats_buck_hash_sys_bytes gauge=5.259247e+06 task_executor_run_latency_seconds,task_type=system 0.25=4413,0.5=11901,1=12565,2.5=12823,5=12844,10=12864,+Inf=74429,sum=4.256783538679698e+11,count=74429 task_executor_run_duration,taskID=00xx0Xx0xx00XX0x0,task_type=threshold 0.5=5.178160855,0.9=5.178160855,0.99=5.178160855,sum=2121.9758301650004,count=570 ``` [](#view-version-1-tables-when-queried-from-influxdb) View version 1 tables when queried from InfluxDB | \_time | \_measurement |\_field| \_value | |--------------------|---------------------------------|-------|------------| |2021-01-01T00:00:00Z|go\_memstats\_alloc\_bytes\_total|counter|1422764240.0| | \_time | \_measurement |\_field| \_value | |--------------------|------------------------------------|-------|---------| |2021-01-01T00:00:00Z|go\_memstats\_buck\_hash\_sys\_bytes| gauge |5259247.0| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | 0.25 |4413.0 | | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | 0.5 |11901.0| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | 1 |12565.0| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | 2.5 |12823.0| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | 5 |12844.0| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | \+Inf |74429.0| | \_time | \_measurement |task\_type|\_field| \_value | |--------------------|-------------------------------------|----------|-------|-----------------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | sum |425678353867.9698| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-------------------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_latency\_seconds| system | count |74429.0| | \_time | \_measurement |task\_type|\_field| \_value | |--------------------|-----------------------------|----------|-------|-----------| |2021-01-01T00:00:00Z|task\_executor\_run\_duration|threshold | 0.5 |5.178160855| | \_time | \_measurement |task\_type|\_field| \_value | |--------------------|-----------------------------|----------|-------|-----------| |2021-01-01T00:00:00Z|task\_executor\_run\_duration|threshold | 0.9 |5.178160855| | \_time | \_measurement |task\_type|\_field| \_value | |--------------------|-----------------------------|----------|-------|-----------| |2021-01-01T00:00:00Z|task\_executor\_run\_duration|threshold | 0.99 |5.178160855| | \_time | \_measurement |task\_type|\_field| \_value | |--------------------|-----------------------------|----------|-------|------------------| |2021-01-01T00:00:00Z|task\_executor\_run\_duration|threshold | sum |2121.9758301650004| | \_time | \_measurement |task\_type|\_field|\_value| |--------------------|-----------------------------|----------|-------|-------| |2021-01-01T00:00:00Z|task\_executor\_run\_duration|threshold | count | 570.0 | ## Metrics version 2 * **\_time**: timestamp * **\_measurement**: `prometheus` * **\_field**: [Prometheus metric name](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)*(`_bucket` is trimmed from histogram metric names)* * **\_value**: [Prometheus metric value](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) * **url**: URL metrics were scraped from * **tags**: A tag for each [Prometheus label](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels). The label name is the tag key and the label value is the tag value. ### Example Prometheus query results The following are example Prometheus metrics scraped from the **InfluxDB OSS 2.x `/metrics`** endpoint: ```sh # HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. # TYPE go_memstats_alloc_bytes_total counter go_memstats_alloc_bytes_total 1.42276424e+09 # HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. # TYPE go_memstats_buck_hash_sys_bytes gauge go_memstats_buck_hash_sys_bytes 5.259247e+06 # HELP task_executor_run_latency_seconds Records the latency between the time the run was due to run and the time the task started execution, by task type # TYPE task_executor_run_latency_seconds histogram task_executor_run_latency_seconds_bucket{task_type="system",le="0.25"} 4413 task_executor_run_latency_seconds_bucket{task_type="system",le="0.5"} 11901 task_executor_run_latency_seconds_bucket{task_type="system",le="1"} 12565 task_executor_run_latency_seconds_bucket{task_type="system",le="2.5"} 12823 task_executor_run_latency_seconds_bucket{task_type="system",le="5"} 12844 task_executor_run_latency_seconds_bucket{task_type="system",le="10"} 12864 task_executor_run_latency_seconds_bucket{task_type="system",le="+Inf"} 74429 task_executor_run_latency_seconds_sum{task_type="system"} 4.256783538679698e+11 task_executor_run_latency_seconds_count{task_type="system"} 74429 # HELP task_executor_run_duration The duration in seconds between a run starting and finishing. # TYPE task_executor_run_duration summary task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.5"} 5.178160855 task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.9"} 5.178160855 task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.99"} 5.178160855 task_executor_run_duration_sum{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 2121.9758301650004 task_executor_run_duration_count{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 570 ``` #### Resulting line protocol ``` prometheus,url=http://localhost:8086/metrics go_memstats_alloc_bytes_total=1.42276424e+09 prometheus,url=http://localhost:8086/metrics go_memstats_buck_hash_sys_bytes=5.259247e+06 prometheus,url=http://localhost:8086/metrics,task_type=system,le=0.25 task_executor_run_latency_seconds=4413 prometheus,url=http://localhost:8086/metrics,task_type=system,le=0.5 task_executor_run_latency_seconds=11901 prometheus,url=http://localhost:8086/metrics,task_type=system,le=1 task_executor_run_latency_seconds=12565 prometheus,url=http://localhost:8086/metrics,task_type=system,le=2.5 task_executor_run_latency_seconds=12823 prometheus,url=http://localhost:8086/metrics,task_type=system,le=5 task_executor_run_latency_seconds=12844 prometheus,url=http://localhost:8086/metrics,task_type=system,le=10 task_executor_run_latency_seconds=12864 prometheus,url=http://localhost:8086/metrics,task_type=system,le=+Inf task_executor_run_latency_seconds=74429 prometheus,url=http://localhost:8086/metrics,task_type=system task_executor_run_latency_seconds_sum=4.256783538679698e+11 prometheus,url=http://localhost:8086/metrics,task_type=system task_executor_run_latency_seconds_count=74429 prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.5 task_executor_run_duration=5.178160855 prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.9 task_executor_run_duration=5.178160855 prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.99 task_executor_run_duration=5.178160855 prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold task_executor_run_duration_sum=2121.9758301650004 prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold task_executor_run_duration_count=570 ``` [](#view-version-2-tables-when-queried-from-influxdb) View version 2 tables when queried from InfluxDB | \_time |\_measurement| url | \_field | \_value | |--------------------|-------------|-----------------------------|---------------------------------|------------| |2021-01-01T00:00:00Z| prometheus |http://localhost:8086/metrics|go\_memstats\_alloc\_bytes\_total|1422764240.0| | \_time |\_measurement| url | \_field | \_value | |--------------------|-------------|-----------------------------|------------------------------------|---------| |2021-01-01T00:00:00Z| prometheus |http://localhost:8086/metrics|go\_memstats\_buck\_hash\_sys\_bytes|5259247.0| | \_time |\_measurement|task\_type| url | le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|----|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|0.25|task\_executor\_run\_latency\_seconds| 4413 | | \_time |\_measurement|task\_type| url |le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|---|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|0.5|task\_executor\_run\_latency\_seconds| 11901 | | \_time |\_measurement|task\_type| url |le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|---|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics| 1 |task\_executor\_run\_latency\_seconds| 12565 | | \_time |\_measurement|task\_type| url |le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|---|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|2.5|task\_executor\_run\_latency\_seconds| 12823 | | \_time |\_measurement|task\_type| url |le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|---|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics| 5 |task\_executor\_run\_latency\_seconds| 12844 | | \_time |\_measurement|task\_type| url | le | \_field |\_value| |--------------------|-------------|----------|-----------------------------|-----|-------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|\+Inf|task\_executor\_run\_latency\_seconds| 74429 | | \_time |\_measurement|task\_type| url | \_field | \_value | |--------------------|-------------|----------|-----------------------------|------------------------------------------|-----------------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|task\_executor\_run\_latency\_seconds\_sum|425678353867.9698| | \_time |\_measurement|task\_type| url | \_field |\_value| |--------------------|-------------|----------|-----------------------------|--------------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus | system |http://localhost:8086/metrics|task\_executor\_run\_latency\_seconds\_count| 74429 | | \_time |\_measurement|task\_type| taskID | url |quantile| \_field | \_value | |--------------------|-------------|----------|-----------------|-----------------------------|--------|-----------------------------|-----------| |2021-01-01T00:00:00Z| prometheus |threshold |00xx0Xx0xx00XX0x0|http://localhost:8086/metrics| 0.5 |task\_executor\_run\_duration|5.178160855| | \_time |\_measurement|task\_type| taskID | url |quantile| \_field | \_value | |--------------------|-------------|----------|-----------------|-----------------------------|--------|-----------------------------|-----------| |2021-01-01T00:00:00Z| prometheus |threshold |00xx0Xx0xx00XX0x0|http://localhost:8086/metrics| 0.9 |task\_executor\_run\_duration|5.178160855| | \_time |\_measurement|task\_type| taskID | url |quantile| \_field | \_value | |--------------------|-------------|----------|-----------------|-----------------------------|--------|-----------------------------|-----------| |2021-01-01T00:00:00Z| prometheus |threshold |00xx0Xx0xx00XX0x0|http://localhost:8086/metrics| 0.99 |task\_executor\_run\_duration|5.178160855| | \_time |\_measurement|task\_type| taskID | url | \_field | \_value | |--------------------|-------------|----------|-----------------|-----------------------------|----------------------------------|------------------| |2021-01-01T00:00:00Z| prometheus |threshold |00xx0Xx0xx00XX0x0|http://localhost:8086/metrics|task\_executor\_run\_duration\_sum|2121.9758301650004| | \_time |\_measurement|task\_type| taskID | url | \_field |\_value| |--------------------|-------------|----------|-----------------|-----------------------------|------------------------------------|-------| |2021-01-01T00:00:00Z| prometheus |threshold |00xx0Xx0xx00XX0x0|http://localhost:8086/metrics|task\_executor\_run\_duration\_count| 570 | #### Related * [Prometheus data model](https://prometheus.io/docs/concepts/data_model/) * [Scrape Prometheus metrics](/influxdb/v2/write-data/developer-tools/scrape-prometheus-metrics/) * [Work with Prometheus in Flux](/flux/v0/prometheus/) * [Telegraf Prometheus input plugin](/telegraf/v1/plugins/#input-prometheus) * [Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) * [prometheus.scrape() function](/flux/v0/stdlib/experimental/prometheus/scrape/) [prometheus](/influxdb/v2/tags/prometheus/) | Scraping tool | InfluxDB Metric version | | --- | --- | | Scraping tool | InfluxDB Metric version | | Telegraf Prometheus plugin | Determined by metric_version configuration option | | InfluxDB scraper | 1 | | Flux prometheus.scrape() | 2 | | _time | _measurement | _field | _value | | --- | --- | --- | --- | | _time | _measurement | _field | _value | | 2021-01-01T00:00:00Z | go_memstats_alloc_bytes_total | counter | 1422764240.0 | | _time | _measurement | _field | _value | | --- | --- | --- | --- | | _time | _measurement | _field | _value | | 2021-01-01T00:00:00Z | go_memstats_buck_hash_sys_bytes | gauge | 5259247.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | 0.25 | 4413.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | 0.5 | 11901.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | 1 | 12565.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | 2.5 | 12823.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | 5 | 12844.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | +Inf | 74429.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | sum | 425678353867.9698 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_latency_seconds | system | count | 74429.0 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_duration | threshold | 0.5 | 5.178160855 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_duration | threshold | 0.9 | 5.178160855 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_duration | threshold | 0.99 | 5.178160855 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_duration | threshold | sum | 2121.9758301650004 | | _time | _measurement | task_type | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | task_type | _field | _value | | 2021-01-01T00:00:00Z | task_executor_run_duration | threshold | count | 570.0 | | _time | _measurement | url | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | http://localhost:8086/metrics | go_memstats_alloc_bytes_total | 1422764240.0 | | _time | _measurement | url | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | http://localhost:8086/metrics | go_memstats_buck_hash_sys_bytes | 5259247.0 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | 0.25 | task_executor_run_latency_seconds | 4413 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | 0.5 | task_executor_run_latency_seconds | 11901 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | 1 | task_executor_run_latency_seconds | 12565 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | 2.5 | task_executor_run_latency_seconds | 12823 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | 5 | task_executor_run_latency_seconds | 12844 | | _time | _measurement | task_type | url | le | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | le | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | +Inf | task_executor_run_latency_seconds | 74429 | | _time | _measurement | task_type | url | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | task_executor_run_latency_seconds_sum | 425678353867.9698 | | _time | _measurement | task_type | url | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | system | http://localhost:8086/metrics | task_executor_run_latency_seconds_count | 74429 | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | --- | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | 2021-01-01T00:00:00Z | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.5 | task_executor_run_duration | 5.178160855 | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | --- | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | 2021-01-01T00:00:00Z | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.9 | task_executor_run_duration | 5.178160855 | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | --- | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | taskID | url | quantile | _field | _value | | 2021-01-01T00:00:00Z | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.99 | task_executor_run_duration | 5.178160855 | | _time | _measurement | task_type | taskID | url | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | taskID | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | task_executor_run_duration_sum | 2121.9758301650004 | | _time | _measurement | task_type | taskID | url | _field | _value | | --- | --- | --- | --- | --- | --- | --- | | _time | _measurement | task_type | taskID | url | _field | _value | | 2021-01-01T00:00:00Z | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | task_executor_run_duration_count | 570 | --- # Release notes Source: https://docs.influxdata.com/influxdb/v2/reference/release-notes/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Find important information about what’s included in new versions of our products: ### [InfluxDB OSS v2 release notes](/influxdb/v2/reference/release-notes/influxdb/) Important changes and what’s new in each version of InfluxDB. ### [influx CLI release notes](/influxdb/v2/reference/release-notes/influx-cli/) Important changes and what’s new in each version of the influx command line interface (CLI). ### [Supported releases](/influxdb/v2/reference/release-notes/supported-release/) Supported releases made to InfluxData. --- # influx CLI release notes Source: https://docs.influxdata.com/influxdb/v2/reference/release-notes/influx-cli/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## v2.9.1 ### Maintenance * Update to go 1.27.3 ## v2.8.0 ### Bug Fixes * Check for all available cookies instead of the count * Don’t import non-existent/unused GPG private key * Create errors-file if it does not exist * Avoid panic on empty tag value * Dbrp correct json output ### Features * Add `--operator-token` flag to restore subcommand * Adds gzip compression level configuration to backups for v2 (requires InfluxDB v2.9+) ### Maintenance * Bump `golang.org/x/text` from 0.3.7 to 0.3.8 * Bump `google.golang.org/protobuf` from 1.30.0 to 1.33.0 * Update to go 1.25.9 ## v2.7.5 ### Maintenance * Upgrade to Go 1.21.9. ## v2.7.4 ### Bug fixes * Disable password length checks to allow InfluxDB to validate passwords. * Handle line protocol line-wrapping with `--skipRowOnError`. ## v2.7.3 ### Bug fixes * Correct packaging for RPM and Windows ZIPs. * Properly handle multiple cookies with `--username-password` flag. ### Maintenance * Upgrade `go` to 1.20.3. ## v2.7.1 ### Features * Add new replication field to better show queue synchronization progress. ### Bug fixes * Update the API for deleting secrets so `influx secret delete` command works correctly. * Fix typo in alias of `bucket update` command. ### Maintenance * Use `fpm` for packaging. * Update `openapi`. * Upgrade `go releaser` to v1.13.1. * Upgrade `go` to 1.19.6. * Bump `sys` to v0.6.0 to support `riscv`. ## v2.6.1 * Internal code cleanup. ## v2.6.0 ### Bug fixes * When using [`influx task create`](/influxdb/v2/reference/cli/influx/task/create/)to create a new task, only override the `every` task option defined in the Flux script when the `-e`,`--every` flag is provided. * Properly clear the terminal when exiting an InfluxQL shell. ### Maintenance * Upgrade Go to 1.19.4. * Update to `openapi` 5.1.1 to enable arm builds. ## v2.5.0 ### Features * Add the `--username-password` flag to [influx config set](/influxdb/v2/reference/cli/influx/config/set/). Include `username:password` after this flag to ensure a session is automatically authenticated for the config. Include `username` (without password) to prompt for a password before creating the session. ### Maintenance * Upgrade to Go 1.19. * Fix Go version in `go.mod`. ### Bug fixes * Fix to allow [influx auth create](/influxdb/v2/reference/cli/influx/auth/create/) to successfully create an API token without error. * Fix stack error typo. * Fix an error where `stdin` could not be used to create tasks. * Update `data_type` to `dataType` to ensure CSV files are successfully uploaded. * Fix to let you create a remote connection for InfluxDB 1.x without requiring a remote org ID (`remoteOrgID`). Add warning that `remoteOrgID` is required for InfluxDB Cloud and InfluxDB OSS, but not required for InfluxDB 1.x (OSS or Enterprise). ## v2.4.0 ### Features * Set membership type to member or owner with[`influx org members add`](/influxdb/v2/reference/cli/influx/org/members/add/). * Add the [InfluxQL Shell (REPL)](/influxdb/v2/reference/cli/influx/v1/shell/). * **(InfluxDB Cloud only)** Manage [InfluxDB Cloud Invokable Scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)with [`influx scripts`](/influxdb/v2/reference/cli/influx/scripts/). * **(InfluxDB OSS only)** Add [username and password support](/influxdb/v2/reference/cli/influx/config/create/#create-a-connection-configuration-that-uses-a-username-and-password)to `influx` CLI connection configurations as alternative to API tokens when using the CLI. ### Maintenance * Upgrade to Go 1.18.3 ### Bug fixes * No longer scope user and organizations permissions to an individual organization. * Properly handle API tokens starting with a hyphen (`-`) passed to the CLI without `=`. * Mutually exclude organization names and organization IDs to eliminate confusion on which to use and whether or not environment variables are overriding command flags. ## v2.3.0 ### Features * Add [`influx remote`](/influxdb/v2/reference/cli/influx/remote/) command. * Add [`influx replication`](/influxdb/v2/reference/cli/influx/replication/) command. * Enhanced error messaging for InfluxDB and OSS specific commands. * Add `api/v2/config` endpoint to display the runtime configuration (for example, when you run `influxd print-config`). This endpoint lets you review runtime configuration while the instance is live. ### Bug fixes * `Auth create` command supports multiple buckets. * Use `influx-debug-id` header for tracing. * Duration parser shows duration missing units on error. * Template apply uses improved diff checking. * Fix error applying `-e jsonnet` template. ## v2.2.1 This release includes two new bug fixes. ### Bug fixes * Improve error messages for unknown subcommands (`Error: command “…” not recognized.`) by describing how to run `./influx --help` to see a list of valid commands. Thanks @slai! * Ensure `org members remove` API calls successfully remove a member from an organization by fixing accidental swap of `orgID` and `userID`. Thanks @geek981108! ## v2.2.0 This release includes three new features and bug fixes. ### Features This release makes it easier to create API tokens with the `influx` CLI, adds support for viewing more than 20 buckets using `influx bucket list`, and adds a shorthand flag for bucket (`-b`) to `influx delete`. #### Create an Operator token in the influx CLI Add the ability to use the `influx` CLI to [create an Operator token](/influxdb/v2/admin/tokens/#operator-token) with read and write permissions to all resources in all organizations available in InfluxDB. (Note, this is the same permissions generated for the initial token created by `influx setup` or `influxd upgrade`.) #### Create an All Access token in the influx CLI Add the ability to use the `influx` CLI to [create an All Access API token](/influxdb/cloud/admin/tokens/create-token/#create-a-token-using-the-influx-cli) with read and write permissions to all resources in an organization. #### View more buckets in the influx CLI Update [`influx bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) with pagination to support displaying more than 20 buckets. By default, buckets are fetched in batches of 20; set `--page-size` to override this default value. You may also limit the total number of buckets to display with `--limit` (by default, there’s no limit). #### New bucket shorthand for influx delete Add the shorthand flag `-b` for `--bucket` to [`influx delete`](/influxdb/cloud/reference/cli/influx/delete/). ### Bug fixes * Detect and warn when the Operator token is changed using `influx restore` (either setting a new `--active` config or updating the `INFLUX_TOKEN` variable). * Set newly-created connection configuration as active in `influx setup`. * Embed timezone data into Windows builds to avoid errors. ## v2.1.1 ### Go version Upgrade to Go 1.17. ### Bug fixes * Fix shell completion for top-level `influx` commands. * Make global `--http-debug` flag visible in help text. * Don’t set empty strings for IDs in permission resources. * Detect and error out on incorrect positional arguments. * Respect value of `--host` flag when writing CLI configs in `setup`. ## v2.1.0 ### New repository This is the initial release of the `influx` CLI from the `influxdata/influx-cli` GitHub repository. ### Breaking changes #### `influx write` skip-header parsing To simplify the CLI parser, the `write` command no longer supports `--skipHeader`as short-hand for `--skipHeader 1`. #### Stricter input validation for `influx template` commands The `apply`, `export`, and `stacks` commands now raise errors when CLI options fail to parse instead of silently discarding bad inputs. This change was made to help users debug when their commands fail to execute as expected. #### Server-side template summarization and validation The `template` and `template validate` commands now use an API request to the server to perform their logic, instead of performing the work on the client-side. Offline summarization and validation is no longer supported. This change was made to avoid significant code duplication between `influxdb` and `influx CLI`, and to allow server-side template logic to evolve without requiring coordinated CLI changes. #### `influx stacks --json` output conventions The output of `influx stacks --json` previously used an UpperCamelCase naming convention for most keys. The command now uses lowerCamelCase consistently for all objects keys, matching the schema returned by the API. ### Features * Add global `--http-debug` flag to all `influx` commands to help inspect communication with InfluxDB servers. * Update [`bucket create`](/influxdb/cloud/reference/cli/influx/bucket/create/) to allow setting a schema type. * Update [`bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) to display schema types. * Bind [`--skip-verify`](/influxdb/cloud/reference/cli/influx/org/members/add/#flags) flag to the `INFLUX_SKIP_VERIFY` environment variable. * (InfluxDB Cloud only) Add [`buck * (InfluxDB OSS only) Updates to `backup` and `restore`: * Reimplement [`backup`](/influxdb/cloud/reference/cli/influx/backup/) to support downloading embedded SQL store from InfluxDB 2.0 or later. * Add [`--compression`](/influxdb/v2/reference/cli/influx/backup/) flag to support gzip compression of downloaded files. * Reimplement `restore` to support uploading embedded SQL store from InfluxDB v2.1.x. * (InfluxDB OSS only) Add [`--password`](/influxdb/cloud/reference/cli/influx/user/password/) flag to `user password` command to allow bypassing interactive prompt. ### Bug fixes * Fix interactive password collection and color rendering in PowerShell. * `org members list` no longer hangs on organizations with more than 10 members. * Detect and warn when inputs to `write` contain standalone CR characters. * `dashboards` command now accepts `--org` flag, or falls back to default org in config. * Return a consistent error when responses fail to decode, including hints for OSS-only and Cloud-only commands. --- # InfluxDB OSS v2 release notes Source: https://docs.influxdata.com/influxdb/v2/reference/release-notes/influxdb/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## v2.9.1 ### Bug Fixes * Fixed an issue where level 3 compactions would stop occurring. * Split compaction queue depth from active running count to fix bug which stopped compaction on resource constrained systems. ### Maintenance * Updated Go to 1.25.10. ## v2.9.0 ### Features #### Token hashing enabled by default InfluxDB OSS 2.9.0 enables [API token hashing](/influxdb/v2/admin/tokens/#token-hashing) by default. Tokens are stored as hashes on disk, which improves security: a copy of the underlying database file doesn’t expose usable tokens. When you start `influxd` 2.9.0 with the default settings, any existing unhashed tokens are migrated to hashed form on startup. After migration, the original token strings cannot be recovered. > [!Important] > ##### Before you upgrade > > * Capture any tokens you still need in plaintext form, including the > operator token. Once `influxd` starts with hashing on, the original > strings are unrecoverable. > * If you may need to downgrade to a version earlier than 2.8.0, start`influxd` 2.9.0 with `--use-hashed-tokens=false`. See[Disable token hashing](/influxdb/v2/admin/tokens/#disable-token-hashing)for env-var and config-file equivalents. ##### Disable token hashing To opt out of the new default — for example, while validating an upgrade or preserving downgrade compatibility — pass `--use-hashed-tokens=false` to`influxd`. Hashing remains optional and reversible for *new* tokens (disabling hashing later means newly created tokens are stored unhashed), but tokens that have already been hashed on disk remain hashed. ##### `influxd upgrade` change The `--use-hashed-tokens` flag has been removed from `influxd upgrade`. Tokens are converted to hashed form only when `influxd` itself runs with token hashing enabled — not as part of the upgrade step. ##### Recommended workflow for backup and restore A backup taken from a 2.9.0 instance with the default settings does not contain a plaintext operator token. To restore that backup with`influx restore --full`, supply the operator token via the new`influx restore --operator-token ` flag (`influx-cli` v2.8.0+). #### Backup gzip compression level (server and CLI) You can now configure the gzip compression level used during backup downloads, separately from the local snapshot file compression that`--compression` controls. * HTTP API (`GET /api/v2/backup/shards/{shardID}` and`GET /api/v2/backup/metadata`): set the `Gzip-Compression-Level` request header to `default`, `full` (best compression), `speedy` (fastest), or`none`. * `influx backup` CLI (`influx-cli` v2.8.0+):`--gzip-compression-level `. The pre-existing `--compression` flag continues to control whether the CLI gzips snapshot files written to local disk. If you set`--gzip-compression-level=none` and do not explicitly set `--compression`, local compression is also disabled. #### Edge data replication: `maxAgeSeconds` validation The replication API (`POST /api/v2/replications` and`PATCH /api/v2/replications/{id}`) now validates `maxAgeSeconds`: * Minimum: 60 seconds (1 minute). * Maximum: 5,184,000 seconds (60 days). * `0` is accepted as a sentinel meaning “use the default” (1 week). Out-of-range values return HTTP 400 with`maxAgeSeconds must be 0 (use default) or between 60 and 5184000`. #### Restore: `--operator-token` flag `influx restore --full` accepts a new `--operator-token ` flag (`influx-cli` v2.8.0+). The CLI uses this token to authenticate post-restore requests when the restored backup contains a hashed (rather than plaintext) operator token. #### Flux upgrade Flux upgraded to v0.200.0. #### Compaction reliability and performance InfluxDB 2.9.0 includes the compaction improvements ported from InfluxDB 1.12.3 and 1.12.4 — locking, scheduling, logging, and edge-case fixes across the TSM and series-file compaction paths. These changes are mostly internal; expect lower lock contention and steadier compaction behavior under load. ### Bug Fixes * Return InfluxQL JSON marshaling errors correctly. ## v2.8.0 ### Features * [5e204dc](https://github.com/influxdata/influxdb/commit/5e204dc): Add optional token hashing #### Token hashing Introduces token hashing. When activated, token hashing stores all API tokens as hashes on disk. While token hashing is a valuable security upgrade, care should be taken when upgrading and enabling token hashing. Use the [`use-hashed-tokens`](/influxdb/v2/reference/config-options/#use-hashed-tokens) configuration option to enable token hashing in InfluxDB. If you are upgrading from an earlier InfluxDB 2.x version, we recommend first upgrading to version 2.8.0 (or later), and then enabling hashed tokens as a separate step. Token hashing is optional and you can enable token hashing at any time after the upgrade. #### How token hashing works Upon upgrading to InfluxDB v2.8.0 or later from version 2.7.12 or earlier releases, the BoltDB schema is upgraded to add a new index bucket. On every startup with token hashing enabled, InfluxDB migrates all unhashed tokens to hashed tokens and deletes the unhashed tokens. With token hashing enabled, any new tokens are stored as hashed tokens. If you then disable token hashing, newly created tokens are stored unhashed, but existing tokens remain hashed on disk. ##### Hashed tokens erased when downgrading Note that once token hashing is enabled, downgrading to a version earlier than 2.8.0 erases all API tokens due to the required schema downgrade. After downgrading, you’ll need to create new tokens for your clients, even if you disable token hashing before you downgrade. Disabling token hashing **does not** unhash tokens stored in hashed form. If token hashing is *never* enabled, then it is possible to downgrade from v2.8.0 to v2.7.12 and earlier. ##### Recommended process 1. Upgrade InfluxDB. 1. Initiate influxd shutdown. 2. Wait for a clean shutdown. 3. Upgrade influxd. 4. Start influxd. 2. Verify the upgrade is successful. 3. Optional: Enable token hashing 1. Initiate influxd shutdown. 2. Wait for a clean shutdown. 3. Do *one* of the following: * Include the `--use-hashed-tokens` command line flag * Set the `INFLUXD_USE_HASHED_TOKENS=true` environment variable in your container environment * Set `use-hashed-tokens` to `true` in your configuration file 4. Start influxd. ### Bug Fixes * [305e61d](https://github.com/influxdata/influxdb/commit/305e61d): Fix compilation on Alpine Linux * [40a6332](https://github.com/influxdata/influxdb/commit/40a6332): Updates post-install for Linux package builds * [1b83d2c](https://github.com/influxdata/influxdb/commit/1b83d2c): Chore: update to go 1.23.12 (2.7) * [40a6332](https://github.com/influxdata/influxdb/commit/40a6332): Updates post-install for Linux package builds ## v2.7.12 ### Features * Add a `--pid-file` option to write a PID file to the specified location on startup. InfluxDB removes the PID file on shutdown. * Add a `--storage-wal-flush-on-shutdown` option to flush the WAL on database shutdown to ensure all data is written to disk. * Improve response error messages for dropped points, adding details including database, retention policy, and which bound was violated for partial writes. ### Bug Fixes * Fix a locking issue in `TagValueIterator` that could cause reads and writes in buckets to block. [PR #26414](https://github.com/influxdata/influxdb/pull/26414) ### Maintenance * Improved startup logging with an “are we there yet” counter for the number and percentage of shards opened. * Update Go to 1.23.9. * Update Flux to v0.196.1. * Refresh dependencies to address security vulnerabilities and improve stability. ## v2.7.11 ### Features * Add startup logging on the percentage of shards opened. * Improve error messages and logging during shard opening. * Add additional logging when loading field set changes. * Add `--pid-file` option to write a PID file on startup. * Add `--storage-wal-flush-on-shutdown` to flush WAL on database shutdown. ### Bug Fixes * Adds check for incompatible WAL formats during startup. * Changes to shard loading to improve maintainability of TSM code. * Hitting `vm.max_mmap_count` count no longer causes data to become unqueryable. ### Maintenance * Minor user interface (UI) updates. * Update Go to 1.22.7. ## v2.7.10 ### Bug Fixes * Update Flux to address performance regression. ### Maintenance * Update Flux to 0.195.2. ## v2.7.9 ### Bug Fixes * Fix UI build error. ### Maintenance * Update `go` toolchain to 1.21.12. ## v2.7.8 ### Bug Fixes * Prevent an infinite loop in write path. * Fix `range()` filter behavior for timestamps before 1970-01-01 (UNIX time 0). * Update to latest `influxdb-templates`. ### Maintenance * Update user interface (UI) with various improvements. ## v2.7.7 ### Features * Disable `file://` URLs when [hardening is enabled](/influxdb/v2/reference/config-options/#hardening-enabled). ### Bug Fixes * Ensure `TSMBatchKeyIterator` and `FileStore` close all `TSMReader`s. * Return `MergeIterator.Close` errors. * Ensure `GROUP BY` queries with an offset that crosses a date time boundary (daylight savings time, British summer time, etc.) do not fail. * Preserve time zone information in the Task Scheduler. * Prevent the retention service from becoming unresponsive. ### Maintenance * Update Flux to v0.195.1. * Update `logrus` to 1.9.3. * Update `golang.org/x/net` to v0.23.0. * Update `protocol` buffers to v5.26.1. * Update `go` toolchain to 1.21.10. ## v2.7.6 ### Features * Add optional [stricter password requirements](/influxdb/v2/reference/config-options/#strong-passwords). ### Bug Fixes * Fix `panic index out of range` error for invalid series keys. * Update broken Flux and performance tests. * Do not panic when querying empty tags. * Improve shard deletion. * Return and respect cursor errors. * Update constant time code to make password strength calculations more constant. ### Maintenance * Upgrade to Go to 1.21.9. ## v2.7.5 ### Features * Add authenticating ID and user ID to request logging. * Write detailed logs from endpoint detection and response (EDR) failures. ### Bug Fixes * Only execute `init_config` on install. * Enable `Secure` when using TLS and enable `HttpOnly`. * Correctly return `4xx` errors instead of `5xx` errors. * Prevent retention service from creating orphaned shard files. ### Maintenance * Emit build commands during tests. * Upgrade Flux to 0.194.5. ## v2.7.4 *Internal changes only.* ## v2.7.3 ### Maintenance * Upgrade Flux to 0.194.3. ## v2.7.1 ### Bug Fixes * Update the InfluxDB UI to remove non-functional Data Explorer. ## v2.7.0 ### Bug Fixes * Update user interface to resolve dashboard crashes and All Access token creation. * Show replication queue size and replication TCP errors. * Correctly handle when the replication queue cannot be found. * Rename stored replication fields to be more clear. * Prevent unauthorized writes from Flux `to()` function. * Add error message when attempting to delete by field. * Prevent scrapers from failing when the `Content-Type` header is not set. * Removed timeout reached with large databases or slow servers. * Changing file permissions on the manifest is no longer necessary. ### Maintenance * Update Flux to v0.193.0. * Update package repository GPG key/ * Add additional error logging when deleting a shard. * Update to Go 1.20.1. * Update end-to-end tests to work locally in UI repo. * Bump `github.com/aws/aws-sdk-go` from 1.30.12 to 1.33.0. * Bump `testcontainers-go` to 0.18.0. * Bump `golang.org/x/net` from 0.5.0 to 0.7.0. * Bump `containerd` to 1.6.18. * Bump `github.com/opencontainers/runc` from 1.1.3 to 1.1.5. ## v2.6.1 ### Bug Fixes * Update user interface (UI) to fix dashboard page crash issue. * Fix `All Access` token creation issue. ## v2.6.0 ### Features * Add the following `influxd` utilities: * [`influxd inspect check-schema`](/influxdb/v2/reference/cli/influxd/inspect/check-schema/) * [`influxd inspect merge-schema`](/influxdb/v2/reference/cli/influxd/inspect/merge-schema/) * [`influxd inspect report-db`](/influxdb/v2/reference/cli/influxd/inspect/report-db/) * Validate packages during the build process. ### Bug Fixes * Optimize [`SHOW FIELD KEY CARDINALITY`](/influxdb/v2/query-data/influxql/explore-schema/#show-field-key-cardinality)InfluxQL command. * Correctly convert replication maximum age setting to seconds. * Fix internal metadata migrations when a replication remote already exists. * Update `/me` and `/users` routes to match documentation. * By default, restrict file permissions to 0750 (`drwxr-x---`). * Correctly handle `NaN` values returned from InfluxDB scrapers. * Pin the user interface (UI) to version that addresses dashboard issues. ### Maintenance * Upgrade to Go 1.18.9. * Upgrade Flux to v0.191.0. ## v2.5.1 ### Bug fixes * Fix permissions issue in Debian and Red Hat package managers. ## v2.5.0 ### Features * Updated user interface (UI). * Allow for incremental changes to `fields.idx`. ### Security updates * Restriction to view tokens only once, immediately after creation. * Set `SameSite=strict` on session cookie. ### Bug fixes * Manually scheduled tasks run when expected. * Fix error where virtual DBRP mappings were being ignored. * Ability to back up all buckets in your InfluxDB instance. * Improved speed of deletes when measurement is part of the predicate. * Improved error messaging when attempting to create user with an ID that already exists. ### Maintenance * Upgrade to [Flux 0.188.1](/flux/v0/release-notes/#v01870) * Upgrade to [Go 1.18.7](https://go.dev/doc/go1.18) * Upgrade to [Rust 1.63.0](https://www.rust-lang.org/) ## v2.4.0 ### Features * Support bucket names in the `replications` API and allow [InfluxDB 1.x DBRP](/influxdb/v2/query-data/influxql/dbrp) names as bucket names. * Add the [InfluxQL shell (REPL)](/influxdb/v2/reference/cli/influx/v1/shell/). * Change to operator model so that `admin` user has instance-level permissions without `operator` token. #### Flux advancement highlights * Add the [`join` package](/flux/v0/stdlib/join/) to support inner joins, right outer joins, left outer joins, and full outer joins. * Promote `experimental.to()` to [`influxdb.wideTo()`](/flux/v0/stdlib/influxdata/influxdb/wideto/). * Add [`initialZero`](/flux/v0/stdlib/universe/derivative/#initialzero) parameter to [`derivative()`](/flux/v0/stdlib/universe/derivative/). * Add `time()` function to the [`date package`](/flux/v0/stdlib/date/) to convert timeable types (time and duration) to time types. * Promote the following functions from `experimental.array` into the [`array` package](/flux/v0/stdlib/array/): * [`array.concat()`](/flux/v0/stdlib/array/concat/) * [`array.filter()`](/flux/v0/stdlib/array/filter/) * [`array.map()`](/flux/v0/stdlib/array/map/) * Promote the following functions from the experimental `http.requests` package into the [`http/requests` package](/flux/v0/stdlib/http/requests/): * [`requests.do()`](/flux/v0/stdlib/http/requests/do/) * [`requests.get()`](/flux/v0/stdlib/http/requests/get/) * [`requests.peek()`](/flux/v0/stdlib/http/requests/peek/) * [`requests.post()`](/flux/v0/stdlib/http/requests/post/) * Promote `experimental.bitwise()` into the [`bitwise` package](/flux/v0/stdlib/bitwise/). * Add new [experimental.catch()](/flux/v0/stdlib/experimental/catch/) and [testing.shouldError()](/flux/v0/stdlib/testing/shoulderror/) functions. * Support conditional expressions, constants, and literals in vectorized [`map()`](/flux/v0/stdlib/universe/map/). * Optimize [`holtWinters()`](/flux/v0/stdlib/universe/holtwinters/) and redundant sorts. * Deprecate the following experimental functions: * `http.get()` * `csv.from()` ### Bug fixes * Log the log level at startup. * Fix panic from `CreateIterator` in Flux queries. * Fix error-caching in `bufio.Writer`. * Remove `MATCHER_BEHAVIOR` environment variable. ### Maintenance * Upgrade to [Go 1.18.4](https://go.dev/doc/go1.18). * Upgrade to [Flux 0.179.0](/flux/v0/release-notes/#v01790). ## v2.3.0 This release includes the following [maintenance](#maintenance), [features](#features), [security updates](#security-updates) and [bug fixes](#bug-fixes). > [!Note] > #### Production ready: replicate data remotely > > InfluxDB 2.2 introduced a technical preview of how to [replicate data from InfluxDB OSS to InfluxDB Cloud](/influxdb/v2/write-data/replication). This feature is now production ready. ### Maintenance * Upgrade from Flux 0.161.0 to [Flux 0.171.0](/flux/v0/release-notes/#v01710). * Upgrade to [Go 1.18.3](https://go.dev/doc/go1.18). ### Features * Add the [`--instance-id`](/influxdb/v2/reference/config-options/?t=JSON#instance-id) flag to `influxd` runtime to add the `_instance_id` tag to remote replications metrics. Helps to identify where the metrics came from, and ensures that two instances don’t overwrite each others’ data. * Add signifier to replication `user-agent` to signify when replication write requests are made. Helps to identify metrics written via replications. #### Flux advancement highlights ##### Performance improvements * Vectorize arithmetic operators in `map()`. * Vectorize logical operations in `map()`. * Enable `movingAverage()` and `cumulativeSum()` optimizations by default. ##### Other highlights * Add `preview()` to experimental package for limiting return rows and tables (as opposed to just rows with `limit()`). * Add `date.scale()` to let users dynamically scale durations in dates. * Add [OpenTracing](https://opentracing.io/docs/overview/spans/) spans to Flux transformations. Lets you monitor Flux scripts more precisely. * Add `trace` option to Flux CLI. * Rename `addDuration()` to [add](/flux/v0/stdlib/date/add/) and `subDuration()` to [sub](/flux/v0/stdlib/date/sub/), and moved both of these functions from the experimental package to the date package. * Add location support to `date.truncate()`. * Add `_status` tag to PagerDuty record. * Refactor operator profile to be in the query statistics. ### Security updates Several security issues were fixed in dependencies and the toolchain used to build InfluxDB, including: * An issue in the `gopkg.in/yaml.v3` package import that could lead to a DoS in the templates service. * An issue in the `github.com/buger/jsonparser` package import that could potentially lead to a DoS in storage authorization. * Cumulative security fixes for Go 1.17.8-[1.18.3](https://go.dev/doc/devel/release#go1.18.minor) are included in this release. These fixes resolve the following InfluxDB issues: * An issue with processing large PEM files that could lead to a DoS in the templates service or flux connections using `to()`. * An issue in TLSv1.3 and a lack of ticket randomness. * A minor issue with `filepath.Clean()` on Windows. ### Bug fixes * Fix race condition when remote replicating deadlocks the remote writer that prevented writes to the target. * Resolve error when creating v1 authorization (`v1 auth`) with a nonexistent bucket ID. * Add fields to the `_tasks` bucket to match schema of the same bucket in InfluxDB Cloud. Provides consistency for clients accessing both. * Fix rare case where measurement cardinality reported less than zero. * Resolve panic on cleaning up failed iterators. ## v2.2.0 This release includes the following new [features](#features) and several [bug fixes](#bug-fixes). ### Features * [Technical preview: replicate data remotely](#technical-preview-replicate-data-remotely) * [Flux updates](#flux-updates) * [Build maintenance](#build-maintenance) * [Task metadata](#task-metadata) * [Troubleshoot with new metrics](#troubleshoot-with-new-metrics) * [Display runtime configuration in use by `influxd`](#display-runtime-configuration-in-use-by-influxd) * [Recover user credentials](#recover-user-credentials) * [Security updates](#security-updates), including a new `hardening-enabled` option to enable additional security. #### Technical preview: replicate data remotely Add the option to [replicate data from InfluxDB OSS to InfluxDB Cloud](/influxdb/v2/write-data/replication). On rare occasions, remote write failures may cause data in the replication queue to get stuck. To ensure data is not dropped, restart the InfluxDB instance replicating data. To assess whether this issue is occurring, we recommend periodically doing one of the following: * Verify your data is successfully replicated to your target bucket. * View your queue size using [`influx replication list`](/influxdb/cloud/reference/cli/influx/replication/list/) for unexpected growth. Replicating data remotely lets you do following: * Create a durable subscription on a per bucket basis for the purposes of replicating data on-write from an InfluxDB OSS instance to InfluxDB Cloud. * Store, analyze, and aggregate data locally while also forwarding newly arriving data to a centralized InfluxDB Cloud account. * Configure a maximum buffer size and data age restrictions to restrict the amount of data stored on disk. #### Flux updates * Update to [Flux v0.150.0](/flux/v0/release-notes/#v01500). * Add option to log Flux queries that are cancelled because of server shutdown. #### Build maintenance * Upgrade `protobuf` library. #### Task metadata * Add option to pass `type=basic` to [`/api/v2/tasks`](/influxdb/v2/api/tasks/) to return task metadata without the query text. #### Troubleshoot with new metrics To assist with troubleshooting and operational management, expose the following metrics in Prometheus Exposition Format. ##### TSM compaction metrics * `storage_compaction` * `storage_compactions_active` * `storage_compactions_duration_seconds_bucket` * `storage_compactions_duration_seconds_count` * `storage_compactions_duration_seconds_sum` * `storage_compactions_queued` * `storage_compactions_total` ##### Failed to add to replication queue metrics * `PointsFailedToQueue` * `BytesFailedToQueue` ##### Write status metrics * `pointsWriteRequested` * `pointsWriteOk` * `pointsWriteDropped` * `pointsWriteErr` * `timeout` ##### Disk size metrics per shard * `total`: number of files per shard * `disk_bytes`: data size in bytes for each shard ##### Cache subsystem metrics * `inuse_bytes`: Current memory consumption of cache * `diskBytes`: Size of most recent snapshot" * `latest_snapshot`: Unix time of most recent snapshot * `writes_total`: Counter of all writes to cache * `writes_err`: Counter of failed writes to cache * `writes_dropped`: Counter of writes (with any dropped points) to cache ##### WAL subsystem metrics * `size`: Size of WAL in bytes * `writes`: Number of write attempts to the WAL * `writes_err`: Number of failed write attempts to the WAL See [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/) for additional detail. #### Display runtime configuration in use by `influxd` * Add `api/v2/config` endpoint to display the runtime configuration (for example, when you run `influxd print-config`). This endpoint lets you review runtime configuration while the instance is live. #### Recover user credentials To recover user credentials, use [`influx recovery user list`](/influxdb/v2/reference/cli/influxd/recovery/user/list/) to retrieve a list of users, and then use [`influx recovery user update`](/influxdb/v2/reference/cli/influxd/recovery/user/update/) to update the password for a specified user. ### Security updates * Add the [`hardening-enabled`](/influxdb/v2/admin/security/enable-hardening) option to limit flux/pkger HTTP requests. The new `hardening-enabled` option ensures that InfluxDB first verifies the IP address of the URL is not private. By default, Flux HTTP and template fetching requests are allowed to access localhost and private IP addresses. * Disable use of jsonnet with `/api/v2/templates/apply`. This prevents crafted authenticated requests from exfiltrating files accessible to the user InfluxDB runs as. * Add read permissions check for querying data. This prevents authenticated requests using a write-only token from reading data via the InfluxQL `/query` compatibility API. * Add write permissions check for `DELETE` and `DROP MEASUREMENT`. This prevents authenticated requests using a read-only token from deleting data via the InfluxQL `/query` compatibility API. Additionally, several security issues were fixed in dependencies and the toolchain used to build InfluxDB, including: * The following cumulative security fixes for [Flux v0.161.0](/flux/v0/release-notes/) since 0.139.0 are included in this release: * Quote db identifiers. This addresses injection vulnerabilities in database connections using `to()`. * Make substring check bounds correctly. This prevents authenticated queries from crashing the Flux engine. * The cumulative security fixes for [Go 1.17.8](https://go.dev/doc/devel/release#go1.17.minor) since Go 1.17.2 are included in this release. This addresses an issue in the InfluxDB test suite. ### Bug fixes * Ensure manual task runs can happen concurrently. * Extend snapshot copy of backup to filesystems that do not support hard links. * Detect misquoted tag values and return an error. * Fix potential deadlock in `influxd inspect dump-tsi`. * Successfully handle errors returned by `Sketch.Merge`. * Return `X-version` and `X-Build` headers for all requests to `/ping` endpoint. * Add error when `meta.db` is missing. * Sync TSI index file before closing. * Fix race condition that could cause `restore` command to fail. * To successfully restore a backup, use copy when a rename spans volumes. * Disable use of jsonnet with `/api/v2/templates/apply`. * Ensure that updating a check (`/checks/{checkID}`) does not require an owner ID. * Remove NATS for scraper processing. Note, this fix does not alter scraper functionality–scrapers still work as they did before. * `nats-port` and `nats-max-payload-bytes` flags have been deprecated. * NATS is no longer embedded in InfluxDB. Because InfluxDB no longer requires a port for NATS, port conflict issues are reduced. * Resolve the issue that prevented the browser from tracking the cookie `expiry` correctly, causing the cookie to expire automatically when restarting the browser or changing tabs. Now, the cookie is correctly preserved. * Allow unlimited Flux HTTP calls. Previously, HTTP requests failed silently after 100 MB of data transfer. * Remove pagination limits on the `/telegrafs` API. Previously, pagination wasn’t exposed to the API, so API requests were limited to the default 20 pages. ## v2.1.1 > [!Note] > To address underlying installation package issues, we bumped the 2.1 release version to 2.1.1. This release includes several new [features](#features) and [bug fixes](#bug-fixes). ### `influx` CLI moved to separate repository The `influx` CLI has been moved to its own GitHub [repository](https://github.com/influxdata/influx-cli/). #### `influxdb` release artifacts affected Release artifacts produced by `influxdb` are impacted as follows: * Release archives (`.tar.gz` and `.zip`) **no longer contain** the `influx` binary. * The `influxdb2` package (`.deb` and `.rpm`) **no longer contains** the `influx` binary. Instead, the package declares a recommended dependency on the new `influxdb2-cli` package. * The `quay.io/influxdb/influxdb` image **no longer contains** the `influx` binary. We recommend migrating to the `influxdb` image hosted on [DockerHub](https://hub.docker.com/_/influxdb). #### Find supported `influx` CLI commands With this change, versions of the `influx` CLI and InfluxDB server (`influxd`) are not guaranteed to exactly match. To check the version of the `influxd` server, see `influxd version` in `influx` CLI or use the `/health` endpoint of your InfluxDB server. > [!Note] > The [`influx` CLI documentation](/influxdb/v2/reference/cli/influx/) has been updated to reflect which `influx` CLI commands work with which versions of InfluxDB. ### Features This release includes the following new features: * [Notebooks, annotations, and visualization updates](#notebooks-annotations-and-visualization-updates) * [API](#api) and [CLI](#cli) updates * Support for latest [Flux](#flux) and [Telegraf](#telegraf) releases * Updates to the [InfluxQL](#influxql) * [Token](#tokens) updates * [Flux location support](#flux) #### Notebooks, annotations, and visualization updates * Add support for [notebooks](/influxdb/v2/tools/notebooks/) and [annotations](/influxdb/v2/visualize-data/annotations/). * Add support for static legends to line graphs and band plots. * Enable new dashboard auto-refresh. * Simplify display of data for table visualizations. #### API * Add new parameters to GET [`/users`](/influxdb/v2/api/users/) API, including: `offset`, `limit`, and `after`. * Add the [`api/v2/backup/metadata`](/influxdb/v2/api/backup/) endpoint for backing up both key-value and SQL metadata, and the [`api/v2/restore/sql`](/influxdb/v2/api/) for restoring SQL metadata. * Deprecated [`POST .../secrets/delete`](/influxdb/v2/api/secrets/). To delete a secret, use [`DELETE .../secrets/{secretID}`](/influxdb/v2/api/secrets/). #### CLI ##### influxd configuration Added several new configuration options to [`influxd`](/influxdb/v2/reference/cli/influxd/): * Add `influxd recovery` command to let you create a recovery [Operator token](/influxdb/v2/admin/tokens/#operator-token). * Add `--sqlite-path` flag for specifying a user-defined path to the SQLite database file. * Add `--storage-wal-max-concurrent-writes` flag to enable tuning memory pressure under heavy write load. * Add `--storage-wal-max-write-delay` flag to prevent deadlocks when the WAL is overloaded with concurrent writes. * Add `--storage-write-timeout` flag to set write request timeouts. * Add `--storage-no-validate-field-size` flag to disable enforcement of max field size. * Update `--store` flag to work with string values disk or memory. Memory continues to store metadata in-memory for testing; disk persists metadata to disk via bolt and SQLite. For more information, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/). ##### influxd inspect Ported the following [`influxd inspect`](/influxdb/v2/reference/cli/influxd/inspect/) commands from InfluxDB 1.x: * [influxd inspect build-tsi](/influxdb/v2/reference/cli/influxd/inspect/build-tsi/) * [influxd inspect delete-tsm](/influxdb/v2/reference/cli/influxd/inspect/delete-tsm/) * [influxd inspect dump-tsi](/influxdb/v2/reference/cli/influxd/inspect/dump-tsi/) * [influxd inspect dump-tsm](/influxdb/v2/reference/cli/influxd/inspect/dump-tsm/) * [influxd inspect dump-wal](/influxdb/v2/reference/cli/influxd/inspect/dump-wal/) * [influxd inspect report-tsi](/influxdb/v2/reference/cli/influxd/inspect/report-tsi/) * [influxd inspect report-tsm](/influxdb/v2/reference/cli/influxd/inspect/report-tsm/) * [influxd inspect verify-seriesfile](/influxdb/v2/reference/cli/influxd/inspect/verify-seriesfile/) * [influxd inspect verify-tombstone](/influxdb/v2/reference/cli/influxd/inspect/verify-tombstone/) * [influxd inspect verify-tsm](/influxdb/v2/reference/cli/influxd/inspect/verify-tsm/) * [influxd inspect verify-wal](/influxdb/v2/reference/cli/influxd/inspect/verify-wal/) ##### influxd downgrade Added the [influxd downgrade command](/influxdb/v2/reference/cli/influxd/downgrade/)to migrate InfluxDB key-value metadata schemas to earlier 2.x versions when necessary. #### Flux * Update to [Flux v0.139.0](/flux/v0/release-notes/#v01390). * Enable writing to remote hosts using the Flux [`to()`](/flux/v0/stdlib/influxdata/influxdb/to/) and [`experimental.to()`](/flux/v0/stdlib/experimental/to/) functions. * Flux now supports locations that dynamically modify time offsets based on your specified timezone. You can also specify fixed time offsets relative to UTC. * Perform [bitwise operations](/flux/v0/stdlib/experimental/bitwise/)on integers and unsigned integers. * [Query](/flux/v0/query-data/sql/vertica/) and[write to Vertica](/flux/v0/query-data/sql/vertica/) SQL databases. * Add the [`hex` package](/flux/v0/stdlib/contrib/bonitoo-io/hex/)for working with hexadecimal string values. #### InfluxQL * `SHOW MEASUREMENTS ON` now supports database and retention policy wildcards. For example, `SHOW MEASUREMENTS ON *.*` to show all databases and `SHOW MEASUREMENTS ON .*` to show all retention policies. * Add hyper log operators `merge_hll`, `sum_hll`, and `count_hll` in InfluxQL to optimize series iteration. (`count_hll` optimizes queries that can be answered without inspecting TSM data.) #### Telegraf * Add the following new [Telegraf plugins](/telegraf/v1/plugins/) to the Load Data page: * Alibaba (Aliyun) CloudMonitor Service Statistics (`aliyuncms`) * AMD ROCm System Management Interface (SMI) (`amd_rocm_smi`) * Counter-Strike: Global Offensive (CS:GO) (`csgo`) * Directory Monitoring (`directory_monitor`) * Intel Data Plane Development Kit (DPDK) (`dpdk`) * Elasticsearch Query (`elasticsearch_query`) * Internet Speed Monitor (`internet_speed`) * KNX (`knx_listener`) * Mdstat (`mdstat`) * Netstat (`netstat`) * NFS Client (`nfsclient`) * OpenTelemetry (`opentelemetry`) * RavenDB (`ravendb`) * SQL (`sql`) * Trig (`trig`) * Twemproxy (`twemproxy`) For more information about each plugin, see [Telegraf plugins](/telegraf/v1/plugins/), and search for the plugin name. #### Tokens * Add support for standard Bearer token syntax. Now you can specify token credentials as: `Authorization: Bearer xxxxxxxx`. * If restoring a backup overwrites the Operator token, the new token value is returned. ### Bug fixes * Log API errors to server logs and tell clients to check the server logs for the error message. * Fix pagination for GET [`/buckets`](/influxdb/v2/api/buckets/) API when displaying results. Previously, pagination was broken if a request included both an `org` filter AND the `after` request parameter. Also corrects `descending` parameter to sort when an `org` filter is used and saved. * Sync series segment to disk after writing. * Do not allow shard creation to create overlapping shards. * Don’t drop shard group durations when upgrading InfluxDB. ## v2.0.9 This release includes several new [features](#features) and [bug fixes](#bug-fixes). ### Features New features include: * [API updates](#api-updates) * [Flux updates](#flux-updates) * [Performance enhancements](#performance-enhancements) #### API updates * Add a new route `/api/v2/resources` that returns a list of known resources to the platform, including the following resource types. Makes it easier to update All Access tokens with current resources: * `AuthorizationsResourceType` * `BucketsResourceType` * `ChecksResourceType` * `DashboardsResourceType` * `DBRPResourceType` * `DocumentsResourceType` * `LabelsResourceType` * `NotificationEndpointResourceType` * `NotificationRuleResourceType` * `OrgsResourceType` * `ScraperResourceType` * `SecretsResourceType` * `SourcesResourceType` * `TasksResourceType` * `TelegrafsResourceType` * `UsersResourceType` * `VariablesResourceType` * `ViewsResourceType` #### Flux updates * Update to [Flux v0.130.0](/flux/v0/release-notes/#v01300). * Add support for [`influxdb.cardinality()`](/flux/v0/stdlib/influxdata/influxdb/cardinality/) function. * Operational improvements: * Add logging to Flux end-to-end tests (`TestFluxEndToEnd`) to help diagnose test failures. * Add `--flux-log-enabled` option to [`influxd`](/influxdb/v2/reference/config-options/) to show detailed logs for Flux queries. #### Performance enhancements * Optimize series iteration for queries that can be answered without inspecting TSM data. * Optimize queries with predicates that contain multiple measurements. ### Bug fixes This release includes the following bug fixes and updates: * [API fix](#api-fix) * [Dependency update](#dependency-update) * [Error updates](#error-updates) * [Limit update](#limit-update) * [Miscellaneous operational fixes](#miscellaneous-operational-fixes) * [Task updates](#task-updates) * [Version maintenance](#version-maintenance) #### API fix * Correctly filter requests to `/api/v2/authorizations` by `org` and `user` parameters. #### Dependency update * Include `curl` as a dependency in `influxdb2` packages. #### Error updates * Add message to set the Flux `content-type` when a query fails to parse as JSON. * Discard excessive errors over `DefaultMaxSavedErrors (100)` to prevent out-of-memory crashes. * Upgrade `golang.org/x/sys` to avoid panics on macs. #### Limit update * Implement hard limit on field size (`MaxFieldValueLength = 1048576`) while parsing line protocol. #### Miscellaneous operational fixes * Resolve the compaction queue stats flutter. * Ensure the TSI index compacts log files that meet one of the following criteria: * Log file hasn’t been updated (no new series have been added to the shard) for 4 (or more) hours (to change this duration, specify a new [`storage-compact-full-write-cold-duration`](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration)) * Log file is one (or more) megabytes (to update this size, specify a new [`storage-max-index-log-file-size`](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size)) * Repair bad port dropping return value names. * Use consistent path separator in permission string representation. * (Windows only) Copy snapshot files being backed up. #### Task updates * Updating an inactive task no longer schedules it. * Preserve comments in Flux queries when saving task definitions. #### Version maintenance * Fix `X-Influxdb-Build` and `X-Influxdb-Version` response header at `/ping`. * Upgrade `influxql` to latest version and fix predicate handling for `SHOW TAG VALUES` meta queries. ## v2.0.8 #### Upcoming changes to influx CLI packaging Beginning in InfluxDB 2.1, the `influx` CLI will no longer be packaged with the release. Future versions of `influx` CLI will be released from the [influx-cli](https://github.com/influxdata/influx-cli) repository. To adopt the new, separate `influx` CLI early, download the latest release from [GitHub](https://github.com/influxdata/influx-cli/releases/tag/v2.3.0) or from the [InfluxData Downloads portal](https://www.influxdata.com/downloads/). ### Go version * Upgrade to Go 1.16. **Requires macOS Sierra 10.12 or later to run.** ### Features * Add `--ui-disabled` option to `influxd` to support running with the UI disabled. * Telemetry improvements: Do not record telemetry data for non-existent paths; replace invalid static asset paths with a slug. * Upgrade to Flux v0.124.0. * Upgrade to UI v2.0.8. * Upgrade `flux-lsp-browser` to v0.5.53. ### Bug fixes * Rename ARM RPM packages with yum-compatible names. * Upgrade to latest version of `influxdata/cron` so that tasks can be created with interval of `every: 1w`. * Avoid rewriting `fields.idx` unnecessarily. * Do not close connection twice in DigestWithOptions. * Remove incorrect optimization for group-by. * Return an error instead of panicking when InfluxQL statement rewrites fail. * Migrate restored KV snapshots to latest schema before using them. * Specify which fields are missing when rejecting an incomplete onboarding request. * Ensure `systemd` unit blocks on startup until HTTP endpoint is ready. * Fix display and parsing of `influxd upgrade` CLI prompts in PowerShell. * Removed unused `chronograf-migator` package and chronograf API service, and updated various “chronograf” references. * Fix display and parsing of interactive `influx` CLI prompts in PowerShell. * Upgrade to `golang-jwt` 3.2.1. * Prevent silently dropped writes when there are overlapping shards. * Invalid requests to `/api/v2` subroutes now return 404 instead of a list of links. * Flux meta queries for `_field` take fast path if `_measurement` is the only predicate. * Copy names from `mmap` mapped memory before closing iterator. ## v2.0.7 ### Features * Optimize [`table.fill()`](/flux/v0/stdlib/experimental/table/fill/)execution within Flux aggregate windows. * Upgrade Flux to [v0.117.0](/flux/v0/release-notes/#v01171). * Upgrade UI to v2.0.7. * Upgrade `flux-lsp-browser` to v0.5.47. ### Bug Fixes * Fix query range calculation (off by one) over partially compacted data. * Deprecate the unsupported `PostSetupUser` API. * Add limits to the `/api/v2/delete` endpoint for start and stop times with error messages. * Add logging to NATS streaming server to help debug startup failures. * Accept `--input` instead of a positional argument in `influx restore`. * Print error instead of panicking when `influx restore` fails to find backup manifests. * Set last-modified time of empty shard directory to the directory’s last-modified time, instead of the Unix epoch. * Remove deadlock in `influx org members list` when an organization has greater than 10 members. * Replace telemetry file name with slug for `ttf`, `woff`, and `eot` files. * Enable use of absolute path for `--upgrade-log` when running `influxd upgrade` on Windows. * Make InfluxQL meta queries respect query timeouts. ## v2.0.6 General Availability ### Bug Fixes * Ensure query configuration written by `influxd upgrade` is valid. * Set `query-concurrency` and `query-queue-size` configuration option defaults to `0` to avoid validation failures when upgrading users. * Correctly validate when `query-concurrency` is `0` and `query-queue-size` is greater than `0`. ## v2.0.5 General Availability InfluxDB v2.0.5 introduced a defect that prevents users from successfully upgrading from InfluxDB 1.x to 2.0 using the `influxd upgrade` command or Docker. To [automatically upgrade from 1.x to 2.0](/influxdb/v2/upgrade/v1-to-v2/automatic-upgrade/)with the `influxd upgrade` command or [with Docker](/influxdb/v2/upgrade/v1-to-v2/docker/), use [InfluxDB v2.0.6](#v206-general-availability). ### Windows Support This release includes our initial Windows preview build. ### Breaking Changes #### /debug/vars removed Prior to this release, the `influxd` server would expose profiling information over the `/debug/vars` endpoint. This endpoint was unauthenticated and not used by InfluxDB systems to report diagnostics. For security and clarity, the endpoint has been removed. Use the `/metrics` endpoint to collect system statistics. #### `influx transpile` removed The `transpile` command has been removed. Send InfluxQL requests directly to the server via the `/api/v2/query`or `/query` HTTP endpoints. #### Default query concurrency changed The default setting for the max number of concurrent Flux queries has been changed from 10 to unlimited (`0`). To limit query concurrency and queue size: 1. Set the `query-concurrency` config parameter to \> 0 when running `influxd` to re-limit the maximum running query count, 2. Set the `query-queue-size` config parameter to \> 0 to set the max number of queries that can be queued before the server starts rejecting requests. #### Prefix for query-controller metrics changed The prefix used for Prometheus metrics from the query controller has changed from `query_control_` to `qc_`. ### Features * Add [Swift client library](https://github.com/influxdata/influxdb-client-swift)to the **Load Data** section of the InfluxDB UI. * Add [`influx task retry-failed` command](/influxdb/v2/reference/cli/influx/task/retry-failed/) to rerun failed runs. * Add [`--compression` option](/influxdb/v2/reference/cli/influx/write/#flags)to the `influx write` command to support Gzip inputs. * Add new `influxd` configuration options: * [pprof-disabled](/influxdb/v2/reference/config-options/#pprof-disabled) * [metrics-disabled](/influxdb/v2/reference/config-options/#metrics-disabled) * [http-read-header-timeout](/influxdb/v2/reference/config-options/#http-read-header-timeout) * [http-read-timeout](/influxdb/v2/reference/config-options/#http-read-timeout) * [http-write-timeout](/influxdb/v2/reference/config-options/#http-write-timeout) * [http-idle-timeout](/influxdb/v2/reference/config-options/#http-idle-timeout) * Add `/debug/pprof/all` HTTP endpoint to gather all profiles at once. * Include the InfluxDB 1.x `http.pprof-enabled` configuration option in the 2.0 configuration file generated by the [InfluxDB upgrade process](/influxdb/v2/upgrade/v1-to-v2/automatic-upgrade/). * Add support for [custom shard group durations](/influxdb/v2/reference/cli/influx/bucket/create#create-a-bucket-with-a-custom-shard-group-duration) on buckets. * Optimize regular expression conditions in InfluxQL subqueries. * Update Telegraf plugins in the InfluxDB UI to include additions and changes from[Telegraf 1.18](/telegraf/v1/release-notes/#v118). * Display task IDs in the tasks list in the InfluxDB UI. * Write to standard output (`stdout`) when `--output-path -` is passed to [`influxd inspect export-lp`](/influxdb/v2/reference/cli/influxd/inspect/export-lp/). * Add `-p, --profilers` flag to [`influx query` command](/influxdb/v2/reference/cli/influx/query/)to enable [Flux profilers](/flux/v0/stdlib/profiler/) on a query executed from the `influx` CLI. * Update InfluxDB OSS UI to match InfluxDB Cloud. * Support disabling concurrency limits in the Flux controller. * Replace unique resource IDs (UI assets, backup shards) with slugs to reduce cardinality of telemetry data. * Standardize HTTP server error log output. * Enable InfluxDB user interface features: * [Band visualization type](/influxdb/v2/visualize-data/visualization-types/band/) * [Mosiac visualization type](/influxdb/v2/visualize-data/visualization-types/mosaic/) * [Configure axis tick marks](/influxdb/v2/visualize-data/visualization-types/graph/#x-axis) * Upload CSV files through the InfluxDB UI * [Edit Telegraf configurations](/influxdb/v2/tools/telegraf-configs/update/#edit-the-configuration-file-directly-in-the-ui) in the InfluxDB UI * [Legend orientation options](/influxdb/v2/visualize-data/visualization-types/graph/#hover-legend) * [Refresh a single dashboard cell](/influxdb/v2/visualize-data/dashboards/control-dashboard/#manually-refresh-a-single-dashboard-cell) * Upgrade to **Flux v0.113.0**. ### Bug Fixes * Prevent “do not have an execution context” error when parsing Flux options in tasks. * Fix swagger to match implementation of DBRPs type. * Fix use-after-free bug in series ID iterator. * Fix TSM and WAL segment size check to check against the local `SegmentSize`. * Fix TSM and WAL segment size computing to correctly calculate `totalOldDiskSize`. * Update references to the documentation site to use current URLs. * Fix data race in then TSM engine when inspecting tombstone statistics. * Fix data race in then TSM cache. * Deprecate misleading `retentionPeriodHrs` key in the onboarding API. * Fix Single Stat graphs with thresholds crashing on negative values. * Fix InfluxDB port in Flux function UI examples. * Remove unauthenticated, unsupported `/debug/vars` HTTP endpoint. * Respect 24 hour clock formats in the InfluxDB UI and add more format choices. * Prevent “do not have an execution context” error when parsing Flux options in tasks. * Prevent time field names from being formatted in the Table visualization. * Log error details when `influxd upgrade` fails to migrate databases. * Fix the cipher suite used when TLS strict ciphers are enabled in `influxd`. * Fix parse error in UI for tag filters containing regular expression meta characters. * Prevent concurrent access panic when gathering bolt metrics. * Fix race condition in Flux controller shutdown. * Reduce lock contention when adding new fields and measurements. * Escape dots in community templates hostname regular expression. ## v2.0.4 General Availability ### Docker #### ARM64 This release extends the Docker builds hosted in `quay.io` to support the Linux/ARM64 platform. #### 2.x nightly images Prior to this release, competing nightly builds caused the nightly Docker tag to contain outdated binaries. This conflict is fixed, and the image tagged with nightly now contains 2.x binaries built from the `HEAD` of the `master` branch. ### Breaking Changes #### `inmem` index option removed This release fully removes the `inmem` indexing option, along with the associated config options: * `max-series-per-database` * `max-values-per-tag` The startup process automatically generates replacement `tsi1` indexes for shards that need it. ### Features #### `influxd` updates * Add new [`influxd upgrade`](/influxdb/v2/reference/cli/influxd/upgrade/) flag `—overwrite-existing-v2` to overwrite existing files at output paths (instead of aborting). * Add new configuration options: - [`nats-port`](/influxdb/v2/reference/config-options/#nats-port)- [`nats-max-payload-bytes`](/influxdb/v2/reference/config-options/#nats-max-payload-bytes) * Add new commands: - Add [`influxd print-config`](/influxdb/v2/reference/cli/influxd/print-config/) to support automated configuration inspection. - Add [`influxd inspect export-lp`](/influxdb/v2/reference/cli/influxd/inspect/export-lp/) to extract data in line-protocol format. #### New Telegraf plugins in UI * Update Telegraf plugins list in UI to include Beat, Intel PowerStats, and Rienmann. #### Performance improvements * Promote schema and fill query optimizations to default behavior. #### Flux updates * Upgrade to [Flux v0.104.0](/flux/v0/release-notes/#v01040). * Upgrade to `flux-lsp-browser` v0.5.31. ### Bug Fixes * Standardize binary naming conventions. * Fix configuration loading issue. * Add Flux dictionary expressions to Swagger documentation. * Ensure `influxdb` service sees default environment variables when running under `init.d`. * Remove upgrade notice from new installs. * Ensure `config.toml` is initialized on new installs. * Include upgrade helper script (`influxdb2-upgrade.sh`) in GoReleaser manifest. * Prevent `influx stack update` from overwriting stack name and description. * Fix timeout setup for `influxd` graceful shutdown. * Require user to set password during initial user onboarding. * Error message improvements: * Remove duplication from task error messages. * Improve error message shown when influx CLI can’t find an `org` by name. * Improve error message when opening BoltDB with unsupported file system options. * Improve messages in DBRP API validation errors. * `influxd upgrade` improvements: * Add confirmation step with file sizes before copying data files. * Prevent panic in `influxd upgrade` when v1 users exist but v1 config is missing. * Fix logging initialization for storage engine. * Don’t return 500 codes for partial write failures. * Don’t leak `.tmp` files while backing up shards. * Allow backups to complete while a snapshot is in progress. * Fix silent failure to register CLI arguments as required. * Fix loading when `INFLUXD_CONFIG_PATH` points to a .yml file. * Prevent extra output row from GROUP BY crossing DST boundary. * Update Flux functions list in UI to reflect that `v1` package was renamed to `schema`. * Set correct `Content-Type` on v1 query responses. * Respect the `--skip-verify` flag when running `influx query`. * Remove blank lines from payloads sent by `influx write`. * Fix infinite loop in Flux parser caused by invalid array expressions. * Support creating users without initial passwords in `influx user create`. * Fix incorrect errors when passing `--bucket-id` to `influx write`. ## v2.0.3 General Availability ### Breaking Changes #### `influxd upgrade` Previously, `influxd upgrade` would attempt to write upgraded `config.toml` files into the same directory as the source`influxdb.conf` file. If this failed, a warning would be logged and `config.toml` would write into the `home` directory of the user who launched the upgrade. This release breaks this behavior in two ways: * By default, `config.toml` writes into the same directory as the Bolt DB and engine files (`~/.influxdbv2/`) * If writing upgraded config fails, the `upgrade` process exits with an error instead of falling back to the `HOME` directory To override the default configuration path (`~/.influxdbv2/`), use the new `--v2-config-path` option to specify the output path to the v2 configuration file (`config.toml`). For details, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2/upgrade/v1-to-v2/). #### InfluxDB v2 packaging We’ve renamed the InfluxDB v2 DEB and RPM packages to clarify versions. The package name is now `influxdb2` and conflicts with any previous `influxdb` package (including initial 2.0.0, 2.0.1, and 2.0.2 packages). This release also defines v2-specific path defaults and provides [helper scripts](https://github.com/influxdata/influxdb/blob/master/scripts/influxdb2-upgrade.sh) for `influxd upgrade` and cleanup cases. ### Features * Allow password to be specified as a CLI option in [`influx v1 auth create`](/influxdb/cloud/reference/cli/influx/auth/create/). * Allow password to be specified as a CLI option in [`influx v1 auth set-password`](/influxdb/cloud/reference/cli/influx/auth/). * Implement [delete with predicate](/influxdb/v2/write-data/delete-data/). * Improve ID-related error messages for `influx v1 dbrp` commands. * Update Flux to [v0.99.0](/flux/v0/release-notes/#v0990). * Update `flux-lsp-browser` to v0.5.25. * Support for ARM64 preview build. ### Bug Fixes * Don’t log bodies of v1 write request bodies. * Fix panic when writing a point with 100 or more tags. * Fix validation of existing DB names when creating DBRP mappings. * Enforce max value of 2147483647 on query concurrency to avoid startup panic. * Automatically migrate existing DBRP mappings from old schema to avoid panic. * Optimize shard lookup in groups containing only one shard. * Always respect the `--name` option in `influx setup`. * Allow for 0 (infinite) values for `--retention` in `influx setup`. * Fix panic when using a `null` value as a record or array in a Flux query. ## v2.0.2 General Availability ### Breaking changes #### DBRP HTTP API now matches Swagger documentation Previously, the database retention policy (DBRP) mapping API did not match the swagger spec. If you’re using scripts based on the previous implementation instead of the swagger spec, you’ll need to either update them or use the new [DBRP CLI commands](/influxdb/v2/reference/cli/influx/v1/dbrp/) instead. ### Features * Improvements to upgrade from 1.x to 2.x: * Warning appears if auth is not enabled in 1.x (`auth-enabled = false`), which is not an option in 2.x. For details, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2/upgrade/v1-to-v2/). * `upgrade` command now checks to see if continuous queries are running and automatically exports them to a local file. * Upgrade to [Flux v0.95.0](/flux/v0/release-notes/#v0950). * Upgrade `flux-lsp-browser` to v.0.5.23. * Manage database retention policy (DBRP) mappings via CLI. See [`influx v1 dbrp`](/influxdb/v2/reference/cli/influx/v1/dbrp/). * Filter task runs by time. ### Bug Fixes * Fixes to `influx upgrade` command: * Remove internal subcommands from help text. * Validate used input paths upfront. * Add locking during TSI iteration creation. * Fix various typos. * Use `--skip-verify` flag for backup/restore CLI command. This is passed to the underlying HTTP client for the `BackupService` and `RestoreService` to support backup and restore on servers with self-signed certificates. * Don’t automatically print help on `influxd` errors. * Add `SameSite=Strict` flag to session cookie. * Ensure `SHOW DATABASES` returns a list of the unique databases only. * Allow scraper to ignore insecure certificates on an endpoint. * Ensure Flux reads across all shards. * Use the associated default retention policies defined within the DBRP mapping if no retention policy is specified as part of a v1 write API call. * Add locking during TSI iterator creation. * Allow self-signed certificates for scraper targets. * Bump version in `package.json` so it appears correctly. ## v2.0.1 General Availability InfluxDB 2.0 general availability (GA) introduces the first **production-ready** open source version of InfluxDB 2.0. This release comprises all features and bug fixes included in prior alpha, beta, and release candidate versions. > [!Note] > #### Known issues > > ##### Delete with predicate API not implemented > > The delete with predicate API (`/api/v2/delete`) has not been implemented and currently returns a `501 Not implemented` message. This API will be implemented post GA. > > ##### Duplicate DBRP mappings per database > > When there are multiple [DBRP mappings](/influxdb/v2/reference/api/influxdb-1x/dbrp/) with the same database name in InfluxDB 1.x, SHOW DATABASES incorrectly returns duplicates. Highlights include: * Support for **upgrading to InfluxDB 2.0**: * To upgrade **from InfluxDB 1.x**, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2/upgrade/v1-to-v2). * To upgrade **from InfluxDB 2.0 beta 16 or earlier**, see [Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0](/influxdb/v2/install/upgrade/v2-beta-to-v2/). * **Flux**, our powerful new functional data scripting language designed for querying, analyzing, and acting on data. This release includes [Flux v0.94.0](/flux/v0/release-notes/#v0940). If you’re new to Flux, [check out how to get started with Flux](/influxdb/v2/query-data/get-started/). Next, delve deeper into the [Flux standard library](/flux/v0/stdlib//) reference docs and see how to [query with Flux](/influxdb/v2/query-data/flux/). * Support for [InfluxDB 1.x API compatibility](/influxdb/v2/reference/api/influxdb-1x/). * **Templates** and **stacks**. Discover how to [use community templates](/influxdb/v2/tools/influxdb-templates/use/) and how to [manage templates with stacks](/influxdb/v2/tools/influxdb-templates/stacks/). If you’re new to InfluxDB 2.0, we recommend checking out [how to get started](/influxdb/v2/get-started/) and [InfluxDB key concepts](/influxdb/v2/reference/key-concepts/). ## v2.0.0 ### Features * Improve UI for v1 `influx auth` commands. * Upgrade to [Flux v0.94.0](/flux/v0/release-notes/#v0940) * Upgrade `flux-lsp-browser` to v0.5.22. * Add [RAS Telegraf input plugin](/telegraf/v1/plugins//#ras). ### Bug Fixes * Remove unused `security-script` option from `influx upgrade` command. * Fix parsing of retention policy CLI arguments in `influx setup` and `influxd upgrade`. * Create CLI configs during upgrade to v2. * Allow write-only v1 tokens to find database retention policies (DBRPs). * Update `v1 auth` description. * Use `db`/`rp` naming convention when migrating databases to buckets. * Improve help text for `influxd` and `--no-password` switch. * Use `10` instead of `MaxInt` when rewriting query-concurrency. * Remove bucket and mapping auto-creation from `/write` 1.x compatibility API. * Fix misuse of `reflect.SliceHeader`. ## v2.0.0-rc.4 ### Features * Upgrade to [Flux v0.93.0](/flux/v0/release-notes/#v0930). * Add `influx backup` and `influx restore` CLI commands to support backing up and restoring data in InfluxDB 2.0. * Add the `v1/authorization` package to support authorizing requests to the InfluxDB 1.x API. ### Bug Fixes * Add a new `CreateUniquePhysicalNode` method, which reads and applies the plan node ID in context. Each physical node has a unique ID to support planner rules applied more than once in a query. Previously, the same node ID (hence the same dataset ID) caused the execution engine to generate undefined results. * A cloned task is now only activated when you select **Active**. Previously, a cloned task was activated if the original task was activated. * Reduce the `influx` binary file size. * Isolate the `TelegrafConfigService` and remove URM interactions. * Use the updated HTTP client for the authorization service. * Make `tagKeys` and `tagValues` work for edge cases involving fields. * Correctly parse float as 64-bits. * Add simple metrics related to installed templates. * Remove extra multiplication of retention policies in onboarding. * Use the `fluxinit` package to initialize the Flux library instead of builtin. * Add Logger to the constructor function to ensure the log field is initialized. * Return an empty iterator instead of null in `tagValues`. * Fix the `/ready` response content type to return `application/json`. ## v2.0.0-rc.3 ### Features * Upgrade to [Flux v0.91.0](/flux/v0/release-notes/#v0910). * Enable window aggregate mean pushdown. * Add `newMultiShardArrayCursors` to aggregate array cursors. * UI updates: * Upgrade `papaparse` to 5.2.0. * Upgrade `flux-lsp-browser` to v0.5.21. * Add properties for storing your tick generation selections, including a `generateAxisTicks` property to turn this feature on and off. * Update generate ticks into an array of properties for each axis. * Add the `legendColorizeRows` property to toggle the color on and off in the legend. ### Bug Fixes * Resolve `invalid operation: fs.Bavail` error that occurred in some cases using when `DiskUsage()`. Now, `fs.Bavail` is always converted to `unit64` to ensure the types in an expression align. * Refactor notifications to isolate the `notification/endpoint/service` package and move the rule service into its own package. * Update to clear log out. * Refactor to allow `newIndexSeriesCursor()` to accept an `influxql.Expr`. * Remove unreferenced packages. ## v2.0.0-rc.2 ### Features * Upgrade to [Flux v0.90.0](/flux/v0/release-notes/#v0900). * Add `--force` option to the `influx stacks rm` command, which lets you remove a stack without the confirmation prompt. * Add `aggregate_resultset` for mean aggregate pushdown to optimize windowed results. * Return an error if adding a resource to a stack (`influx stacks update --addResource`) fails due to an invalid resource type or resource ID. ### Bug Fixes * Update `pkger` test templates to use valid Flux to avoid `found unexpected argument end` error. Previously, any template with a `v.dashboardVariable` returned an `undefined identifier v` error. * Update the InfluxDB configuration file `/etc/influxdb/influxdb.conf` to recognize the user’s home directory. Previously, if a user (other than root user) ran the `upgrade` command, a permissions error occurred. * Remove the Telegraf RAS Daemon plugin and other miscellaneous Telegraf plugin updates. * Update the `derivative` in the InfluxDB UI (`ui/src/timeMachiner`) to specify the `unit` is one second (`1s`). * Enable the new `AuthorizationService` from authorization package in the `launcher` package (`cmd\influxd\launcher`). * Update `config upgrade` to save the correct InfluxDB configuration filename. ## v2.0.0-rc.1 ### Features * Add [`influx upgrade`](/influxdb/v2/reference/cli/influxd/upgrade/) command for upgrading from 1.x to 2.0. * Upgrade to Flux v0.89.0. ### Bug Fixes * Enable scrapers. (Scrapers did not work in rc0.) * Update default number of tasks listed with `influx task list` to 100. * Add support for [duration unit identifiers](/flux/v0/spec/lexical-elements/#duration-literals) to templates. * Preserve cell colors in imported and exported templates. * Resolve issue to ensure the `influx` CLI successfully returns a single Telegraf configuration. * Ensure passwords are at least 8 characters in `influx setup`. ## v2.0.0-rc.0 #### Manual upgrade required To simplify the migration for existing users of InfluxDB 1.x, this release includes significant breaking changes that require a manual upgrade from all alpha and beta versions. For more information, see [Upgrade to InfluxDB OSS 2.0rc](/influxdb/v2/install/upgrade/v2-beta-to-v2/), ### Breaking changes #### Manual upgrade * To continue using data from InfluxDB 2.0 beta 16 or earlier, you must move all existing data out of the `~/.influxdbv2` (or equivalent) path, including `influxd.bolt`. All existing dashboards, tasks, integrations, alerts, users, and tokens must be recreated. For information on how to migrate your data, see [Upgrade to InfluxDB OSS 2.0rc](/influxdb/v2/install/upgrade/v2-beta-to-v2/). #### Port update to 8086 * Change the default port of InfluxDB from 9999 back to 8086. If you would still like to run on port 9999, you can start `influxd` with the `--http-bind-address` option. You must also [update any InfluxDB CLI configuration profiles](/influxdb/v2/reference/cli/influx/config/set/) with the new port number. #### Support for 1.x storage engine and InfluxDB 1.x compatibility API * Port the TSM1 storage engine. This change supports a multi-shared storage engine and InfluxQL writes and queries using the InfluxDB 1.x API compatibility [`/write`](/influxdb/v2/reference/api/influxdb-1x/write/) and [`/query`](/influxdb/v2/reference/api/influxdb-1x/query/) endpoints. #### Disable delete with predicate API * Disable the delete with predicate API (`/api/v2/delete`). This API now returns a `501 Not implemented` message. ### Features #### Load Data redesign * Update the Load Data page to increase discovery and ease of use. Now, you can [load data from sources in the InfluxDB user interface](/influxdb/v2/write-data/no-code/load-data/). #### Community templates added to InfluxDB UI * Add [InfluxDB community templates](/influxdb/v2/tools/influxdb-templates/) directly in the InfluxDB user interface (UI). #### New data sources * Add InfluxDB v2 Listener, NSD, OPC-UA, and Windows Event Log to the Sources page. #### CLI updates * Add option to print raw query results in [`influx query`](/influxdb/v2/reference/cli/influx/query/). * Add ability to export resources by name using [`influx export`](/influxdb/v2/reference/cli/influx/export/). * Add new processing options and enhancements to [`influx write`](/influxdb/v2/reference/cli/influx/write/). * Add `--active-config` flag to [`influx` commands](/influxdb/v2/reference/cli/influx/#commands) to set the configuration for a single command. * Add `influxd`[configuration options](/influxdb/v2/reference/config-options/#configuration-options) for storage options and InfluxQL coordinator tuning. * Add `max-line-length` switch to the [`influx write`](/influxdb/v2/reference/cli/influx/write/) command to address `token too long errors` for large inputs. #### API updates * List buckets in the API now supports the `after` (ID) parameter as an alternative to `offset`. #### Task updates * Record last success and failure run times in the task. * Inject the task option `latestSuccessTime` in Flux `Extern`. ### Bug Fixes * Add description to [`influx auth`](/influxdb/v2/reference/cli/influx/auth/) command outputs. * Resolve issues with check triggers in notification tasks by including the edge of the observed boundary. * Detect and provide warning about duplicate tag names when writing CSV data using `influx write`. * Ensure the group annotation does not override the existing line part (measurement, field, tag, time) in a CSV group annotation. * Added `PATCH` to the list of allowed methods. ## v2.0.0-beta.16 This release includes breaking changes: * Remove `influx repl` command. To use the Flux REPL, build the REPL from source. * Drop deprecated `/packages` route tree. * Support more types for template `envRef` default value and require explicit default values. * Remove orgs/labels nested routes from the API. ### Features * Add resource links to a stack’s resources from public HTTP API list/read calls. * Enhance resource creation experience when limits are reached. * Add `dashboards` command to `influx` CLI. * Allow user onboarding to optionally set passwords. * Limit query response sizes for queries built in QueryBuilder by requiring an aggregate window. ### Bug Fixes * Require all `influx` CLI flag arguments to be valid. * Dashboard cells correctly map results when multiple queries exist. * Dashboard cells and overlay use UTC as query time when toggling to UTC timezone. * Bucket names may not include quotation marks. ### UI Improvements * Alerts page filter inputs now have tab indices for keyboard navigation. ## v2.0.0-beta.15 ### Features * Add event source to stacks. * Add ability to uninstall stacks. * Drop deprecated `influx pkg` commands. * Add Telegraf management commands to `influx` CLI. * Enable dynamic destination for the `influx` CLI configuration file. ### Bug Fixes * Allow 0 to be the custom set minimum value for y domain. * Single Stat cells render properly in Safari. * Limit variable querying when submitting queries to used variables. ## v2.0.0-beta.14 ### Features * Extend `influx stacks update` command with ability to add resources without apply template. * Consolidate all InfluxDB template and stack functionality into two new public APIs: `/api/v2/templates` and `/api/v2/stacks`. * Extend template `Summary` and `Diff` nested types with `kind` identifiers. * Add static builds for Linux. * Update Flux to v.0.71.1. ### Bug Fixes * Don’t overwrite build date set via `ldflags`. * Fix issue where define query was unusable after importing a Check. * Update documentation links ## v2.0.0-beta.13 ### Features * Cancel submitted queries in the Data Explorer. * Extend templates with the source `file|url|reader`. * Collect stats on installed InfluxData community template usage. * Allow raw `github.com` host URLs for `yaml|json|jsonnet` URLs in InfluxDB templates. * Allow for remote files for all `influx template` commands. * Extend stacks API with update capability. * Add support for config files to `influxd` and any `cli.NewCommand` use case. * Extend `influx stacks` command with new `influx stacks update` command. * Skip resources in a template by kind or by `metadata.name`. * Extend `influx apply` with resource filter capabilities. * Provide active configuration when running `influx config` without arguments. * Enable `influxd` binary to look for a configuration file on startup. * Add environmental default values to the template parser. * Templates will store which dashboard variable should be selected by default. ### Bug Fixes * Fix `uint` overflow during setup on 32bit systems. * Drop support for `--local` flag within `influx` CLI. * Fix issue where undefined queries in cells result in error in dashboard. * Add support for day and week time identifiers in the CLI for bucket and setup commands. * Cache dashboard cell query results to use as a reference for cell configurations. * Validate `host-url` for `influx config create` and `influx config set` commands. * Fix `influx` CLI flags to accurately depict flags for all commands. ## v2.0.0-beta.12 ### Features * Add option for Cloud users to use the `influx` CLI to interact with a Cloud instance. For more information, see how to [download and install the influx CLI](/influxdb/v2/get-started/) and then learn more about how the [influx - InfluxDB command line interface](/influxdb/v2/reference/cli/influx/) works. * Consolidate `influx apply` commands under templates. Remove some nesting of the `influx` CLI commands. * Make all `influx apply` applications stateful through stacks. * Add ability to export a stack’s existing resource state using `influx export`. * Update `influx apply` commands with improved usage and examples in long form. * Update `influx` CLI to include the `-version` command and return the User-Agent header. * Add `RedirectTo` functionality to ensure Cloud users are redirected to the page that they were trying access after logging into Cloud. * Maintain sort order on a dashboard after navigating away. * Allow tasks to open in new tabs. ### Bug Fixes * Support organization name and ID in DBRP operations. * Prevent the CLI from failing when an unexpected flag is entered in the CLI. * `influx delete` now respects the configuration settings. * Store initialization for `pkger` enforced on reads. * Backfill missing `fillColumns` field for histograms in `pkger`. * Notify the user how to escape presentation mode when the feature is toggled. ### UI Improvements * Display bucket ID in bucket list and enable 1-click copying. * Update Tokens list to be consistent with other resource lists. * Reduce the number of variables being hydrated when toggling variables. * Redesign dashboard cell loading indicator to be more obvious. ## v2.0.0-beta.11 The beta 11 version was **not released**. Changes below are included in the beta 12 release. ### Features * Ability to set UTC time for a custom time range query. * Ability to set a minimum or maximum value for the y-axis visualization setting (rather than requiring both). * New `csv2lp` library for converting CSV (comma separated values) to InfluxDB line protocol. * Add influxdb version to the InfluxDB v2 API `/health` endpoint. ### Bug Fixes * Automatically adjust the drop-down list width to ensure the longest item in a list is visible. * Fix bug in Graph + Single Stat visualizations to ensure `timeFormat` persists. * Authorizer now exposes the full permission set. This adds the ability to derive which organizations the Authorizer has access to read or write to without using a User Request Management (URM) service. * Fix issue causing variable selections to hydrate all variable values, decreasing the impact on network requests. * Resolve scrollbar issues to ensure datasets are visible and scrollable. * Check status now displays a warning if loading a large amount. ## v2.0.0-beta.10 ### Features * Add ability to delete a stack and all associated resources. * Enforce DNS name compliance on the `metadata.name` field in all `pkger` resources. * Add stateful `pkg` management with stacks. ### Bug Fixes * Ensure `UpdateUser` cleans up the index when updating names. * Ensure Checks can be set for zero values. ### UI Improvements * Create buckets in the Data Explorer and Cell Editor. ## v2.0.0-beta.9 ### Bug Fixes * Add index for URM by user ID to improve lookup performance. * Existing session expiration time is respected on session renewal. * Make CLI respect environment variables and flags and extend support for config orgs to all commands. ### UI Improvements * Update layout of alerts page to work on all screen sizes. * Sort dashboards on Getting Started page by recently modified. * Add single-color schemes for visualizations: Solid Red, Solid Blue, Solid Yellow, Solid Green, and Solid Purple. ## v2.0.0-beta.8 ### Features * Add `influx config` CLI command to switch back to previous activated configuration. * Introduce new navigation menu. * Add `-file` option to `influx query` and `influx task` CLI commands. * Add support for command line options to limit memory for queries. ### Bug Fixes * Fix card size and layout issues in dashboards index view. * Fix check graph font and lines defaulting to black causing graph to be unreadable * Fix text-wrapping display issue and popover sizing bug when adding labels to a resource. * Respect the now-time of the compiled query if provided. * Fix spacing between ticks. * Fix typos in Flux functions list. ### UI Improvements * Update layout of Alerts page to work on all screen sizes. * Sort dashboards on Getting Started page by recently modified. ## v2.0.0-beta.7 ### Features * Add option to display dashboards in [light mode](/influxdb/v2/visualize-data/dashboards/control-dashboard/#toggle-dark-mode-and-light-mode). * Add [shell `completion` commands](/influxdb/v2/reference/cli/influx/completion/) to the `influx` CLI. specified shell (`bash` or `zsh`). * Make all `pkg` resources unique by `metadata.name` field. * Ensure Telegraf configuration tokens aren’t retrievable after creation. New tokens can be created after Telegraf has been setup. * [Delete bucket by name](/influxdb/v2/admin/buckets/delete-bucket/#delete-a-bucket-by-name) using the `influx` CLI. * Add helper module to write line protocol to specified URL, organization, and bucket. * Add [`pkg stack`](/influxdb/v2/reference/cli/influx/stacks) for stateful package management. * Add `--no-tasks` flag to `influxd` to disable scheduling of tasks. * Add ability to output CLI output as JSON and hide table headers. * Add an [easy way to switch configurations](/influxdb/v2/reference/cli/influx/config/#quickly-switch-between-configurations) using the `influx` CLI. ### Bug fixes * Fix NodeJS logo display in Firefox. * Fix Telegraf configuration bugs where system buckets were appearing in the Buckets list. * Fix threshold check bug where checks could not be created when a field had a space in the name. * Reuse slices built by iterator to reduce allocations. * Updated duplicate check error message to be more explicit and actionable. ### UI improvements * Redesign OSS Login page. * Display graphic when a dashboard has no cells. ## v2.0.0-beta.6 ### Features * Clicking on bucket name takes user to Data Explorer with bucket selected. * Extend pkger (InfluxDB Templates) dashboards with table view support. * Allow for retention to be provided to `influx setup` command as a duration. * Extend `influx pkg export all` capabilities to support filtering by label name and resource type. * Added new login and sign-up screen for InfluxDB Cloud users that allows direct login from their region. * Added new `influx config` CLI for managing multiple configurations. ### Bug Fixes * Fixed issue where tasks were exported for notification rules. * Fixed issue where tasks were not exported when exporting by organization ID. * Fixed issue where tasks with imports in the query would break in pkger. * Fixed issue where selecting an aggregate function in the script editor did not add the function to a new line. * Fixed issue where creating a dashboard variable of type “map” piped the incorrect value when map variables were used in queries. * Added missing usernames to `influx auth` CLI commands. * Disabled group functionality for check query builder. * Fixed cell configuration error that popped up when users created a dashboard and accessed the “Disk Usage” cell for the first time. * Listing all the default variables in the Variable tab of the script editor. * Fixed bug that prevented the interval status on the dashboard header from refreshing on selections. * Updated table custom decimal feature for tables to update on focus. * Fixed UI bug that set Telegraf config buttons off-center and resized config selections when filtering through the data. * Fixed UI bug that caused dashboard cells to error when using `v.bucket` for the first time. * Fixed appearance of client library logos in Safari. * Fixed UI bug that prevented checks created with the query builder from updating. * Fixed a bug that prevented dashboard cell queries from working properly when creating group queries using the query builder. ### UI Improvements * Swap `billingURL` with `checkoutURL`. * Move Cloud navigation to top of page instead of within left side navigation. * Adjust aggregate window periods to use duration input with validation. ## v2.0.0-beta.5 ### Features * Update Flux to v0.61.0. * Add secure flag to session cookie. * Add optional secret value flag to `influx secret` command. ### Bug Fixes * Sort dashboards on homepage alphabetically. * Tokens page now sorts by status. * Set the default value of tags in a check. * Fix sort by variable type. * Calculate correct stacked line cumulative when lines are different lengths. * Resource cards are scrollable. * Query Builder groups on column values, not tag values. * Scatterplots render tooltips correctly. * Remove pkger gauge chart requirement for color threshold type. * Remove secret confirmation from `influx secret update`. ## v2.0.0-beta.4 ### Features * Added labels to buckets. * Connect Monaco Editor to Flux LSP server. * Update Flux to v0.59.6. ### Bug Fixes * Revert bad indexing of `UserResourceMappings` and `Authorizations`. * Prevent gauge visualization from becoming too small. ## v2.0.0-beta.3 ### Features * Extend `influx cli pkg command` with ability to take multiple files and directories. * Extend `influx cli pkg command` with ability to take multiple URLs, files, directories, and stdin at the same time. * `influx` CLI can manage secrets. ### Bug Fixes * Fix notification rule renaming panics in UI. * Fix the tooltip for stacked line graphs. * Fixed false success notification for read-only users creating dashboards. * Fix issue with pkger/http stack crashing on duplicate content type. ## v2.0.0-beta.2 ### Features * Change Influx packages to be CRD compliant. * Allow trailing newline in credentials file and CLI integration. * Add support for prefixed cursor search to ForwardCursor types. * Add backup and restore. * Introduce resource logger to tasks, buckets and organizations. ### Bug Fixes * Check engine closed before collecting index metrics. * Reject writes which use any of the reserved tag keys. ### UI Improvements * Swap `billingURL` with `checkoutURL`. * Move Cloud navigation to top of page instead of within left side navigation. * Adjust aggregate window periods to use duration input with validation. ## v2.0.0-beta.1 ### Features * Add support for notification endpoints to `influx` templates and packages. * Drop `id` prefix for secret key requirement for notification endpoints. * Add support for check resource to `pkger` parser. * Add support for check resource `pkger` dry run functionality * Add support for check resource `pkger` apply functionality * Add support for check resource `pkger` export functionality * Add new `kv.ForwardCursor` interface. * Add support for notification rule to `pkger` parser. * Add support for notification rule `pkger` dry run functionality * Add support for notification rule `pkger` apply functionality. * Add support for notification rule `pkger` export functionality. * Add support for tasks to `pkger` parser. * Add support for tasks to `pkger` dry run functionality * Add support for tasks to `pkger` apply functionality. * Add support for tasks to `pkger` export functionality. * Add `group()` to Query Builder. * Add last run status to check and notification rules. * Add last run status to tasks. * Extend `pkger` apply functionality with ability to provide secrets outside of package. * Add hide headers flag to `influx` CLI task find command. * Manual overrides for readiness endpoint. * Drop legacy inmem service implementation in favor of KV service with inmem dependency. * Drop legacy bolt service implementation in favor of KV service with bolt dependency. * While creating check, also display notification rules that would match check based on tag rules. * Increase default bucket retention period to 30 days. * Add toggle to table thresholds to allow users to choose between setting threshold colors to text or background. * Add developer documentation. * Capture User-Agent header as query source for logging purposes. ### Bug Fixes * Ensure environment variables are applied consistently across command and fixes issue where `INFLUX_` environment variable prefix was not set globally. * Remove default frontend sorting when flux queries specify sorting. * Store canceled task runs in the correct bucket. * Update `sortby` functionality for table frontend sorts to sort numbers correctly. * Prevent potential infinite loop when finding tasks by organization. * Retain user input when parsing invalid JSON during import. * Fix test issues due to multiple flush/sign-ins being called in the same test suite. * Update `influx` CLI to show only “see help” message, instead of the whole usage. * Fix notification tag-matching rules and enable tests to verify. * Extend y-axis when stacked graph is selected. * Fix query reset bug that was resetting query in script editor whenever dates were changed. * Fix table threshold bug defaulting set colors to the background. * Time labels no longer squished to the left. * Fix underlying issue with disappearing queries made in Advanced Mode. * Prevent negative zero and allow zero to have decimal places. * Limit data loader bucket selection to non system buckets. ### UI Improvements * Add honeybadger reporting to create checks. ## v2.0.0-alpha.21 ### Features * Add stacked line layer option to graphs. * Annotate log messages with trace ID, if available. * Bucket create to accept an organization name flag. * Add trace ID response header to query endpoint. ### Bug Fixes * Allow table columns to be draggable in table settings. * Light up the home page icon when active. * Make numeric inputs first class citizens. * Prompt users to make a dashboard when dashboards are empty. * Remove name editing from query definition during threshold check creation. * Wait until user stops dragging and releases marker before zooming in after threshold changes. * Adds properties to each cell on `GET /dashboards/{dashboardID}`. * Gracefully handle invalid user-supplied JSON. * Fix crash when loading queries built using the query builder. * Create cell view properties on dashboard creation. * Update scrollbar style. * Fixed table UI threshold colorization issue. * Fixed windowPeriod issue that stemmed from Webpack rules. * Added delete functionality to note cells so that they can be deleted * Fix failure to create labels when creating Telegraf configs * Fix crash when editing a Telegraf config. * Updated start/end time functionality so that custom script time ranges overwrite dropdown selections. ## v2.0.0-alpha.20 ### Features * Add TLS insecure skip verify to influx CLI. * Extend influx cli user create to allow for organization ID and user passwords to be set on user. * Auto-populate organization IDs in the code samples. * Expose bundle analysis tools for front end resources. * Allow users to view just the output section of a Telegraf config. * Allow users to see string data in single stat graph type. ### Bug Fixes * Fix long startup when running `influx help`. * Mock missing Flux dependencies when creating tasks. * Ensure array cursor iterator stats accumulate all cursor stats. * Hide Members section in Cloud environments. * Change how cloud mode is enabled. * Merge front end development environments. * Refactor table state logic on the front end. * Arrows in tables show data in ascending and descending order. * Sort by retention rules now sorts by second. * Horizontal scrollbar no longer covering data; * Allow table columns to be draggable in table settings. * Light up the home page icon when active. * Make numeric inputs first-class citizens. * Prompt users to make a dashboard when dashboards are empty. * Remove name editing from query definition during threshold check creation. * Wait until user stops dragging and releases marker before zooming in after threshold changes. ### UI Improvements * Redesign cards and animations on Getting Started page. * Allow users to filter with labels in Telegraf input search. ## v2.0.0-alpha.19 ### Features * Add shortcut for toggling comments and submitting in Script Editor. ### UI Improvements * Redesign page headers to be more space-efficient. * Add 403 handler that redirects back to the sign-in page on oats-generated routes. ### Bug Fixes * Ensure users are created with an active status. * Added missing string values for `CacheStatus` type. * Disable saving for threshold check if no threshold selected. * Query variable selector shows variable keys, not values. * Create Label overlay disables the submit button and returns a UI error if name field is empty. * Log error as info message on unauthorized API call attempts. * Ensure `members` and `owners` endpoints lead to 404 when organization resource does not exist. * Telegraf UI filter functionality shows results based on input name. * Fix Telegraf UI sort functionality. * Fix task UI sort functionality. * Exiting a configuration of a dashboard cell properly renders the cell content. * Newly created checks appear on the checklist. * Changed task runs success status code from 200 to 201 to match Swagger documentation. * Text areas have the correct height. ## v2.0.0-alpha.18 ### Features * Add jsonweb package for future JWT support. * Added the JMeter Template dashboard. ### UI Improvements * Display dashboards index as a grid. * Add viewport scaling to html meta for responsive mobile scaling. * Remove rename and delete functionality from system buckets. * Prevent new buckets from being named with the reserved `_` prefix. * Prevent user from selecting system buckets when creating Scrapers, Telegraf configurations, read/write tokens, and when saving as a task. * Limit values from draggable threshold handles to 2 decimal places. * Redesign check builder UI to fill the screen and make more room for composing message templates. * Move Tokens tab from Settings to Load Data page. * Expose all Settings tabs in navigation menu. * Added Stream and table functions to query builder. ### Bug Fixes * Remove scrollbars blocking onboarding UI step. ## v2.0.0-alpha.17 ### Features * Optional gzip compression of the query CSV response. * Add task types. * When getting task runs from the API, runs will be returned in order of most recently scheduled first. ### Bug Fixes * Fix authentication when updating a task with invalid org or bucket. * Update the documentation link for Telegraf. * Fix to surface errors properly as task notifications on create. * Fix limiting of get runs for task. ## v2.0.0-alpha.16 ### Bug Fixes * Add link to documentation text in line protocol upload overlay. * Fix issue in Authorization API, can’t create auth for another user. * Fix Influx CLI ignored user flag for auth creation. * Fix the map example in the documentation. * Ignore null/empty Flux rows which prevents a single stat/gauge crash. * Fixes an issue where clicking on a dashboard name caused an incorrect redirect. * Upgrade templates lib to 0.5.0. * Upgrade giraffe lib to 0.16.1. * Fix incorrect notification type for manually running a task. * Fix an issue where canceled tasks did not resume. ## v2.0.0-alpha.15 ### Features * Add time zone support to UI. * Added new storage inspection tool to verify TSM files. ### Bug Fixes * Fix incorrect reporting of tasks as successful when errors occur during result iteration. #### Known Issues The version of Flux included in Alpha 14 introduced `null` support. Most issues related to the `null` implementation have been fixed, but one known issue remains–the `map()` function panics if the first record processed has a`null` value. ## v2.0.0-alpha.14 ### Features * Add `influxd inspect verify-wal` tool. * Move to [Flux 0.34.2](/flux/v0/release-notes/#v0342) - includes new string functions and initial multi-datasource support with `sql.from()`. * Only click save once to save cell. * Enable selecting more columns for line visualizations. ### UI Improvements * Draw gauges correctly on HiDPI displays. * Clamp gauge position to gauge domain. * Improve display of error messages. * Remove rendering bottleneck when streaming Flux responses. * Prevent variable dropdown from clipping. ## v2.0.0-alpha.13 ### Features * Add static templates for system, Docker, Redis, Kubernetes. ## v2.0.0-alpha.12 ### Features * Enable formatting line graph y ticks with binary prefix. * Add x and y column pickers to graph types. * Add option to shade area below line graphs. ### Bug Fixes * Fix performance regression in graph tooltips. ## v2.0.0-alpha.11 ### Bug Fixes * Correctly check if columnKeys include xColumn in heatmap. ## v2.0.0-alpha.10 ### Features * Add heatmap visualization type. * Add scatterplot graph visualization type. * Add description field to tasks. * Add CLI arguments for configuring session length and renewal. * Add smooth interpolation option to line graphs. ### Bug Fixes * Removed hardcoded bucket for Getting Started with Flux dashboard. * Ensure map type variables allow for selecting values. * Generate more idiomatic Flux in query builder. * Expand tab key presses to two spaces in the Flux editor. * Prevent dragging of variable dropdowns when dragging a scrollbar inside the dropdown. * Improve single stat computation. * Fix crash when opening histogram settings with no data. ### UI Improvements * Render checkboxes in query builder tag selection lists. * Fix jumbled card text in Telegraf configuration wizard. * Change scrapers in scrapers list to be resource cards. * Export and download resource with formatted resource name with no spaces. ## v2.0.0-alpha.9 **This will remove all tasks from your InfluxDB v2.0 instance.** Before upgrading, [export all existing tasks](/influxdb/v2/process-data/manage-tasks/export-task/). After upgrading, [reimport your exported tasks](/influxdb/v2/process-data/manage-tasks/create-task/#import-a-task). ### Features * Set autorefresh of dashboard to pause if absolute time range is selected. * Switch task back end to a more modular and flexible system. * Add org profile tab with ability to edit organization name. * Add org name to dashboard page title. * Add cautioning to bucket renaming. * Add option to generate All Access token in tokens tab. * Add option to generate read/write token in tokens tab. * Add new Local Metrics Dashboard template that is created during Quick Start. ### Bug Fixes * Fixed scroll clipping found in label editing flow. * Prevent overlapping text and dot in time range dropdown. * Updated link in notes cell to a more useful site. * Show error message when adding line protocol. * Update UI Flux function documentation. * Update System template to support math with floats. * Fix the `window` function documentation. * Fix typo in the `range` Flux function example. * Update the `systemTime` function to use `system.time`. ### UI Improvements * Add general polish and empty states to Create Dashboard from Template overlay. ## v2.0.0-alpha.8 ### Features * Add the ability to edit token’s description. * Add the option to create a dashboard from a template. * Add the ability to add labels on variables. * Add switch organizations dropdown to home navigation menu item. * Add create org to side nav. * Add “Getting Started with Flux” template. * Update to Flux v0.25.0. ### Bug Fixes * Update shift to timeShift in Flux functions sidebar. ### UI Improvements * Update cursor to grab when hovering draggable areas. * Sync note editor text and preview scrolling. * Add the ability to create a bucket when creating an organization. ## v2.0.0-alpha.7 ### Features * Insert Flux function near cursor in Flux Editor. * Enable the use of variables in the Data Explorer and Cell Editor Overlay. * Add a variable control bar to dashboards to select values for variables. * Add ability to add variable to script from the side menu. * Use time range for meta queries in Data Explorer and Cell Editor Overlay. * Fix screen tearing bug in raw data view. * Add copy to clipboard button to export overlays. * Enable copying error messages to the clipboard from dashboard cells. * Add the ability to update token’s status in token list. * Allow variables to be re-ordered within control bar on a dashboard. * Add the ability to delete a template. * Save user preference for variable control bar visibility and default to visible. * Add the ability to clone a template. * Add the ability to import a variable. ### Bug Fixes * Fix mismatch in bucket row and header. * Allows user to edit note on cell. * Fix empty state styles in scrapers in org view. * Fix bucket creation error when changing retention rules types. * Fix task creation error when switching schedule types. * Fix hidden horizontal scrollbars in flux raw data view. * Fix screen tearing bug in raw data View. * Fix routing loop. ### UI Improvements * Move bucket selection in the query builder to the first card in the list. * Ensure editor is automatically focused in Note Editor. * Add ability to edit a template’s name. ## v2.0.0-alpha.6 ### Release Notes We have updated the way we do predefined dashboards to [include Templates](https://github.com/influxdata/influxdb/pull/12532)in this release which will cause existing Organizations to not have a System dashboard created when they build a new Telegraf configuration. In order to get this functionality, remove your existing data and start from scratch. ***This will remove all data from your InfluxDB v2.0 instance including time series data.*** ###### Linux and macOS ```sh rm -f ~/.influxdbv2/influxd.bolt ``` Once completed, `v2.0.0-alpha.6` can be started. ### Features * Add ability to import a dashboard. * Add ability to import a dashboard from organization view. * Add ability to export a dashboard and a task. * Add `run` subcommand to `influxd` binary. This is also the default when no subcommand is specified. * Add ability to save a query as a variable from the Data Explorer. * Add System template on onboarding. ### Bug Fixes * Stop scrollbars from covering text in Flux editor. ### UI Improvements * Fine tune keyboard interactions for managing labels from a resource card. ## v2.0.0-alpha.5 This release includes a breaking change to the format in which Time-Structured Merge Tree (TSM) and index data are stored on disk.***Existing local data will not be queryable after upgrading to this release.*** Prior to installing this release, remove all storage-engine data from your local InfluxDB 2.x installation. To remove only TSM and index data and preserve all other InfluxDB 2.x data (organizations, buckets, settings, etc), run the following command. ###### Linux and macOS ```sh rm -rf ~/.influxdbv2/engine ``` Once completed, InfluxDB v2.0.0-alpha.5 can be started. ### Features * Add labels to cloned tasks. * Add ability to filter resources by clicking a label. * Add ability to add a member to org. * Improve representation of TSM tagsets on disk. * Add ability to remove a member from org. * Update to Flux v0.21.4. ### Bug Fixes * Prevent clipping of code snippets in Firefox. * Prevent clipping of cell edit menus in dashboards. ### UI Improvements * Make code snippet copy functionality easier to use. * Always show live preview in note cell editor. * Redesign scraper creation workflow. * Show warning in Telegraf and scraper lists when user has no buckets. * Streamline label addition, removal, and creation from the dashboards list. ## v2.0.0-alpha.4 ### Features * Add the ability to run a task manually from tasks page. * Add the ability to select a custom time range in explorer and dashboard. * Display the version information on the login page. * Add the ability to update a variable’s name and query. * Add labels to cloned dashboard. * Add ability filter resources by label name. * Add ability to create or add labels to a resource from labels editor. * Update to Flux v0.20. ### Bug Fixes * Update the bucket retention policy to update the time in seconds. ### UI Improvements * Update the preview in the label overlays to be shorter. * Add notifications to scrapers page for created/deleted/updated scrapers. * Add notifications to buckets page for created/deleted/updated buckets. * Update the admin page to display error for password length. ## v2.0.0-alpha.3 ### Features * Add the ability to name a scraper target. * Display scraper name as the first and only updatable column in scrapers list. * Add the ability to view runs for a task. * Display last completed run for tasks list. * Add the ability to view the logs for a specific task run. ### Bug Fixes * Update the inline edit for resource names to guard for empty strings. * Prevent a new template dashboard from being created on every Telegraf config update. * Fix overlapping buttons in Telegraf verify data step. ### UI Improvements * Move the download Telegraf config button to view config overlay. * Combine permissions for user by type. ## v2.0.0-alpha.2 ### Features * Add instructions button to view `$INFLUX_TOKEN` setup for Telegraf configs. * Save the `$INFLUX_TOKEN` environmental variable in Telegraf configs. * Update Tasks tab on Organizations page to look like Tasks Page. * Add view button to view the Telegraf config toml. * Add plugin information step to allow for config naming and configure one plugin at a time. * Update Dashboards tab on Organizations page to look like Dashboards Page. ### Bug Fixes * Update the System Telegraf Plugin bundle to include the Swap plugin. * Revert behavior allowing users to create authorizations on behalf of another user. ### UI Improvements * Change the wording for the plugin config form button to “Done.” * Change the wording for the Collectors configure step button to “Create and Verify.” * Standardize page loading spinner styles. * Show checkbox on “Save As” button in Data Explorer. * Make collectors plugins side bar visible in only the configure step. * Swap retention policies on Create bucket page. ## v2.0.0-alpha.1 This is the initial alpha release of InfluxDB 2.0. --- # Supported releases Source: https://docs.influxdata.com/influxdb/v2/reference/release-notes/supported-release/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxData provides support for the following minor, major, and maintenance releases: ##### Major * Includes new features, enhancements to existing features, and applicable error corrections from all prior releases. * InfluxDB supports backward compatibility within a major release. ##### Minor (x.Y.z) * Includes new minor features, enhancements to existing features, and includes applicable error corrections from prior minor and maintenance releases. ##### Maintenance (x.y.Z) * Includes error corrections severely affecting a number of customers that cannot wait for the next major or minor release. Include applicable error corrections made in prior maintenance releases. Released as as needed based on customer feedback and outstanding errors (no predefined schedule). * Interim (x.y.z.A) Fourth digit (or beyond) are an exception, and only delivered to address specific customer issues. These releases are retired in a timely manner by the customer once the issue has been addressed in a standard release. * InfluxData provides Support Services for the current and previous Minor Release (x.Y) including Maintenance Releases (x.y.Z) included in the respective Minor Release. * When InfluxData releases a Major Release (X.y), InfluxData will provide Support Services for the current and preceding Major Release (X.y), including all Maintenance Releases (x.y.Z) included in the respective Minor Release that is available at least 12 months from the Major Release. For more information about supported 2.x releases, click [here](https://www.influxdata.com/legal/support-policy/). > [!Note] > The link above contains the full legal description of the supported releases. #### Related * [Release notes](/influxdb/v2/reference/release-notes/) --- # Sample data Source: https://docs.influxdata.com/influxdb/v2/reference/sample-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use sample data to familiarize yourself with time series data and InfluxDB. InfluxData provides many sample time series datasets to use with InfluxDB. You can also use the [Flux InfluxDB sample package](/flux/v0/stdlib/influxdata/influxdb/sample/)to view, download, and output sample datasets. * [Live datasets](#live-datasets) * [Air sensor sample data](#air-sensor-sample-data) * [Bitcoin sample data](#bitcoin-sample-data) * [NOAA NDBC data](#noaa-ndbc-data) * [USGS Earthquake data](#usgs-earthquake-data) * [Static datasets](#static-datasets) * [Bird migration sample data](#bird-migration-sample-data) * [Machine production sample data](#machine-production-sample-data) * [NOAA water sample data](#noaa-water-sample-data) ## Live datasets Live sample datasets are continually updated with new data. These sets can be loaded once and treated as a “static” dataset, or you can create an [InfluxDB task](/influxdb/v2/process-data/get-started/) to periodically collect and write new data. * [Air sensor sample data](#air-sensor-sample-data) * [Bitcoin sample data](#bitcoin-sample-data) * [NOAA NDBC data](#noaa-ndbc-data) * [USGS Earthquake data](#usgs-earthquake-data) ### Air sensor sample data **Size**: \~600 KB • **Updated**: every 15m Air sensor sample data represents an “Internet of Things” (IoT) use case by simulating temperature, humidity, and carbon monoxide levels for multiple rooms in a building. To continually download and write updated air sensor sample data to a bucket,[create an InfluxDB task](/influxdb/v2/process-data/manage-tasks/create-task/)with the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" option task = { name: "Collect air sensor sample data", every: 15m, } sample.data(set: "airSensor") |> to(bucket: "example-bucket") ``` [](#companion-relational-sensor-data) Companion relational sensor data The air sensor sample dataset is paired with a relational SQL dataset with meta information about sensors in each room. These two sample datasets are used to demonstrate[how to join time series data and relational data with Flux](/influxdb/v2/query-data/flux/sql/#join-sql-data-with-data-in-influxdb)in the [Query SQL data sources](/influxdb/v2/query-data/flux/sql/) guide. [Download SQL air sensor data](https://influx-testdata.s3.amazonaws.com/sample-sensor-info.csv) ### Bitcoin sample data **Size**: \~700 KB • **Updated**: every 15m The Bitcoin sample dataset provides Bitcoin prices from the last 30 days—[Powered by CoinDesk](https://www.coindesk.com/price/bitcoin). To continually download and write updated Bitcoin sample data to a bucket,[create an InfluxDB task](/influxdb/v2/process-data/manage-tasks/create-task/)with the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" option task = { name: "Collect Bitcoin sample data", every: 15m, } sample.data(set: "bitcoin") |> to(bucket: "example-bucket") ``` ### NOAA NDBC data **Size**: \~1.3 MB • **Updated**: every 15m The **National Oceanic and Atmospheric Administration (NOAA) National Data Buoy Center (NDBC)**dataset provides the latest observations from the NOAA NDBC network of buoys throughout the world. To continually download and write updated NOAA NDBC sample data to a bucket,[create an InfluxDB task](/influxdb/v2/process-data/manage-tasks/create-task/)with the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" option task = { name: "Collect NOAA NDBC sample data", every: 15m, } sample.data(set: "noaa") |> to(bucket: "example-bucket") ``` ### USGS Earthquake data **Size**: \~6 MB • **Updated**: every 15m The United States Geological Survey (USGS) earthquake dataset contains observations collected from USGS seismic sensors around the world over the last week. To continually download and write updated USGS earthquake sample data to a bucket,[create an InfluxDB task](/influxdb/v2/process-data/manage-tasks/create-task/)with the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" option task = { name: "Collect USGS sample data", every: 15m, } sample.data(set: "usgs") |> to(bucket: "example-bucket") ``` ## Static datasets Static datasets are fixed datasets from a specific past time range. * [Bird migration sample data](#bird-migration-sample-data) * [Machine production sample data](#machine-production-sample-data) * [NOAA water sample data](#noaa-water-sample-data) ### Bird migration sample data **Size**: \~1.2 MB **Time range**: 2019-04-01T13:00:00Z to 2019-04-12T20:00:00Z Bird migration sample data is adapted from the[Movebank: Animal Tracking dataset](https://www.kaggle.com/pulkit8595/movebank-animal-tracking)and represents animal migratory movements throughout 2019. To download and write the bird migration sample data to a bucket, run the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" sample.data(set: "birdMigration") |> to("example-bucket") ``` The bird migration sample dataset is used in the [Work with geo-temporal data](/influxdb/v2/query-data/flux/geo/)guide to demonstrate how to query and analyze geo-temporal data. ### Machine production sample data **Size**: \~11.9 MB **Time range**: 2021-08-01T00:00:00Z to 2021-08-02T00:00:00Z The machine production sample dataset includes states and metrics reported from four automated grinding wheel stations on a production line. To download and write the machine production sample data to a bucket, run the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" sample.data(set: "machineProduction") |> to(bucket: "example-bucket") ``` The machine production data is used in the[IoT sensor common query](/influxdb/v2/query-data/common-queries/iot-common-queries/) guide. ### NOAA water sample data **Size**: \~10 MB **Time range**: 2019-08-17T00:00:00Z to 2019-09-17T22:00:00Z The **National Oceanic and Atmospheric Administration (NOAA) water sample dataset**is static dataset extracted from[NOAA Center for Operational Oceanographic Products and Services](http://tidesandcurrents.noaa.gov/stations.html) data. The sample dataset includes 15,258 observations of water levels (ft) collected every six minutes at two stations (Santa Monica, CA (ID 9410840) and Coyote Creek, CA (ID 9414575)) over the period from **August 17, 2019** through **September 17, 2019**. To download and write the NOAA water sample data to a bucket, run the following Flux query.*Replace `example-bucket` with your target bucket*. ```js import "influxdata/influxdb/sample" sample.data(set: "noaaWater") |> to(bucket: "example-bucket") ``` The NOAA water sample dataset is used to demonstrate Flux queries in the[Common queries](/influxdb/v2/query-data/common-queries/) and[Common tasks](/influxdb/v2/process-data/common-tasks/) guides. --- # InfluxDB syntaxes Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB uses a handful of languages and syntaxes to perform tasks such as writing, querying, processing, and deleting data. The following articles provide information about the different syntaxes used with InfluxDB and the contexts in which they’re used: ### [Flux](/influxdb/v2/reference/syntax/flux/) Flux is a functional data scripting language designed for querying, analyzing, and acting on data. ### [InfluxQL](/influxdb/v2/reference/syntax/influxql/) InfluxQL is an SQL-like query language for interacting with data in InfluxDB. ### [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) InfluxDB uses line protocol to write data points. It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point. ### [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) InfluxDB and Flux return query results in annotated CSV format. You can also read annotated CSV directly from Flux with the `csv.from()` function, write data to InfluxDB using annotated CSV and the `influx write` command, or upload a CSV file in the UI. ### [Delete predicate](/influxdb/v2/reference/syntax/delete-predicate/) InfluxDB uses an InfluxQL-like predicate syntax to determine what data points to delete. [syntax](/influxdb/v2/tags/syntax/) --- # Annotated CSV Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/annotated-csv/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB `/api/v2/query` API returns query results in annotated CSV format. You can also write data to InfluxDB using annotated CSV and the `influx write` command, or [upload a CSV file](/influxdb/v2/write-data/no-code/load-data/)in the InfluxDB UI. CSV tables must be encoded in UTF-8 and Unicode Normal Form C as defined in [UAX15](http://www.unicode.org/reports/tr15/). InfluxDB removes carriage returns before newline characters. ## CSV response format InfluxDB annotated CSV supports encodings listed below. ### Tables A table may have the following rows and columns. #### Rows * **Annotation rows**: describe column properties. * **Header row**: defines column labels (one header row per table). * **Record row**: describes data in the table (one record per row). ##### Example ```csv #group,false,false,true,true,false,false,true,true,true,true #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string #default,mean,,,,,,,,, ,result,table,_start,_stop,_time,_value,_field,_measurement,host,region ,,0,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,15.43,mem,m,A,east ,,1,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,59.25,mem,m,B,east ,,2,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,52.62,mem,m,C,east ``` #### Columns In addition to the data columns, a table may include the following columns: * **Annotation column**: Displays the name of an annotation. Only used in annotation rows and is always the first column. Value can be empty or a supported [annotation](#annotations). The response format uses a comma (`,`) to separate an annotation name from values in the row. To account for this, rows in the table start with a leading comma; you’ll notice an empty column for the entire length of the table. * **Result column**: Contains the name of the result specified by the query. * **Table column**: Contains a unique ID for each table in a result. ### Multiple tables and results If a file or data stream contains multiple tables or results, the following requirements must be met: * A table column indicates which table a row belongs to. * All rows in a table are contiguous. * An empty row delimits a new table boundary in the following cases: * Between tables in the same result that do not share a common table schema. * Between concatenated CSV files. * Each new table boundary starts with new annotation and header rows. ##### Example ```csv #group,false,false,true,true,false,false,true,true,true,true #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string #default,_result,,,,,,,,, ,result,table,_start,_stop,_time,_value,_field,_measurement,host,region ,,0,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,15.43,mem,m,A,east ,,1,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,59.25,mem,m,B,east ,,2,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,52.62,mem,m,C,east #group,false,false,true,true,true,true,false,false,true,true #datatype,string,long,string,string,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,string #default,_result,,,,,,,,, ,result,table,_field,_measurement,_start,_stop,_time,_value,host,region ,,3,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,ok,A,east ,,4,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,info,B,east ,,5,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,info,C,east ``` ## Dialect options Flux supports the following dialect options for `text/csv` format. | Option | Description |Default| |-----------------|-----------------------------------------------------------------|-------| | **header** | If true, the header row is included. |`true` | | **delimiter** | Character used to delimit columns. | `,` | | **quoteChar** | Character used to quote values containing the delimiter. | `"` | | **annotations** | List of annotations to encode (datatype, group, or default). |`empty`| |**commentPrefix**|String prefix to identify a comment. Always added to annotations.| `#` | ## Annotations Annotation rows describe column properties, and start with `#` (or commentPrefix value). The first column in an annotation row always contains the annotation name. Subsequent columns contain annotation values as shown in the table below. |Annotation name| Values | Description | |---------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | **datatype** |a [data type](#data-types) or [line protocol element](#line-protocol-elements)|Describes the type of data or which line protocol element the column represents.| | **group** | boolean flag `true` or `false` | Indicates the column is part of the group key. | | **default** | a value of the column’s data type | Value to use for rows with an empty value. | Some tools might use or require a comma (`,`) to separate the annotation name from values in an annotation row. > [!Note] > To encode a table with its [group key](/influxdb/v2/reference/glossary/#group-key), > the `datatype`, `group`, and `default` annotations must be included. > If a table has no rows, the `default` annotation provides the group key values. ## Data types | Datatype |Flux type| Description | |------------|---------|--------------------------------------------------------------------------------------------------------------| | boolean | bool | “true” or “false” | |unsignedLong| uint | unsigned 64-bit integer | | long | int | signed 64-bit integer | | double | float | IEEE-754 64-bit floating-point number | | string | string | UTF-8 encoded string | |base64Binary| bytes | base64 encoded sequence of bytes as defined in RFC 4648 | | dateTime | time |instant in time, may be followed with a colon : and a description of the format (number, RFC3339, RFC3339Nano)| | duration |duration | length of time represented as an unsigned 64-bit integer number of nanoseconds | ## Line protocol elements The `datatype` annotation accepts [data types](#data-types) and **line protocol elements**. Line protocol elements identify how columns are converted into line protocol when using the[`influx write` command](/influxdb/v2/reference/cli/influx/write/) to write annotated CSV to InfluxDB. |Line protocol element| Description | |---------------------|---------------------------------------------------------------| | `measurement` | column value is the measurement | | `field` *(default)* |column header is the field key, column value is the field value| | `tag` | column header is the tag key, column value is the tag value | | `time` | column value is the timestamp *(alias for `dateTime`)* | |`ignore` or`ignored` | column is ignored and not included in line protocol | ### Mixing data types and line protocol elements Columns with [data types](#data-types) (other than `dateTime`) in the`#datatype` annotation are treated as **fields** when converted to line protocol. Columns without a specified data type default to `field` when converted to line protocol and **column values are left unmodified** in line protocol.*See an example [below](#example-of-mixing-data-types-line-protocol-elements) and[line protocol data types and format](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format).* ### Time columns A column with `time` or `dateTime` `#datatype` annotations are used as the timestamp when converted to line protocol. If there are multiple `time` or `dateTime` columns, the last column (on the right) is used as the timestamp in line protocol. Other time columns are ignored and the `influx write` command outputs a warning. Time column values should be **Unix nanosecond timestamps**, **RFC3339**, or **RFC3339Nano**. ##### Example line protocol elements in datatype annotation ```csv #group false,false,false,false,false,false,false #datatype measurement,tag,tag,field,field,ignored,time #default ,,,,,, m,cpu,host,time_steal,usage_user,nothing,time cpu,cpu1,host1,0,2.7,a,1482669077000000000 cpu,cpu1,host2,0,2.2,b,1482669087000000000 ``` Resulting line protocol: ```text cpu,cpu=cpu1,host=host1 time_steal=0,usage_user=2.7 1482669077000000000 cpu,cpu=cpu1,host=host2 time_steal=0,usage_user=2.2 1482669087000000000 ``` ##### Example of mixing data types and line protocol elements ```csv #group,false,false,false,false,false,false,false,false,false #datatype,measurement,tag,string,double,boolean,long,unsignedLong,duration,dateTime #default,test,annotatedDatatypes,,,,,, ,m,name,s,d,b,l,ul,dur,time ,,,str1,1.0,true,1,1,1ms,1 ,,,str2,2.0,false,2,2,2us,2020-01-11T10:10:10Z ``` Resulting line protocol: ```text test,name=annotatedDatatypes s="str1",d=1,b=true,l=1i,ul=1u,dur=1000000i 1 test,name=annotatedDatatypes s="str2",d=2,b=false,l=2i,ul=2u,dur=2000i 1578737410000000000 ``` ## Errors If an error occurs during execution, a table returns with: * An error column that contains an error message. * A reference column with a unique reference code to identify more information about the error. * A second row with error properties. If an error occurs: * Before InfluxDB responds with data, the HTTP status code indicates an error. The output table contains error details. * After InfluxDB sends partial results to the client, the error is encoded as the next table and remaining results are discarded. In this case, the HTTP status code remains 200 OK. ##### Example Encoding for an error with the datatype annotation: ```csv #datatype,string,long ,error,reference ,Failed to parse query,897 ``` #### Related * [csv.from() function](/flux/v0/stdlib/csv/from/) * [Extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended/) [csv](/influxdb/v2/tags/csv/)[syntax](/influxdb/v2/tags/syntax/) | Option | Description | Default | | --- | --- | --- | | Option | Description | Default | | header | If true, the header row is included. | true | | delimiter | Character used to delimit columns. | , | | quoteChar | Character used to quote values containing the delimiter. | " | | annotations | List of annotations to encode (datatype, group, or default). | empty | | commentPrefix | String prefix to identify a comment. Always added to annotations. | # | | Annotation name | Values | Description | | --- | --- | --- | | Annotation name | Values | Description | | datatype | a data type or line protocol element | Describes the type of data or which line protocol element the column represents. | | group | boolean flag true or false | Indicates the column is part of the group key. | | default | a value of the column’s data type | Value to use for rows with an empty value. | | Datatype | Flux type | Description | | --- | --- | --- | | Datatype | Flux type | Description | | boolean | bool | “true” or “false” | | unsignedLong | uint | unsigned 64-bit integer | | long | int | signed 64-bit integer | | double | float | IEEE-754 64-bit floating-point number | | string | string | UTF-8 encoded string | | base64Binary | bytes | base64 encoded sequence of bytes as defined in RFC 4648 | | dateTime | time | instant in time, may be followed with a colon : and a description of the format (number, RFC3339, RFC3339Nano) | | duration | duration | length of time represented as an unsigned 64-bit integer number of nanoseconds | | Line protocol element | Description | | --- | --- | | Line protocol element | Description | | measurement | column value is the measurement | | field (default) | column header is the field key, column value is the field value | | tag | column header is the tag key, column value is the tag value | | time | column value is the timestamp (alias for dateTime ) | | ignore or ignored | column is ignored and not included in line protocol | --- # Extended annotated CSV Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/annotated-csv/extended/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). **Extended annotated CSV** provides additional annotations and options that specify how CSV data should be converted to [line protocol](/influxdb/v2/reference/syntax/line-protocol/)and written to InfluxDB. InfluxDB uses the [`csv2lp` library](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp)to convert CSV into line protocol. Extended annotated CSV supports all [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/)annotations. The Flux [`csv.from` function](/flux/v0/stdlib/csv/from/) only supports[annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), not extended annotated CSV. To write data to InfluxDB, line protocol must include the following: * [measurement](/influxdb/v2/reference/syntax/line-protocol/#measurement) * [field set](/influxdb/v2/reference/syntax/line-protocol/#field-set) * [timestamp](/influxdb/v2/reference/syntax/line-protocol/#timestamp) *(Optional but recommended)* * [tag set](/influxdb/v2/reference/syntax/line-protocol/#tag-set) *(Optional)* Extended CSV annotations identify the element of line protocol a column represents. ## CSV Annotations Extended annotated CSV extends and adds the following annotations: * [datatype](#datatype) * [constant](#constant) * [timezone](#timezone) * [concat](#concat) ### datatype Use the `#datatype` annotation to specify the [line protocol element](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)a column represents. To explicitly define a column as a **field** of a specific data type, use the field type in the annotation (for example: `string`, `double`, `long`, etc.). | Data type | Resulting line protocol | |-----------------------------|---------------------------------------| | [measurement](#measurement) | Column is the **measurement** | | [tag](#tag) | Column is a **tag** | | [dateTime](#datetime) | Column is the **timestamp** | | [field](#field) | Column is a **field** | | [ignored](#ignored) | Column is ignored | | [string](#string) | Column is a **string field** | | [double](#double) | Column is a **float field** | | [long](#long) | Column is an **integer field** | |[unsignedLong](#unsignedlong)|Column is an **unsigned integer field**| | [boolean](#boolean) | Column is a **boolean field** | #### measurement Indicates the column is the **measurement**. #### tag Indicates the column is a **tag**. The **column label** is the **tag key**. The **column value** is the **tag value**. #### dateTime Indicates the column is the **timestamp**.`time` is an alias for `dateTime`. If the [timestamp format](#supported-timestamp-formats) includes a time zone, the parsed timestamp includes the time zone offset. By default, all timestamps are UTC. You can also use the [`#timezone` annotation](#timezone) to adjust timestamps to a specific time zone. > [!Note] > There can only be **one** `dateTime` column. The `influx write` command converts timestamps to [Unix timestamps](/influxdb/v2/reference/glossary/#unix-timestamp). Append the timestamp format to the `dateTime` datatype with (`:`). ```csv #datatype dateTime:RFC3339 #datatype dateTime:RFC3339Nano #datatype dateTime:number #datatype dateTime:2006-01-02 ``` ##### Supported timestamp formats |Timestamp format| Description | Example | |----------------|-----------------|--------------------------------| | **RFC3339** |RFC3339 timestamp| `2020-01-01T00:00:00Z` | |**RFC3339Nano** |RFC3339 timestamp|`2020-01-01T00:00:00.000000000Z`| | **number** | Unix timestamp | `1577836800000000000` | > [!Note] > If using the `number` timestamp format and timestamps are **not in nanoseconds**, > use the [`influx write --precision` flag](/influxdb/v2/reference/cli/influx/write/#flags)to specify the [timestamp precision](/influxdb/v2/reference/glossary/#precision). ##### Custom timestamp formats To specify a custom timestamp format, use timestamp formats as described in the[Go time package](https://golang.org/pkg/time). For example: `2020-01-02`. #### field Indicates the column is a **field**. The **column label** is the **field key**. The **column value** is the **field value**. > [!Note] > With the `field` datatype, field values are copies **as-is** to line protocol. > For information about line protocol values and how they are written to InfluxDB, > see [Line protocol data types and formats](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format). > We generally recommend specifying the [field type](#field-types) in annotations. #### ignored The column is ignored and not written to InfluxDB. #### Field types The column is a **field** of a specified type. The **column label** is the **field key**. The **column value** is the **field value**. * [string](#string) * [double](#double) * [long](#long) * [unsignedLong](#unsignedlong) * [boolean](#boolean) ##### string Column is a **[string](/influxdb/v2/reference/glossary/#string) field**. ##### double Column is a **[float](/influxdb/v2/reference/glossary/#float) field**. By default, InfluxDB expects float values that use a period (`.`) to separate the fraction from the whole number. If column values include or use other separators, such as commas (`,`) to visually separate large numbers into groups, specify the following **float separators**: * **fraction separator**: Separates the fraction from the whole number. * **ignored separator**: Visually separates the whole number into groups but ignores the separator when parsing the float value. Use the following syntax to specify **float separators**: ```sh # Syntax # Example ., # With the float separators above # 1,200,000.15 => 1200000.15 ``` Append **float separators** to the `double` datatype annotation with a colon (`:`). For example: ``` #datatype "double:.," ``` > [!Note] > If your **float separators** include a comma (`,`), wrap the column annotation in double > quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. > You can also [define a custom column separator](#define-custom-column-separator). ##### long Column is an **[integer](/influxdb/v2/reference/glossary/#integer) field**. If column values contain separators such as periods (`.`) or commas (`,`), specify the following **integer separators**: * **fraction separator**: Separates the fraction from the whole number.***Integer values are truncated at the fraction separator when converted to line protocol.*** * **ignored separator**: Visually separates the whole number into groups but ignores the separator when parsing the integer value. Use the following syntax to specify **integer separators**: ```sh # Syntax # Example ., # With the integer separators above # 1,200,000.00 => 1200000i ``` Append **integer separators** to the `long` datatype annotation with a colon (`:`). For example: ``` #datatype "long:.," ``` > [!Note] > If your **integer separators** include a comma (`,`), wrap the column annotation in double > quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. > You can also [define a custom column separator](#define-custom-column-separator). ##### unsignedLong Column is an **[unsigned integer (uinteger)](/influxdb/v2/reference/glossary/#unsigned-integer) field**. If column values contain separators such as periods (`.`) or commas (`,`), specify the following **uinteger separators**: * **fraction separator**: Separates the fraction from the whole number.***Uinteger values are truncated at the fraction separator when converted to line protocol.*** * **ignored separator**: Visually separates the whole number into groups but ignores the separator when parsing the uinteger value. Use the following syntax to specify **uinteger separators**: ```sh # Syntax # Example ., # With the uinteger separators above # 1,200,000.00 => 1200000u ``` Append **uinteger separators** to the `long` datatype annotation with a colon (`:`). For example: ``` #datatype "unsignedLong:.," ``` > [!Note] > If your **uinteger separators** include a comma (`,`), wrap the column annotation in double > quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. > You can also [define a custom column separator](#define-custom-column-separator). ##### boolean Column is a **[boolean](/influxdb/v2/reference/glossary/#boolean) field**. If column values are not [supported boolean values](/influxdb/v2/reference/syntax/line-protocol/#boolean), specify the **boolean format** with the following syntax: ```sh # Syntax : # Example y,Y,1:n,N,0 # With the boolean format above # y => true, Y => true, 1 => true # n => false, N => false, 0 => false ``` Append the **boolean format** to the `boolean` datatype annotation with a colon (`:`). For example: ``` #datatype "boolean:y,Y:n,N" ``` > [!Note] > If your **boolean format** contains commas (`,`), wrap the column annotation in double > quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. > You can also [define a custom column separator](#define-custom-column-separator). ### constant Use the `#constant` annotation to define a constant column label and value for each row. The `#constant` annotation provides a way to supply[line protocol elements](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)that don’t exist in the CSV data. Use the following syntax to define constants: ``` #constant ,, ``` To provide multiple constants, include each `#constant` annotations on a separate line. ``` #constant measurement,m #constant tag,dataSource,csv ``` > [!Note] > For constants with `measurement` and `dateTime` datatypes, the second value in > the constant definition is the **column-value**. ### timezone Use the `#timezone` annotation to update timestamps to a specific timezone. By default, timestamps are parsed as UTC. Use the `±HHmm` format to specify the timezone offset relative to UTC. ### strict mode Use the `:strict` keyword to indicate a loss of precision when parsing `long` or `unsignedLong` data types. Turn on strict mode by using a column data type that ends with `strict`, such as `long:strict`. When parsing `long` or `unsignedLong` value from a string value with fraction digits, the whole CSV row fails when in a strict mode. A warning is printed when not in a strict mode, saying `line x: column y: '1.2' truncated to '1' to fit into long data type`. For more information on strict parsing, see the [package documentation](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp). ##### Timezone examples | Timezone |Offset | |-------------------------------|-------| | US Mountain Daylight Time |`-0600`| | Central European Summer Time |`+0200`| |Australia Eastern Standard Time|`+1000`| | Apia Daylight Time |`+1400`| ##### Timezone annotation example ``` #timezone -0600 ``` ### concat The `#concat` annotation adds a new column that is concatenated from existing columns according to bash-like string interpolation literal with variables referencing existing column labels. For example: ``` #concat,string,fullName,${firstName} ${lastName} ``` This is especially useful when constructing a timestamp from multiple columns. For example, the following annotation will combine the given CSV columns into a timestamp: ``` #concat,dateTime:2006-01-02,${Year}-${Month}-${Day} Year,Month,Day,Hour,Minute,Second,Tag,Value 2020,05,22,00,00,00,test,0 2020,05,22,00,05,00,test,1 2020,05,22,00,10,00,test,2 ``` ## Define custom column separator If columns are delimited using a character other than a comma, use the `sep`keyword to define a custom separator **in the first line of your CSV file**. ``` sep=; ``` ## Annotation shorthand Extended annotated CSV supports **annotation shorthand**. Include the column label, datatype, and *(optional)* default value in each column header row using the following syntax: ``` || ``` ##### Example annotation shorthand ``` m|measurement,location|tag|Hong Kong,temp|double,pm|long|0,time|dateTime:RFC3339 weather,San Francisco,51.9,38,2020-01-01T00:00:00Z weather,New York,18.2,,2020-01-01T00:00:00Z weather,,53.6,171,2020-01-01T00:00:00Z ``` ##### The shorthand explained * The `m` column represents the **measurement** and has no default value. * The `location` column is a **tag** with the default value, `Hong Kong`. * The `temp` column is a **field** with **float** (`double`) values and no default value. * The `pm` column is a **field** with **integer** (`long`) values and a default of `0`. * The `time` column represents the **timestamp**, uses the **RFC3339** timestamp format, and has no default value. ##### Resulting line protocol ``` weather,location=San\ Francisco temp=51.9,pm=38i 1577836800000000000 weather,location=New\ York temp=18.2,pm=0i 1577836800000000000 weather,location=Hong\ Kong temp=53.6,pm=171i 1577836800000000000 ``` #### Related * [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/) * [influx write](/influxdb/v2/reference/cli/influx/write/) * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) [csv](/influxdb/v2/tags/csv/)[syntax](/influxdb/v2/tags/syntax/)[write](/influxdb/v2/tags/write/) | Data type | Resulting line protocol | | --- | --- | | Data type | Resulting line protocol | | measurement | Column is the measurement | | tag | Column is a tag | | dateTime | Column is the timestamp | | field | Column is a field | | ignored | Column is ignored | | string | Column is a string field | | double | Column is a float field | | long | Column is an integer field | | unsignedLong | Column is an unsigned integer field | | boolean | Column is a boolean field | | Timestamp format | Description | Example | | --- | --- | --- | | Timestamp format | Description | Example | | RFC3339 | RFC3339 timestamp | 2020-01-01T00:00:00Z | | RFC3339Nano | RFC3339 timestamp | 2020-01-01T00:00:00.000000000Z | | number | Unix timestamp | 1577836800000000000 | | Timezone | Offset | | --- | --- | | Timezone | Offset | | US Mountain Daylight Time | -0600 | | Central European Summer Time | +0200 | | Australia Eastern Standard Time | +1000 | | Apia Daylight Time | +1400 | --- # Delete predicate syntax Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/delete-predicate/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB uses an InfluxQL-like predicate syntax to determine what data[points](/influxdb/v2/reference/glossary/#point) to delete. InfluxDB uses the delete predicate to evaluate the [series keys](/influxdb/v2/reference/glossary/#series-key)of points in the time range specified in the delete request. Points with series keys that evaluate to `true` for the given predicate are deleted. Points with series keys that evaluate to `false` are preserved. A delete predicate is comprised of one or more [predicate expressions](/influxdb/v2/reference/glossary/#predicate-expression). The left operand of the predicate expression is the column name. The right operand is the column value. Operands are compared using [comparison operators](#comparison-operators). Use [logical operators](#logical-operators) to combine two or more predicate expressions. ##### Example delete predicate ```sql key1="value1" AND key2="value" ``` > [!Note] > #### Predicates with special characters or keywords > > If your predicate contains keywords or strings with special characters, wrap each in escaped > quotes to ensure the predicate string is parsed correctly. > > Because delete predicates follow [InfluxQL](/influxdb/v2/reference/syntax/influxql) syntax, [any InfluxQL keyword](/influxdb/v2/reference/syntax/influxql/spec/#keywords)that matches your tag name needs to be escaped. Keywords are case-insensitive. > > ``` > // Escaped due to the "-" > "_measurement=\"example-dash\"" > > // Escaped because "Name" is a keyword > "_measurement=example and \"Name\"=predicate" > ``` #### Column limitations when deleting data **InfluxDB 2.10** supports deleting data by any column or tag***except*** the following: * `_time` * `_field` * `_value` *InfluxDB 2.10 does not support deleting data **by field**.* ## Logical operators Logical operators join two or more predicate expressions. |Operator| Description | |--------|----------------------------------------------------------------------------| | `AND` |Both left and right operands must be `true` for the expression to be `true`.| ## Comparison operators Comparison operators compare left and right operands and return `true` or `false`. |Operator|Description| Example |Result| |--------|-----------|-------------|------| | `=` | Equal to |`"abc"="abc"`|`true`| ## Delete predicate examples * [Delete points by measurement](#delete-points-by-measurement) * [Delete points by tag set](#delete-points-by-tag-set) ### Delete points by measurement The following will delete points in the `sensorData` measurement: ```sql _measurement="sensorData" ``` ### Delete points by tag set The following will delete points from the `prod-1.4` host in the `us-west` region: ```sql host="prod-1.4" AND region="us-west" ``` ## Limitations The delete predicate syntax has the following limitations. * Delete predicates do not support regular expressions. * Delete predicates do not support the `OR` logical operator. * Delete predicates only support equality (`=`), not inequality (`!=`). * Delete predicates can use any column or tag **except** `_time`, `_field`, or `_value`. #### Related * [Delete data](/influxdb/v2/write-data/delete-data/) * [influx delete](/influxdb/v2/reference/cli/influx/delete/) [syntax](/influxdb/v2/tags/syntax/)[delete](/influxdb/v2/tags/delete/) | Operator | Description | | --- | --- | | Operator | Description | | AND | Both left and right operands must be true for the expression to be true . | | Operator | Description | Example | Result | | --- | --- | --- | --- | | Operator | Description | Example | Result | | = | Equal to | "abc"="abc" | true | --- # Flux syntax Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/flux/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux is a functional data scripting language designed for querying, analyzing, and acting on data. ## Flux documentation View the [Flux documentation](/flux/v0/) for more information about the Flux syntax. * [Get started with Flux](/flux/v0/get-started/) * [Flux standard library](/flux/v0/stdlib/) * [Flux language specification](/flux/v0/spec/) **The following provide information about Flux and InfluxDB:** ### [Flux vs InfluxQL](/influxdb/v2/reference/syntax/flux/flux-vs-influxql/) Flux is an alternative to InfluxQL and other SQL-like query languages for querying and analyzing data. Learn about what’s possible with Flux and how Flux compares to InfluxQL. [syntax](/influxdb/v2/tags/syntax/)[flux](/influxdb/v2/tags/flux/) --- # Flux vs InfluxQL Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/flux/flux-vs-influxql/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Flux is an alternative to [InfluxQL](/influxdb/v2/query-data/influxql/)and other SQL-like query languages for querying and analyzing data. Flux uses functional language patterns that overcome many InfluxQL limitations. Check out the following distinctions between Flux and InfluxQL: * [Tasks possible with Flux](#tasks-possible-with-flux) * [InfluxQL and Flux parity](#influxql-and-flux-parity) ## Tasks possible with Flux * [Joins](#joins) * [Math across measurements](#math-across-measurements) * [Sort by tags](#sort-by-tags) * [Group by any column](#group-by-any-column) * [Window by calendar months and years](#window-by-calendar-months-and-years) * [Work with multiple data sources](#work-with-multiple-data-sources) * [DatePart-like queries](#datepart-like-queries) * [Pivot](#pivot) * [Histograms](#histograms) * [Covariance](#covariance) * [Cast booleans to integers](#cast-booleans-to-integers) * [String manipulation and data shaping](#string-manipulation-and-data-shaping) * [Work with geo-temporal data](#work-with-geo-temporal-data) ### Joins InfluxQL has never supported joins. Although you can use a join in a [TICKscript](/kapacitor/v1/reference/tick/introduction/), TICKscript’s join capabilities are limited. Flux’s [`join()` function](/flux/v0/stdlib/universe/join/) lets you join data **from any bucket, any measurement, and on any columns** as long as each data set includes the columns to join on. ```js dataStream1 = from(bucket: "example-bucket1") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "network" and r._field == "bytes-transferred") dataStream2 = from(bucket: "example-bucket2") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "httpd" and r._field == "requests-per-sec") join(tables: {d1: dataStream1, d2: dataStream2}, on: ["_time", "_stop", "_start", "host"]) ``` *For an in-depth walkthrough of using the `join()` function, see [how to join data with Flux](/influxdb/v2/query-data/flux/join/).* ### Math across measurements Being able to perform joins across measurements lets you calculate data from separate measurements. The example below takes data from two measurements, `mem` and `processes`, joins them, and then calculates the average amount of memory used per running process: ```js // Memory used (in bytes) memUsed = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used") // Total processes running procTotal = from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "processes" and r._field == "total") // Join memory used with total processes to calculate // the average memory (in MB) used for running processes. join(tables: {mem: memUsed, proc: procTotal}, on: ["_time", "_stop", "_start", "host"]) |> map(fn: (r) => ({_time: r._time, _value: r._value_mem / r._value_proc / 1000000})) ``` ### Sort by tags InfluxQL’s sorting capabilities only let you control the sort order of `time` using the `ORDER BY time` clause. The Flux [`sort()` function](/flux/v0/stdlib/universe/sort)sorts records based on a list of columns. Depending on the column type, Flux sorts records lexicographically, numerically, or chronologically. ```js from(bucket: "example-bucket") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime") |> sort(columns: ["region", "host", "_value"]) ``` ### Group by any column InfluxQL lets you group by tags or time intervals only. Flux lets you group data by any column, including `_value`. Use the Flux [`group()` function](/flux/v0/stdlib/universe/group/)to define which columns to group data by. ```js from(bucket:"example-bucket") |> range(start: -12h) |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime" ) |> group(columns:["host", "_value"]) ``` ### Window by calendar months and years InfluxQL does not support windowing data by calendar months and years due to their varied lengths. Flux supports calendar month and year duration units (`1mo`, `1y`) and lets you window and aggregate data by calendar month and year. ```js from(bucket:"example-bucket") |> range(start:-1y) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) |> aggregateWindow(every: 1mo, fn: mean) ``` ### Work with multiple data sources InfluxQL can only query data stored in InfluxDB. Flux can query data from other data sources such as CSV, PostgreSQL, MySQL, Google BigTable, and more. Join that data with data in InfluxDB to enrich query results. * [Flux CSV package](/flux/v0/stdlib/csv/) * [Flux SQL package](/flux/v0/stdlib/sql/) * [Flux BigTable package](/flux/v0/stdlib/experimental/bigtable/) ```js import "csv" import "sql" csvData = csv.from(csv: rawCSV) sqlData = sql.from( driverName: "postgres", dataSourceName: "postgresql://user:password@localhost", query: "SELECT * FROM example_table", ) data = from(bucket: "example-bucket") |> range(start: -24h) |> filter(fn: (r) => r._measurement == "sensor") auxData = join(tables: {csv: csvData, sql: sqlData}, on: ["sensor_id"]) enrichedData = join(tables: {data: data, aux: auxData}, on: ["sensor_id"]) enrichedData |> yield(name: "enriched_data") ``` *For an in-depth walkthrough of querying SQL data, see [Query SQL data sources](/influxdb/v2/query-data/flux/sql/).* ### DatePart-like queries InfluxQL doesn’t support DatePart-like queries that only return results during specified hours of the day. The Flux [`hourSelection` function](/flux/v0/stdlib/universe/hourselection/)returns only data with time values in a specified hour range. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r.cpu == "cpu-total") |> hourSelection(start: 9, stop: 17) ``` ### Pivot Pivoting data tables isn’t supported in InfluxQL. Use the Flux [`pivot()` function](/flux/v0/stdlib/universe/pivot)to pivot data tables by `rowKey`, `columnKey`, and `valueColumn` parameters. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu" and r.cpu == "cpu-total") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") ``` ### Histograms Generating histograms isn’t supported in InfluxQL. Use the Flux [`histogram()` function](/flux/v0/stdlib/universe/histogram) to generate a cumulative histogram. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> histogram(buckets: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]) ``` *For more examples, see [how to create histograms with Flux](/influxdb/v2/query-data/flux/histograms/).* ### Covariance Flux provides functions for simple covariance calculations. Use the [`covariance()` function](/flux/v0/stdlib/universe/covariance)to calculate the covariance between two columns and the [`cov()` function](/flux/v0/stdlib/universe/cov)to calculate the covariance between two data streams. ###### Covariance between two columns ```js from(bucket: "example-bucket") |> range(start:-5m) |> covariance(columns: ["x", "y"]) ``` ###### Covariance between two streams of data ```js table1 = from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "measurement_1") table2 = from(bucket: "example-bucket") |> range(start: -15m) |> filter(fn: (r) => r._measurement == "measurement_2") cov(x: table1, y: table2, on: ["_time", "_field"]) ``` ### Cast booleans to integers InfluxQL supports type casting for numeric data types (floats to integers and vice versa) only. Use [Flux type conversion functions](/flux/v0/function-types/#type-conversions)to perform many more type conversions, including casting boolean values to integers. ##### Cast boolean field values to integers ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "m" and r._field == "bool_field") |> toInt() ``` ### String manipulation and data shaping InfluxQL doesn’t support string manipulation when querying data. Use [Flux Strings package](/flux/v0/stdlib/strings/) functions to operate on string data. Combine functions in this package with the [`map()` function](/flux/v0/stdlib/universe/map/) to perform operations like sanitizing and normalizing strings. ```js import "strings" from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "weather" and r._field == "temp") |> map( fn: (r) => ({ r with location: strings.toTitle(v: r.location), sensor: strings.replaceAll(v: r.sensor, t: " ", u: "-"), status: strings.substring(v: r.status, start: 0, end: 8) }) ) ``` ### Work with geo-temporal data InfluxQL doesn’t support working with geo-temporal data. The [Flux Geo package](/flux/v0/stdlib/experimental/geo/) is a collection of functions that let you shape, filter, and group geo-temporal data. ```js import "experimental/geo" from(bucket: "geo/autogen") |> range(start: -1w) |> filter(fn: (r) => r._measurement == "taxi") |> geo.shapeData(latField: "latitude", lonField: "longitude", level: 20) |> geo.filterRows(region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0}, strict: true) |> geo.asTracks(groupBy: ["fare-id"]) ``` ## InfluxQL and Flux parity We’re continuing to add functions to complete parity between Flux and InfluxQL. The table below shows InfluxQL statements, clauses, and functions along with their equivalent Flux functions. *For a complete list of Flux functions, [view all Flux functions](/flux/v0/stdlib/all-functions/).* | InfluxQL | Flux Functions | |------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [SELECT](/influxdb/v1/query_language/explore-data/#the-basic-select-statement) | [filter()](/flux/v0/stdlib/universe/filter/) | | [WHERE](/influxdb/v1/query_language/explore-data/#the-where-clause) | [filter()](/flux/v0/stdlib/universe/filter/), [range()](/flux/v0/stdlib/universe/range/) | | [GROUP BY](/influxdb/v1/query_language/explore-data/#the-group-by-clause) | [group()](/flux/v0/stdlib/universe/group/) | | [INTO](/influxdb/v1/query_language/explore-data/#the-into-clause) | [to()](/flux/v0/stdlib/influxdata/influxdb/to/) | | [ORDER BY](/influxdb/v1/query_language/explore-data/#order-by-time-desc) | [sort()](/flux/v0/stdlib/universe/sort/) | | [LIMIT](/influxdb/v1/query_language/explore-data/#the-limit-clause) | [limit()](/flux/v0/stdlib/universe/limit/) | | [SLIMIT](/influxdb/v1/query_language/explore-data/#the-slimit-clause) | – | | [OFFSET](/influxdb/v1/query_language/explore-data/#the-offset-clause) | – | | [SOFFSET](/influxdb/v1/query_language/explore-data/#the-soffset-clause) | – | | [SHOW DATABASES](/influxdb/v1/query_language/explore-schema/#show-databases) | [buckets()](/flux/v0/stdlib/universe/buckets/) | | [SHOW MEASUREMENTS](/influxdb/v1/query_language/explore-schema/#show-measurements) | [schema.measurements](/flux/v0/stdlib/influxdata/influxdb/schema/measurements) | | [SHOW FIELD KEYS](/influxdb/v1/query_language/explore-schema/#show-field-keys) | [keys()](/flux/v0/stdlib/universe/keys/) | | [SHOW RETENTION POLICIES](/influxdb/v1/query_language/explore-schema/#show-retention-policies) | [buckets()](/flux/v0/stdlib/universe/buckets/) | | [SHOW TAG KEYS](/influxdb/v1/query_language/explore-schema/#show-tag-keys) | [schema.tagKeys()](/flux/v0/stdlib/influxdata/influxdb/schema/tagkeys), [schema.measurementTagKeys()](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagkeys) | | [SHOW TAG VALUES](/influxdb/v1/query_language/explore-schema/#show-tag-values) |[schema.tagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/tagvalues), [schema.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues)| | [SHOW SERIES](/influxdb/v1/query_language/explore-schema/#show-series) | – | | [CREATE DATABASE](/influxdb/v1/query_language/manage-database/#create-database) | N/A | | [DROP DATABASE](/influxdb/v1/query_language/manage-database/#delete-a-database-with-drop-database) | N/A | | [DROP SERIES](/influxdb/v1/query_language/manage-database/#drop-series-from-the-index-with-drop-serie) | N/A | | [DELETE](/influxdb/v1/query_language/manage-database/#delete-series-with-delete) | N/A | | [DROP MEASUREMENT](/influxdb/v1/query_language/manage-database/#delete-measurements-with-drop-measurement) | N/A | | [DROP SHARD](/influxdb/v1/query_language/manage-database/#delete-a-shard-with-drop-shard) | N/A | |[CREATE RETENTION POLICY](/influxdb/v1/query_language/manage-database/#create-retention-policies-with-create-retention-policy)| N/A | | [ALTER RETENTION POLICY](/influxdb/v1/query_language/manage-database/#modify-retention-policies-with-alter-retention-policy) | N/A | | [DROP RETENTION POLICY](/influxdb/v1/query_language/manage-database/#delete-retention-policies-with-drop-retention-policy) | N/A | | [COUNT](/influxdb/v1/query_language/functions#count) | [count()](/flux/v0/stdlib/universe/count/) | | [DISTINCT](/influxdb/v1/query_language/functions#distinct) | [distinct()](/flux/v0/stdlib/universe/distinct/) | | [INTEGRAL](/influxdb/v1/query_language/functions#integral) | [integral()](/flux/v0/stdlib/universe/integral/) | | [MEAN](/influxdb/v1/query_language/functions#mean) | [mean()](/flux/v0/stdlib/universe/mean/) | | [MEDIAN](/influxdb/v1/query_language/functions#median) | [median()](/flux/v0/stdlib/universe/median/) | | [MODE](/influxdb/v1/query_language/functions#mode) | [mode()](/flux/v0/stdlib/universe/mode/) | | [SPREAD](/influxdb/v1/query_language/functions#spread) | [spread()](/flux/v0/stdlib/universe/spread/) | | [STDDEV](/influxdb/v1/query_language/functions#stddev) | [stddev()](/flux/v0/stdlib/universe/stddev/) | | [SUM](/influxdb/v1/query_language/functions#sum) | [sum()](/flux/v0/stdlib/universe/sum/) | | [BOTTOM](/influxdb/v1/query_language/functions#bottom) | [bottom()](/flux/v0/stdlib/universe/bottom/) | | [FIRST](/influxdb/v1/query_language/functions#first) | [first()](/flux/v0/stdlib/universe/first/) | | [LAST](/influxdb/v1/query_language/functions#last) | [last()](/flux/v0/stdlib/universe/last/) | | [MAX](/influxdb/v1/query_language/functions#max) | [max()](/flux/v0/stdlib/universe/max/) | | [MIN](/influxdb/v1/query_language/functions#min) | [min()](/flux/v0/stdlib/universe/min/) | | [PERCENTILE](/influxdb/v1/query_language/functions#percentile) | [quantile()](/flux/v0/stdlib/universe/quantile/) | | [SAMPLE](/influxdb/v1/query_language/functions#sample) | [sample()](/flux/v0/stdlib/universe/sample/) | | [TOP](/influxdb/v1/query_language/functions#top) | [top()](/flux/v0/stdlib/universe/top/) | | [ABS](/influxdb/v1/query_language/functions#abs) | [math.abs()](/flux/v0/stdlib/math/abs/) | | [ACOS](/influxdb/v1/query_language/functions#acos) | [math.acos()](/flux/v0/stdlib/math/acos/) | | [ASIN](/influxdb/v1/query_language/functions#asin) | [math.asin()](/flux/v0/stdlib/math/asin/) | | [ATAN](/influxdb/v1/query_language/functions#atan) | [math.atan()](/flux/v0/stdlib/math/atan/) | | [ATAN2](/influxdb/v1/query_language/functions#atan2) | [math.atan2()](/flux/v0/stdlib/math/atan2/) | | [CEIL](/influxdb/v1/query_language/functions#ceil) | [math.ceil()](/flux/v0/stdlib/math/ceil/) | | [COS](/influxdb/v1/query_language/functions#cos) | [math.cos()](/flux/v0/stdlib/math/cos/) | | [CUMULATIVE\_SUM](/influxdb/v1/query_language/functions#cumulative-sum) | [cumulativeSum()](/flux/v0/stdlib/universe/cumulativesum/) | | [DERIVATIVE](/influxdb/v1/query_language/functions#derivative) | [derivative()](/flux/v0/stdlib/universe/derivative/) | | [DIFFERENCE](/influxdb/v1/query_language/functions#difference) | [difference()](/flux/v0/stdlib/universe/difference/) | | [ELAPSED](/influxdb/v1/query_language/functions#elapsed) | [elapsed()](/flux/v0/stdlib/universe/elapsed/) | | [EXP](/influxdb/v1/query_language/functions#exp) | [math.exp()](/flux/v0/stdlib/math/exp/) | | [FLOOR](/influxdb/v1/query_language/functions#floor) | [math.floor()](/flux/v0/stdlib/math/floor/) | | [HISTOGRAM](/influxdb/v1/query_language/functions#histogram) | [histogram()](/flux/v0/stdlib/universe/histogram/) | | [LN](/influxdb/v1/query_language/functions#ln) | [math.log()](/flux/v0/stdlib/math/log/) | | [LOG](/influxdb/v1/query_language/functions#log) | [math.logb()](/flux/v0/stdlib/math/logb/) | | [LOG2](/influxdb/v1/query_language/functions#log2) | [math.log2()](/flux/v0/stdlib/math/log2/) | | [LOG10](/influxdb/v1/query_language/functions#logt10) | [math.log10()](/flux/v0/stdlib/math/log10/) | | [MOVING\_AVERAGE](/influxdb/v1/query_language/functions#moving-average) | [movingAverage()](/flux/v0/stdlib/universe/movingaverage/) | | [NON\_NEGATIVE\_DERIVATIVE](/influxdb/v1/query_language/functions#non-negative-derivative) | [derivative(nonNegative:true)](/flux/v0/stdlib/universe/derivative/) | | [NON\_NEGATIVE\_DIFFERENCE](/influxdb/v1/query_language/functions#non-negative-difference) | [difference(nonNegative:true)](/flux/v0/stdlib/universe/derivative/) | | [POW](/influxdb/v1/query_language/functions#pow) | [math.pow()](/flux/v0/stdlib/math/pow/) | | [ROUND](/influxdb/v1/query_language/functions#round) | [math.round()](/flux/v0/stdlib/math/round/) | | [SIN](/influxdb/v1/query_language/functions#sin) | [math.sin()](/flux/v0/stdlib/math/sin/) | | [SQRT](/influxdb/v1/query_language/functions#sqrt) | [math.sqrt()](/flux/v0/stdlib/math/sqrt/) | | [TAN](/influxdb/v1/query_language/functions#tan) | [math.tan()](/flux/v0/stdlib/math/tan/) | | [HOLT\_WINTERS](/influxdb/v1/query_language/functions#holt-winters) | [holtWinters()](/flux/v0/stdlib/universe/holtwinters/) | | [CHANDE\_MOMENTUM\_OSCILLATOR](/influxdb/v1/query_language/functions#chande-momentum-oscillator) | [chandeMomentumOscillator()](/flux/v0/stdlib/universe/chandemomentumoscillator/) | | [EXPONENTIAL\_MOVING\_AVERAGE](/influxdb/v1/query_language/functions#exponential-moving-average) | [exponentialMovingAverage()](/flux/v0/stdlib/universe/exponentialmovingaverage/) | | [DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE](/influxdb/v1/query_language/functions#double-exponential-moving-average) | [doubleEMA()](/flux/v0/stdlib/universe/doubleema/) | | [KAUFMANS\_EFFICIENCY\_RATIO](/influxdb/v1/query_language/functions#kaufmans-efficiency-ratio) | [kaufmansER()](/flux/v0/stdlib/universe/kaufmanser/) | | [KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE](/influxdb/v1/query_language/functions#kaufmans-adaptive-moving-average) | [kaufmansAMA()](/flux/v0/stdlib/universe/kaufmansama/) | | [TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE](/influxdb/v1/query_language/functions#triple-exponential-moving-average) | [tripleEMA()](/flux/v0/stdlib/universe/tripleema/) | | [TRIPLE\_EXPONENTIAL\_DERIVATIVE](/influxdb/v1/query_language/functions#triple-exponential-derivative) | [tripleExponentialDerivative()](/flux/v0/stdlib/universe/tripleexponentialderivative/) | | [RELATIVE\_STRENGTH\_INDEX](/influxdb/v1/query_language/functions#relative-strength-index) | [relativeStrengthIndex()](/flux/v0/stdlib/universe/relativestrengthindex/) | | InfluxQL | Flux Functions | | --- | --- | | InfluxQL | Flux Functions | | SELECT | filter() | | WHERE | filter() , range() | | GROUP BY | group() | | INTO | to() | | ORDER BY | sort() | | LIMIT | limit() | | SLIMIT | – | | OFFSET | – | | SOFFSET | – | | SHOW DATABASES | buckets() | | SHOW MEASUREMENTS | schema.measurements | | SHOW FIELD KEYS | keys() | | SHOW RETENTION POLICIES | buckets() | | SHOW TAG KEYS | schema.tagKeys() , schema.measurementTagKeys() | | SHOW TAG VALUES | schema.tagValues() , schema.measurementTagValues() | | SHOW SERIES | – | | CREATE DATABASE | N/A | | DROP DATABASE | N/A | | DROP SERIES | N/A | | DELETE | N/A | | DROP MEASUREMENT | N/A | | DROP SHARD | N/A | | CREATE RETENTION POLICY | N/A | | ALTER RETENTION POLICY | N/A | | DROP RETENTION POLICY | N/A | | COUNT | count() | | DISTINCT | distinct() | | INTEGRAL | integral() | | MEAN | mean() | | MEDIAN | median() | | MODE | mode() | | SPREAD | spread() | | STDDEV | stddev() | | SUM | sum() | | BOTTOM | bottom() | | FIRST | first() | | LAST | last() | | MAX | max() | | MIN | min() | | PERCENTILE | quantile() | | SAMPLE | sample() | | TOP | top() | | ABS | math.abs() | | ACOS | math.acos() | | ASIN | math.asin() | | ATAN | math.atan() | | ATAN2 | math.atan2() | | CEIL | math.ceil() | | COS | math.cos() | | CUMULATIVE_SUM | cumulativeSum() | | DERIVATIVE | derivative() | | DIFFERENCE | difference() | | ELAPSED | elapsed() | | EXP | math.exp() | | FLOOR | math.floor() | | HISTOGRAM | histogram() | | LN | math.log() | | LOG | math.logb() | | LOG2 | math.log2() | | LOG10 | math.log10() | | MOVING_AVERAGE | movingAverage() | | NON_NEGATIVE_DERIVATIVE | derivative(nonNegative:true) | | NON_NEGATIVE_DIFFERENCE | difference(nonNegative:true) | | POW | math.pow() | | ROUND | math.round() | | SIN | math.sin() | | SQRT | math.sqrt() | | TAN | math.tan() | | HOLT_WINTERS | holtWinters() | | CHANDE_MOMENTUM_OSCILLATOR | chandeMomentumOscillator() | | EXPONENTIAL_MOVING_AVERAGE | exponentialMovingAverage() | | DOUBLE_EXPONENTIAL_MOVING_AVERAGE | doubleEMA() | | KAUFMANS_EFFICIENCY_RATIO | kaufmansER() | | KAUFMANS_ADAPTIVE_MOVING_AVERAGE | kaufmansAMA() | | TRIPLE_EXPONENTIAL_MOVING_AVERAGE | tripleEMA() | | TRIPLE_EXPONENTIAL_DERIVATIVE | tripleExponentialDerivative() | | RELATIVE_STRENGTH_INDEX | relativeStrengthIndex() | --- # InfluxQL syntax Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/influxql/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ### [Influx Query Language (InfluxQL) 2.x specification](/influxdb/v2/reference/syntax/influxql/spec/) Reference (spec) for Influx Query Language (InfluxQL) 2.x. ### [InfluxQL internals reference](/influxdb/v2/reference/syntax/influxql/internals/) Read about the implementation of InfluxQL. --- # InfluxQL internals reference Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/influxql/internals/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 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 provided 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, a statement such as this: ```sql SELECT MEAN(value) FROM cpu GROUP BY time(10m) ``` In this case, `MEAN(value)` is a `MeanIterator` wrapping an iterator from the underlying shards. However, if we can add an additional iterator 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 trasverses 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 which do not need stronger sorting guarantees. * Sorted Merge Iterator - This iterator also 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/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. It is resource intensive so it 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 first before performing the calculation. This iterator is created by the engine itself and is never requested to be created by the lower levels. --- # Influx Query Language (InfluxQL) 2.x specification Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/influxql/spec/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxQL is a SQL-like query language used to interact with InfluxDB and work with your times series data. Find Influx Query Language (InfluxQL) definitions and details, including: * [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) To learn more about InfluxQL, browse the following topics: * [Explore your data with InfluxQL](/influxdb/v2/query-data/influxql/explore-data/) * [Explore your schema with InfluxQL](/influxdb/v2/query-data/influxql/explore-schema/) * [Query engine internals](/influxdb/v2/reference/syntax/influxql/internals/) ## Notation The syntax is specified using Extended Backus-Naur Form (“EBNF”). EBNF is the same notation used in the [Go](http://golang.org) programming language specification, which can be found [here](https://golang.org/ref/spec). ``` 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 characters plus the underscore character \_ (U+005F) is considered a letter. Only decimal digits are supported. ``` letter = ascii_letter | "_" . ascii_letter = "A" … "Z" | "a" … "z" . digit = "0" … "9" . ``` ### Identifiers Identifiers are tokens which refer to [database](/influxdb/v2/reference/glossary/#database) names, [retention policy](/influxdb/v2/reference/glossary/#retention-policy-rp) names, [user](/influxdb/v2/reference/glossary/#user) names, [measurement](/influxdb/v2/reference/glossary/#measurement) names, [tag keys](/influxdb/v2/reference/glossary/#tag-key), and [field keys](/influxdb/v2/reference/glossary/#field-key). The rules: * double quoted identifiers can contain any unicode character other than a new line * double quoted identifiers can contain escaped `"` characters (i.e., `\"`) * double quoted identifiers can contain 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 keywords as an[identifier](/influxdb/v2/reference/glossary/#identifier) you will need to double quote that identifier in every query. The keyword `time` is a special case.`time` can be a database name,[measurement](/influxdb/v2/reference/glossary/#measurement) name,[retention policy](/influxdb/v2/reference/glossary/#retention-policy-rp) name,[subscription](/influxdb/v2/reference/glossary/#subscription) name, and[user](/influxdb/v2/reference/glossary/#user) name. In those cases, `time` does not require double quotes in queries.`time` cannot be a [field key](/influxdb/v2/reference/glossary/#field-key) or[tag key](/influxdb/v2/reference/glossary/#tag-key); InfluxDB rejects writes with `time` as a field key or tag key and returns an error. See [Frequently Asked Questions](/influxdb/v2/reference/faq/) for more information. ### Literals #### Integers InfluxQL supports decimal integer literals. Hexadecimal and octal literals are not currently supported. ``` int_lit = ( "1" … "9" ) { digit } . ``` #### Floats InfluxQL supports floating-point literals. Exponents are not 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 (i.e., `\'`). ``` string_lit = `'` { unicode_char } `'` . ``` #### Durations Duration literals specify a length of time. An integer literal followed immediately (with no spaces) by a duration unit 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 The date and time literal format is not specified in EBNF like the rest of this document. It is specified using Go’s date / time parsing format, which is a reference date 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] > **NOTE:** InfluxQL supports using regular expressions when specifying: > > * [field keys](/influxdb/v2/reference/glossary/#field-key) and [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/) > * [measurements](/influxdb/v2/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause) > * [tag values](/influxdb/v2/reference/glossary/#tag-value) and string [field values](/influxdb/v2/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/) > * [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) > > Currently, InfluxQL does not support using regular expressions to match non-string field values in the `WHERE` clause, [databases](/influxdb/v2/reference/glossary/#database), and [retention polices](/influxdb/v2/reference/glossary/#retention-policy-rp). ## Queries A query is composed of one or more statements separated by a semicolon. ``` query = statement { ";" statement } . statement = delete_stmt | drop_measurement_stmt | explain_stmt | explain_analyze_stmt | select_stmt | show_databases_stmt | show_field_key_cardinality_stmt | show_field_keys_stmt | show_measurement_exact_cardinality_stmt | show_measurements_stmt | show_series_exact_cardinality_stmt | show_series_stmt | show_tag_key_cardinality_stmt | show_tag_key_exact_cardinality_stmt | show_tag_keys_stmt | show_tag_values_with_key = stmt | show_tag_values_cardinality_stmt . ``` ## Statements ### DELETE ``` delete_stmt = "DELETE" ( from_clause | where_clause | from_clause where_clause ) . ``` #### Examples ```sql DELETE FROM "cpu" DELETE FROM "cpu" WHERE time < '2000-01-01T00:00:00Z' DELETE WHERE time < '2000-01-01T00:00:00Z' ``` ### DROP MEASUREMENT ``` drop_measurement_stmt = "DROP MEASUREMENT" measurement . ``` #### Examples ```sql -- drop the cpu measurement DROP MEASUREMENT "cpu" ``` ### 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 does not support joins, the cost of a 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. The elements of `EXPLAIN` query plan include: * 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 on 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, executing 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' ``` May produce an output 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 is not 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 the executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and the required memory. First, InfluxDB determines the effective time range of the query and selects the shards to access (in InfluxDB Enterprise, shards may be on remote nodes). 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: | `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 | For more information about storage blocks, see [TSM files](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm). ### 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 CARDINALITY Refers to the group of commands used to estimate or count exactly the cardinality of measurements, series, tag keys, tag key values, and field keys. The SHOW CARDINALITY commands are available in two variations: estimated and exact. Estimated values are calculated using sketches and are a safe default for all cardinality sizes. Exact values are counts directly from TSM (Time-Structured Merge Tree) data, but are expensive to run for high cardinality data. Unless required, use the estimated variety. Filtering by `time` is only supported when Time Series Index (TSI) is enabled on a database. See the specific SHOW CARDINALITY commands for details: * [SHOW FIELD KEY CARDINALITY](#show-field-key-cardinality) * [SHOW SERIES CARDINALITY](#show-series-cardinality) * [SHOW TAG KEY CARDINALITY](#show-tag-key-cardinality) * [SHOW TAG VALUES CARDINALITY](#show-tag-values-cardinality) ### SHOW DATABASES ``` show_databases_stmt = "SHOW DATABASES" . ``` #### Example ```sql -- show all databases SHOW DATABASES ``` ### SHOW FIELD KEY CARDINALITY Estimates or counts exactly the cardinality of the field key set for the current database unless a database is specified using the `ON ` option. > > > **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. > When using these query clauses, the query falls back to an exact count. > Filtering by `time` is only supported when Time Series Index (TSI) is enabled and `time` is not supported in the `WHERE` clause. > > ```sql show_field_key_cardinality_stmt = "SHOW FIELD KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] show_field_key_exact_cardinality_stmt = "SHOW FIELD KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] ``` #### Examples ```sql -- show estimated cardinality of the field key set of current database SHOW FIELD KEY CARDINALITY -- show exact cardinality on field key set of specified database SHOW FIELD KEY EXACT CARDINALITY ON mydb ``` ### 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 SERIES ``` show_series_stmt = "SHOW SERIES" [on_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Example ```sql SHOW SERIES FROM "telegraf"."autogen"."cpu" WHERE cpu = 'cpu8' ``` ### SHOW SERIES EXACT CARDINALITY Estimates or counts exactly the cardinality of the series for the current database unless a database is specified using the ON option. #### Example SHOW SERIES EXACT CARDINALITY" [ on\_clause ] [ from\_clause ] [ where\_clause ] [ group\_by\_clause ] [ limit\_clause ] [ offset\_clause ] ```sql SHOW SERIES EXACT CARDINALITY ON mydb ``` * [Series cardinality](/influxdb/v2/reference/glossary/#series-cardinality) is the major factor that affects RAM requirements. For more information, see: * [Don’t have too many series](/influxdb/v2/reference/faq/#why-does-series-cardinality-matter). As the number of unique series grows, so does the memory usage. High series cardinality can force the host operating system to kill the InfluxDB process with an out of memory (OOM) exception. > [!Note] > **NOTE:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. > When using these query clauses, the query falls back to an exact count. > Filtering by `time` is not supported in the `WHERE` clause. ### SHOW TAG KEY CARDINALITY Estimates or counts exactly the cardinality of tag key set on the current database unless a database is specified using the `ON ` option. > > > **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. > When using these query clauses, the query falls back to an exact count. > Filtering by `time` is only supported when TSI (Time Series Index) is enabled and `time` is not supported in the `WHERE` clause. > > ``` show_tag_key_cardinality_stmt = "SHOW TAG KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] show_tag_key_exact_cardinality_stmt = "SHOW TAG KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] ``` #### Examples ```sql -- show estimated tag key cardinality SHOW TAG KEY CARDINALITY -- show exact tag key cardinality SHOW TAG KEY EXACT CARDINALITY ``` ### 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' ``` ### SHOW TAG VALUES CARDINALITY Estimates or counts exactly the cardinality of tag key values for the specified tag key on the current database unless a database is specified using the `ON ` option. > [!Note] > **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. > When using these query clauses, the query falls back to an exact count. > Filtering by `time` is only supported when TSI (Time Series Index) is enabled. ``` show_tag_values_cardinality_stmt = "SHOW TAG VALUES CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause show_tag_values_exact_cardinality_stmt = "SHOW TAG VALUES EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause ``` #### Examples ```sql -- show estimated tag key values cardinality for a specified tag key SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey" -- show estimated tag key values cardinality for a specified tag key SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey" -- show exact tag key values cardinality for a specified tag key SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey" -- show exact tag key values cardinality for a specified tag key SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey" ``` ## 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 . ``` ## 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 | --- # Line protocol Source: https://docs.influxdata.com/influxdb/v2/reference/syntax/line-protocol/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB uses line protocol to write data points. It is a text-based format that provides the measurement, 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 myMeasurement,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 myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000 ### Measurement (Required) The measurement name. InfluxDB accepts one measurement per point.*Measurement names are case-sensitive and subject to [naming restrictions](#naming-restrictions).* ***Data type:** [String](#string)* ### 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).* > > ``` > measurementName fieldKey="field string value" 1556813561098000000 > ``` ### Timestamp ***Optional*** – The [unix timestamp](/influxdb/v2/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](/influxdb/v2/write-data/#timestamp-precision). ### Whitespace Whitespace in line protocol determines how InfluxDB interprets the data point. The **first unescaped space** delimits the measurement and the tag set from the field set. The **second unescaped space** delimits the field set from the timestamp. myMeasurement,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 myMeasurement fieldKey=1.0 myMeasurement fieldKey=1 myMeasurement 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 myMeasurement fieldKey=1i myMeasurement fieldKey=12485903i myMeasurement 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 myMeasurement fieldKey=1u myMeasurement fieldKey=12485903u ``` ### String Plain text string. Length limit 64KB. ##### String example ```lp # String measurement name, field key, and field value myMeasurement 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 myMeasurement fieldKey=true myMeasurement fieldKey=false myMeasurement fieldKey=t myMeasurement fieldKey=f myMeasurement fieldKey=TRUE myMeasurement fieldKey=FALSE ``` > [!Note] > Do not quote boolean field values. > Quoted field values are interpreted as strings. ### Unix timestamp Unix timestamp in a [specified precision](/influxdb/v2/reference/glossary/#unix-timestamp). Default precision is nanoseconds (`ns`). | Minimum timestamp | Maximum timestamp | |----------------------|---------------------| |`-9223372036854775806`|`9223372036854775806`| ##### Unix timestamp example ```lp myMeasurementName fieldKey="fieldValue" 1556813561098000000 ``` ## Quotes Line protocol supports single and double quotes as described in the following table: | Element | Double quotes | Single quotes | |-----------|---------------------------------------|---------------------------------------| |Measurement|*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 measurement 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 | |-----------|-------------------------| |Measurement| 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 # Measurement name with spaces my\ Measurement fieldKey="string value" # Double quotes in a string field value myMeasurement fieldKey="\"string\" within a string" # Tag keys and values with spaces myMeasurement,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100 # Emojis myMeasurement,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 myMeasurement fieldKey="string value" 1556813561098000000 ``` ## Naming restrictions Measurement names, tag keys, and field keys cannot begin with an underscore `_`. The `_` namespace is reserved for InfluxDB system use. ## Duplicate points A point is uniquely identified by the measurement name, tag set, and timestamp. If you submit line protocol with the same measurement, 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. #### Related * [Write data to InfluxDB](/influxdb/v2/write-data/) [write](/influxdb/v2/tags/write/)[line protocol](/influxdb/v2/tags/line-protocol/)[syntax](/influxdb/v2/tags/syntax/) | Minimum integer | Maximum integer | | --- | --- | | Minimum integer | Maximum integer | | -9223372036854775808i | 9223372036854775807i | | Minimum uinteger | Maximum uinteger | | --- | --- | | Minimum uinteger | Maximum uinteger | | 0u | 18446744073709551615u | | 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 | | Measurement | 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 | | Measurement | 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 | | \ | \ | | \\ | \ | | \\\ | \\ | | \\\\ | \\ | | \\\\\ | \\\ | | \\\\\\ | \\\ | --- # Usage telemetry Source: https://docs.influxdata.com/influxdb/v2/reference/telemetry/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxData collects information, or *telemetry data*, about the usage of InfluxDB to help improve the product. Learn what data InfluxDB collects and sends to InfluxData, how it’s used, and how you can opt out. ## Metrics Collection For each InfluxDB 2.x installation, we collect the following at startup and then every 8 hours: ### Tags | Tags | Description | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | arch | Microarchitecture InfluxDB was compiled for | | build date | Date associated with the InfluxDB build | | commit | SHA of commit associated with the InfluxDB build | | cpus | Number of CPUs running InfluxDB | | functions | Flux functions | | id | Snowflake identifier for the InfluxDB instance | | Index partition | Identifies the index partition used by the underlying InfluxDB storage engine | | ip | IP Address of the inbound connection which reports the statistics. This is **not** the specific IP Address of the machine running InfluxDB unless it is exposed directly on the public Internet. | | org | Identifier for an organization. Allows for grouping of statistics by organization within the InfluxDB instance | | os | Operating System InfluxDB is running on | | result | Text allowing grouping of Flux query invocations results | |series file partition| Identifies the series files in use for the underlying InfluxDB storage engine. This is not the metadata about series. | | status | Status of write ahead log (associated to number of successful /failed writes) | | user\_agent |Typically, this is set by the browser, InfluxDB client libraries (includes the language [Go, JavaScript, Java, C#, Ruby, Python, etc.] and version), and other technologies [such as third-party dashboarding applications, etc.].| | version | InfluxDB version | With those tag elements, we then leverage a combination of the unique combination of `id`, `ip`, and storage system specifics (where applicable) to capture usage counts of the various subsystems within InfluxDB. ### Fields | Fields | Description | |---------------------------|-----------------------------------------------------------------------------| | buckets total counter | Total number of buckets present within the InfluxDB instance | | bytes written counter | Total number of bytes written | | bytes scanned counter |Total number of bytes scanned within the storage system via queries and tasks| | dashboards total counter | Total number of dashboards present within the InfluxDB instance | |flux function total counter| Total number of calls by function invoked within Flux | | http api requests counter | Total number of API invocations by each API path | | query duration histogram | Histogram counting duration of queries into bins | |organizations total counter| Total number of organizations present within the InfluxDB instance | | scrapers total counter | Total number of scrapers configured within the InfluxDB instance | | series total counter | Total number of series present within the InfluxDB instance | | storage total counter | Total number of bytes stored within the InfluxDB instance | | task scheduler gauge | Number of tasks running within the InfluxDB instance | | telegrafs total counter | Total number of Telegraf configurations within the InfluxDB instance | | tokens total counter | Total number of tokens present within the InfluxDB instance | | uptime gauge | Number of seconds InfluxDB has been continuously running | | users total counter | Total number of users present within the InfluxDB instance | | wal current segment gauge | Number of bytes in the current segments for the write ahead log | | wal writes total counter | Total number of writes to the write ahead log by status (ok, fail, etc.) | ## Disable telemetry To “opt-out” of collecting and sending InfluxDB telemetry data, include the `--reporting-disabled` flag with the `influxd` command when starting InfluxDB. #### Related * [influxd - InfluxDB service](/influxdb/v2/reference/cli/influxd/) * [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/) | Tags | Description | | --- | --- | | Tags | Description | | arch | Microarchitecture InfluxDB was compiled for | | build date | Date associated with the InfluxDB build | | commit | SHA of commit associated with the InfluxDB build | | cpus | Number of CPUs running InfluxDB | | functions | Flux functions | | id | Snowflake identifier for the InfluxDB instance | | Index partition | Identifies the index partition used by the underlying InfluxDB storage engine | | ip | IP Address of the inbound connection which reports the statistics. This is not the specific IP Address of the machine running InfluxDB unless it is exposed directly on the public Internet. | | org | Identifier for an organization. Allows for grouping of statistics by organization within the InfluxDB instance | | os | Operating System InfluxDB is running on | | result | Text allowing grouping of Flux query invocations results | | series file partition | Identifies the series files in use for the underlying InfluxDB storage engine. This is not the metadata about series. | | status | Status of write ahead log (associated to number of successful /failed writes) | | user_agent | Typically, this is set by the browser, InfluxDB client libraries (includes the language [Go, JavaScript, Java, C#, Ruby, Python, etc.] and version), and other technologies [such as third-party dashboarding applications, etc.]. | | version | InfluxDB version | | Fields | Description | | --- | --- | | Fields | Description | | buckets total counter | Total number of buckets present within the InfluxDB instance | | bytes written counter | Total number of bytes written | | bytes scanned counter | Total number of bytes scanned within the storage system via queries and tasks | | dashboards total counter | Total number of dashboards present within the InfluxDB instance | | flux function total counter | Total number of calls by function invoked within Flux | | http api requests counter | Total number of API invocations by each API path | | query duration histogram | Histogram counting duration of queries into bins | | organizations total counter | Total number of organizations present within the InfluxDB instance | | scrapers total counter | Total number of scrapers configured within the InfluxDB instance | | series total counter | Total number of series present within the InfluxDB instance | | storage total counter | Total number of bytes stored within the InfluxDB instance | | task scheduler gauge | Number of tasks running within the InfluxDB instance | | telegrafs total counter | Total number of Telegraf configurations within the InfluxDB instance | | tokens total counter | Total number of tokens present within the InfluxDB instance | | uptime gauge | Number of seconds InfluxDB has been continuously running | | users total counter | Total number of users present within the InfluxDB instance | | wal current segment gauge | Number of bytes in the current segments for the write ahead log | | wal writes total counter | Total number of writes to the write ahead log by status (ok, fail, etc.) | --- # InfluxDB OSS URLs Source: https://docs.influxdata.com/influxdb/v2/reference/urls/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB OSS is accessed at `localhost:8086` by default, but you can also customize your InfluxDB host and port. **Default host:** `localhost` **Default port:** `8086` ``` http://localhost:8086/ ``` ## Customize your InfluxDB OSS URL To customize your InfluxDB host and port, use the[`http-bind-address` configuration option](/influxdb/v2/reference/config-options/#http-bind-address)when starting `influxd`. ```sh # Syntax influxd --http-bind-address : # Example - Run InfluxDB at http://example.com:8080 influxd --http-bind-address example.com:8080 # Example - Run InfluxDB at http://localhost:8080 influxd --http-bind-address :8080 ``` > [!Note] > #### Configure DNS routing > > You must configure DNS routing to successfully route requests to your custom hostname. > Methods for configuring DNS routing vary depending on your operating system and > network architecture and are not covered in this documentation. --- # InfluxDB tools and integrations Source: https://docs.influxdata.com/influxdb/v2/tools/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### Flux VS Code extension no longer available > > The `vsflux` extension is no longer available in the Visual Studio Marketplace.`vsflux` and the `flux-lsp` Flux Language Server Protocol plugin are no longer maintained. > Their repositories have been archived and are no longer receiving updates. ### [Telegraf configurations](/influxdb/v2/tools/telegraf-configs/) InfluxDB OSS lets you automatically generate Telegraf configurations or upload custom Telegraf configurations that collect metrics and write them to InfluxDB OSS. ### [Notebooks](/influxdb/v2/tools/notebooks/) Use notebooks to build and annotate processes and data flows for time series data. ### [InfluxDB templates](/influxdb/v2/tools/influxdb-templates/) InfluxDB templates are prepackaged InfluxDB configurations that contain everything from dashboards and Telegraf configurations to notifications and alerts. ### [Install and use the influx CLI](/influxdb/v2/tools/influx-cli/) Use the `influx` and `influxd` command line interfaces to interact with and manage InfluxDB. ### [Use the Interactive Flux REPL](/influxdb/v2/tools/flux-repl/) Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact with InfluxDB and other data sources. ### [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) Use the InfluxQL interactive shell to execute InfluxQL queries and interact with InfluxDB. ### [Use the Flux LSP with Vim](/influxdb/v2/tools/flux-vim-lsp/) Use the Flux LSP with Vim to add auto-completion, syntax checking, and other language-specific features to your editor. ### [Use Grafana with InfluxDB OSS](/influxdb/v2/tools/grafana/) Use [Grafana](https://grafana.com/) to visualize data from your **InfluxDB** instance. ### [Use Chronograf with InfluxDB OSS](/influxdb/v2/tools/chronograf/) Chronograf is a data visualization and dashboarding tool designed to visualize data in InfluxDB 1.x. It is part of the [TICKstack](/platform/) that provides an InfluxQL data explorer, Kapacitor integrations, and more. Continue to use Chronograf with **InfluxDB Cloud** and **InfluxDB OSS 2.x** and the [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ### [Use Kapacitor with InfluxDB OSS](/influxdb/v2/tools/kapacitor/) [Kapacitor](/kapacitor/) is a data processing framework that makes it easy to create alerts, run ETL (Extract, Transform and Load) jobs and detect anomalies. Use Kapacitor with **InfluxDB OSS 2.x**. ### [Downsample data with Quix Streams](/influxdb/v2/tools/downsample-data-quix/) Use Quix Streams to create Python service that downsamples data stored in InfluxDB. ### [Use Postman with the InfluxDB API](/influxdb/v2/tools/postman/) Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, to interact with the [InfluxDB API](/influxdb/v2/api-guide/). ### [Use the InfluxDB documentation MCP server](/influxdb/v2/tools/mcp-server/) Query InfluxDB documentation from your IDE using the InfluxDB documentation Model Context Protocol (MCP) server. --- # Use Chronograf with InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/tools/chronograf/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Chronograf](/chronograf/v1/) is a data visualization and dashboarding tool designed to visualize data in InfluxDB 1.x. It is part of the [TICKstack](/platform/)that provides an InfluxQL data explorer, Kapacitor integrations, and more. Continue to use Chronograf with **InfluxDB Cloud** and **InfluxDB OSS 2.10** and the[1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ## Create an InfluxDB connection 1. In Chronograf, click **Configuration** in the left navigation bar, and then click **Add Connection**. 2. Toggle the **InfluxDB v2 Auth** option at the bottom of the form.InfluxDB v2 Auth toggle 3. Enter your InfluxDB connection credentials: * **Connection URL:** InfluxDB URL *(see [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/)or [InfluxDB OSS URLs](/influxdb/v2/reference/urls/))* ``` http://localhost:8086 ``` * **Connection Name:** Name to uniquely identify this connection configuration * **Organization:** InfluxDB [organization](/influxdb/v2/admin/organizations/) * **Token:** InfluxDB [API token](/influxdb/v2/admin/tokens/) * **Telegraf Database Name:** InfluxDB [bucket](/influxdb/v2/admin/buckets/)Chronograf uses to populate parts of the application, including the Host List page (default is `telegraf`) * **Default Retention Policy:** default [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp)***(leave blank)*** #### DBRPs map to InfluxDB buckets #### In InfluxDB 2.10, database/retention-policy (DBRP) combinations are mapped to buckets using the `database-name/retention-policy` naming convention.**DBRP mappings are required to query InfluxDB 2.10 using InfluxQL.** For information, see [DBRP mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/). 4. Click **Add Connection**. 5. Select the dashboards you would like to create, and then click **Next**. 6. To configure a Kapacitor connection, provide the necessary credentials, and then click **Continue**. Otherwise, click **Skip**.*For information about using Kapacitor with InfluxDB Cloud or InfluxDB OSS 2.10, see [Use Kapacitor with InfluxDB](/influxdb/v2/tools/kapacitor/).* 7. Click **Finish**. ## Important notes * [Update upgraded InfluxDB connections](#update-upgraded-influxdb-connections) * [No administrative functionality](#no-administrative-functionality) * [Limited InfluxQL support](#limited-influxql-support) ### Update upgraded InfluxDB connections If using Chronograf with an InfluxDB instance that was upgraded from 1.x to 2.x, update your InfluxDB connection configuration in Chronograf to use the**InfluxDB v2 Auth** option and provide an organization and a token.**Without an organization, Chronograf cannot use Flux to query InfluxDB.** ### No administrative functionality Chronograf cannot be used for administrative tasks in InfluxDB Cloud and InfluxDB OSS 2.10. For example, you **cannot** do the following: * Define databases * Modify retention policies * Add users * Kill queries When connected to an InfluxDB Cloud or InfluxDB 2.10 database, functionality in the **InfluxDB Admin** section of Chronograf is disabled. To complete administrative tasks, use the following: * **InfluxDB user interface (UI)** * [InfluxDB CLI](/influxdb/v2/reference/cli/influx/) * [InfluxDB v2 API](/influxdb/v2/reference/api/) ### Limited InfluxQL support InfluxDB Cloud and InfluxDB OSS 2.10 support InfluxQL **read-only** queries. For more information, see [InfluxQL support](/influxdb/v2/query-data/influxql/#influxql-support). #### Related * [Chronograf documentation](/chronograf/v1/) --- # Downsample data with Quix Streams Source: https://docs.influxdata.com/influxdb/v2/tools/downsample-data-quix/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A common practice when processing high volume data is to downsample it before comitting it to InfluxDB to reduce the overall disk usage as data collects over time. This guide walks through the process of creating a series of Python services that ingest from an InfluxDB v2 bucket, downsample and publish the data to another InfluxDB v2 bucket. By aggregating data within windows of time, then storing the aggregate values back to InfluxDB, you can reduce disk usage and costs over time. The guide uses the InfluxDB v2 and Quix Streams Python client libraries and can be run locally or deployed within Quix Cloud with a free trial. It assumes you have setup a Python project and virtual environment. ## Pipeline architecture The following diagram illustrates how data is passed between processes as it is downsampled: InfluxDB v2 Source Producer Downsampling Process InfluxDB v2 Sink Consumer ![Quix logo](/svgs/quix-logo-white.svg) ![Quix Streams logo](/svgs/quix-python-heart.svg) > [!Note] > It is usually more efficient to write raw data directly to Kafka rather than > writing raw data to InfluxDB first (essentially starting the Quix Streams > pipeline with the “influxv2-data” topic). However, this guide assumes that you > already have raw data in InfluxDB that you want to downsample. 1. [Set up prerequisites](#set-up-prerequisites) 2. [Install dependencies](#install-dependencies) 3. [Prepare InfluxDB buckets](#prepare-influxdb-buckets) 4. [Create the downsampling logic](#create-the-downsampling-logic) 5. [Create the producer and consumer clients](#create-the-producer-and-consumer-clients) 1. [Create the producer](#create-the-producer) 2. [Create the consumer](#create-the-consumer) 6. [Run the machine data generator](#run-the-machine-data-generator) 7. [Get the full downsampling code files](#get-the-full-downsampling-code-files) ## Set up prerequisites The process described in this guide requires the following: * InfluxDB v2 with data ready for downsampling. [Use the machine data generator code](#run-the-machine-data-generator) below. * A [Quix Cloud](https://portal.platform.quix.io/self-sign-up/) account or a local Apache Kafka or Red Panda installation. * Familiarity with basic Python and Docker concepts. ## Install dependencies Use `pip` to install the following dependencies: * `influxdb-client` (InfluxDB v2 client library) * `quixstreams<2.5` (Quix Streams client library) * `pandas` (data analysis and manipulation tool) ```sh pip install influxdb-client pandas quixstreams<2.5 ``` ## Prepare InfluxDB buckets The downsampling process involves two InfluxDB buckets. Each bucket has a [retention period](/influxdb/v2/reference/glossary/#retention-period)that specifies how long data persists before it expires and is deleted. By using two buckets, you can store unmodified, high-resolution data in a bucket with a shorter retention period and then downsampled, low-resolution data in a bucket with a longer retention period. Ensure you have a bucket for each of the following: * One to query unmodified data from your InfluxDB v2 cluster * The other to write downsampled data into ## Create the downsampling logic This process reads the raw data from the input Kafka topic that stores data streamed from the InfluxDB v2 bucket, downsamples it, and then sends it to an output topic which is later written back to another bucket. 1. Use the Quix Streams library’s `Application` class to initialize a connection to the Kafka topics. ``` from quixstreams import Application app = Application(consumer_group="downsampling-process", auto_offset_reset="earliest") input_topic = app.topic("input") output_topic = app.topic("output") # ... ``` 2. Configure the Quix Streams built-in windowing function to create a tumbling window that continuously downsamples the data into 1-minute buckets. ``` # ... target_field = "temperature" # The field that you want to downsample. def custom_ts_extractor(value): # ... # truncated for brevity - custom code that defines the "time_recorded" # field as the timestamp to use for windowing... topic = app.topic(input_topic, timestamp_extractor=custom_ts_extractor) sdf = ( sdf.apply(lambda value: value[target_field]) # Extract temperature values .tumbling_window(timedelta(minutes=1)) # 1-minute tumbling windows .mean() # Calculate average temperature .final() # Emit results at window completion ) sdf = sdf.apply( lambda value: { "time": value["end"], # End of the window "temperature_avg": value["value"], # Average temperature } ) sdf.to_topic(output_topic) # Output results to the "downsampled" topic # ... ``` The results are streamed to the Kafka topic, `downsampled`. > [!Note] > Note: “sdf” stands for “Streaming Dataframe”. You can find the full code for this process in the[Quix GitHub repository](https://github.com/quixio/template-invluxdbv2-tsm-downsampling/blob/tutorial/Downsampler/main.py). ## Create the producer and consumer clients Use the `influxdb_client` and `quixstreams` modules to instantiate two clients that interact with InfluxDB and Kafka: * A **producer** client configured to read from your InfluxDB bucket with *unmodified* data and *produce* that data to Kafka. * A **consumer** client configured to *consume* data from Kafka and write the *downsampled* data to the corresponding InfluxDB bucket. ### Create the producer Provide the following credentials for the producer: * **INFLUXDB\_HOST**: [InfluxDB URL](/influxdb/v2/reference/urls/)*(without the protocol)* * **INFLUXDB\_ORG**: InfluxDB organization name * **INFLUXDB\_TOKEN**: InfluxDB API token with read and write permissions on the buckets you want to query and write to. * **INFLUXDB\_BUCKET**: InfluxDB bucket name The producer queries for fresh data from InfluxDB at specific intervals. It writes the raw data to a Kafka topic called `influxv2-data`. ```py from quixstreams import Application import influxdb_client # Create a Quix Application app = Application(consumer_group="influxdbv2_migrate", auto_create_topics=True) # Define the topic using the "output" environment variable topic = app.topic(os.getenv("output", "influxv2-data")) # Create an InfluxDB v2 client influxdb2_client = influxdb_client.InfluxDBClient(token=os.environ["INFLUXDB_TOKEN"], org=os.environ["INFLUXDB_ORG"], url=os.environ["INFLUXDB_HOST"]) ## ... remaining code trunctated for brevity ... # Function to fetch data from InfluxDB # It runs in a continuous loop, periodically fetching data based on the interval. def get_data(): # Run in a loop until the main thread is terminated while run: try: # Query InfluxDB 2.0 using flux flux_query = f''' from(bucket: "{bucket}") |> range(start: -{interval}) |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") ''' logger.info(f"Sending query: {flux_query}") ## ... remaining code trunctated for brevity ... # Create a pre-configured Producer object. with app.get_producer() as producer: for res in get_data(): # Get the data from InfluxDB records = json.loads(res) for index, obj in enumerate(records): logger.info(f"Produced message with key:{message_key}, value:{obj}") # Publish the data to the Kafka topic producer.produce( topic=topic.name, key=message_key, value=obj, ) ``` You can find the full code for this process in the[Quix GitHub repository](https://github.com/quixio/template-invluxdbv2-tsm-downsampling/blob/tutorial/InfluxDB%20V2%20Data%20Source/main.py). ### Create the consumer As before, provide the following credentials for the consumer: * **INFLUXDB\_HOST**: [InfluxDB URL](/influxdb/v2/reference/urls/)*(without the protocol)* * **INFLUXDB\_ORG**: InfluxDB organization name * **INFLUXDB\_TOKEN**: InfluxDB API token with read and write permissions on the buckets you want to query and write to. * **INFLUXDB\_BUCKET**: InfluxDB bucket name > [!Note] > Note: These will be your InfluxDB v2 credentials. This process reads messages from the Kafka topic `downsampled-data` and writes each message as a point dictionary back to InfluxDB. ``` from quixstreams import Application, State from influxdb_client import InfluxDBClient, Point # Create a Quix platform-specific application instead app = Application(consumer_group=consumer_group_name, auto_offset_reset="earliest", use_changelog_topics=False) input_topic = app.topic(os.getenv("input", "input-data")) # Initialize InfluxDB v2 client influx2_client = InfluxDBClient(url=localhost:8086, token=API_TOKEN, org=ORG_NAME) ## ... remaining code trunctated for brevity ... def send_data_to_influx(message: dict, state: State): global last_write_time_ns, points_buffer, service_start_state try: ## ... code trunctated for brevity ... # Check if it's time to write the batch # 10k records have accumulated or 15 seconds have passed if len(points_buffer) >= 10000 or int(time() * 1e9) - last_write_time_ns >= 15e9: with influx2_client.write_api() as write_api: logger.info(f"Writing batch of {len(points_buffer)} points written to InfluxDB.") write_api.write(influx_bucket, influx_org, points_buffer) # Clear the buffer and update the last write time points_buffer = [] last_write_time_ns = int(time() * 1e9) ## ... code trunctated for brevity ... except Exception as e: logger.info(f"{str(datetime.utcnow())}: Write failed") logger.info(e) ## ... code trunctated for brevity ... # We use Quix Streams StreamingDataframe (SDF) to handle every message # in the Kafka topic by writing it to InfluxDB sdf = app.dataframe(input_topic) sdf = sdf.update(send_data_to_influx, stateful=True) if __name__ == "__main__": logger.info("Starting application") app.run(sdf) ``` You can find the full code for this process in the[Quix GitHub repository](https://github.com/quixio/quix-samples/tree/develop/python/destinations/influxdb_2). ## Run the Machine data generator Now it’s time to run the machine data generator code which will populate your source bucket with data which will be read by the [producer](#create-the-consumer). Run `main.py` from the `Machine data to InfluxDB` folder in the GitHub repository. ## Get the full downsampling code files To get the complete set of files referenced in this tutorial, clone the Quix “downsampling” repository. ### Clone the downsampling template repository To clone the downsampling template, enter the following command in the command line: ```sh git clone https://github.com/quixio/template-invluxdbv2-tsm-downsampling.git ``` This repository contains the following folders which store different parts of the whole pipeline: * **Machine Data to InfluxDB**: A script that generates synthetic machine data and writes it to InfluxDB. This is useful if you dont have your own data yet, or just want to work with test data first. * It produces a reading every 250 milliseconds. * This script originally comes from the[InfluxCommunity repository](https://github.com/InfluxCommunity/Arrow-Task-Engine/blob/master/machine_simulator/src/machine_generator.py)but has been adapted to write directly to InfluxDB rather than using an MQTT broker. * **InfluxDB v2 Data Source**: A service that queries for fresh data from InfluxDB at specific intervals. It’s configured to look for the measurement produced by the previously-mentioned synthetic machine data generator. It writes the raw data to a Kafka topic called “influxv2-data”. * **Downsampler**: A service that performs a 1-minute tumbling window operation on the data from InfluxDB and emits the mean of the “temperature” reading every minute. It writes the output to a “downsampled” Kafka topic. * **InfluxDB v2 Data Sink**: A service that reads from the “downsampled” topic and writes the downsampled records as points back into InfluxDB. --- # Use the Interactive Flux REPL Source: https://docs.influxdata.com/influxdb/v2/tools/flux-repl/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact with InfluxDB and other data sources.[Build the REPL](#build-the-repl) from the Flux source code. > [!Note] > Flux REPL supports running Flux scripts against InfluxDB 1.8+. ## Build the REPL To use the Flux REPL, build it from source using the [Flux repository](https://github.com/influxdata/flux/). For instructions, see the [Flux repository README](https://github.com/influxdata/flux/#requirements). ## Use the REPL * [Open a REPL session](#open-a-repl-session) * [Query data from InfluxDB](#query-data-from-influxdb) * [Multi-line entries](#multi-line-entries) * [Exit the REPL](#exit-the-repl) ### Open a REPL session To open a new REPL session, run: ```sh ./flux repl ``` ### Query data from InfluxDB To query data from InfluxDB (local or remote), provide the host, organization, and token parameters to the [`from()` function](/flux/v0/stdlib/influxdata/influxdb/from/). ```js from( bucket: "example-bucket", host: "http://localhost:8086", org: "example-org", token: "My5uP3rS3cRetT0k3n", ) ``` ### Multi-line entries Multi-line scripts like the example above work when pasted into the REPL. Pasting newlines from the clipboard is allowed. However, you cannot enter newline characters directly from the keyboard. ### Exit the REPL Exit the REPL by pressing **Control + D**. [flux](/influxdb/v2/tags/flux/) --- # Use the Flux LSP with Vim Source: https://docs.influxdata.com/influxdb/v2/tools/flux-vim-lsp/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). > [!Important] > #### Flux-LSP no longer maintained > > The `flux-lsp` Flux Language Server Protocol plugin is no longer maintained. > The [`flux-lsp` repo](https://github.com/influxdata/flux-lsp) has been archived and is no longer receiving updates. ## Requirements * Vim 8+ * [npm](https://www.npmjs.com/get-npm) ## Install the Flux plugin There are many ways to install and manage Vim plugins. We recommend either of the following two methods: * [Install with vim-lsp](#install-with-vim-lsp) * [Install with vim-coc](#install-with-vim-coc) Both methods require you to add the following to your `.vimrc` so that Vim can recognize the `.flux` file type: ``` " Flux file type au BufRead,BufNewFile *.flux set filetype=flux ``` ### Install with vim-lsp 1. **Install `flux-lsp-cli` with npm** ``` npm i -g @influxdata/flux-lsp-cli ``` 2. **Install [vim-lsp](https://github.com/prabirshrestha/vim-lsp)** If it doesn’t exist yet, create a directory called `pack/$USER/start/` in your `~/.vim/` and clone `vim-lsp` into it: ``` cd ~ mkdir -p .vim/pack/$USER/start/ cd .vim/pack/$USER/start/ git clone https://github.com/prabirshrestha/vim-lsp ``` 3. **Edit your `.vimrc`** Next, edit your `.vimrc` configuration file to include the following: ``` let g:lsp_diagnostics_enabled = 1 if executable('flux-lsp') au User lsp_setup call lsp#register_server({ \ 'name': 'flux lsp', \ 'cmd': {server_info->[&shell, &shellcmdflag, 'flux-lsp']}, \ 'whitelist': ['flux'], \ }) endif autocmd FileType flux nmap gd (lsp-definition) ``` ### Install with vim-coc 1. **Install `flux-lsp-cli` from npm** ``` npm i -g @influxdata/flux-lsp-cli ``` 2. **Install plug-vim** [Install plug-vim](https://github.com/junegunn/vim-plug#installation), a plugin manager for Vim. 3. **Install vim-coc** [Install vim-coc](https://github.com/neoclide/coc.nvim#quick-start), a code-completion plugin for Vim. 4. **Configure vim-coc** vim-coc uses a `coc-settings.json` located in your `~/.vim/` directory. To run the Flux LSP, add the Flux section under `languageserver`: ``` { "languageserver": { "flux": { "command": "flux-lsp", "filetypes": ["flux"] } } } ``` To debug flux-lsp, configure it to log to `/tmp/fluxlsp`: ``` { "languageserver": { "flux": { "command": "flux-lsp", "args": ["-l", "/tmp/fluxlsp"], "filetypes": ["flux"] } } } ``` --- # Use Grafana with InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/tools/grafana/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/)to visualize data from your **InfluxDB 2.10** instance. > [!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)* > [!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 interface dynamically adapts based on your product and query language > selection in [URL and authentication](#configure-url-and-authentication). * [Install Grafana](#install-grafana) * [Create an InfluxDB data source](#create-an-influxdb-data-source) * [Query and visualize data](#query-and-visualize-data) ## Install Grafana 1. [Start InfluxDB OSS 2.x](/influxdb/v2/install/#configure-and-start-influxdb). 2. [Sign up for Grafana Cloud](https://grafana.com/products/cloud/) or[download and install Grafana](https://grafana.com/grafana/download). 3. 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](#linux)[macOS (Homebrew)](#macos-homebrew)[Windows](#windows) ``` 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. 4. 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/). > [!Note] > SQL is only supported in InfluxDB 3. > For more information, see how to [get started with InfluxDB 3 Core](/influxdb3/core/get-started/). ## Quick reference | Configuration | Value | |---------------------|--------------------| |**Product selection**|**InfluxDB OSS 2.x**| | | **URL** | [Server URL](/influxdb/v2/reference/urls/)–for example, `https://localhost:8086` | | **Query languages** | Flux, InfluxQL | | **Authentication** | API token or v1 username/password | | **Organization** | Organization name or ID (Flux only) | | **Default Bucket** | Default bucket for Flux queries (Flux only) | | **Database** | Database name mapped to bucket (InfluxQL only) | ## Create an InfluxDB data source 1. In your Grafana interface, click **Connections** in the left sidebar. 2. Click **Data sources**. 3. Click **Add new connection**. 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 [server URL](/influxdb/v2/reference/urls/)–for example, `https://localhost:8086` * **Product**: From the dropdown, select **InfluxDB OSS 2.x** * **Query Language**: Select **Flux** 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). [Flux](#flux) [InfluxQL](#influxql) ## Configure Grafana to use Flux When you select **Flux** as the query language, configure the following: * **Organization**: Your InfluxDB [organization name or ID](/influxdb/v2/admin/organizations/view-orgs/) * **Default Bucket**: The default [bucket](/influxdb/v2/admin/buckets/) to use in Flux queries * **Token**: Your InfluxDB [API token](/influxdb/v2/admin/tokens/) Flux configuration for InfluxDB OSS 2.x Click **Save & Test**. Grafana attempts to connect to InfluxDB OSS 2.x and returns the results of the test. ## Configure Grafana to use InfluxQL > [!Important] > #### DBRP mapping required > > To query InfluxDB OSS 2.x with InfluxQL, you must first create Database and Retention Policy (DBRP) mappings. > The configuration form displays a warning if DBRP mapping is required. When you select **InfluxQL** as the query language, you can authenticate using either tokens or username/password credentials. ### Token authentication (recommended) Configure the following fields: * **Database**: The database name [mapped to your InfluxDB bucket](#create-dbrp-mappings) * **User**: Enter any string (this field is required by the form) * **Password**: Your InfluxDB [API token](/influxdb/v2/admin/tokens/) ### Username and password authentication Configure the following fields: * **Database**: The database name [mapped to your InfluxDB bucket](#create-dbrp-mappings) * **User**: Your [v1 authorization username](#create-v1-authorizations) * **Password**: Your [v1 authorization password](#create-v1-authorizations) InfluxQL configuration for InfluxDB OSS 2.x with DBRP warning Click **Save & Test**. Grafana attempts to connect to InfluxDB OSS 2.x and returns the results of the test. ### Create DBRP mappings When using InfluxQL to query InfluxDB, the query must specify a database and retention policy. InfluxDB DBRP mappings associate database and retention policy combinations with InfluxDB OSS 2.x buckets. #### View existing DBRP mappings Use the [`influx v1 dbrp list`](/influxdb/v2/reference/cli/influx/v1/dbrp/list/) command: ```sh influx v1 dbrp list ``` ### Create a DBRP mappings Use the influx v1 dbrp create command: ```sh influx v1 dbrp create \ --db example-db \ --rp example-rp \ --bucket-id 00xX00o0X001 \ --default ``` Provide: * `--db:` Database name * `--rp:` Retention policy name (not retention period) * `--bucket-id:` Bucket ID * `--default:` (Optional) Make this the default retention policy for the database > [!Note] > **Repeat for each DBRP combination**Each unique database and retention policy combination used by Grafana must be mapped to an InfluxDB OSS 2.x bucket. For more information, see [Database and retention policy mapping](/influxdb/v2/api-guide/influxdb-1x/dbrp/). ### Create v1 authorizations InfluxDB OSS 2.x provides a v1-compatible authentication API for username/password authentication. #### View existing v1 authorizations Use the [`influx v1 auth list`](/influxdb/v2/reference/cli/influx/v1/auth/list/) command: ```sh influx v1 auth list ``` #### Create a v1 authorization Use the [`influx v1 auth create`](/influxdb/v2/reference/cli/influx/v1/auth/create/) command: ```sh influx v1 auth create \ --read-bucket 00xX00o0X001 \ --write-bucket 00xX00o0X001 \ --username example-user ``` Provide: * `--read-bucket`: Bucket ID to grant read permissions * `--write-bucket`: Bucket ID to grant write permissions * `--username`: New username You’ll be prompted to enter a password. ## Query and visualize data With your InfluxDB connection configured, use Grafana to query and visualize time series data. ### Query inspection in Grafana To learn about query management and inspection in Grafana, see the[Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/). ### Build visualizations with Grafana For a comprehensive walk-through of creating visualizations with Grafana, see the [Grafana documentation](https://grafana.com/docs/grafana/latest/). #### Related * [Grafana documentation](https://grafana.com/docs/) * [Get started with Flux and InfluxDB](/influxdb/v2/query-data/get-started/) [grafana](/influxdb/v2/tags/grafana/) | Configuration | Value | | --- | --- | | Configuration | Value | | Product selection | InfluxDB OSS 2.x | --- # Install and use the influx CLI Source: https://docs.influxdata.com/influxdb/v2/tools/influx-cli/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` CLI to interact with and manage your InfluxDB instance. Write and query data, generate InfluxDB templates, export data, and more. > [!Note] > The [`influx` CLI](/influxdb/v2/reference/cli/influx) is packaged and versioned > separately from the InfluxDB server (`influxd`). * [Install the influx CLI](#install-the-influx-cli) * [Set up the influx CLI](#set-up-the-influx-cli) * [Use influx CLI commands](#use-influx-cli-commands) ## Install the influx CLI [macOS](#macos)[Linux](#linux)[Windows](#windows) Do one of the following: * [Use Homebrew](#use-homebrew) * [Manually download and install](#manually-download-and-install) ### Use Homebrew ```sh brew install influxdb-cli ``` > [!Note] > If you used Homebrew to install **InfluxDB 2.10**, the `influxdb-cli`formula was downloaded as a dependency and should already be installed. > If installed, `influxdb-cli` will appear in the output of the following command: > > ``` > brew list | grep influxdb-cli > ``` ### Manually download and install 1. Download the `influx` CLI package [from your browser](#download-from-your-browser)or [from the command line](#download-from-the-command-line). #### Download from your browser #### [influx CLI v2.9.1 (macOS)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-darwin-amd64.tar.gz) #### Download from the command line #### ``` curl -LO https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-darwin-amd64.tar.gz \ --output-dir ~/Downloads ``` 2. Unpackage the downloaded binary. Do one of the following: * In **Finder**, double-click the downloaded package file. * In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**) use `tar` to extract the package–for example, enter the following command to extract it into `~/Downloads`: ``` tar zxvf ~/Downloads/influxdb2-client-2.9.1-darwin-amd64.tar.gz \ --directory ~/Downloads ``` 3. Optional: Place the `influx` binary in your `$PATH`–for example, copy the binary to `/usr/local/bin`: ``` sudo cp ~/Downloads/influx /usr/local/bin/ ``` With the `influx` binary in your `$PATH` (`/usr/local/bin`), you can enter `influx` in your terminal to run the CLI. If you do not move the `influx` binary into your `$PATH`, enter the path to the binary to run the CLI–for example: ``` ~/Downloads/influx ``` 4. (macOS Catalina and newer) Authorize the `influx` binary. macOS requires downloaded binaries to be signed by registered Apple developers. When you first attempt to run `influx`, macOS prevents it from running. To authorize the `influx` binary: **Allow the binary on macOS Ventura** 1. Follow the preceding instructions to attempt to start `influx`. 2. Open **System Settings** and click **Privacy & Security**. 3. Under the **Security** heading, there is a message about “influxd” being blocked, click **Allow Anyway**. 4. When prompted, enter your password to allow the setting. 5. Close **System Settings**. 6. Attempt to start `influx`. 7. A prompt appears with the message *“macOS cannot verify the developer of “influx”…”"*. Click **Open**. **Allow the binary on macOS Catalina** 1. Attempt to run an `influx` command. 2. Open **System Preferences** and click **Security & Privacy**. 3. Under the **General** tab, there is a message about `influx` being blocked. Click **Open Anyway**. 1. Download the `influx` CLI package [from your browser](#download-from-your-browser)or [from the command line](#download-from-the-command-line). #### Download from your browser #### [influx CLI v2.9.1 (amd64)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-amd64.tar.gz)[influx CLI v2.9.1 (arm)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-arm64.tar.gz) #### Download from the command line #### ``` # amd64 wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-amd64.tar.gz ``` ``` # arm wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-arm64.tar.gz ``` 2. Unpackage the downloaded binary. ***Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary.* ``` # amd64 tar xvzf ./influxdb2-client-2.9.1-linux-amd64.tar.gz ``` ``` # arm tar xvzf ./influxdb2-client-2.9.1-linux-arm64.tar.gz ``` 3. Optional: Place the unpackaged `influx` executable in your system `$PATH`. ``` # amd64 sudo cp ./influx /usr/local/bin/ ``` ``` # arm sudo cp ./influx /usr/local/bin/ ``` If you do not move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server–for example: ``` ./influx ``` > [!Note] > We recommend running `influx` CLI commands in Powershell. > Command Prompt is not fully compatible. 1. Download the `influx` CLI package. [influx CLI v2.9.1 (Windows)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-windows-amd64.zip) 2. Expand the downloaded archive. Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired. ``` > Expand-Archive .\influxdb2-client-2.9.1-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\' > mv 'C:\Program Files\InfluxData\influxdb2-client-2.9.1-windows-amd64' 'C:\Program Files\InfluxData\influx' ``` 3. Grant network access to the `influx` CLI. When using the `influx` CLI for the first time, **Windows Defender** displays the following message: > > > Windows Defender Firewall has blocked some features of this app. > > To grant the `influx` CLI the required access, do the following: 1. Select **Private networks, such as my home or work network**. 2. Click **Allow access**. ## Set up the influx CLI * [Provide required authentication credentials](#provide-required-authentication-credentials) * [Enable shell completion (Optional)](#enable-shell-completion-optional) ### Provide required authentication credentials To avoid having to pass your InfluxDB **host**, **API token**, and **organization**with each command, store them in an `influx` CLI configuration (config).`influx` commands that require these credentials automatically retrieve these credentials from the active config. Use the [`influx config create` command](/influxdb/v2/reference/cli/influx/config/create/)to create an `influx` CLI config and set it as active: ```sh influx config create --config-name CONFIG_NAME \ --host-url http://localhost:8086 \ --org ORG \ --token API_TOKEN \ --active ``` Replace the following: * `CONFIG_NAME`: Connection configuration name. * `ORG_NAME`: your InfluxDB [organization](/influxdb/v2/admin/organizations/). * `API_TOKEN`: your [API token](/influxdb/v2/admin/tokens/). For more information about managing CLI configurations, see the[`influx config` documentation](/influxdb/v2/reference/cli/influx/config/). For instructions on how to create API tokens, see [Create a token](/influxdb/v2/admin/tokens/create-token/). #### Authenticate with a username and password The **`influx` CLI 2.4.0+** lets you create connection configurations that authenticate with **InfluxDB OSS 2.4+** using the username and password combination that you would use to log into the InfluxDB user interface (UI). The CLI retrieves a session cookie and stores it, unencrypted, in your[configs path](/influxdb/v2/reference/internals/file-system-layout/#configs-path). Use the `--username-password`, `-p` option to provide your username and password using the `:` syntax. If no password is provided, the CLI prompts for a password after each command that requires authentication. ```sh influx config create \ -n CONFIG_NAME \ -u http://localhost:8086 \ -p USERNAME:PASSWORD \ -o ORG ``` Replace the following: * `CONFIG_NAME`: Connection configuration name. * `ORG`: [your organization name](/influxdb/v2/admin/organizations/). * `USERNAME:PASSWORD`: your UI username and password combination. ### Enable shell completion (Optional) To install `influx` shell completion scripts, see[`influx completion`](/influxdb/v2/reference/cli/influx/completion/#install-completion-scripts). ## Use influx CLI commands *For information about `influx` CLI commands, see the[`influx` CLI reference documentation](/influxdb/v2/reference/cli/influx/).* #### Related * [influx - InfluxDB command line interface](/influxdb/v2/reference/cli/influx/) [cli](/influxdb/v2/tags/cli/) --- # InfluxDB templates Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB templates are prepackaged InfluxDB configurations that contain everything from dashboards and Telegraf configurations to notifications and alerts. Use templates to monitor your technology stack, set up a fresh instance of InfluxDB, back up your dashboard configuration, or[share your configuration](https://github.com/influxdata/community-templates/) with the InfluxData community. **InfluxDB templates do the following:** * Reduce setup time by giving you resources that are already configured for your use-case. * Facilitate secure, portable, and source-controlled InfluxDB resource states. * Simplify sharing and using pre-built InfluxDB solutions. [View InfluxDB community templates](https://github.com/influxdata/community-templates/) ## Template manifests A template **manifest** is a file that defines InfluxDB [resources](#template-resources). Template manifests support the following formats: * [YAML](https://yaml.org/) * [JSON](https://www.json.org/) * [Jsonnet](https://jsonnet.org/) > [!Note] > Template manifests are compatible with[Kubernetes Custom Resource Definitions (CRD)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/). The `metadata.name` field in manifests uniquely identifies each resource in the template.`metadata.name` values must be [DNS-1123](https://tools.ietf.org/html/rfc1123) compliant. The `spec` object contains the resource configuration. #### Example ```yaml # bucket-template.yml # Template manifest that defines two buckets. apiVersion: influxdata.com/v2alpha1 kind: Bucket metadata: name: thirsty-shaw-91b005 spec: description: My IoT Center Bucket name: iot-center retentionRules: - everySeconds: 86400 type: expire --- apiVersion: influxdata.com/v2alpha1 kind: Bucket metadata: name: upbeat-fermat-91b001 spec: name: air_sensor --- ``` *See [Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/) for information about generating template manifests.* ### Template resources Templates may contain the following InfluxDB resources: * [buckets](/influxdb/v2/admin/buckets/create-bucket/) * [checks](/influxdb/v2/monitor-alert/checks/create/) * [dashboards](/influxdb/v2/visualize-data/dashboards/create-dashboard/) * [dashboard variables](/influxdb/v2/visualize-data/variables/create-variable/) * [labels](/influxdb/v2/visualize-data/labels/) * [notification endpoints](/influxdb/v2/monitor-alert/notification-endpoints/create/) * [notification rules](/influxdb/v2/monitor-alert/notification-rules/create/) * [tasks](/influxdb/v2/process-data/manage-tasks/create-task/) * [Telegraf configurations](/influxdb/v2/write-data/no-code/use-telegraf/) ## Stacks Use **InfluxDB stacks** to manage InfluxDB templates. When you apply a template, InfluxDB associates resources in the template with a stack. Use stacks to add, update, or remove InfluxDB templates over time. For more information, see [InfluxDB stacks](#influxdb-stacks) below. ### [Use InfluxDB templates](/influxdb/v2/tools/influxdb-templates/use/) Use the `influx` command line interface (CLI) to summarize, validate, and apply templates from your local filesystem and from URLs. ### [Create an InfluxDB template](/influxdb/v2/tools/influxdb-templates/create/) Use the InfluxDB UI and the `influx export` command to create InfluxDB templates. ### [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/) Use an InfluxDB stack to manage your InfluxDB templates—add, update, or remove templates over time. [templates](/influxdb/v2/tags/templates/) --- # Create an InfluxDB template Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) and the [`influx export` command](/influxdb/v2/reference/cli/influx/export/) to create InfluxDB templates from [resources](/influxdb/v2/tools/influxdb-templates/#template-resources) in an organization. Add buckets, Telegraf configurations, tasks, and more in the InfluxDB UI and then export those resources as a template. * [Create a template](#create-a-template) * [Export resources to a template](#export-resources-to-a-template) * [Include user-definable resource names](#include-user-definable-resource-names) * [Troubleshoot template results and permissions](#troubleshoot-template-results-and-permissions) * [Share your InfluxDB templates](#share-your-influxdb-templates) ## Create a template Creating an organization to contain only your template resources is an easy way to ensure you export the resources you want. Follow these steps to create a template from a new organization. 1. [Start InfluxDB](/influxdb/v2/get-started/). 2. [Create an organization](/influxdb/v2/admin/organizations/create-org/). 3. In the InfluxDB UI, add one or more [resources](/influxdb/v2/tools/influxdb-templates/#template-resources). 4. [Create an **All Access** API token](/influxdb/v2/admin/tokens/create-token/) (or a token that has **read** access to the organization). 5. Use the API token from **Step 4** with the [`influx export all` subcommand](/influxdb/v2/reference/cli/influx/export/all/) to [export all resources]() in the organization to a template file. ``` influx export all \ -o YOUR_INFLUX_ORG \ -t YOUR_ALL_ACCESS_TOKEN \ -f ~/templates/template.yml ``` ## Export resources to a template The [`influx export` command](/influxdb/v2/reference/cli/influx/export/) and subcommands let you export [resources](#template-resources) from an organization to a template manifest. Your [API token](/influxdb/v2/admin/tokens/) must have **read** access to resources that you want to export. If you want to export resources that depend on other resources, be sure to export the dependencies. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) or by environment variables (`INFLUX_HOST`, `INFLUX_ORG`, and `INFLUX_TOKEN`). > If you do not have a CLI configuration set up or the environment variables set, include these required credentials for each command with the following flags: > > * `--host`: [InfluxDB host](/influxdb/v2/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token To create a template that **adds, modifies, and deletes resources** when applied to an organization, use [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/). First, [initialize the stack](/influxdb/v2/tools/influxdb-templates/stacks/init/)and then [export the stack](#export-a-stack). To create a template that only **adds resources** when applied to an organization (and doesn’t modify existing resources there), choose one of the following: * [Export all resources](#export-all-resources) to export all resources or a filtered subset of resources to a template. * [Export specific resources](#export-specific-resources) by name or ID to a template. ### Export all resources To export all [resources](/influxdb/v2/tools/influxdb-templates/#template-resources)within an organization to a template manifest file, use the[`influx export all` subcommand](/influxdb/v2/reference/cli/influx/export/all/)with the `--file` (`-f`) option. Provide the following: * **Destination path and filename** for the template manifest. The filename extension determines the output format: * `your-template.yml`: [YAML](https://yaml.org/) format * `your-template.json`: [JSON](https://json.org/) format ```sh # Syntax influx export all -f ``` #### Export resources filtered by labelName or resourceKind The [`influx export all` subcommand](/influxdb/v2/reference/cli/influx/export/all/)accepts a `--filter` option that exports only resources that match specified label names or resource kinds. To filter on label name *and* resource kind, provide a `--filter` for each. #### Export only dashboards and buckets with specific labels The following example exports resources that match this predicate logic: ```js (resourceKind == "Bucket" or resourceKind == "Dashboard") and (labelName == "Example1" or labelName == "Example2") ``` ```sh influx export all \ -f ~/templates/template.yml \ --filter=resourceKind=Bucket \ --filter=resourceKind=Dashboard \ --filter=labelName=Example1 \ --filter=labelName=Example2 ``` For more options and examples, see the[`influx export all` subcommand](/influxdb/v2/reference/cli/influx/export/all/). ### Export specific resources To export specific [resources](/influxdb/v2/tools/influxdb-templates/#template-resources) by name or ID, use the **[`influx export` command](/influxdb/v2/reference/cli/influx/export/)** with one or more lists of resources to include. Provide the following: * **Destination path and filename** for the template manifest. The filename extension determines the output format: * `your-template.yml`: [YAML](https://yaml.org/) format * `your-template.json`: [JSON](https://json.org/) format * **Resource options** with corresponding lists of resource IDs or resource names to include in the template. For information about what resource options are available, see the[`influx export` command](/influxdb/v2/reference/cli/influx/export/). ```sh # Syntax influx export -f [resource-flags] ``` #### Export specific resources by ID ```sh influx export \ --org-id ed32b47572a0137b \ -f ~/templates/template.yml \ -t $INFLUX_TOKEN \ --buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \ --dashboards=00000xX0x0X00x000 \ --telegraf-configs=00000x0x000X0x0X0 ``` #### Export specific resources by name ```sh influx export \ --org-id ed32b47572a0137b \ -f ~/templates/template.yml \ --bucket-names=bucket1,bucket2 \ --dashboard-names=dashboard1,dashboard2 \ --telegraf-config-names=telegrafconfig1,telegrafconfig2 ``` ### Export a stack To export an InfluxDB [stack](/influxdb/v2/tools/influxdb-templates/stacks/) and all its associated resources as a template, use the`influx export stack` command. Provide the following: * **Organization name** or **ID** * **API token** with read access to the organization * **Destination path and filename** for the template manifest. The filename extension determines the output format: * `your-template.yml`: [YAML](https://yaml.org/) format * `your-template.json`: [JSON](https://json.org/) format * **Stack ID** #### Export a stack as a template ```sh # Syntax influx export stack \ -o \ -t \ -f \ # Example influx export stack \ -o my-org \ -t mYSuP3RS3CreTt0K3n -f ~/templates/awesome-template.yml \ 05dbb791a4324000 ``` ## Include user-definable resource names After exporting a template manifest, replace resource names with **environment references**to let users customize resource names when installing your template. 1. [Export a template](#export-a-template). 2. Select any of the following resource fields to update: * `metadata.name` * `associations[].name` * `endpointName` *(unique to `NotificationRule` resources)* 3. Replace the resource field value with an `envRef` object with a `key` property that references the key of a key-value pair the user provides when installing the template. During installation, the `envRef` object is replaced by the value of the referenced key-value pair. If the user does not provide the environment reference key-value pair, InfluxDB uses the `key` string as the default value. [YAML](#yaml)[JSON](#json) ``` apiVersion: influxdata.com/v2alpha1 kind: Bucket metadata: name: envRef: key: bucket-name-1 ``` ``` { "apiVersion": "influxdata.com/v2alpha1", "kind": "Bucket", "metadata": { "name": { "envRef": { "key": "bucket-name-1" } } } } ``` Using the example above, users are prompted to provide a value for `bucket-name-1`when [applying the template](/influxdb/v2/tools/influxdb-templates/use/#apply-templates). Users can also include the `--env-ref` flag with the appropriate key-value pair when installing the template. ```sh # Set bucket-name-1 to "myBucket" influx apply \ -f /path/to/template.yml \ --env-ref=bucket-name-1=myBucket ``` *If sharing your template, we recommend documenting what environment references exist in the template and what keys to use to replace them.* > [!Note] > #### Resource fields that support environment references > > Only the following fields support environment references: > > * `metadata.name` > * `spec.endpointName` > * `spec.associations.name` ## Troubleshoot template results and permissions If you get unexpected results, missing resources, or errors when exporting templates, check the following: * [Ensure `read` access](#ensure-read-access) * [Use Organization ID](#use-organization-id) * [Check for resource dependencies](#check-for-resource-dependencies) ### Ensure read access The [API token](/influxdb/v2/admin/tokens/) must have **read** access to resources that you want to export. The `influx export all` command only exports resources that the API token can read. For example, to export all resources in an organization that has ID `abc123`, the API token must have the `read:/orgs/abc123` permission. To learn more about permissions, see [how to view authorizations](/influxdb/v2/admin/tokens/view-tokens/) and [how to create a token](/influxdb/v2/admin/tokens/create-token/) with specific permissions. ### Use Organization ID If your token doesn’t have **read** access to the organization and you want to [export specific resources](#export-specific-resources), use the `--org-id ` flag (instead of `-o ` or `--org `) to provide the organization. ### Check for resource dependencies If you want to export resources that depend on other resources, be sure to export the dependencies as well. Otherwise, the resources may not be usable. ## Share your InfluxDB templates Share your InfluxDB templates with the entire InfluxData community. Contribute your template to the [InfluxDB Community Templates](https://github.com/influxdata/community-templates/) repository on GitHub. [View InfluxDB Community Templates](https://github.com/influxdata/community-templates/) #### Related * [influx export](/influxdb/v2/reference/cli/influx/export/) * [influx export all](/influxdb/v2/reference/cli/influx/export/all/) [templates](/influxdb/v2/tags/templates/) --- # InfluxDB stacks Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use InfluxDB stacks to manage [InfluxDB templates](/influxdb/v2/influxdb-templates). When you apply a template, InfluxDB associates resources in the template with a stack. Use the stack to add, update, or remove InfluxDB templates over time. * [Save time with stacks](#save-time-with-stacks) * [Initialize a stack](#initialize-a-stack) * [Update a stack](#update-a-stack) * [View stacks](#view-stacks) * [Remove a stack](#remove-a-stack) ### [Save time with stacks](/influxdb/v2/tools/influxdb-templates/stacks/save-time/) Discover how to use InfluxDB stacks to save time. ### [Initialize a stack](/influxdb/v2/tools/influxdb-templates/stacks/init/) InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/v2/tools/influxdb-templates/use/) **without providing a stack ID**. To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/v2/reference/cli/influx/stacks/init/). ```sh influx apply \ -o example-org \ -f path/to/template.yml ``` ```sh influx stacks init \ -o example-org \ -n "Example Stack" \ -d "InfluxDB stack for monitoring some awesome stuff" \ -u https://example.com/template-1.yml \ -u https://example.com/template-2.yml ``` [Read more ](/influxdb/v2/tools/influxdb-templates/stacks/init/) ### [Update a stack](/influxdb/v2/tools/influxdb-templates/stacks/update/) Use the [`influx apply` command](/influxdb/v2/reference/cli/influx/apply/) to update a stack with a modified template. When applying a template to an existing stack, InfluxDB checks to see if the resources in the template match existing resources. InfluxDB updates, adds, and removes resources to resolve differences between the current state of the stack and the newly applied template. ```sh influx apply \ -o example-org \ -u http://example.com/template-1.yml \ -u http://example.com/template-2.yml \ --stack-id=12ab34cd56ef ``` [Read more ](/influxdb/v2/tools/influxdb-templates/stacks/update/) ### [View stacks](/influxdb/v2/tools/influxdb-templates/stacks/view/) Use the [`influx stacks` command](/influxdb/v2/reference/cli/influx/stacks/) to view installed InfluxDB stacks and their associated resources. ```sh influx stacks -o example-org ``` [Read more ](/influxdb/v2/tools/influxdb-templates/stacks/view/) ### [Remove a stack](/influxdb/v2/tools/influxdb-templates/stacks/remove/) Use the [`influx stacks remove` command](/influxdb/v2/reference/cli/influx/stacks/remove/) to remove an InfluxDB stack and all its associated resources. ```sh influx stacks remove \ -o example-org \ --stack-id=12ab34cd56ef ``` [Read more ](/influxdb/v2/tools/influxdb-templates/stacks/remove/) > [!Note] > **Key differences between stacks and templates**: > > * A template defines a set of resources in a text file outside of InfluxDB. When you apply a template, a stack is automatically created to manage the applied template. > * Stacks add, modify or delete resources in an instance. > * Templates do not recognize resources in an instance. All resources in the template are added, creating duplicate resources if a resource already exists. #### Related --- # Initialize an InfluxDB stack Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/init/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/v2/tools/influxdb-templates/use/)**without providing a stack ID**. To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/v2/reference/cli/influx/stacks/init/). ## Initialize a stack when applying a template To automatically create a new stack when [applying an InfluxDB template](/influxdb/v2/tools/influxdb-templates/use/)**don’t provide a stack ID**. InfluxDB applies the resources in the template to a new stack and provides the **stack ID** the output. ```sh influx apply \ -o example-org \ -f path/to/template.yml ``` ## Manually initialize a new stack Use the [`influx stacks init` command](/influxdb/v2/reference/cli/influx/stacks/init/)to create or initialize a new InfluxDB stack. **Provide the following:** * Organization name or ID * Stack name * Stack description * InfluxDB template URLs ```sh # Syntax influx stacks init \ -o \ -n \ -d # Example influx stacks init \ -o example-org \ -n "Example Stack" \ -d "InfluxDB stack for monitoring some awesome stuff" \ -u https://example.com/template-1.yml \ -u https://example.com/template-2.yml ``` #### Related * [influx stacks init](/influxdb/v2/reference/cli/influx/stacks/init/) --- # Remove an InfluxDB stack Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/remove/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`influx stacks remove` command](/influxdb/v2/reference/cli/influx/stacks/remove/)to remove an InfluxDB stack and all its associated resources. **Provide the following:** * Organization name or ID * Stack ID ```sh # Syntax influx stacks remove -o --stack-id= # Example influx stacks remove \ -o example-org \ --stack-id=12ab34cd56ef ``` #### Related * [influx stacks remove](/influxdb/v2/reference/cli/influx/stacks/remove/) --- # Save time with InfluxDB stacks Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/save-time/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Save time and money using InfluxDB stacks. Here’s a few ideal use cases: * [Automate deployments with GitOps and stacks](#automate-deployments-with-gitops-and-stacks) * [Apply updates from source-controlled templates](#apply-updates-from-source-controlled-templates) * [Apply template updates across multiple InfluxDB instances](#apply-template-updates-across-multiple-influxdb-instances) * [Develop templates](#develop-templates) ### Automate deployments with GitOps and stacks GitOps is popular way to configure and automate deployments. Use InfluxDB stacks in a GitOps workflow to automatically update distributed instances of InfluxDB OSS or InfluxDB Cloud. To automate an InfluxDB deployment with GitOps and stacks, complete the following steps: 1. [Set up a GitHub repository](#set-up-a-github-repository) 2. [Add existing resources to the GitHub repository](#add-existing-resources-to-the-github-repository) 3. [Automate the creation of a stack for each folder](#automate-the-creation-of-a-stack-for-each-folder) 4. [Set up Github Actions or CircleCI](#set-up-github-actions-or-circleci) #### Set up a GitHub repository Set up a GitHub repository to back your InfluxDB instance. Determine how you want to organize the resources in your stacks within your Github repository. For example, organize resources under folders for specific teams or functions. We recommend storing all resources for one stack in the same folder. For example, if you monitor Redis, create a `redis` stack and put your Redis monitoring resources (a Telegraf configuration, four dashboards, a label, and two alert checks) into one Redis folder, each resource in a separate file. Then, when you need to update a Redis resource, it’s easy to find and make changes in one location. > [!Note] > Typically, we **do not recommend** using the same resource in multiple stacks. If your organization uses the same resource in multiple stacks, before you delete a stack, verify the stack does not include resources that another stack depends on. Stacks with buckets often contain data used by many different templates. Because of this, we recommend keeping buckets separate from the other stacks. #### Add existing resources to the GitHub repository Skip this section if you are starting from scratch or don’t have existing resources you want to add to your stack. Use the `influx export` command to quickly export resources. Keep all your resources in a single file or have files for each one. You can always split or combine them later. For example, if you export resources for three stacks: `buckets`, `redis`, and `mysql`, your folder structure might look something like this when you are done: ```sh influxdb-assets/ ├── buckets/ │ ├── telegraf_bucket.yml ├── redis/ │ ├── redis_overview_dashboard.yml │ ├── redis_label.yml │ ├── redis_cpu_check.yml │ └── redis_mem_check.yml ├── mysql/ │ ├── mysql_assets.yml └── README.md ``` > [!Note] > When you export a resource, InfluxDB creates a `meta.name` for that resource. These resource names should be unique inside your InfluxDB instance. Use a good naming convention to prevent duplicate `meta.names`. Changing the `meta.name` of the InfluxDB resource will cause the stack to orphan the resource with the previous name and create a new resource with the updated name. Add the exported resources to your new GitHub repository. #### Automate the creation of a stack for each folder To automatically create a stack from each folder in your GitHub repository, create a shell script to check for an existing stack and if the stack isn’t found, use the `influx stacks init` command to create a new stack. The following sample script creates a `redis` stack and automatically applies those changes to your instance: ```sh echo "Checking for existing redis stack..." REDIS_STACK_ID=$(influx stacks --stack-name redis --json | jq -r '.[0].ID') if [ "$REDIS_STACK_ID" == "null" ]; then echo "No stack found. Initializing our stack..." REDIS_STACK_ID=$(influx stacks init -n redis --json | jq -r '.ID') fi # Setting the base path BASE_PATH="$(pwd)" echo "Applying our redis stack..." cat $BASE_PATH/redis/*.yml | \ influx apply --force true --stack-id $REDIS_STACK_ID -q ``` > [!Note] > The `--json` flag in the InfluxDB CLI is very useful when scripting against the CLI. This flag lets you grab important information easily using [`jq`](https://stedolan.github.io/jq/manual/v1.6/). Repeat this step for each of the stacks in your repository. When a resource in your stack changes, re-run this script to apply updated resources to your InfluxDB instance. Re-applying a stack with an updated resource won’t add, delete, or duplicate resources. #### Set up Github Actions or CircleCI Once you have a script to apply changes being made to your local instance, automate the deployment to other environments as needed. Use the InfluxDB CLI to maintain multiple [configuration profiles]() to easily switch profile and issue commands against other InfluxDB instances. To apply the same script to a different InfluxDB instance, change your active configuration profile using the `influx config set` command. Or set the desired profile dynamically using the `-c, --active-config` flag. > [!Note] > Before you run automation scripts against shared environments, we recommend manually running the steps in your script. Verify your deployment automation software lets you run a custom script, and then set up the custom script you’ve built locally another environment. For example, here’s a custom Github Action that automates deployment: ``` name: deploy-influxdb-resources on: push: branches: [ master ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 with: ref: ${{ github.ref }} - name: Deploys repo to cloud env: # These secrets can be configured in the Github repo to connect to # your InfluxDB instance. INFLUX_TOKEN: ${{ secrets.INFLUX_TOKEN }} INFLUX_ORG: ${{ secrets.INFLUX_ORG }} INFLUX_URL: ${{ secrets.INFLUX_URL }} GITHUB_REPO: ${{ github.repository }} GITHUB_BRANCH: ${{ github.ref }} run: | cd /tmp wget https://download.influxdata.com/platform/nightlies/influx_nightly_linux_amd64.tar.gz tar xvfz influx_nightly_linux_amd64.tar.gz sudo cp influx_nightly_linux_amd64/influx /usr/local/bin/ cd $GITHUB_WORKSPACE # This runs the script to set up your stacks chmod +x ./setup.sh ./setup.sh prod ``` For more information about using GitHub Actions in your project, check out the complete [Github Actions documentation](https://github.com/features/actions). ### Apply updates from source-controlled templates You can use a variety of InfluxDB templates from many different sources including[Community Templates](https://github.com/influxdata/community-templates/) or self-built custom templates. As templates are updated over time, stacks let you gracefully apply updates without creating duplicate resources. ### Apply template updates across multiple InfluxDB instances In many cases, you may have more than one instance of InfluxDB running and want to apply the same template to each separate instance. Using stacks, you can make changes to a stack on one instance,[export the stack as a template](/influxdb/v2/tools/influxdb-templates/create/#export-a-stack)and then apply the changes to your other InfluxDB instances. ### Develop templates InfluxDB stacks aid in developing and maintaining InfluxDB templates. Stacks let you modify and update template manifests and apply those changes in any stack that uses the template. #### Related * [influx stacks](/influxdb/v2/reference/cli/influx/stacks/) --- # Update an InfluxDB stack Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`influx apply` command](/influxdb/v2/reference/cli/influx/apply/)to update a stack with a modified template. When applying a template to an existing stack, InfluxDB checks to see if the resources in the template match existing resources. InfluxDB updates, adds, and removes resources to resolve differences between the current state of the stack and the newly applied template. Each stack is uniquely identified by a **stack ID**. For information about retrieving your stack ID, see [View stacks](/influxdb/v2/tools/influxdb-templates/stacks/view/). **Provide the following:** * Organization name or ID * Stack ID * InfluxDB template URLs to apply ```sh influx apply \ -o example-org \ -u http://example.com/template-1.yml \ -u http://example.com/template-2.yml \ --stack-id=12ab34cd56ef ``` Template resources are uniquely identified by their `metadata.name` field. If errors occur when applying changes to a stack, all applied changes are reversed and the stack is returned to its previous state. #### Related * [influx apply](/influxdb/v2/reference/cli/influx/apply/) * [influx stacks update](/influxdb/v2/reference/cli/influx/stacks/update/) --- # View InfluxDB stacks Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/stacks/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`influx stacks` command](/influxdb/v2/reference/cli/influx/stacks/)to view installed InfluxDB stacks and their associated resources. **Provide the following:** * Organization name or ID ```sh # Syntax influx stacks -o # Example influx stacks -o example-org ``` ### Filter stacks To output information about specific stacks, use the `--stack-name` or `--stack-id`flags to filter output by stack names or stack IDs. ##### Filter by stack name ```sh # Syntax influx stacks \ -o \ --stack-name= # Example influx stacks \ -o example-org \ --stack-name=stack1 \ --stack-name=stack2 ``` ### Filter by stack ID ```sh # Syntax influx stacks \ -o \ --stack-id= # Example influx stacks \ -o example-org \ --stack-id=12ab34cd56ef \ --stack-id=78gh910i11jk ``` #### Related * [influx stacks](/influxdb/v2/reference/cli/influx/stacks/) --- # Use InfluxDB templates Source: https://docs.influxdata.com/influxdb/v2/tools/influxdb-templates/use/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the `influx` command line interface (CLI) to summarize, validate, and apply templates from your local filesystem and from URLs. * [Use InfluxDB community templates](#use-influxdb-community-templates) * [View a template summary](#view-a-template-summary) * [Validate a template](#validate-a-template) * [Apply templates](#apply-templates) ## Use InfluxDB community templates The [InfluxDB community templates repository](https://github.com/influxdata/community-templates/)is home to a growing number of InfluxDB templates developed and maintained by others in the InfluxData community. Apply community templates directly from GitHub using a template’s download URL or download the template. > [!Note] > The community templates are under the following root URL: > > ``` > https://raw.githubusercontent.com/influxdata/community-templates/master/ > ``` > > For example, to access the Docker community template, use the following URL: > > ``` > https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml > ``` [View InfluxDB Community Templates](https://github.com/influxdata/community-templates/) ## View a template summary To view a summary of what’s included in a template before applying the template, use the [`influx template` command](/influxdb/v2/reference/cli/influx/template/). View a summary of a template stored in your local filesystem or from a URL. [From a file](#from-a-file)[From a URL](#from-a-url) ```text # Syntax influx template -f ``` ```bash # Example influx template -org ORG_NAME -f /path/to/templates/TEMPLATE_FILE.yml ``` ```text # Syntax influx template -org -u ``` ```bash # Example influx template -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml ``` ## Validate a template To validate a template before you install it or troubleshoot a template, use the [`influx template validate` command](/influxdb/v2/reference/cli/influx/template/validate/). Validate a template stored in your local filesystem or from a URL. [From a file](#from-a-file-2)[From a URL](#from-a-url-2) ```text # Syntax influx template validate -org -f ``` ```bash # Example influx template validate -org ORG_NAME -f /path/to/templates/TEMPLATE_FILE.yml ``` ```text # Syntax influx template validate -u ``` ```bash # Example influx template validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml ``` ## Apply templates Use the [`influx apply` command](/influxdb/v2/reference/cli/influx/apply/) to install templates from your local filesystem or from URLs. The default output is a summary of the template in “pretty” format and a prompt to confirm applying the changes. ```text # Syntax influx apply \ -o \ -f \ -u \ --secret== ``` * [Apply a template from a file](#apply-a-template-from-a-file) * [Apply all templates in a directory](#apply-all-templates-in-a-directory) * [Apply a template from a URL](#apply-a-template-from-a-url) * [Apply templates from both files and URLs](#apply-templates-from-both-files-and-urls) * [Define environment references](#define-environment-references) * [Include a secret when installing a template](#include-a-secret-when-installing-a-template) > [!Note] > #### Apply templates to an existing stack > > To apply a template to an existing stack, include the stack ID when applying the template. > Any time you apply a template without a stack ID, InfluxDB initializes a new stack > and all new resources. > For more information, see [InfluxDB stacks](/influxdb/v2/tools/influxdb-templates/stacks/). > > You can extract a stack ID from the output of `influx stacks` and pass it to `influx apply`: > > ``` > # Extract stack ID by name and apply a template to that stack > influx stacks | grep STACK_NAME | awk '{print $1}' | xargs -I{} influx apply -o ORG_NAME -f /path/to/TEMPLATE_FILE.yml --stack-id {} > ``` ### Apply a template from a file To install templates stored on your local machine, use the `-f` or `--file` flag to provide the **file path** of the template manifest. ```bash # Example # Apply multiple templates influx apply -o ORG_NAME \ -f /path/to/templates/TEMPLATE_FILE_1.yml \ -f /path/to/templates/TEMPLATE_FILE_2.yml ``` To skip the confirmation and apply the templates non-interactively, pass `--force yes`: ```bash # Download templates for tests curl https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml \ -so /path/to/templates/TEMPLATE_FILE_1.yml && curl https://raw.githubusercontent.com/influxdata/community-templates/master/github/github.yml \ -so /path/to/templates/TEMPLATE_FILE_2.yml && influx apply -o ORG_NAME \ -f /path/to/templates/TEMPLATE_FILE_1.yml \ -f /path/to/templates/TEMPLATE_FILE_2.yml \ --force yes ``` ### Apply all templates in a directory To apply all templates in a directory, use the `-f` or `--file` flag to provide the **directory path** of the directory where template manifests are stored. By default, this only applies templates stored in the specified directory. To apply all templates stored in the specified directory and its subdirectories, include the `-R`, `--recurse` flag. ```bash # Examples # Apply all templates in a directory influx apply -o ORG_NAME -f /path/to/templates/ # Apply all templates in a directory and its subdirectories influx apply -o ORG_NAME -f /path/to/templates/ --recurse ``` ### Apply a template from a URL To apply templates from a URL, use the `-u` or `--template-url` flag to provide the URL of the template manifest. ```bash # Example # Apply multiple templates from URLs influx apply -o ORG_NAME \ -u https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml \ -u https://raw.githubusercontent.com/influxdata/community-templates/master/github/github.yml ``` ### Apply templates from files and URLs To apply templates from files and URLs in a single command, include multiple file or directory paths and URLs, each with the appropriate `-f` or `-u` flag. ```bash # Example influx apply -o ORG_NAME \ -u https://raw.githubusercontent.com/influxdata/community-templates/master/raspberry-pi/raspberry-pi-system.yml \ -u https://raw.githubusercontent.com/influxdata/community-templates/master/minio/minio.yml \ -f /path/to/templates/TEMPLATE_FILE_1.yml \ -f /path/to/templates/TEMPLATE_FILE_2.yml \ --recurse ``` ### Define environment references Some templates include [environment references](/influxdb/v2/tools/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names. The `influx apply` command prompts you to provide a value for each environment reference in the template. You can also provide values for environment references by including an `--env-ref`flag with a key-value pair comprised of the environment reference key and the value to replace it. ```bash # Example influx apply -o ORG_NAME -f /path/to/templates/TEMPLATE_FILE.yml \ --env-ref=bucket-name-1=myBucket \ --env-ref=label-name-1=Label1 \ --env-ref=label-name-2=Label2 ``` ### Include a secret when installing a template Some templates use [secrets](/influxdb/v2/admin/secrets/) in queries. Secret values are not included in templates. To define secret values when installing a template, include the `--secret` flag with the secret key-value pair. ```bash # Examples # Define a single secret when applying a template influx apply -o ORG_NAME -f /path/to/templates/TEMPLATE_FILE.yml \ --secret=FOO=BAR # Define multiple secrets when applying a template influx apply -o ORG_NAME -f /path/to/templates/TEMPLATE_FILE.yml \ --secret=FOO=bar \ --secret=BAZ=quz ``` *To add a secret after applying a template, see [Add secrets](/influxdb/v2/admin/secrets/add/).* #### Related * [influx apply](/influxdb/v2/reference/cli/influx/apply/) * [influx template](/influxdb/v2/reference/cli/influx/template/) * [influx template validate](/influxdb/v2/reference/cli/influx/template/validate/) [templates](/influxdb/v2/tags/templates/) --- # Use the InfluxQL shell Source: https://docs.influxdata.com/influxdb/v2/tools/influxql-shell/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxQL interactive shell to execute InfluxQL queries with InfluxDB. * [Map database and retention policies to buckets](#map-database-and-retention-policies-to-buckets) * [Download and install the influx CLI](#download-and-install-the-influx-cli) * [Start the InfluxQL shell](#start-the-influxql-shell) * [Execute InfluxQL queries](#execute-influxql-queries) * [Use and configure display formats](#use-and-configure-display-formats) * [InfluxQL shell helper commands](#influxql-shell-helper-commands) ## Map database and retention policies to buckets InfluxQL queries require a database and retention policy to query data. In InfluxDB 2.10, databases and retention policies have been combined and replaced with [buckets](/influxdb/v2/reference/glossary/#bucket). To use the InfluxQL to query an InfluxDB 2.10 bucket, first map your DBRP combinations to an appropriate bucket. For information about creating DBRP mappings, see[Query data with InfluxQL](/influxdb/v2/query-data/influxql/). ## Download and install the influx CLI The InfluxQL REPL is included in the **`influx` CLI (2.4+)**.[Download and install the `influx` CLI](/influxdb/v2/tools/influx-cli/#install-the-influx-cli). ## Start the InfluxQL shell Use the [`influx v1 shell` command](/influxdb/v2/reference/cli/influx/v1/shell/)to start an InfluxQL shell session. ```sh influx v1 shell ``` ### Configure your InfluxDB connection The `influx v1 shell` command requires the following to connect to InfluxDB: * [InfluxDB host](/influxdb/v2/reference/urls/) * [Organization name or ID](/influxdb/v2/admin/organizations/view-orgs/) * [API token](/influxdb/v2/admin/tokens/) Use one of the following methods to provide these credentials to the `influx v1 shell` command: [CLI config *(Recommended)*](#)[Command flags](#command-flags)[Environment variables](#environment-variables) The `influx` CLI lets your configure and store multiple sets of connection credentials to use with commands. Each set of credentials is a **CLI config**. Use CLI configs to provide required credentials to the `influx v1 shell` command. 1. Create a new CLI config and set it to *active*. ``` influx config create --config-name \ --host-url http://localhost:8086 \ --org example-org \ --token mY5up3Rs3CrE7t0k3N \ --active ``` 2. Start an InfluxQL shell ``` influx v1 shell ``` All `influx` commands use credentials provided by the active CLI config. For more information about managing CLI configs, see the[`influx config` documentation](/influxdb/v2/reference/cli/influx/config/). Use `influx v1 shell` command flags to provide the required credentials: ```sh influx v1 shell \ --host http://localhost:8086 \ --org example-org \ --token mY5up3Rs3CrE7t0k3N ``` Use environment variables to provided the required credentials. The `influx` CLI will automatically use the following environment variables for required credentials if the environment variables are set: * `INFLUX_HOST` * `INFLUX_ORG` or `INFLUX_ORG_ID` * `INFLUX_TOKEN` ```sh export INFLUX_HOST=http://localhost:8086 export INFLUX_ORG=example-org export INFLUX_TOKEN=mY5up3Rs3CrE7t0k3N influx v1 shell ``` ## Execute InfluxQL queries Within the InfluxQL shell, execute any InfluxQL query supported by InfluxDB 2.10. For information about what queries are supported see[InfluxQL support in InfluxDB 2.10](/influxdb/v2/query-data/influxql/#influxql-support). View the [InfluxQL documentation (1.11)](/influxdb/v1/query_language/)for in-depth documentation about the query language. ## Use and configure display formats The InfluxQL shell outputs query results using different display formats. Use the [`format` helper command](#format) to specify which display format to use. [table *(default)*](#)[column](#column)[csv](#csv)[json](#json) The InfluxQL shell uses the `table` display format by default. If using another display format and you want to switch back to the `table` format, run the following *in the InfluxQL shell*. ```sql format table ``` ### Table-formatted results The table format outputs results in an interactive table format. InfluxQL shell table display format Results are paginated. Use `shift + up/down arrow` to navigate between pages. Use `q` to exit out of the interactive table display. ### Configure the table display format #### Use scientific notation To display values using scientific notation, use the [`scientific` helper command](#scientific)to toggle scientific notation. #### Specify timestamp precision or format To specify the precision or format of timestamps returned in results, use the[`precision` helper command](#precision). ```sql -- Return results formatted as RFC3339 timestamps precision rfc3339 -- Return results with second-precision unix timestamps precision s ``` To use the `column` format, run the following *in the InfluxQL shell*. ```sql format column ``` ### Column-formatted results The `column` format displays results in a text-based column format. ``` name: cpu time usage_user usage_system ---- ---------- ------------ 1.62767581e+09 5.476026754935672 2.5629805588360313 1.62767581e+09 0.4999999999972715 0.09999999999990905 1.62767581e+09 18.718718718689555 10.810810810692704 1.62767581e+09 6.500000000090222 3.2000000000343425 1.62767581e+09 4.1999999999336435 1.3999999999778812 1.62767581e+09 7.992007992122577 4.095904095946467 1.62767581e+09 0.3000000000054934 0.1000000000010732 ``` ### Configure the column display format #### Specify timestamp precision To specify the precision or format of timestamps returned in results, use the[`precision` helper command](#precision). ```sql -- Return results formatted as RFC3339 timestamps precision rfc3339 -- Return results with second-precision unix timestamps precision s ``` To use the `csv` format, run the following *in the InfluxQL shell*. ```sql format csv ``` ### CSV-formatted results The `csv` format displays results in CSV format. ```csv name,time,usage_user,usage_system cpu,1.62767582e+09,4.207038819798416,3.5194098893833914 cpu,1.62767582e+09,0.19980019980215585,0.19980019980215585 cpu,1.62767582e+09,14.914914914981258,14.114114114162232 cpu,1.62767582e+09,5.805805805828698,4.004004003985887 cpu,1.62767582e+09,2.5025025025339978,1.8018018018273916 cpu,1.62767582e+09,7.299999999874271,5.699999999930733 cpu,1.62767582e+09,0.09999999999647116,0.0999999999987449 ``` ### Configure the CSV display format #### Specify timestamp precision To specify the precision or format of timestamps returned in results, use the[`precision` helper command](#precision). ```sql -- Return results formatted as RFC3339 timestamps precision rfc3339 -- Return results with second-precision unix timestamps precision s ``` To use the `json` format, run the following *in the InfluxQL shell*. ```sql format json ``` ### JSON-formatted results The `csv` format displays results in JSON format. ```json { "results": [ { "series": [ { "columns": [ "time", "usage_user", "usage_system" ], "name": "cpu", "values": [ [ 1627675850, 4.601935685334947, 4.139868872973054 ], [ 1627675850, 0.3992015968099201, 0.2994011976074401 ], [ 1627675850, 7.599999999947613, 7.299999999995634 ], [ 1627675850, 0.3992015968098205, 0.4990019960088718 ], [ 1627675850, 9.59040959050348, 8.49150849158481 ], [ 1627675850, 0.2997002996974768, 0.39960039959966437 ], [ 1627675850, 9.590409590464631, 8.691308691326773 ] ] } ], "statement_id": 0 } ] } ``` [](#) ### Configure the JSON display format #### Pretty print JSON output By default, the `json` display format returns an unformatted JSON string. To format the JSON, use the [`pretty` helper command](#pretty) to toggle JSON pretty printing. #### Specify timestamp precision To specify the precision or format of timestamps returned in results, use the[`precision` helper command](#precision). ```sql -- Return results formatted as RFC3339 timestamps precision rfc3339 -- Return results with second-precision unix timestamps precision s ``` ## InfluxQL shell helper commands The InfluxQL shell supports the following helper commands: * [clear](#clear) * [exit](#exit) * [format](#format) * [gopher](#gopher) * [help](#help) * [history](#history) * [precision](#precision) * [pretty](#pretty) * [quit](#quit) * [scientific](#scientific) * [use](#use) ### clear Clear session based-settings such as database. ### exit Exit the InfluxQL shell. ### format Specify the data display format. The InfluxQL supports the following display formats: * csv * json * column * table *(default)* ```sql -- Display query output using column display format column ``` For more information, see [Use and configure display formats](#use-and-configure-display-formats). ### gopher Print the Go gopher. ### help Print the InfluxQL shell help options. ### history View the InfluxQL shell history. ### precision Specify the format or precision of timestamps. Use one of the following: * rfc3339 * h * m * s * ms * u * ns *(default)* ```sql -- Set timestamp precision to seconds precision s ``` ### pretty Toggle “pretty print” for the [`json` display format](#format). ### quit Exit the InfluxQL shell ### scientific Toggle scientific number format for the [`table` display format](#format). ### use Set the database and retention policy (optional) to use for queries. ```sql -- Use the exampledb database use exampledb -- Use the exampledb database and examplerp retention policy use exampledb.examplerp ``` #### Related * [influx v1 shell](/influxdb/v2/reference/cli/influx/v1/shell/) [InfluxQL](/influxdb/v2/tags/influxql/) --- # Use Kapacitor with InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/tools/kapacitor/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Kapacitor](/kapacitor/v1/) is a data processing framework that makes it easy to create alerts, run ETL jobs and detect anomalies. Kapacitor interacts with **InfluxDB Cloud** and **InfluxDB OSS 2.10** using the[InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/), so you can continue using Kapacitor without having to migrate libraries of TICKscripts to InfluxDB tasks. > [!Note] > #### Support for stream tasks > > InfluxDB Cloud and InfluxDB OSS 2.10 do not have subscription APIs and**do not support Kapacitor stream tasks**, but you can continue to use stream > tasks by writing data directly to Kapacitor. > For more information, see [below](#use-kapacitor-stream-tasks). #### On this page * [Configure Kapacitor to connect to InfluxDB](#configure-kapacitor-to-connect-to-influxdb) * [Use Kapacitor batch tasks](#use-kapacitor-batch-tasks) * [Use Kapacitor stream tasks](#use-kapacitor-stream-tasks) * [Write back to InfluxDB](#write-back-to-influxdb) ## Configure Kapacitor to connect to InfluxDB To connect Kapacitor to InfluxDB Cloud or InfluxDB OSS 2.10, update the `[[influxdb]]`section(s) of your [Kapacitor configuration file](/kapacitor/v1/administration/configuration/#kapacitor-configuration-file): * [Specify your InfluxDB URL](#specify-your-influxdb-url) * [Provide InfluxDB authentication credentials](#provide-influxdb-authentication-credentials) * [Disable InfluxDB subscriptions](#disable-influxdb-subscriptions) ### Specify your InfluxDB URL Provide your InfluxDB URL in the `[[influxdb]].urls` configuration option. For more information, see [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/)or [InfluxDB OSS URLs](/influxdb/v2/reference/urls/). ```toml [[influxdb]] # ... urls = ["http://localhost:8086"] ``` ### Provide InfluxDB authentication credentials InfluxDB Cloud and InfluxDB OSS 2.10 require authentication. Provide the following credentials in your `[[influxdb]].username` and `[[influxdb]].password`configuration options: * **username:** InfluxDB username * **password:** InfluxDB [API token](/influxdb/v2/admin/tokens/) ```toml [[influxdb]] # ... username = "influxdb-username" password = "influxdb-token" ``` Kapacitor is subject to InfluxDB token permission restrictions. To query or write to an InfluxDB bucket, the InfluxDB token must have read and/or write permissions for the target bucket. For information about token permissions, see [Create a token](/influxdb/v2/admin/tokens/create-token/). ### Disable InfluxDB subscriptions InfluxDB Cloud and InfluxDB OSS 2.10 do not have subscriptions APIs. Set the `[[influxdb]].disable-subscriptions`to `true` to disable InfluxDB subscriptions. ```toml [[influxdb]] # ... disable-subscriptions = true ``` ## Use Kapacitor batch tasks Kapacitor batch tasks use the `query` endpoint of the 1.x compatibility API and require no change to use with InfluxDB Cloud and InfluxDB OSS. For information about writing back to InfluxDB in Kapacitor tasks, see [Write back to InfluxDB](#write-back-to-influxdb) below. ## Use Kapacitor stream tasks InfluxDB Cloud and OSS 2.10 do not have subscription APIs and do not support Kapacitor stream tasks directly. To use Kapacitor stream tasks, write data directly to Kapacitor using the [Kapacitor `write` API](/kapacitor/v1/working/api/#writing-data). We recommend using the [Telegraf InfluxDB output plugin](/telegraf/v1/plugins/#output-influxdb) to write data to both InfluxDB Cloud or OSS and Kapacitor. ##### Write data using the Telegraf InfluxDB output plugin To write data to both InfluxDB and Kapacitor using the InfluxDB output plugin, complete the following steps: 1. [Install Telegraf](/telegraf/v1/install/). 2. [Create a DBRP mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings). 3. In the [Telegraf InfluxDB output plugin](/telegraf/v1/plugins/#output-influxdb) configuration file, specify the following options, replacing `database`, `retention_policy`, `username` and `password` to match your DBRP mapping, and set `skip_database_creation` to `true`: ```toml # Write to Kapacitor [[outputs.influxdb]] urls = ["http://localhost:9092"] database = "example-db" retention_policy = "example-rp" # Write to InfluxDB Cloud or OSS [[outputs.influxdb]] urls = ["http://localhost:8086"] database = "example-db" retention_policy = "example-rp" username = "influxdb-username" password = "influxdb-token" skip_database_creation = true ``` ## Write back to InfluxDB If using the Kapacitor `InfluxDBOut` node to write data to InfluxDB 2.10, InfluxDB maps the specified database and retention policy to a corresponding bucket. You can also manually map database/retention policy combinations (DBRPs) to buckets. For more information, see [DBRP mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/). The following example TICKscript writes to the `my-db/my-rp` bucket in InfluxDB Cloud or InfluxDB OSS 2.10. ```js batch |query('SELECT errors / total AS error_percent from requests') // Write the transformed data to InfluxDB |influxDBOut() .database('my-db') .retentionPolicy('my-rp') .measurement('errors') .tag('kapacitor', 'true') .tag('version', '0.2') ``` #### Related * [Kapacitor documentation](/kapacitor/v1/) --- # Use the InfluxDB documentation MCP server Source: https://docs.influxdata.com/influxdb/v2/tools/mcp-server/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **InfluxDB documentation MCP server** lets AI tools and agents search InfluxDB 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 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](#claude-desktop)[ChatGPT Desktop](#chatgpt-desktop)[GitHub Copilot (VS Code)](#github-copilot-vs-code)[Cursor](#cursor)[OpenCode](#opencode) 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?” > > [MCP](/influxdb/v2/tags/mcp/)[LLM](/influxdb/v2/tags/llm/)[AI](/influxdb/v2/tags/ai/) --- # Notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Notebooks are a way to build and annotate processes and data flows for time series data. Notebooks include cells and controls to transform the data in your bucket and other countless possibilities. To learn how to use notebooks, check out the following articles: ### [Overview of notebooks](/influxdb/v2/tools/notebooks/overview/) Learn about the building blocks of a notebook. ### [Create a notebook](/influxdb/v2/tools/notebooks/create-notebook/) Create a notebook to explore, visualize, and process your data. ### [Manage notebooks](/influxdb/v2/tools/notebooks/manage-notebooks/) View, update, and delete notebooks. ### [Downsample data with notebooks](/influxdb/v2/tools/notebooks/downsample/) Create a notebook to downsample data. Downsampling aggregates or summarizes data within specified time intervals, reducing the overall disk usage as data collects over time. ### [Normalize data with notebooks](/influxdb/v2/tools/notebooks/clean-data/) Learn how to create a notebook that normalizes or cleans data to make it easier to work with. ### [Troubleshoot notebooks](/influxdb/v2/tools/notebooks/troubleshoot-notebooks/) Common issues with the notebooks feature. [notebooks](/influxdb/v2/tags/notebooks/) --- # Normalize data with notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/clean-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Learn how to create a notebook that normalizes data. Data normalization is the process of modifying or cleaning data to make it easier to work with. Examples include adjusting numeric values to a uniform scale and modifying strings. Walk through the following example to create a notebook that queries[NOAA NDBC sample data](/influxdb/v2/reference/sample-data/#noaa-ndbc-data), normalizes degree-based wind directions to cardinal directions, and then writes the normalized data to a bucket. 1. [Create a new notebook](/influxdb/v2/tools/notebooks/create-notebook/). 2. In the **Build a Query** cell: 1. In the **FROM** column under **Sample**, select **NOAA National Buoy Data**. 2. In the next **FILTER** column, select **\_measurement** from the drop-down list and select the **ndbc** measurement in the list of measurements. 3. In the next **FILTER** column, select **\_field** from the drop-down list, and select the **wind\_dir\_degt** field from the list of fields. 3. Click after your **Build a Query** cell to add a new cell and select **Flux Script**. 4. In the Flux script cell: 1. Define a custom function (`cardinalDir()`) that converts a numeric degree value to a cardinal direction (N, NNE, NE, etc.). 2. Use `__PREVIOUS_RESULT__` to load the output of the previous notebook cell into the Flux script. 3. Use [`map()`](/flux/v0/stdlib/universe/map/) to iterate over each input row, update the field key to `wind_dir_cardinal`, and normalize the `_value` column to a cardinal direction using the custom`cardinalDir()` function. 4. Use [`to()`](/flux/v0/stdlib/influxdata/influxdb/to/)to write the normalized data back to InfluxDB. Specify an existing bucket to write to or[create a new bucket](/influxdb/v2/admin/buckets/create-bucket/). ``` import "array" cardinalDir = (d) => { _cardinal = if d >= 348.7 or d < 11.25 then "N" else if d >= 11.25 and d < 33.75 then "NNE" else if d >= 33.75 and d < 56.25 then "NE" else if d >= 56.25 and d < 78.75 then "ENE" else if d >= 78.75 and d < 101.25 then "E" else if d >= 101.25 and d < 123.75 then "ESE" else if d >= 123.75 and d < 146.25 then "SE" else if d >= 146.25 and d < 168.75 then "SSE" else if d >= 168.75 and d < 191.25 then "S" else if d >= 191.25 and d < 213.75 then "SSW" else if d >= 213.75 and d < 236.25 then "SW" else if d >= 236.25 and d < 258.75 then "WSW" else if d >= 258.75 and d < 281.25 then "W" else if d >= 281.25 and d < 303.75 then "WNW" else if d >= 303.75 and d < 326.25 then "NW" else if d >= 326.25 and d < 348.75 then "NNW" else "" return _cardinal } __PREVIOUS_RESULT__ |> map(fn: (r) => ({r with _field: "wind_dir_cardinal", _value: cardinalDir(d: r._value), })) |> to(bucket: "example-bucket") ``` 5. Click after your **Flux Script** cell to add a new cell and select **Output to Bucket**. Select a bucket from the **Choose a bucket**drop-down list. 6. *(Optional)* Click and select **Note** to add a cell containing notes about what this notebook does. For example, the cell might say, “This notebook converts decimal degree wind direction values to cardinal directions.” 7. Click **Preview** in the upper left to verify that your notebook runs and previews the output. 8. Click **Run** to run the notebook and write the normalized data to your bucket. ## Continuously run a notebook To continuously run your notebook, export the notebook as a task: 1. Click to add a new cell and then select**Task**. 2. Provide the following: * **Every**: Interval that the task should run at. * **Offset**: *(Optional)* Time to wait after the defined interval to execute the task. This allows the task to capture late-arriving data. 3. Click **Export as Task**. [notebooks](/influxdb/v2/tags/notebooks/) --- # Create a notebook Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/create-notebook/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create a notebook to explore, visualize, and process your data. Learn how to add and configure cells to customize your notebook. To learn the benefits and concepts of notebooks, see[Overview of Notebooks](/influxdb/v2/tools/notebooks/overview/). * [Create a notebook from a preset](#create-a-notebook-from-a-preset) * [Use data source cells](#use-data-source-cells) * [Use visualization cells](#use-visualization-cells) * [Add a data source cell](#add-a-data-source-cell) * [Add a validation cell](#add-a-validation-cell) * [Add a visualization cell](#add-a-visualization-cell) ## Create a notebook from a preset To create a new notebook, do the following: 1. In the navigation menu on the left, click **Notebooks**. Notebooks 2. In the **Notebooks** page, select one of the following options under **Create a Notebook**: * **New Notebook**: includes a [query builder cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), and a [visualization cell](#add-a-visualization-cell). * **Set an Alert**: includes a [query builder cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), a [visualization cell](#add-a-visualization-cell), and an [alert builder cell](#add-an-action-cell). * **Schedule a Task**: includes a [Flux Script editor cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), and a [task schedule cell](#add-an-action-cell). * **Write a Flux Script**: includes a [Flux script editor cell](#add-a-data-source-cell), and a [validation cell](#add-a-validation-cell). 3. Enter a name for your notebook in the **Untitled Notebook** field. 4. Do the following at the top of the page: * Select your local time zone or UTC. * Choose a time [range](/flux/v0/stdlib/universe/range/) for your data. 5. Your notebook should have a **Data Source** cell as the first cell. **Data Source** cells provide data to subsequent cells. The presets (listed in step 2) include either a **Query Builder** or a **Flux Script** as the first cell. 6. To define your data source query, do one of the following: * If your notebook uses a **Query Builder** cell, select your bucket and any additional filters for your query. * If your notebook uses a **Flux Script** cell, enter or paste a [Flux script](/influxdb/v2/query-data/flux/). 7. Select and click **Preview** (or press **CTRL + Enter**) under the notebook title. InfluxDB displays query results in **Validate the Data** and **Visualize the Result** *without writing data or running actions*. 8. (Optional) Change your visualization settings with the drop-down menu and the **Configure** button at the top of the **Visualize the Result** cell. 9. (Optional) Toggle the **Presentation** switch to display visualization cells and hide all other cells. 10. (Optional) Configure notebook actions (**Alert**, **Task**, or **Output to Bucket**) . 11. (Optional) To run your notebook actions, select and click **Run** under the notebook title. 12. (Optional) To add a new cell, follow the steps for one of the cell types: ``` - [Add a data source cell](#add-a-data-source-cell) - [Add a validation cell](#add-a-validation-cell) - [Add a visualization cell](#add-a-visualization-cell) - [Add an action cell](#add-an-action-cell) ``` 1. (Optional) [Convert a query builder cell into raw Flux script](#convert-a-query-builder-to-flux) to view and edit the code. ## Use Data Source cells ### Convert a Query Builder to Flux To edit the raw Flux script of a **Query Builder** cell, convert the cell to Flux. You can’t convert a **Flux Script** editor cell to a **Query Builder** cell. Once you convert a **Query Builder** cell to a **Flux Script** editor cell, you can’t convert it back. 1. Click the icon in the **Query Builder** cell you want to edit as Flux, and then select **Convert to |\> Flux**. You won’t be able to undo this step. A **Flux Script** editor cell containing the raw Flux script replaces the **Query Builder** cell. 2. View and edit the Flux script as needed. ## Use visualization cells * To change your [visualization type](/influxdb/v2/visualize-data/visualization-types/), select a new type from the drop-down list at the top of the cell. * (For histogram only) To specify values, click **Select**. * To configure the visualization, click **Configure**. * To download results as an annotated CSV file, click the **CSV** button. * To export to the dashboard, click **Export to Dashboard**. ## Add a data source cell Add a [data source cell](/influxdb/v2/tools/notebooks/overview/#data-source) to pull information into your notebook. To add a data source cell, do the following: 1. Click . 2. Select **Flux Script** or **Query Builder** as your input, and then select or enter the bucket to pull data from. 3. Select filters to narrow your data. 4. Select **Preview** (**CTRL + Enter**) or**Run** in the upper left drop-down list. ## Add a validation cell A validation cell uses the **Table** [visualization type](/influxdb/v2/visualize-data/visualization-types/) to display query results from a data source cell. To add a **Table** visualization cell, do the following: 1. Click . 2. Under **Visualization**, click **Table**. ## Add a visualization cell Add a visualization cell to render query results as a [Visualization type](/influxdb/v2/visualize-data/visualization-types/). To add a Table visualization cell, do the following: 1. Click . 2. Under **Visualization**, select one of the following visualization cell-types: * **Table**: Display data in tabular format. * **Graph**: Visualize data using InfluxDB visualizations. * **Note**: Use Markdown to add notes or other information to your notebook. To modify a visualization cell, see [use visualization cells](#use-visualization-cells). For detail on available visualization types and how to use them, see [Visualization types](/influxdb/v2/visualize-data/visualization-types/). ## Add an action cell Add an [action cell](/influxdb/v2/tools/notebooks/overview/#action) to create an [alert](/influxdb/v2/monitor-alert/) , process data with a [task](/influxdb/v2/process-data/manage-tasks/), or output data to a bucket . If your cell contains a custom script that uses any output function to write data to InfluxDB (for example: the `to()` function) or sends data to a third-party service, clicking Preview will write data. * [Add an Alert cell](#add-an-alert-cell) * [Add an Output to Bucket cell](#add-an-output-to-bucket-cell) * [Add a Task cell](#add-a-task-cell) ### Add an Alert cell To add an [alert](/influxdb/v2/monitor-alert/) to your notebook, do the following: 1. Enter a time range to automatically check the data and enter your query offset. 2. Customize the conditions to send an alert. 3. Select an endpoint to receive an alert: * Slack and a Slack Channel * HTTP post * PagerDuty 4. (Optional) Personalize your message. By default, the message is: ``` ${strings.title(v: r._type)} for ${r._source_measurement} triggered at ${time(v: r._source_timestamp)}! ``` 5. Click **Test Alert** to send a test message to your configured **Endpoint**. The test will not schedule the new alert. 6. Click **Export Alert Task** to create your alert. ### Add an Output to Bucket cell To write **Data Source** results to a bucket, do the following: 1. Click . 2. Click **Output to Bucket**. 3. In the **Choose a bucket** drop-down list, select or create a bucket. 4. Click **Preview** to view the query result in validation cells. 5. Select and click **Run** in the upper left to write the query result to the bucket. ### Add a Task cell To add a [task](/influxdb/v2/process-data/manage-tasks/) to your notebook, do the following: 1. Click . 2. Click **Task**. 3. Enter a time and an offset to schedule the task. 4. Click **Export as Task** to save. [notebooks](/influxdb/v2/tags/notebooks/) --- # Downsample data with notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/downsample/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create a notebook to downsample data. Downsampling aggregates or summarizes data within specified time intervals, reducing the overall disk usage as data collects over time. The following example creates a notebook that queries **Coinbase bitcoin price sample data** from the last hour, downsamples the data into ten minute summaries, and then writes the downsampled data to an InfluxDB bucket. 1. If you do not have an existing bucket to write the downsampled data to,[create a new bucket](/influxdb/v2/admin/buckets/create-bucket/). 2. [Create a new notebook](/influxdb/v2/tools/notebooks/create-notebook/). 3. Select **Past 1h** from the time range drop-down list at the top of your notebook. 4. In the **Build a Query** cell: 1. In the **FROM** column under **Sample**, select **Coinbase bitcoin price**. 2. In the next **FILTER** column, select **\_measurement** from the drop-down list and select the **coindesk** measurement in the list of measurements. 3. In the next **FILTER** column, select **\_field** from the drop-down list, and select the **price** field from the list of fields. 4. In the next **FILTER** column, select **code** from the drop-down list, and select a currency code. 5. Click after your **Build a Query** cell to add a new cell and select **Flux Script**. 6. In the Flux script cell: 1. Use `__PREVIOUS_RESULT__` to load the output of the previous notebook cell into the Flux script. 2. Use [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/)to window data into ten minute intervals and return the average of each interval. Specify the following parameters: * **every**: Window interval *(should be less than or equal to the duration of the queried time range)*. For this example, use `10m`. * **fn**: [Aggregate](/flux/v0/function-types/#aggregates)or [selector](/flux/v0/function-types/#selectors) function to apply to each window. For this example, use `mean`. ``` __PREVIOUS_RESULT__ |> aggregateWindow(every: 10m, fn: mean) |> to(bucket: "example-bucket") ``` 7. Click after your**Flux Script** cell to add a new cell and select**Output to Bucket**. Select a bucket from the **Choose a bucket**drop-down list. 8. *(Optional)* Click and select **Note** to add a note to describe your notebook, for example, “Downsample Coinbase bitcoin prices into hourly averages.” 9. Click **Preview** in the upper left to verify that your notebook runs and displays the output. 10. Click **Run** to run the notebook and write the downsampled data to your bucket. ## Continuously run a notebook To continuously run your notebook, export the notebook as a task: 1. Click to add a new cell, and then select**Task**. 2. Provide the following: * **Every**: Interval that the task should run at. * **Offset**: *(Optional)* Time to wait after the defined interval to execute the task. This allows the task to capture late-arriving data. 3. Click **Export as Task**. [notebooks](/influxdb/v2/tags/notebooks/) --- # Manage notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/manage-notebooks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Manage your notebooks in the UI: * [View or update a notebook](#view-or-update-notebooks) * [Delete a notebook](#delete-a-notebook) ## View or update notebooks 1. In the navigation menu on the left, click **Notebooks**. Notebooks A list of notebooks appears. 2. Click a notebook to open it. 3. To update, edit the notebook’s cells and content. Changes are saved automatically. ## Delete a notebook 1. In the navigation menu on the left, click **Notebooks**. Notebooks 2. Hover over a notebook in the list that appears. 3. Click **Delete Notebook**. 4. Click **Confirm**. [notebooks](/influxdb/v2/tags/notebooks/) --- # Overview of notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/overview/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Learn how notebooks can help to streamline and simplify your day-to-day business processes. See an overview of [notebook concepts](/influxdb/v2/tools/notebooks/overview/#notebook-concepts), [notebook controls](/influxdb/v2/tools/notebooks/overview/#notebook-controls), and [notebook cell types](/influxdb/v2/tools/notebooks/overview/#notebook-cell-types) also know as the basic building blocks of a notebook. ## Notebook concepts You can think of an InfluxDB notebook as a collection of sequential data processing steps. Each step is represented by a “cell” that performs an action such as querying, visualizing, processing, or writing data to your buckets. Notebooks help you do the following: * Create snippets of live code, equations, visualizations, and explanatory notes. * Create alerts or scheduled tasks. * Downsample and normalize data. * Build runbooks to share with your teams. * Output data to buckets. ## Notebook controls The following options appear at the top of each notebook. ### Preview/Run mode * Select **Preview** (or press **Control+Enter**) to display results of each cell without writing data. Helps to verify that cells return expected results before writing data. ### Save Notebook (appears before first save) Select Save Notebook to save all notebook cells. Once you’ve saved the notebook, this button disappears and the notebook automatically saves as subsequent changes are made. > [!Note] > Saving the notebook does not save cell results. When you open a saved notebook, click **Run** to update cell results. ### Local or UTC timezone Click the timezone drop-down list to select a timezone to use for the notebook. Select either the local time (default) or UTC. ### Time range Select from the options in the dropdown list or select **Custom Time Range** to enter a custom time range with precision up to nanoseconds, and then click **Apply Time Range**. ## Notebook cell types The following cell types are available for your notebook: * [Data source](#data-source) * [Visualization](#visualization) * [Action](#action) ### Data source At least one data source (input) cell is required in a notebook for other cells to run. * **Query Builder**: Build a query with the Flux query builder. * **Flux Script**: Enter a raw Flux script. Data source cells work like the **Query Builder** or **Script Editor** in Data Explorer. For more information, see how to [query data with Flux and the Data Explorer](/influxdb/v2/query-data/execute-queries/data-explorer/#query-data-with-flux-and-the-data-explorer). ### Visualization * **Table**: View your data in a table. * **Graph**: View your data in a graph. * **Note**: Create explanatory notes or other information for yourself or your team members. ### Action * **Alert**: Set up alerts. See how to [monitor data and send alerts](/influxdb/v2/monitor-alert/). * **Tasks**: Use the notebook to set up and export a task. See how to [manage tasks in InfluxDB](/influxdb/v2/process-data/manage-tasks/). [notebooks](/influxdb/v2/tags/notebooks/) --- # Troubleshoot notebooks Source: https://docs.influxdata.com/influxdb/v2/tools/notebooks/troubleshoot-notebooks/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ### No measurements appear in my bucket even though there’s data in it. Try changing the time range. You might have measurements prior to the time range you selected. For example, if the selected time range is `Past 1h` and the last write happened 16 hours ago, you’d need to change the time range to `Past 24h` (or more) to see your data. [notebooks](/influxdb/v2/tags/notebooks/) --- # Use Postman with the InfluxDB API Source: https://docs.influxdata.com/influxdb/v2/tools/postman/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, to interact with the [InfluxDB API](/influxdb/v2/api-guide/). ## Install Postman Download Postman from the [official downloads page](https://www.postman.com/downloads/). Or to install with Homebrew on macOS, run the following command: ```sh brew install --cask postman ``` ## Send authenticated API requests with Postman All requests to the [InfluxDB v2 API](/influxdb/v2/api-guide/) must include an [InfluxDB API token](/influxdb/v2/admin/tokens/). > [!Note] > #### Authenticate with a username and password > > If you need to send a username and password (`Authorization: Basic`) to the [InfluxDB 1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/), see how to [authenticate with a username and password scheme](/influxdb/v2/reference/api/influxdb-1x/#authenticate-with-the-token-scheme). To configure Postman to send an [InfluxDB API token](/influxdb/v2/admin/tokens/) with the `Authorization: Token` HTTP header, do the following: 1. If you have not already, [create a token](/influxdb/v2/admin/tokens/create-token/). 2. In the Postman **Authorization** tab, select **API Key** in the **Type** dropdown. 3. For **Key**, enter `Authorization`. 4. For **Value**, enter `Token INFLUX_API_TOKEN`, replacing *`INFLUX_API_TOKEN`* with the token generated in step 1. 5. Ensure that the **Add to** option is set to **Header**. #### Test authentication credentials To test the authentication, in Postman, enter your InfluxDB API `/api/v2/` root endpoint URL and click **Send**. ###### InfluxDB v2 API root endpoint ```sh http://localhost:8086/api/v2 ``` [api](/influxdb/v2/tags/api/)[authentication](/influxdb/v2/tags/authentication/) --- # Telegraf configurations Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB lets you automatically generate Telegraf configurations or upload custom Telegraf configurations that collect metrics and write them to InfluxDB. Telegraf retrieves configurations from InfluxDB on startup. ## Use InfluxDB Telegraf configurations With a Telegraf configuration stored in InfluxDB, the `telegraf` agent can retrieve the configuration from an InfluxDB HTTP(S) endpoint. * Ensure Telegraf has network access to InfluxDB (OSS or Cloud). * Start the `telegraf` agent using the `--config` flag to provide the URL of the InfluxDB Telegraf configuration. For example: ``` telegraf --config http://localhost:8086/api/v2/telegrafs/ ``` > [!Note] > *[Setup instructions](/influxdb/v2/tools/telegraf-configs/view/#view-setup-instructions) for > each Telegraf configuration are provided in the InfluxDB UI.* ## Manage Telegraf configurations ### [Clone a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/clone/) Use the InfluxDB UI to clone an Telegraf configuration. ### [Create a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/create/) Use the InfluxDB UI or the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to create an Telegraf configuration. ### [View Telegraf configurations](/influxdb/v2/tools/telegraf-configs/view/) Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to view and download InfluxDB Telegraf configurations. ### [Update a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/update/) Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to update InfluxDB Telegraf configurations. ### [Remove a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/remove/) Use the InfluxDB UI or the [`influx` CLI](/influxdb/v2/reference/cli/influx/) to remove Telegraf configurations from InfluxDB. #### Related * [Manually configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/manual-config/) * [Automatically configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/) [telegraf](/influxdb/v2/tags/telegraf/) --- # Clone a Telegraf configuration Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/clone/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) to clone a Telegraf configuration. 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 2. Hover over the configuration you want to clone, click the icon, and then click **Clone**. The clone appears in your list of Telegraf configurations. --- # Create a Telegraf configuration Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/create/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Telegraf has an extensive list of plugins for many different technologies and use cases. Not all plugins are available through the InfluxDB UI, but you can[create and upload custom Telegraf configurations](#create-a-custom-telegraf-configuration)to include any of the available [Telegraf plugins](/telegraf/v1/plugins/). Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/)to create a Telegraf configuration. To create a Telegraf configuration, do one of the following: * [Use the InfluxDB UI](#use-the-influxdb-ui) * [Use the `influx` CLI](#use-the-influx-cli) * [Create a custom Telegraf configuration](#create-a-custom-telegraf-configuration) ## Use the InfluxDB UI Use the InfluxDB UI to automatically generate and store new Telegraf configurations in InfluxDB. Creating the configuration in the UI lets you select from a list of available technologies and generates a Telegraf configuration to collect metrics from those technologies. For more information, see [Automatically configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/). ## Use the influx CLI Use the [`influx telegrafs create` command](/influxdb/v2/reference/cli/influx/telegrafs/create/)to upload a Telegraf configuration file from your local machine and create a new Telegraf configuration in InfluxDB. Provide the following: * **Telegraf configuration name** * **Telegraf configuration description** * **Telegraf configuration file** > [!Note] > If a **name** and **description** are not provided, they are set to empty strings. ```sh # Syntax influx telegrafs create \ -n \ -d \ -f /path/to/telegraf.conf # Example influx telegrafs create \ -n "Example Telegraf config" -d "This is a description for an example Telegraf configuration." -f /path/to/telegraf.conf ``` ## Create a custom Telegraf configuration 1. Create a custom Telegraf configuration file that includes the `outputs.influxdb_v2`output plugin. *See [Manually configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/manual-config/)*for more information. 2. Add and customize [Telegraf plugins](/telegraf/v1/plugins/) and save your changes. 3. [Use the `influx telegrafs create` command](#use-the-influx-cli) to upload your custom Telegraf configuration to InfluxDB. #### Related * [Manually configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/manual-config/) * [Automatically configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/) * [Update a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/update/) --- # Remove a Telegraf configuration Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/remove/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/)to remove Telegraf configurations from InfluxDB. > [!Note] > Deleting a Telegraf configuration does not affect ***running*** Telegraf agents. > However, if an agents stops, it needs a new configuration to start. To remove a Telegraf configuration, do one of the following: * [Use the InfluxDB UI](#use-the-influxdb-ui) * [Use the `influx` CLI](#use-the-influx-cli) ## Use the InfluxDB UI 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 2. Hover over the configuration you want to delete, click the icon, and then click **Delete**. ## Use the influx CLI Use the [`influx telegrafs rm` command](/influxdb/v2/reference/cli/influx/telegrafs/rm/)to remove a Telegraf configuration from InfluxDB. Provide the following: * **Telegraf configuration ID** (shown in the output of `influx telegrafs`) ```sh # Syntax influx telegrafs rm -i # Example influx telegrafs rm -i 12ab34de56fg78hi ``` --- # Update a Telegraf configuration Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/update/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/)to update InfluxDB Telegraf configurations. To update a Telegraf configuration, do one of the following: * [Use the InfluxDB UI](#use-the-influxdb-ui) * [Use the `influx` CLI](#use-the-influx-cli) > [!Note] > Telegraf doesn’t detect changes to remote configurations. If you edit a remote configuration, you must restart Telegraf or send it a SIGHUP command for your changes to take effect. ## Use the InfluxDB UI ### Update the name or description of a configuration 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 2. Hover over the configuration you want to edit and click to update the name or description. 3. Press **Return** or click out of the editable field to save your changes. ### Edit the configuration file directly in the UI 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 2. To edit the configuration file: a. Click the name of the configuration. b. Add or update [Telegraf plugin settings](/telegraf/v1/plugins/) in the window that appears. > [!Note] > The text editor window doesn’t detect if any plugins or settings are misconfigured. Any errors in your configuration that may cause Telegraf to fail when you restart it. c. Click **Save Changes** and then **Save** again to confirm. 3. To apply the updated configuration, restart Telegraf. To find the exact command to start Telegraf, click **Setup Instructions** on the **Telegraf** page. ### Download and verify the configuration file 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 2. Click the **name** of the Telegraf configuration to customize. 3. Click **Download Config** to download the Telegraf configuration file to your local machine. 4. Review the configuration file. Add or update [Telegraf plugin](/telegraf/v1/plugins/) settings and save your changes. 5. [Use the `influx telegrafs update` command](#use-the-influx-cli) to upload your modified Telegraf configuration to InfluxDB and replace the existing configuration. 6. To apply the updated configuration, restart Telegraf. To find the exact command to start Telegraf, click **Setup Instructions** on the **Telegraf** page. ## Use the influx CLI Use the [`influx telegrafs update` command](/influxdb/v2/reference/cli/influx/telegrafs/update/)to update an existing InfluxDB Telegraf configuration name, description, or settings from a Telegraf configuration file on your local machine. Provide the following: * **Telegraf configuration ID** (shown in the output of `influx telegrafs`) * **Telegraf configuration name** * **Telegraf configuration description** * **Telegraf configuration file** If a **name** and **description** are not provided, they are replaced with empty strings. ```sh # Syntax influx telegrafs update \ -i \ -n \ -d \ -f /path/to/telegraf.conf # Example influx telegrafs update \ -i 12ab34de56fg78hi -n "Example Telegraf config" -d "This is a description for an example Telegraf configuration." -f /path/to/telegraf.conf ``` --- # View Telegraf configurations Source: https://docs.influxdata.com/influxdb/v2/tools/telegraf-configs/view/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2/reference/cli/influx/)to view and download InfluxDB Telegraf configurations. To view Telegraf configurations, do one of the following: * [Use the InfluxDB UI](#use-the-influxdb-ui) * [Use the `influx` CLI](#use-the-influx-cli) ## Use the InfluxDB UI In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data ### View and download the telegraf.conf To view the `telegraf.conf` associated with the configuration, click the **Name** of the configuration. Then click **Download Config** to download the file. ### View setup instructions To view the setup instructions for a Telegraf configuration, click **Setup Instructions**. Setup instructions include commands for adding your InfluxDB API token as an environment variable and starting Telegraf with the specific configuration. ## Use the influx CLI Use the [`influx telegrafs` command](/influxdb/v2/reference/cli/influx/telegrafs/) to list Telegraf configurations stored in InfluxDB. ```sh influx telegrafs ``` --- # Visualize data with the InfluxDB UI Source: https://docs.influxdata.com/influxdb/v2/visualize-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB user interface (UI) provides tools for building custom dashboards to visualize your data. The following articles outline ways to customize and manage dashboards. > [!Note] > The InfluxDB UI is packaged with InfluxDB and runs as part of the InfluxDB server. > To access the UI, start the [`influxd` service](/influxdb/v2/reference/cli/influxd/)and visit [http://localhost:8086](http://localhost:8086) in your web browser. ### [Manage InfluxDB dashboards](/influxdb/v2/visualize-data/dashboards/) Create, edit, and manage custom dashboards in the InfluxDB user interface (UI). ### [Use and manage variables](/influxdb/v2/visualize-data/variables/) Dashboard variables allow you to alter specific components of cells’ queries without having to edit the queries, making it easy to interact with your dashboard cells and explore your data. ### [Manage labels in the InfluxDB UI](/influxdb/v2/visualize-data/labels/) Labels are a way to add visual metadata to dashboards, tasks, and other items in the InfluxDB UI. View and manage labels in the InfluxDB user interface. ### [Use annotations in dashboards](/influxdb/v2/visualize-data/annotations/) Add annotations to your InfluxDB dashboards to provide useful, contextual information about single points in time. ### [Visualization types](/influxdb/v2/visualize-data/visualization-types/) The InfluxDB UI provides multiple visualization types to visualize your data in a format that makes the most sense for your use case. Use the available customization options to customize each visualization. [visualize](/influxdb/v2/tags/visualize/) --- # Use annotations in dashboards Source: https://docs.influxdata.com/influxdb/v2/visualize-data/annotations/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Add annotations to your dashboards to provide useful, contextual information about single points in time. After an annotation is created, edit the annotation by updating the text or timestamp, or delete the annotation. * [Create an annotation](#create-an-annotation) * [Edit an annotation](#edit-an-annotation) * [View or hide annotations](#view-or-hide-annotations) * [Delete an annotation](#delete-an-annotation) > [!Note] > Annotations may be useful to highlight operations or anomalies for your team to reference. ## Create an annotation 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Select an existing dashboard to add the annotation to, or [create a new dashboard](/influxdb/cloud/visualize-data/dashboards/create-dashboard/), and then click the **Annotations** button. 3. In a dashboard cell, do one of the following: * Press Shift and click the graph at the time you want to annotate. * To add an annotation to a time range, press Shift, click the start time, and then drag your cursor to the end time. 4. On the **Add Annotation** page: 1. Verify the time or time range, and update if needed. 2. Enter a message (maximum of 255 characters) to associate with the selected time or time range. 3. Click **Save Annotation**. The annotation appears in the cell (dotted lines indicate the selected time or time range). ## Edit an annotation 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Open the dashboard with the annotation to edit, and then click the annotation to open it. 3. Update the text (maximum of 255 characters) or timestamp, and then click **Save Annotation**. ## View or hide annotations By default, annotations are visible. 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Open a dashboard with annotations: * To hide annotations, click the **Annotations** button. The button is gray when annotations are hidden. * To show annotations, click the **Annotations** button. The button is purple when annotations are visible. ## Delete an annotation 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Open a dashboard with the annotation to delete, click the dotted annotation line, and then click **Delete Annotation**. [labels](/influxdb/v2/tags/labels/)[annotations](/influxdb/v2/tags/annotations/) --- # Manage InfluxDB dashboards Source: https://docs.influxdata.com/influxdb/v2/visualize-data/dashboards/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create, edit, and manage dashboards from the **Dashboards** tab in the left navigation. ### [Create a dashboard](/influxdb/v2/visualize-data/dashboards/create-dashboard/) Create a new dashboard or import an existing dashboard in the InfluxDB user interface (UI). ### [Control a dashboard](/influxdb/v2/visualize-data/dashboards/control-dashboard/) Control an InfluxDB dashboard in the InfluxDB user interface (UI). ### [Export a dashboard](/influxdb/v2/visualize-data/dashboards/export-dashboard/) Export a dashboard using the InfluxDB user interface (UI). ### [Delete a dashboard](/influxdb/v2/visualize-data/dashboards/delete-dashboard/) Delete a dashboard from the InfluxDB user interface (UI). ### View your dashboard ID Use the InfluxDB UI or `influx` CLI to view your dashboard ID. ### Dashboard ID in the UI When viewing a dashboard in the InfluxDB UI, your dashboard ID appears in the URL. ```sh http://localhost:8086/orgs/03a2bbf46249a000/dashboards/04b6b15034cc000/... ``` ### Dashboard ID in the CLI Use [`influx dashboards`](/influxdb/v2/reference/cli/influx/dashboards/) to view a list of dashboards and IDs. ```sh > influx dashboards ID Name 03a2bbf46249a000 dashboard-1 03ace3a859669000 dashboard-2 ``` [dashboards](/influxdb/v2/tags/dashboards/) --- # Control a dashboard Source: https://docs.influxdata.com/influxdb/v2/visualize-data/dashboards/control-dashboard/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## Control at the dashboard level Use dashboard controls in the upper left to update your dashboard. ### Add a cell Click **Add Cell** to open the Data Explorer and configure a new cell for your dashboard. For details on using the Data Explorer, see [Explore metrics](/influxdb/v2/visualize-data/explore-metrics/). ### Add a note 1. Click **Add Note** to add a note cell to your dashboard. 2. Enter your note in Markdown in the left pane. A preview appears in the right pane. 3. Enable the **Show note when query returns no data** option to show the note only when the query displays no data. 4. Click **Save**. ### Select timezone Click the timezone dropdown to select a timezone to use for the dashboard. Select either the local time (default) or UTC. Select timezone ### Manually refresh dashboard Click the refresh button () to manually refresh the dashboard’s data. #### Manually refresh a single dashboard cell 1. Click the on the dashboard cell you want to refresh. 2. Click **Refresh**. ### Select time range 1. Select from the time range options in the dropdown menu. Select time range 2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. The default time range is 5 minutes. > > > The custom time range uses the selected timezone (local time or UTC). > > ### Add variables Click **Variables** to display variables available for your dashboard. For details, see [Use and manage variables](/influxdb/v2/visualize-data/variables/) ### Presentation mode Click the fullscreen icon () to enter presentation mode. Presentation mode allows you to view [a dashboard] in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. ### Toggle dark mode and light mode Click the moon or sun icons to toggle your dashboard between **dark mode** and **light mode.** Dark & light mode [dashboards](/influxdb/v2/tags/dashboards/) --- # Create a dashboard Source: https://docs.influxdata.com/influxdb/v2/visualize-data/dashboards/create-dashboard/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## Create a new dashboard 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Click the **Create Dashboard** menu in the upper right and select **New Dashboard**. 3. Enter a name for your dashboard in the **Name this dashboard** field in the upper left. **To import an existing dashboard**: 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Click the **Create Dashboard** menu in the upper right and select **Import Dashboard**. 3. In the window that appears: * Select **Upload File** to drag-and-drop or select a file. * Select **Paste JSON** to paste in JSON. 4. Click **Import JSON as Dashboard**. ## Clone a dashboard 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Hover over the dashboard and click . 3. Click **Clone**. The cloned dashboard opens. #### Add data to your dashboard 1. From your dashboard, click **Add Cell**. 2. Create a query in the Data Explorer following the instructions in [Explore metrics](/influxdb/v2/visualize-data/explore-metrics). 3. Enter a name for your cell in the upper left. 4. Click the checkmark icon (**✓**) to save the cell to your dashboard. You can also send data to your dashboard directly from the Data Explorer. For details, [Explore metrics](/influxdb/v2/visualize-data/explore-metrics). #### Add a note to your dashboard 1. From your dashboard, click **Add Note** in the upper left. 2. Enter your note in the window that appears. You can use Markdown syntax to format your note. 3. To preview your Markdown formatting, click the **Preview** option. 4. Click **Save**. [dashboards](/influxdb/v2/tags/dashboards/) --- # Delete a dashboard Source: https://docs.influxdata.com/influxdb/v2/visualize-data/dashboards/delete-dashboard/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To delete a dashboard from the InfluxDB user interface (UI): 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Hover over the dashboard in the list of dashboards and click . 3. Click **Delete**. Deleting a dashboard cannot be undone. [dashboards](/influxdb/v2/tags/dashboards/) --- # Export a dashboard Source: https://docs.influxdata.com/influxdb/v2/visualize-data/dashboards/export-dashboard/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB lets you export dashboards from the InfluxDB user interface (UI). 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Hover over a dashboard and click the gear icon (), and then select **Download Template**. 3. Your browser downloads the dashboard template JSON file. If prompted, choose a save location. [dashboards](/influxdb/v2/tags/dashboards/) --- # Manage labels in the InfluxDB UI Source: https://docs.influxdata.com/influxdb/v2/visualize-data/labels/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Labels are a way to add visual metadata to dashboards, tasks, and other items in the InfluxDB UI. To manage labels: * In the navigation menu on the left, select **Settings** \> **Labels**. Settings #### Create a label 1. Click **Create Label**. 2. Enter a **Name** for the label. 3. Enter a description for the label *(Optional)*. 4. Select a **Color** for the label. 5. Click **Create Label**. #### Edit a label 1. In the label list view, click the name of the label you would like to edit. The **Edit Label** overlay will appear. 2. Make the desired changes to the label. 3. Click **Save Changes**. #### Delete a label 1. In the label list view, hover over the label you would like to delete and click . 2. Click **Delete**. ### Add labels to dashboard items 1. In the list view of dashboards, tasks, or other assets, hover over the item to which you would like to add a label. 2. Click the  icon that appears below the name. The **Add Labels** overlay will appear. 3. Type the name of the label you would like to add to filter the list of available labels. Click the label you would like to add. [labels](/influxdb/v2/tags/labels/) --- # Use and manage variables Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Dashboard variables let you alter specific components of cells’ queries without having to edit the queries, making it easy to interact with your dashboard cells and explore your data. Variables are scoped by organization. ## Use dashboard variables Both [predefined dashboard variables](#predefined-dashboard-variables) and [custom dashboard variables](#custom-dashboard-variables)are stored in a `v` record associated with each dashboard. Reference each variable using dot-notation (e.g. `v.variableName`). ```js from(bucket: v.bucket) |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == v.measurement and r._field == v.field) |> aggregateWindow(every: v.windowPeriod, fn: mean) ``` When building Flux queries for dashboard cells, view available dashboard variables in the **Variables** tab next to the Functions tab. Click a variable name to add it to your query and select a value from the **Value** dropdown. ## Link to dashboards with variables defined in the URL When you apply a variable to your dashboard, `&vars[variable_name]=value` is appended to the URL so you can share the link with the variables included. ## Predefined dashboard variables The InfluxDB user interface (UI) provides the following predefined dashboard variables: #### v.timeRangeStart Specifies the beginning of the queried time range. This variable is typically used to define the [`start` parameter](/flux/v0/stdlib/universe/range#start)of the `range()` function. The **Time Range** selector defines the value of this variable. #### v.timeRangeStop Specifies the end of the queried time range. This variable is typically used to define the [`stop` parameter](/flux/v0/stdlib/universe/range#stop)of the `range()` function. The **Time Range** selector defines the value of this variable. It defaults to `now`. #### v.windowPeriod Specifies the period of windowed data. This variable is typically used to define the `every` or `period` parameters of the[`window()` function](/flux/v0/stdlib/universe/window)in data aggregation operations. The value of this variable is calculated by analyzing the duration of the Flux query it is used within. Queries that fetch data from a longer time range will have a larger `v.windowPeriod` duration. ## Custom dashboard variables Create, manage, and use custom dashboard variables in the InfluxDB user interface (UI). ### [Create a variable](/influxdb/v2/visualize-data/variables/create-variable/) Create dashboard variables in the Data Explorer, from the Organization page, or import a variable. ### [Update a variable](/influxdb/v2/visualize-data/variables/update-variable/) Update a dashboard variable in the InfluxDB user interface. ### [View variables](/influxdb/v2/visualize-data/variables/view-variables/) View dashboard variables in the InfluxDB user interface. ### [Export a variable](/influxdb/v2/visualize-data/variables/export-variable/) Export a dashboard variable in the InfluxDB user interface. ### [Delete a variable](/influxdb/v2/visualize-data/variables/delete-variable/) Delete a dashboard variable in the InfluxDB user interface. ### [Variable types](/influxdb/v2/visualize-data/variables/variable-types/) Overview of the types of dashboard variables available in InfluxDB ### [Common variable queries](/influxdb/v2/visualize-data/variables/common-variables/) Useful queries to use to populate values in common dashboard variable use cases. [variables](/influxdb/v2/tags/variables/) --- # Common variable queries Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/common-variables/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). ## List buckets List all buckets in the current organization. ***Flux functions:**[buckets()](/flux/v0/stdlib/universe/buckets/),[rename()](/flux/v0/stdlib/universe/rename/),[keep()](/flux/v0/stdlib/universe/keep/)* ```js buckets() |> rename(columns: {"name": "_value"}) |> keep(columns: ["_value"]) ``` ## List measurements List all measurements in a specified bucket. ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/) **Flux functions:** [schema.measurements()](/flux/v0/stdlib/influxdata/influxdb/schema/measurements/)* ```js import "influxdata/influxdb/schema" schema.measurements(bucket: "bucket-name") ``` ## List fields in a measurement List all fields in a specified bucket and measurement. ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/) **Flux functions:** [schema.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues/)* ```js import "influxdata/influxdb/schema" schema.measurementTagValues( bucket: "bucket-name", measurement: "measurement-name", tag: "_field", ) ``` ## List unique tag values List all unique tag values for a specific tag in a specified bucket. The example below lists all unique values of the `host` tag. ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/)* ***Flux functions:** [schema.tagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/tagvalues/)* ```js import "influxdata/influxdb/schema" schema.tagValues(bucket: "bucket-name", tag: "host") ``` ## List Docker containers List all Docker containers when using the Docker Telegraf plugin. ***Telegraf plugin:** [Docker](/telegraf/v1/plugins/#input-docker)* ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/)* ***Flux functions:** [schema.tagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/tagvalues/)* ```js import "influxdata/influxdb/schema" schema.tagValues(bucket: "bucket-name", tag: "container_name") ``` ## List Kubernetes pods List all Kubernetes pods when using the Kubernetes Telegraf plugin. ***Telegraf plugin:** [Kubernetes](/telegraf/v1/plugins/#input-kubernetes)* ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/)* ***Flux functions:** [schema.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues/)* ```js import "influxdata/influxdb/schema" schema.measurementTagValues( bucket: "bucket-name", measurement: "kubernetes_pod_container", tag: "pod_name", ) ``` ## List Kubernetes nodes List all Kubernetes nodes when using the Kubernetes Telegraf plugin. ***Telegraf plugin:** [Kubernetes](/telegraf/v1/plugins/#input-kubernetes)* ***Flux package:** [InfluxDB schema](/flux/v0/stdlib/influxdata/influxdb/schema/)* ***Flux functions:** [schema.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues/)* ```js import "influxdata/influxdb/schema" schema.measurementTagValues( bucket: "bucket-name", measurement: "kubernetes_node", tag: "node_name", ) ``` [variables](/influxdb/v2/tags/variables/) --- # Create a variable Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/create-variable/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Create dashboard variables in the Data Explorer, from the Settings section, or import a variable.**Variable names must be unique.** There are multiple variable types that provide different means of populating your list of variable values.*For information about variable types, see [Variable types](/influxdb/v2/visualize-data/variables/variable-types/).* > [!Note] > ##### Variable name restrictions > > Variable names must begin with a letter or underscore (`_`). > > The following names cannot be used as dashboard variables because they are reserved keywords in Flux:`and`, `import`, `not`, `return`, `option`, `test`, `empty`, `in`, `or`, `package`, and `builtin`. ## Create a variable in the Data Explorer > [!Note] > InfluxData recommends using the Data Explorer to create[Query dashboard variables](/influxdb/v2/visualize-data/variables/variable-types/#query). > The [Table visualization type](/influxdb/v2/visualize-data/visualization-types/table/) and**View Raw Data** option to provide human-readable query results. 1. Click the **Data Explorer** icon in the sidebar. Data Explorer 2. Use the **Query Builder** or **Script Editor** to build a query. 3. Use the [Table visualization type](/influxdb/v2/visualize-data/visualization-types/table/)or enable the **View Raw Data** option to view human-readable query results. 4. Click **Save As** in the upper right. 5. In the window that appears, select **Variable**. 6. Enter a name for your variable in the **Name** field. 7. Click **Create**. *For information about common Query variables, see [Common variable queries](/influxdb/v2/visualize-data/variables/common-variables/).* ## Create a variable in the Settings section 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. 3. Enter a name for your variable. 4. Select your variable type. For details on each type, see [Variable types](/influxdb/v2/visualize-data/variables/variable-types/). 5. Enter the appropriate variable information. 6. Click **Create**. ## Import a variable InfluxDB lets you import variables exported from InfluxDB in JSON format. 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. 3. Click the **Create Variable** drop-down menu and select **Import Variable**. 4. In the window that appears: * Select **Upload File** to drag and drop or select a file. * Select **Paste JSON** to paste in JSON. 1. Click **Import JSON as Variable**. [variables](/influxdb/v2/tags/variables/) --- # Delete a variable Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/delete-variable/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Delete an existing variable in the InfluxDB user interface (UI). ### Delete a variable 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. 3. Hover over a variable, click the icon, and **Delete**. Once deleted, any dashboards with queries that utilize the variable will no longer function correctly. [variables](/influxdb/v2/tags/variables/) --- # Export a variable Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/export-variable/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Export dashboard variables from the InfluxDB user interface (UI). Variables are exported as downloadable JSON files. ### Export a variable 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. 3. Hover over a variable in the list, then click the gear icon () and select **Export**. 4. Your browser downloads the variable JSON file. If prompted, choose a save location. [variables](/influxdb/v2/tags/variables/) --- # Update a variable Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/update-variable/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update an existing dashboard variable’s name or JSON content in the InfluxDB user interface (UI). ### Update a variable 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. 3. Click a variable’s name from the list. 4. Update the variable’s name, type, and associated information. 5. Click **Submit**. [variables](/influxdb/v2/tags/variables/) --- # Variable types Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/variable-types/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Variable types determine how a variable’s list of possible values is populated. The following variable types are available: * [Map](#map) * [Query](#query) * [CSV](#csv) ### Map Map variables use a list of key value pairs in CSV format to map keys to specific values. Keys populate the variable’s value list in the InfluxDB user interface (UI), but values are used when actually processing the query. The most common use case for map variables is aliasing simple, human-readable keys to complex values. ##### Map variable example ```js Juanito MacNeil,"5TKl6l8i4idg15Fxxe4P" Astrophel Chaudhary,"bDhZbuVj5RV94NcFXZPm" Ochieng Benes,"YIhg6SoMKRUH8FMlHs3V" Mila Emile,"o61AhpOGr5aO3cYVArC0" ``` ### Query Query variable values are populated using the `_value` column of a Flux query. ##### Query variable example ```js // List all buckets buckets() |> rename(columns: {"name": "_value"}) |> keep(columns: ["_value"]) ``` *For examples of dashboard variable queries, see [Common variable queries](/influxdb/v2/visualize-data/variables/common-variables).* > [!Note] > #### Important things to note about variable queries > > * The variable will only use values from the `_value` column. > If the data you’re looking for is in a column other than `_value`, use the[`rename()`](/flux/v0/stdlib/universe/rename/) or[`map()`](/flux/v0/stdlib/universe/map/) functions > to change the name of that column to `_value`. > * The variable will only use the first table in the output stream. > Use the [`group()` function](/flux/v0/stdlib/universe/group)to group everything into a single table. > * Do not use any [predefined dashboard variables](/influxdb/v2/visualize-data/variables/#predefined-dashboard-variables) in variable queries. ### CSV CSV variables use a CSV-formatted list to populate variable values. A common use case is when the list of potential values is static and cannot be queried from InfluxDB. ##### CSV variable examples ``` value1, value2, value3, value4 ``` ``` value1 value2 value3 value4 ``` ## Use custom dashboard variables Use the Flux `v` record and [dot or bracket notation](/flux/v0/data-types/composite/record/#reference-values-in-a-record) to access custom dashboard variables. For example, to use a custom dashboard variable named `exampleVar` in a query, reference the variable with `v.exampleVar`: ``` from(bucket: "telegraf") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "cpu" ) |> filter(fn: (r) => r._field == "usage_user" ) |> filter(fn: (r) => r.cpu == v.exampleVar) ``` **To select variable values:** * **In a dashboard:** Use the dashboard variable drop-down menus at the top of your dashboard. * **In the Script Editor:** Click the **Variables** tab on the right of the Script Editor, click the name of the variable, and then select the variable value from the drop-down menu. *For more on using dashboard variables, see [Use and manage variables](/influxdb/v2/visualize-data/variables/).* [variables](/influxdb/v2/tags/variables/) --- # View variables Source: https://docs.influxdata.com/influxdb/v2/visualize-data/variables/view-variables/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). View a list of dashboard variables in the InfluxDB user interface (UI) from an organization or from the Data Explorer. ## View variables in the organization 1. Click the **Settings** icon in the navigation bar. Settings 2. Select the **Variables** tab. ## View variables in the Data Explorer 1. Click the **Data Explorer** icon in the navigation bar. Data Explorer 2. Switch to **Script Editor**. 3. Click the **Variables** tab to the right of the script editor. [variables](/influxdb/v2/tags/variables/) --- # Visualization types Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB UI provides multiple visualization types to visualize your data in a format that makes the most sense for your use case. Use the available customization options to customize each visualization. ### [Band](/influxdb/v2/visualize-data/visualization-types/band/) ### [Gauge](/influxdb/v2/visualize-data/visualization-types/gauge/) The Gauge view displays the single value most recent value for a time series in a gauge view. ### [Graph](/influxdb/v2/visualize-data/visualization-types/graph/) The Graph view lets you select from multiple graph types such as line graphs and bar graphs *(Coming)*. ### [Graph + Single Stat](/influxdb/v2/visualize-data/visualization-types/graph-single-stat/) The Graph + Single Stat view displays the specified time series in a line graph and overlays the single most recent value as a large numeric value. ### [Heatmap](/influxdb/v2/visualize-data/visualization-types/heatmap/) A Heatmap displays the distribution of data on an x and y axes where color represents different concentrations of data points. ### [Histogram](/influxdb/v2/visualize-data/visualization-types/histogram/) A histogram is a way to view the distribution of data. The y-axis is dedicated to count, and the x-axis is divided into bins. ### [Mosaic](/influxdb/v2/visualize-data/visualization-types/mosaic/) The Mosaic visualization displays state changes in your time series data. This visualization type is useful when you want to show changes in string-based states over time. ### [Scatter](/influxdb/v2/visualize-data/visualization-types/scatter/) The Scatter view uses a scatter plot to display time series data. ### [Single stat](/influxdb/v2/visualize-data/visualization-types/single-stat/) The Single Stat view displays the most recent value of the specified time series as a numerical value. ### [Table](/influxdb/v2/visualize-data/visualization-types/table/) The Table option displays the results of queries in a tabular view, which is sometimes easier to analyze than graph views of data. --- # Band visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/band/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Band** visualization displays the upper and lower boundaries for groups of data over time. Boundaries are determined by applying aggregate functions to your data for a specified window period, and then setting the aggregate functions for a specified upper, main, or lower boundary. ## Set up the Band visualization To see bands (boundaries) in the **Band Plot** visualization, you must set up two or three boundaries for comparison. ### Set up the band visualization in the Data Explorer 1. Click the **Data Explorer** icon in the navigation bar. Data Explorer 2. Enter your query (see [Explore data with Flux and the Data Explorer](/influxdb/v2/visualize-data/explore-metrics/#explore-data-with-flux-and-the-data-explorer)). You must include the aggregate functions used to determine the Band Plot visualization boundaries in your query. 3. Select the **Band Plot** option from the visualization dropdown in the upper left, and then click **Customize**. 4. Under **Data**, select the following: * For **X Column** and **Y Column**, select the columns to display for the x- and y- axes. * For **Time Format**, select the timestamp format to display in the visualization. 5. Under **Aggregate Functions**, select a function to determine each boundary (column) for comparison (select two or three): * In the **Upper Column** field, select a function for the upper boundary. * In the **Main Column** field, select a function for the main boundary. * In the **Lower Column** field, select a function for the lower boundary. 6. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. **Tip:** If you do not see shaded boundaries in the **Band Plot** visualization, verify the query window period includes a sufficient number of data points for the selected aggregate function. By default, the window period is automatically set to ten seconds (`10s`). To adjust your window period, select **Custom**, and then enter a supported time unit (for example nanoseconds (`ns`), microseconds (`us`), milliseconds (`ms`), seconds (`s`), or hours (`h`). Band example ### Set up the band plot visualization in the Script Editor 1. Click the **Data Explorer** icon in the navigation bar. Data Explorer 2. Click **Script Editor**. 3. Select the **Band Plot** option from the visualization dropdown in the upper left. 4. Create three aggregate functions: one for the main boundary, one for the upper boundary, and one for the lower boundary. The following example uses the [`mean()`](/flux/v0/stdlib/universe/mean/), [`max()`](/flux/v0/stdlib/universe/max/), and [`min()`](/flux/v0/stdlib/universe/min) functions: ```js from(bucket: "bucket_1") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r["_measurement"] == "cpu") |> filter(fn: (r) => r["_field"] == "usage_system") |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") |> aggregateWindow(every: 15s, fn: mean, createEmpty: false) |> yield(name: "mean") from(bucket: "bucket_1") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r["_measurement"] == "cpu") |> filter(fn: (r) => r["_field"] == "usage_system") |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") |> aggregateWindow(every: 15s, fn: max, createEmpty: false) |> yield(name: "max") from(bucket: "bucket_1") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r["_measurement"] == "cpu") |> filter(fn: (r) => r["_field"] == "usage_system") |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") |> aggregateWindow(every: 15s, fn: min, createEmpty: false) |> yield(name: "min") ``` 1. (Optional) Customize the name of the yielded results for each function by editing the `name` parameter in the [`yield()`](/flux/v0/stdlib/universe/yield/) function. For example, to change the name of the first function from `mean` to `Average`, modify the last line to the following: ```js |> yield(name: "Average") ``` 1. Click **Customize** in the upper left. 2. Under **Aggregate Functions**, enter the functions you created to determine each boundary (column) for comparison. If you changed the `yield` name for any of the functions above, enter the modified name here instead of the function name: * In the **Upper Column Name** field, enter the result set to use for the upper boundary. * In the **Main Column Name** field, enter the result set to use for the main boundary. * In the **Lower Column Name** field, enter the function for the lower boundary. 3. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, static legend, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. ### Customize column names ## Band behavior Like a line graph, the band visualization shows how values change over time. Additionally, it displays upper and lower “bands” for the measurements. For example, in the band chart above, the lines represent the mean `usage_system` values for the `cpu` measurement for `cpu0` and `cpu1`. The upper and lower limits of the bands are defined by the `max` and `min` aggregate functions, respectively. ## Band controls To view **Band** controls, click **Customize** next to the visualization dropdown. ###### Data * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select a column to display on the y-axis. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a ###### Aggregate functions * **Upper Column**: Aggregate function to display for upper bounds of data. * **Main Column**: Aggregate function to display for main graph line. * **Lower Column**: Aggregate function to display for lower bounds of data. ###### Options * **Interpolation**: * **Linear**: Display a time series in a line graph. * **Smooth**: Display a time series in a line graph with smooth point interpolation. * **Step**: Display a time series in a staircase graph. * **Line Colors**: Select a color scheme to use for your graph. * **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: * **auto** or **X-Axis**: Show all points with the same x value along the y-axis. * **Y-Axis**: Show all points with the same y value along the x-axis. * **X-Y Axis**: Show only the point being currently hovered over. ###### X-Axis * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of timestamp ticks to display. * **Start Tick Marks At**: Enter the time, in RFC3339 format, to start displaying ticks. Use the **Date Picker** field to automatically generate an RFC3339 formatted timestamp for this field. * **Tick Mark Interval**: Enter the number of milliseconds in between each timestamp tick. ###### Y-Axis * **Y Axis Label**: Enter the label for the y-axis. * **Y-Value Unit Prefix**: Select the prefix to add to the y-value: * **None**: Select to add no prefix. * **SI**: (default) Select to add an International System of Units (SI) or metric prefix. * **Binary**: Select to add a binary multiple prefix. * **Y Axis Prefix**: Enter the prefix to add to the y-value. * **Y Axis Suffix**: Enter the suffix to add to the y-value. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **Y Axis Domain**: Select the method to generate the y-axis value range: * **Auto**: Select to automatically determine the value range based on values in the data set. * **Custom**: To customize the y-axis domain, manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Enter the minimum y-axis value. * **Max**: Enter the maximum y-axis value. ###### Legend * **Hover Legend**: * **Hide**: Hide the legend that appears upon hover. * **Show**: Show the legend upon hover. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the hover legend opacity using the slider. * **Colorize Rows**: Select to display hover legend rows in colors. * **Static Legend**: * **Hide**: Hide the static legend. * **Show**: Always show the static legend. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the static legend opacity using the slider. * **Colorize Rows**: Select to display static legend rows in colors. * **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. * **Height**: Adjust the height of the static legend using the slider. --- # Gauge visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/gauge/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Gauge** visualization displays the most recent value for a time series in a gauge. Gauge example Select the **Gauge** option from the visualization dropdown in the upper left. ## Gauge behavior The gauge visualization displays a single numeric data point within a defined spectrum (*default is 0-100*). It uses the latest point in the first table (or series) returned by the query. > [!Note] > #### Queries should return one table > > Flux does not guarantee the order in which tables are returned. > If a query returns multiple tables (or series), the table order can change between query executions > and result in the Gauge displaying inconsistent data. > For consistent results, the Gauge query should return a single table. ## Gauge Controls To view **Gauge** controls, click **Customize** next to the visualization dropdown. * **Value Prefix**: Prefix to add to the gauge value. * **Value Suffix**: Suffix to add to the gauge value. * **Axis Prefix**: Prefix to add to the gauge axis. * **Axis Suffix**: Suffix to add to the gauge axis. * **Decimal Places**: The number of decimal places to display for the gauge. * **Auto** or **Custom**: Enable or disable auto-setting. ###### Colorized Thresholds * **Add a Threshold**: Change the color of the gauge based on the current value. * **Minimum**: Enter the minimum value at which the gauge should appear in the selected color. Choose a color from the dropdown menu next to the value. * **Maximum**: Enter the maximum value at which the gauge should appear in the selected color. Choose a color from the dropdown menu next to the value. ## Gauge examples Gauge visualizations are useful for showing the current value of a metric and displaying where it falls within a spectrum. ### Steam pressure gauge The following example queries sensor data that tracks the pressure of steam pipes in a facility and displays it as a gauge. ###### Query pressure data from a specific sensor ```js from(bucket: "example-bucket") |> range(start: -1m) |> filter(fn: (r) => r._measurement == "steam-sensors" and r._field == "psi" r.sensorID == "a211i") ``` ###### Visualization options for pressure gauge Pressure gauge example --- # Graph + Single Stat visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/graph-single-stat/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Graph + Single Stat** view displays the specified time series in a line graph and overlays the single most recent value as a large numeric value. Line Graph + Single Stat example Select the **Graph + Single Stat** option from the visualization dropdown in the upper left. ## Graph + Single Stat behavior The Graph visualization color codes each table (or series) in the queried data set. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). The Single Stat visualization displays a single numeric data point. It uses the latest point in the first table (or series) returned by the query. > [!Note] > #### Queries should return one table > > Flux does not guarantee the order in which tables are returned. > If a query returns multiple tables (or series), the table order can change between query executions > and result in the Single Stat visualization displaying inconsistent data. > For consistent Single Stat results, the query should return a single table. ## Graph + Single Stat Controls To view **Graph + Single Stat** controls, click **Customize** next to the visualization dropdown. ###### Data * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select a column to display on the y-axis. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a ###### Options * **Line Colors**: Select a color scheme to use for your graph. * **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: * **auto** or **X Axis**: Show all points with the same x value along the y-axis. * **Y Axis**: Show all points with the same y value along the x-axis. * **X & Y Axis**: Show only the point currently being hovered over. * **Shade area below graph**: Shade in the area below the graph lines. ###### X Axis * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. ###### Y Axis * **Y Axis Label**: Label for the y-axis. * **Y Value Unit Prefix**: * **None**: No prefix. * **SI**: International System of Units (SI) or metric prefix. * **Binary**: Binary multiple prefix. * **Y Axis Prefix**: Prefix to be added to y-value. * **Y Axis Suffix**: Suffix to be added to y-value. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **Y Axis Domain**: The y-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Minimum y-axis value. * **Max**: Maximum y-axis value. * **Positioning**: * **Overlaid**: Display graph lines overlaid on each other. * **Stacked**: Display graph lines stacked on top of each other. ###### Customize Single-Stat * **Prefix**: Prefix to be added to the single stat. * **Suffix**: Suffix to be added to the single stat. * **Decimal Places**: The number of decimal places to display for the single stat. * **Auto** or **Custom**: Enable or disable auto-setting. ###### Colorized Thresholds * **Base Color**: Select a base or background color from the selection list. * **Add a Threshold**: Change the color of the single stat based on the current value. * **Value is**: Enter the value at which the single stat should appear in the selected color. Choose a color from the dropdown menu next to the value. * **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. Choose **Background** for the background of the graph to change color based on the configured thresholds. ###### Hover Legend * **Display Hover Legend**: * **Hide**: Hide the legend that appears upon hover. * **Show**: Show the legend upon hover. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the hover legend opacity using the slider. * **Colorize Rows**: Select to display hover legend rows in colors. ###### Static Legend * **Display Static Legend**: * **Hide**: Hide the static legend. * **Show**: Always show the static legend. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the static legend opacity using the slider. * **Colorize Rows**: Select to display static legend rows in colors. * **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. * **Height**: Adjust the height of the static legend using the slider. ## Graph + Single Stat examples The primary use case for the Graph + Single Stat visualization is to show the current or latest value as well as historical values. ### Show current value and historical values The following example shows the current percentage of memory used as well as memory usage over time: ###### Query memory usage percentage ```js from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") ``` ###### Memory allocations percentage visualization with static legend Graph + Single Stat Memory Usage Example #### Related * [Graph visualization](/influxdb/v2/visualize-data/visualization-types/graph/) * [Single Stat visualization](/influxdb/v2/visualize-data/visualization-types/single-stat/) --- # Graph visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/graph/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The Graph visualization provides several types of graphs, each configured through the [Graph controls](#graph-controls). Line Graph example Select the **Graph** option from the visualization dropdown in the upper left. ## Graph behavior The Graph visualization color codes each table (or series) in the queried data set. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). ## Graph controls To view **Graph** controls, click **Customize** next to the visualization dropdown. ###### Data * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select a column to display on the y-axis. ###### Options * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a * **Interpolation**: Select from the following options: * **Linear**: Display a time series in a line graph * **Smooth**: Display a time series in a line graph with smooth point interpolation. * **Step**: Display a time series in a staircase graph. * **Line Colors**: Select a color scheme to use for your graph. * **Shade Area Below Lines**: Shade in the area below the graph lines. * **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: * **auto** or **X Axis**: Show all points with the same x value along the y-axis. * **Y Axis**: Show all points with the same y value along the x-axis. * **X & Y Axis**: Show only the point currently being hovered over. ###### X Axis * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. ###### Y Axis * **Y Axis Label**: Label for the y-axis. * **Y-Value Unit Prefix**: * **None**: * **SI**: * **Binary**: * **Y Axis Prefix**: Prefix to be added to y-value. * **Y Axis Suffix**: Suffix to be added to y-value. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **Y Axis Domain**: The y-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Minimum y-axis value. * **Max**: Maximum y-axis value. * **Positioning**: * **Overlaid**: Display graph lines overlaid on each other. * **Stacked**: Display graph lines stacked on top of each other. ###### Hover Legend * **Display Hover Legend**: * **Hide**: Hide the legend that appears upon hover. * **Show**: Show the legend upon hover. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the hover legend opacity using the slider. * **Colorize Rows**: Select to display hover legend rows in colors. ###### Static Legend * **Display Static Legend**: * **Hide**: Hide the static legend. * **Show**: Always show the static legend. * **Orientation**: Select the orientation of the legend: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the static legend opacity using the slider. * **Colorize Rows**: Select to display static legend rows in colors. * **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. * **Height**: Adjust the height of the static legend using the slider. ## Graph Examples ##### Graph with linear interpolation and static legend Line Graph example ##### Graph with smooth interpolation and hover legend Step-Plot Graph example ##### Graph with step interpolation and no visible legend Step-Plot Graph example --- # Heatmap visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/heatmap/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A **Heatmap** displays the distribution of data on an x and y axes where color represents different concentrations of data points. Heatmap example Select the **Heatmap** option from the visualization dropdown in the upper left. ## Heatmap behavior Heatmaps divide data points into “bins” – segments of the visualization with upper and lower bounds for both [X and Y axes](#data). The [Bin Size option](#options) determines the bounds for each bin. The total number of points that fall within a bin determine the its value and color. Warmer or brighter colors represent higher bin values or density of points within the bin. ## Heatmap Controls To view **Heatmap** controls, click **Customize** next to the visualization dropdown. ###### Data * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select a column to display on the y-axis. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a ###### Options * **Color Scheme**: Select a color scheme to use for your heatmap. * **Bin Size**: Specify the size of each bin. Default is 10. ###### X Axis * **X Axis Label**: Label for the x-axis. * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **X Axis Domain**: The x-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Minimum x-axis value. * **Max**: Maximum x-axis value. ###### Y Axis * **Y Axis Label**: Label for the y-axis. * **Y Tick Prefix**: Prefix to be added to y-value. * **Y Tick Suffix**: Suffix to be added to y-value. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **Y Axis Domain**: The y-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Minimum y-axis value. * **Max**: Maximum y-axis value. ###### Hover Legend * **Orientation**: Select the orientation of the legend that appears upon hover: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the legend opacity using the slider. * **Colorize Rows**: Select to display legend rows in colors. ## Heatmap examples ### Cross-measurement correlation The following example explores possible correlation between CPU and Memory usage. It uses data collected with the Telegraf [Mem](/telegraf/v1/plugins//#mem)and [CPU](/telegraf/v1/plugins//#cpu) input plugins. ###### Join CPU and memory usage The following query joins CPU and memory usage on `_time`. Each row in the output table contains `_value_cpu` and `_value_mem` columns. ```js cpu = from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") mem = from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") join(tables: {cpu: cpu, mem: mem}, on: ["_time"], method: "inner") ``` ###### Use a heatmap to visualize correlation In the Heatmap visualization controls, `_value_cpu` is selected as the [X Column](#data)and `_value_mem` is selected as the [Y Column](#data). The domain for each axis is also customized to account for the scale difference between column values. Heatmap correlation example ## Important notes ### Differences between a heatmap and a scatter plot Heatmaps and [Scatter plots](/influxdb/v2/visualize-data/visualization-types/scatter/)both visualize the distribution of data points on X and Y axes. However, in certain cases, heatmaps provide better visibility into point density. For example, the dashboard cells below visualize the same query results: Heatmap vs Scatter plot The heatmap indicates isolated high point density, which isn’t visible in the scatter plot. In the scatter plot visualization, points that share the same X and Y coordinates appear as a single point. #### Related * [Scatter visualization](/influxdb/v2/visualize-data/visualization-types/scatter/) --- # Histogram visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/histogram/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). A histogram is a way to view the distribution of data. The y-axis is dedicated to count, and the X-axis is divided into bins. Histogram example Select the **Histogram** option from the visualization dropdown in the upper left. ## Histogram behavior The Histogram visualization is a bar graph that displays the number of data points that fall within “bins” – segments of the X axis with upper and lower bounds. Bin thresholds are determined by dividing the width of the X axis by the number of bins set using the [Bins option](#options). Data within bins can be further grouped or segmented by selecting columns in the[Group By option](#options). > [!Note] > The Histogram visualization automatically bins, segments, and counts data. > To work properly, query results **should not** be structured as histogram data. ## Histogram Controls To view **Histogram** controls, click **Customize** next to the visualization dropdown. ###### Data * **X Column**: The column to select data from. * **Group By**: The column to group by. ###### Options * **Color Scheme**: Select a color scheme to use for your graph. * **Positioning**: Select **Stacked** to stack groups in a bin on top of each other. Select **Overlaid** to overlay groups in each bin. * **Bins**: Enter a number of bins to divide data into or select Auto to automatically calculate the number of bins. * **Auto** or **Custom**: Enable or disable auto-setting. ###### X Axis * **X Axis Label**: Label for the x-axis. * **X Axis Domain**: The x-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the value range of the x-axis. * **Min**: Minimum x-axis value. * **Max**: Maximum x-axis value. ###### Hover Legend * **Orientation**: Select the orientation of the legend that appears upon hover: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the legend opacity using the slider. * **Colorize Rows**: Select to display legend rows in colors. ## Histogram examples ### View error counts by severity over time The following example uses the Histogram visualization to show the number of errors “binned” by time and segmented by severity.*It utilizes data from the [Telegraf Syslog plugin](/telegraf/v1/plugins//#syslog).* ##### Query for errors by severity code ```js from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "syslog" and r._field == "severity_code") ``` ##### Histogram settings In the Histogram visualization options, select `_time` as the [X Column](#data)and `severity` as the [Group By](#data) option: Errors histogram --- # Mosaic visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/mosaic/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Mosaic** visualization displays state changes in your time series data. This visualization type is useful when you want to show changes in string-based states over time. Mosaic data visualization Select the **Mosaic** option from the visualization dropdown in the upper left. ## Mosaic behavior The mosaic visualization displays colored tiles based on string values in a specified column. Each unique string value is represented by a different color. ## Mosaic controls To view **Mosaic** controls, click **Customize** next to the visualization dropdown. ###### Data * **Fill Column**: Select a column to fill in the mosaic tiles. * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select one or more columns to display on the y-axis. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a ###### Options * **Color Scheme**: Select a color scheme to use for your graph. ###### X Axis * **X Axis Label**: Enter a label for the x-axis. * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of timestamp ticks to display. * **Start Tick Marks At**: Enter the time, in RFC3339 format, to start displaying ticks. Use the **Date Picker** field to automatically generate an RFC3339 formatted timestamp for this field. * **Tick Mark Interval**: Enter the number of milliseconds in between each timestamp tick. ###### Y Axis * **Y Axis Label**: Enter a label for the y-axis. * **Y Label Separator**: If there’s more than one column on the y-axis, enter a delimiter to separate the label, such as a comma or space. If there’s no separator specified, the labels are a continuous string of all y columns. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. ###### Hover Legend * **Orientation**: Select the orientation of the legend that appears upon hover: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the legend opacity using the slider. * **Colorize Rows**: Select to display legend rows in colors. ## Example query The following query uses the [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data)to display changes in water levels over time. Use `level description` as the **Fill Column** in the [visualization controls](#data). ```js from(bucket: "noaa") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "h2o_feet") |> filter(fn: (r) => r._field == "level description") |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false) ``` --- # Scatter visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/scatter/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Scatter** view uses a scatter plot to display time series data. Scatter plot example Select the **Scatter** option from the visualization dropdown in the upper left. ## Scatter behavior The scatter visualization maps each data point to X and Y coordinates. X and Y axes are specified with the [X Column](#data) and [Y Column](#data) visualization options. Each unique series is differentiated using fill colors and symbols. Use the [Symbol Column](#data) and [Fill Column](#data) options to select columns used to differentiate points in the visualization. ## Scatter controls To view **Scatter** controls, click **Customize** next to the visualization dropdown. ###### Data * **Symbol Column**: Define a column containing values that should be differentiated with symbols. * **Fill Column**: Define a column containing values that should be differentiated with fill color. * **X Column**: Select a column to display on the x-axis. * **Y Column**: Select a column to display on the y-axis. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a ###### Options * **Color Scheme**: Select a color scheme to use for your scatter plot. ###### X Axis * **X Axis Label**: Label for the x-axis. * **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **X Axis Domain**: The x-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum x-axis value, maximum x-axis value, or range by including both. * **Min**: Minimum x-axis value. * **Max**: Maximum x-axis value. ###### Y Axis * **Y Axis Label**: Label for the y-axis. * **Y Tick Prefix**: Prefix to be added to y-value. * **Y Tick Suffix**: Suffix to be added to y-value. * **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: * **Auto**: Select to automatically generate tick marks. * **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: * **Total Tick Marks**: Enter the total number of ticks to display. * **Start Tick Marks At**: Enter the value to start ticks at. * **Tick Mark Interval**: Enter the interval in between each tick. * **Y Axis Domain**: The y-axis value range. * **Auto**: Automatically determine the value range based on values in the data set. * **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. * **Min**: Minimum y-axis value. * **Max**: Maximum y-axis value. ###### Hover Legend * **Orientation**: Select the orientation of the legend that appears upon hover: * **Horizontal**: Select to display the legend horizontally. * **Vertical**: Select to display the legend vertically. * **Opacity**: Adjust the legend opacity using the slider. * **Colorize Rows**: Select to display legend rows in colors. ## Scatter examples ### Cross-measurement correlation The following example explores possible correlation between CPU and Memory usage. It uses data collected with the Telegraf [Mem](/telegraf/v1/plugins//#mem)and [CPU](/telegraf/v1/plugins//#cpu) input plugins. ###### Query CPU and memory usage The following query creates a union of CPU and memory usage. It scales the CPU usage metric to better align with baseline memory usage. ```js cpu = from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total") // Scale CPU usage |> map(fn: (r) => ({r with _value: r._value + 60.0, _time: r._time})) mem = from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") union(tables: [cpu, mem]) ``` ###### Use a scatter plot to visualize correlation In the Scatter visualization controls, points are differentiated based on their group keys. Heatmap correlation example ## Important notes ### Differences between a scatter plot and a heatmap Scatter plots and [Heatmaps](/influxdb/v2/visualize-data/visualization-types/heatmap/)both visualize the distribution of data points on X and Y axes. However, in certain cases, scatterplots can “hide” points if they share the same X and Y coordinates. For example, the dashboard cells below visualize the same query results: Heatmap vs Scatter plot The heatmap indicates isolated high point density, which isn’t visible in the scatter plot. In the scatter plot visualization, points that share the same X and Y coordinates appear as a single point. #### Related * [Heatmap visualization](/influxdb/v2/visualize-data/visualization-types/heatmap/) --- # Single Stat visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/single-stat/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Single Stat** view displays the most recent value of the specified time series as a numerical value. Single stat example Select the **Single Stat** option from the visualization dropdown in the upper left. ## Single Stat behavior The Single Stat visualization displays a single numeric data point. It uses the latest point in the first table (or series) returned by the query. > [!Note] > #### Queries should return one table > > Flux does not guarantee the order in which tables are returned. > If a query returns multiple tables (or series), the table order can change between query executions > and result in the Single Stat visualization displaying inconsistent data. > For consistent results, the Single Stat query should return a single table. ## Single Stat Controls To view **Single Stat** controls, click **Customize** next to the visualization dropdown. * **Prefix**: Prefix to be added to the single stat. * **Suffix**: Suffix to be added to the single stat. * **Decimal Places**: The number of decimal places to display for the single stat. * **Auto** or **Custom**: Enable or disable auto-setting. ###### Colorized Thresholds * **Base Color**: Select a base or background color from the selection list. * **Add a Threshold**: Change the color of the single stat based on the current value. * **Value is**: Enter the value at which the single stat should appear in the selected color. Choose a color from the dropdown menu next to the value. * **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. Choose **Background** for the background of the graph to change color based on the configured thresholds. ## Single Stat examples ### Show human-readable current value The following example shows the current memory usage displayed has a human-readable percentage: ###### Query memory usage percentage ```js from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") ``` ###### Memory usage as a single stat Graph + Single Stat Memory Usage Example --- # Table visualization Source: https://docs.influxdata.com/influxdb/v2/visualize-data/visualization-types/table/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The **Table** option displays the results of queries in a tabular view, which is sometimes easier to analyze than graph views of data. Table example Select the **Table** option from the visualization dropdown in the upper left. ## Table behavior The table visualization renders queried data in structured, easy-to-read tables. Columns and rows match those in the query output. If query results contain multiple tables, only one table is shown at a time. Select other output tables in the far left column of the table visualization. Tables are identified by their [group key](/flux/v0/get-started/data-model/#group-key). ## Table Controls To view **Table** controls, click **Customize** next to the visualization dropdown. ###### Formatting * **Default Sort Field**: Select the default sort field. Default is **time**. * **Time Format**: Select the time format. Options include: * YYYY-MM-DD HH:mm:ss ZZ * YYYY-MM-DD hh:mm:ss a ZZ * DD/MM/YYYY HH:mm:ss.sss * DD/MM/YYYY hh:mm:ss.sss a * MM/DD/YYYY HH:mm:ss.sss * MM/DD/YYYY hh:mm:ss.sss a * YYYY/MM/DD HH:mm:ss * YYYY/MM/DD hh:mm:ss a * HH:mm * hh:mm a * HH:mm:ss * hh:mm:ss a * HH:mm:ss ZZ * hh:mm:ss a ZZ * HH:mm:ss.sss * hh:mm:ss.sss a * MMMM D, YYYY HH:mm:ss * MMMM D, YYYY hh:mm:ss a * dddd, MMMM D, YYYY HH:mm:ss * dddd, MMMM D, YYYY hh:mm:ss a * **Decimal Places**: Enter the number of decimal places. Default (empty field) is **unlimited**. * **Auto** or **Custom**: Enable or disable auto-setting. ###### Colorized Thresholds * **Base Color**: Select a base or background color from the selection list. * **Add a Threshold**: Change the color of the table based on the current value. * **Value is**: Enter the value at which the table should appear in the selected color. Choose a color from the dropdown menu next to the value. ###### Column Settings * **First Column**: Toggle to **Fixed** to lock the first column so that the listings are always visible. Threshold settings do not apply in the first column when locked. * **Table Columns**: * Enter a new name to rename any of the columns. * Click the eye icon next to a column to hide it. * [additional]: Enter name for each additional column. * Change the order of the columns by dragging to the desired position. ## Table examples Tables are helpful when displaying many human-readable metrics in a dashboard such as cluster statistics or log messages. ### Human-readable cluster metrics The following example queries the latest reported memory usage from a cluster of servers. ###### Query the latest memory usage from each host ```js from(bucket: "example-bucket") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") |> group(columns: ["host"]) |> last() |> group() |> keep(columns: ["_value", "host"]) ``` ###### Cluster metrics in a table Human readable metrics in a table --- # Write data to InfluxDB Source: https://docs.influxdata.com/influxdb/v2/write-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). 1. Learn the [best practices](/influxdb/v2/write-data/best-practices/) for writing data. 2. Discover how to write data [without coding](/influxdb/v2/write-data/no-code/), by [loading data source in the UI](/influxdb/v2/write-data/no-code/load-data/), or using [developer tools](/influxdb/v2/write-data/developer-tools/). 3. Do any of the following: * [Troubleshoot the most common issues writing data](/influxdb/v2/write-data/troubleshoot/) * [Delete data you no longer need](/influxdb/v2/write-data/delete-data/) * [Query and explore data](/influxdb/v2/query-data/) * [Process data](/influxdb/v2/process-data/) * [Visualize data](/influxdb/v2/visualize-data/) * [Migrate data](/influxdb/cloud/write-data/migrate-data/) * [Monitor and alert](/influxdb/v2/monitor-alert/) The following video discusses different ways to write data to InfluxDB: #### Related * [Use Telegraf to write data](/influxdb/v2/write-data/no-code/use-telegraf/) * [/influxdb/v2/api/write-data/ InfluxDB v1 API /write endpoint](/influxdb/v2/api/write-data/%20InfluxDB%20v1%20API%20/write%20endpoint) * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) * [influx write](/influxdb/v2/reference/cli/influx/write/) * [Migrate data to InfluxDB](/influxdb/v2/write-data/migrate-data/) * [How to Ingest Data in InfluxDB (Video)](/resources/videos/ingest-data/) [write](/influxdb/v2/tags/write/)[line protocol](/influxdb/v2/tags/line-protocol/) --- # Best practices for writing data Source: https://docs.influxdata.com/influxdb/v2/write-data/best-practices/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles provide recommendations and best practices for writing data to InfluxDB. ### [Optimize writes to InfluxDB](/influxdb/v2/write-data/best-practices/optimize-writes/) Simple tips to optimize performance and system overhead when writing data to InfluxDB. ### [Handle duplicate data points](/influxdb/v2/write-data/best-practices/duplicate-points/) InfluxDB identifies unique data points by their measurement, tag set, and timestamp. This article discusses methods for preserving data from two points with a common measurement, tag set, and timestamp but a different field set. ### [InfluxDB schema design](/influxdb/v2/write-data/best-practices/schema-design/) Design your schema for simpler and more performant queries. ### [Resolve high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/) Reduce high series cardinality in InfluxDB. If reads and writes to InfluxDB have started to slow down, you may have high cardinality. Find the source of high cardinality and adjust your schema to resolve high cardinality issues. --- # Handle duplicate data points Source: https://docs.influxdata.com/influxdb/v2/write-data/best-practices/duplicate-points/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB identifies unique data points by their measurement, tag set, and timestamp (each a part of [Line protocol](/influxdb/v2/reference/syntax/line-protocol) used to write data to InfluxDB). ```txt web,host=host2,region=us_west firstByte=15.0 1559260800000000000 --- ------------------------- ------------------- | | | Measurement Tag set Timestamp ``` ## Duplicate data points For points that have the same measurement name, tag set, and timestamp, InfluxDB creates a union of the old and new field sets. For any matching field keys, InfluxDB uses the field value of the new point. For example: ```sh # Existing data point web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 # New data point web,host=host2,region=us_west firstByte=15.0 1559260800000000000 ``` After you submit the new data point, InfluxDB overwrites `firstByte` with the new field value and leaves the field `dnsLookup` alone: ```sh # Resulting data point web,host=host2,region=us_west firstByte=15.0,dnsLookup=7.0 1559260800000000000 ``` ```sh from(bucket: "example-bucket") |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) |> filter(fn: (r) => r._measurement == "web") Table: keys: [_measurement, host, region] _time _measurement host region dnsLookup firstByte -------------------- ------------ ----- ------- --------- --------- 2019-05-31T00:00:00Z web host2 us_west 7 15 ``` ## Preserve duplicate points To preserve both old and new field values in duplicate points, use one of the following strategies: * [Add an arbitrary tag](#add-an-arbitrary-tag) * [Increment the timestamp](#increment-the-timestamp) ### Add an arbitrary tag Add an arbitrary tag with unique values so InfluxDB reads the duplicate points as unique. For example, add a `uniq` tag to each data point: ```sh # Existing point web,host=host2,region=us_west,uniq=1 firstByte=24.0,dnsLookup=7.0 1559260800000000000 # New point web,host=host2,region=us_west,uniq=2 firstByte=15.0 1559260800000000000 ``` > [!Note] > It is not necessary to retroactively add the unique tag to the existing data point. > Tag sets are evaluated as a whole. > The arbitrary `uniq` tag on the new point allows InfluxDB to recognize it as a unique point. > However, this causes the schema of the two points to differ and may lead to challenges when querying the data. After writing the new point to InfluxDB: ```sh from(bucket: "example-bucket") |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) |> filter(fn: (r) => r._measurement == "web") Table: keys: [_measurement, host, region, uniq] _time _measurement host region uniq firstByte dnsLookup -------------------- ------------ ----- ------- ---- --------- --------- 2019-05-31T00:00:00Z web host2 us_west 1 24 7 Table: keys: [_measurement, host, region, uniq] _time _measurement host region uniq firstByte -------------------- ------------ ----- ------- ---- --------- 2019-05-31T00:00:00Z web host2 us_west 2 15 ``` ### Increment the timestamp Increment the timestamp by a nanosecond to enforce the uniqueness of each point. ```sh # Old data point web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 # New data point web,host=host2,region=us_west firstByte=15.0 1559260800000000001 ``` After writing the new point to InfluxDB: ```sh from(bucket: "example-bucket") |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) |> filter(fn: (r) => r._measurement == "web") Table: keys: [_measurement, host, region] _time _measurement host region firstByte dnsLookup ------------------------------ ------------ ----- ------- --------- --------- 2019-05-31T00:00:00.000000000Z web host2 us_west 24 7 2019-05-31T00:00:00.000000001Z web host2 us_west 15 ``` > [!Note] > The output of examples queries in this article has been modified to clearly show > the different approaches and results for handling duplicate data. [best practices](/influxdb/v2/tags/best-practices/)[write](/influxdb/v2/tags/write/) --- # Optimize writes to InfluxDB Source: https://docs.influxdata.com/influxdb/v2/write-data/best-practices/optimize-writes/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use these tips to optimize performance and system overhead when writing data to InfluxDB. * [Batch writes](#batch-writes) * [Sort tags by key](#sort-tags-by-key) * [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible) * [Use gzip compression](#use-gzip-compression) * [Synchronize hosts with NTP](#synchronize-hosts-with-ntp) * [Write multiple data points in one request](#write-multiple-data-points-in-one-request) > [!Note] > The following tools write to InfluxDB and employ *most* write optimizations by default: > > * [Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/) > * [InfluxDB client libraries](/influxdb/v2/api-guide/client-libraries/) > * [InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) ## Batch writes Write data in batches to minimize network overhead when writing data to InfluxDB. > [!Note] > The optimal batch size is 5000 lines of line protocol. ## Sort tags by key Before writing data points to InfluxDB, sort tags by key in lexicographic order.*Verify sort results match results from the [Go `bytes.Compare` function](http://golang.org/pkg/bytes/#Compare).* ```sh # Line protocol example with unsorted tags measurement,tagC=therefore,tagE=am,tagA=i,tagD=i,tagB=think fieldKey=fieldValue 1562020262 # Optimized line protocol example with tags sorted by key measurement,tagA=i,tagB=think,tagC=therefore,tagD=i,tagE=am fieldKey=fieldValue 1562020262 ``` ## Use the coarsest time precision possible By default, InfluxDB writes data in nanosecond 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 precision possible for timestamps. *Specify timestamp precision when [writing to InfluxDB](/influxdb/v2/write-data/#timestamp-precision).* ## Use gzip compression Use gzip compression to speed up writes to InfluxDB and reduce network bandwidth. Benchmarks have shown up to a 5x speed improvement when data is compressed. [Telegraf](#telegraf)[Client libraries](#client-libraries)[InfluxDB API](#influxdb-api) ### Enable gzip compression in Telegraf In the `influxdb_v2` output plugin configuration in your `telegraf.conf`, set the`content_encoding` option to `gzip`: ```toml [[outputs.influxdb_v2]] urls = ["http://localhost:8086"] # ... content_encoding = "gzip" ``` ### Enable gzip compression in InfluxDB client libraries Each [InfluxDB client library](/influxdb/v2/api-guide/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](/influxdb/v2/api-guide/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`. ``` echo "airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630525358 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630525358" | gzip > air-sensors.gzip curl --request POST \ "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=ns" \ --header "Authorization: Token YOUR_API_TOKEN" \ --header "Content-Encoding: gzip" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary @air-sensors.gzip ``` ## 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`). ## Rate limiting Use the [`influx write`](/influxdb/v2/reference/cli/influx/write/) `--rate-limit` flag to control the rate of writes. Use one of the following string formats to specify the rate limit: * `COUNT(B|kB|MB)`, or * `COUNT(B|kB|MB)/TIME(s|sec|m|min)` where `COUNT` is a decimal number and `TIME` is a positive whole number. Spaces in the value are ignored. For example: “5MB / 5min” can be also expressed as `17476.266666667Bs`, `1MB/1min`, `1MB/min`, `1MBmin` or `1MBm`. If the rate limit format is invalid, `influx write` prints out the format and an exact regular expression. The `--rate-limit` flag can be also used with [`influx write dryrun`](/influxdb/v2/reference/cli/influx/write/dryrun/). > [!Important] > By default, the free tier rate limit in InfluxDB Cloud is `1MB/min`. [best practices](/influxdb/v2/tags/best-practices/)[write](/influxdb/v2/tags/write/) --- # Resolve high series cardinality Source: https://docs.influxdata.com/influxdb/v2/write-data/best-practices/resolve-high-cardinality/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). If reads and writes to InfluxDB have started to slow down, high [series cardinality](/influxdb/v2/reference/glossary/#series-cardinality) (too many series) may be causing memory issues. Take steps to understand and resolve high series cardinality. 1. [Learn the causes of high cardinality](#learn-the-causes-of-high-series-cardinality) 2. [Measure series cardinality](#measure-series-cardinality) 3. [Resolve high cardinality](#resolve-high-cardinality) ## Learn the causes of high series cardinality InfluxDB indexes the following data elements to speed up reads: * [measurement](/influxdb/v2/reference/glossary/#measurement) * [tags](/influxdb/v2/reference/glossary/#tag) Each unique set of indexed data elements forms a [series key](/influxdb/v2/reference/glossary/#series-key).[Tags](/influxdb/v2/reference/glossary/#tag) containing highly variable information like unique IDs, hashes, and random strings lead to a large number of [series](/influxdb/v2/reference/glossary/#series), also known as high [series cardinality](/influxdb/v2/reference/glossary/#series-cardinality). High series cardinality is a primary driver of high memory usage for many database workloads. ## Measure series cardinality Use the following to measure series cardinality of your buckets: * [`influxdb.cardinality()`](/flux/v0/stdlib/influxdata/influxdb/cardinality): Flux function that returns the number of unique [series keys](/influxdb/v2/reference/glossary/#series) in your data. * [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality): InfluxQL command that returns the number of unique [series keys](/influxdb/v2/reference/glossary/#series) in your data. ## Resolve high cardinality To resolve high series cardinality, complete the following steps (for multiple buckets if applicable): 1. [Review tags](#review-tags). 2. [Improve your schema](#improve-your-schema). 3. [Delete high cardinality data](#delete-data-to-reduce-high-cardinality). ## Review tags Review your tags to ensure each tag **does not contain** unique values for most entries: * Scan your tags for [common tag issues](#common-tag-issues). * Use the example Flux query below to [count unique tag values](#count-unique-tag-values). ### Common tag issues Look for the following common issues, which often cause many unique tag values: * **Writing log messages to tags**. If a log message includes a unique timestamp, pointer value, or unique string, many unique tag values are created. * **Writing timestamps to tags**. Typically done by accident in client code. * **Unique tag values that grow over time** For example, a user ID tag may work at a small startup, but may begin to cause issues when the company grows to hundreds of thousands of users. ### Count unique tag values The following example Flux query shows you which tags are contributing the most to cardinality. Look for tags with values orders of magnitude higher than others. ```js // Count unique values for each tag in a bucket import "influxdata/influxdb/schema" cardinalityByTag = (bucket) => schema.tagKeys(bucket: bucket) |> map( fn: (r) => ({ tag: r._value, _value: if contains(set: ["_stop", "_start"], value: r._value) then 0 else (schema.tagValues(bucket: bucket, tag: r._value) |> count() |> findRecord(fn: (key) => true, idx: 0))._value, }), ) |> group(columns: ["tag"]) |> sum() cardinalityByTag(bucket: "example-bucket") ``` > [!Note] > If you’re experiencing runaway cardinality, the query above may timeout. If you experience a timeout, run the queries below—one at a time. 1. Generate a list of tags: ``` // Generate a list of tags import "influxdata/influxdb/schema" schema.tagKeys(bucket: "example-bucket") ``` 2. Count unique tag values for each tag: ``` // Run the following for each tag to count the number of unique tag values import "influxdata/influxdb/schema" tag = "example-tag-key" schema.tagValues(bucket: "my-bucket", tag: tag) |> count() ``` These queries should help identify the sources of high cardinality in each of your buckets. To determine which specific tags are growing, check the cardinality again after 24 hours to see if one or more tags have grown significantly. ## Improve your schema To minimize cardinality in the future, design your schema for easy and performant querying. Review [best practices for schema design](/influxdb/v2/write-data/best-practices/schema-design/). ## Delete data to reduce high cardinality Consider whether you need the data that is causing high cardinality. If you no longer need this data, you can [delete the whole bucket](/influxdb/v2/admin/buckets/delete-bucket/) or [delete a range of data](/influxdb/v2/write-data/delete-data/). --- # InfluxDB schema design Source: https://docs.influxdata.com/influxdb/v2/write-data/best-practices/schema-design/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Design your [schema](/influxdb/v2/reference/key-concepts/data-elements/) for simpler and more performant queries. Follow design guidelines to make your schema easy to query. Learn how these guidelines lead to more performant queries. * [Design to query](#design-to-query) * [Keep measurements and keys simple](#keep-measurements-and-keys-simple) * [Use tags and fields](#use-tags-and-fields) * [Use fields for unique and numeric data](#use-fields-for-unique-and-numeric-data) * [Use tags to improve query performance](#use-tags-to-improve-query-performance) * [Keep tags simple](#keep-tags-simple) > [!Note] > Good schema design can prevent high series cardinality, resulting in better performing queries. If you notice data reads and writes slowing down or want to learn how cardinality affects performance, see how to [resolve high cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/). ## Design to query The schemas below demonstrate [measurements](/influxdb/v2/reference/glossary/#measurement), [tag keys](/influxdb/v2/reference/glossary/#tag-key), and [field keys](/influxdb/v2/reference/glossary/#field-key) that are easy to query. | measurement |tag key |tag key|field key| field key | |------------------|--------|-------|---------|-----------| | airSensor |sensorId|station|humidity |temperature| |waterQualitySensor|sensorId|station| pH |temperature| The `airSensor` and `waterQualitySensor` schemas illustrate the following guidelines: * Each measurement is a simple name that describes a schema. * Keys [don’t repeat within a schema](#avoid-duplicate-names-for-tags-and-fields). * Keys [don’t use reserved keywords or special characters](#avoid-keywords-and-special-characters-in-keys). * Tags (`sensorId` and `station`) [store metadata common across many data points](#use-tags-to-improve-query-performance). * Fields (`humidity`, `pH`, and `temperature`) [store numeric data](#use-fields-for-unique-and-numeric-data). * Fields [store unique or highly variable](#use-fields-for-unique-and-numeric-data) data. * Measurements and keys [don’t contain data](#keep-measurements-and-keys-simple); tag values and field values will store data. The following points (formatted as line protocol) use the `airSensor` and `waterQualitySensor` schemas: ``` airSensor,sensorId=A0100,station=Harbor humidity=35.0658,temperature=21.667 1636729543000000000 waterQualitySensor,sensorId=W0101,station=Harbor pH=6.1,temperature=16.103 1472515200000000000 ``` ### Keep measurements and keys simple Store data in [tag values](/influxdb/v2/reference/glossary/#tag-value) or [field values](/influxdb/v2/reference/glossary/#field-value), not in [tag keys](/influxdb/v2/reference/glossary/#tag-key), [field keys](/influxdb/v2/reference/glossary/#field-key), or [measurements](/influxdb/v2/reference/glossary/#measurement). If you design your schema to store data in tag and field values, your queries will be easier to write and more efficient. In addition, you’ll keep cardinality low by not creating measurements and keys as you write data. To learn more about the performance impact of high series cardinality, see how to [resolve high cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/). #### Compare schemas Compare the following valid schemas represented by line protocol. **Recommended**: the following schema stores metadata in separate `crop`, `plot`, and `region` tags. The `temp` field contains variable numeric data. ##### ``` ## Good Measurements schema - Data encoded in tags (recommended) weather_sensor,crop=blueberries,plot=1,region=north temp=50.1 1472515200000000000 weather_sensor,crop=blueberries,plot=2,region=midwest temp=49.8 1472515200000000000 ``` **Not recommended**: the following schema stores multiple attributes (`crop`, `plot` and `region`) concatenated (`blueberries.plot-1.north`) within the measurement, similar to Graphite metrics. ##### ``` ## Bad Measurements schema - Data encoded in the measurement (not recommended) blueberries.plot-1.north temp=50.1 1472515200000000000 blueberries.plot-2.midwest temp=49.8 1472515200000000000 ``` **Not recommended**: the following schema stores multiple attributes (`crop`, `plot` and `region`) concatenated (`blueberries.plot-1.north`) within the field key. ##### ``` ## Bad Keys schema - Data encoded in field keys (not recommended) weather_sensor blueberries.plot-1.north.temp=50.1 1472515200000000000 weather_sensor blueberries.plot-2.midwest.temp=49.8 1472515200000000000 ``` #### Compare queries Compare the following queries of the [*Good Measurements*](#good-measurements-schema) and [*Bad Measurements*](#bad-measurements-schema) schemas. The [Flux](/flux/v0/) queries calculate the average `temp` for blueberries in the `north` region **Easy to query**: [*Good Measurements*](#good-measurements-schema) data is easily filtered by `region` tag values, as in the following example. ```js // Query *Good Measurements*, data stored in separate tags (recommended) from(bucket:"example-bucket") |> range(start:2016-08-30T00:00:00Z) |> filter(fn: (r) => r._measurement == "weather_sensor" and r.region == "north" and r._field == "temp") |> mean() ``` **Difficult to query**: [*Bad Measurements*](#bad-measurements-schema) requires regular expressions to extract `plot` and `region` from the measurement, as in the following example. ```js // Query *Bad Measurements*, data encoded in the measurement (not recommended) from(bucket:"example-bucket") |> range(start:2016-08-30T00:00:00Z) |> filter(fn: (r) => r._measurement =~ /\.north$/ and r._field == "temp") |> mean() ``` Complex measurements make some queries impossible. For example, calculating the average temperature of both plots is not possible with the [*Bad Measurements*](#bad-measurements-schema) schema. #### Keep keys simple In addition to keeping your keys free of data, follow these additional guidelines to make them easier to query: * [Avoid keywords and special characters](#avoid-keywords-and-special-characters-in-keys) * [Avoid duplicate names for tags and fields](#avoid-duplicate-names-for-tags-and-fields) ##### Avoid keywords and special characters in keys To simplify query writing, don’t include reserved keywords or special characters in tag and field keys. If you use [Flux keywords](/flux/v0/spec/lexical-elements/#keywords) in keys, then you’ll have to wrap the keys in double quotes. If you use non-alphanumeric characters in keys, then you’ll have to use [bracket notation](/flux/v0/data-types/composite/record/#bracket-notation) in [Flux](/flux/v0/). ##### Avoid duplicate names for tags and fields Avoid using the same name for a [tag key](/influxdb/v2/reference/glossary/#tag-key) and a [field key](/influxdb/v2/reference/glossary/#field-key) within the same schema. Your query results may be unpredictable if you have a tag and a field with the same name. ## Use tags and fields [Tag values](/influxdb/v2/reference/glossary/#tag-value) are indexed and [field values](/influxdb/v2/reference/glossary/#field-value) aren’t. This means that querying tags is more performant than querying fields. Your queries should guide what you store in tags and what you store in fields. ### Use fields for unique and numeric data * Store unique or frequently changing values as field values. * Store numeric values as field values. ([Tags](/influxdb/v2/reference/glossary/#tag-value) only store strings). ### Use tags to improve query performance * Store values as tag values if they can be reasonably indexed. * Store values as [tag values](/influxdb/v2/reference/glossary/#tag-value) if the values are used in [filter()](/flux/v0/universe/filter/) or [group()](/flux/v0/universe/group/) functions. * Store values as tag values if the values are shared across multiple data points, i.e. metadata about the field. Because InfluxDB indexes tags, the query engine doesn’t need to scan every record in a bucket to locate a tag value. For example, consider a bucket that stores data about thousands of users. With `userId` stored in a [field](/influxdb/v2/reference/glossary/#field), a query for user `abcde` requires InfluxDB to scan `userId` in every row. ```js from(bucket: "example-bucket") |> range(start: -7d) |> filter(fn: (r) => r._field == "userId" and r._value == "abcde") ``` To retrieve data more quickly, filter on a tag to reduce the number of rows scanned. The tag should store data that can be reasonably indexed. The following query filters by the `company` tag to reduce the number of rows scanned for `userId`. ```js from(bucket: "example-bucket") |> range(start: -7d) |> filter(fn: (r) => r.company == "Acme") |> filter(fn: (r) => r._field == "userId" and r._value == "abcde") ``` ### Keep tags simple Use one tag for each data attribute. If your source data contains multiple data attributes in a single parameter, split each attribute into its own tag. When each tag 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. #### Compare schemas Compare the following valid schemas represented by line protocol. **Recommended**: the following schema splits location data into `plot` and `region` tags. ##### ``` ## Good Tags schema - Data encoded in multiple tags weather_sensor,crop=blueberries,plot=1,region=north temp=50.1 1472515200000000000 weather_sensor,crop=blueberries,plot=2,region=midwest temp=49.8 1472515200000000000 ``` **Not recommended**: the following schema stores multiple attributes (`plot` and `region`) concatenated within the `location` tag value (`plot-1.north`). ##### ``` ## Bad Tags schema - Multiple data encoded in a single tag weather_sensor,crop=blueberries,location=plot-1.north temp=50.1 1472515200000000000 weather_sensor,crop=blueberries,location=plot-2.midwest temp=49.8 1472515200000000000 ``` #### Compare queries Compare queries of the [*Good Tags*](#good-tags-schema) and [*Bad Tags*](#bad-tags-schema) schemas. The [Flux](/flux/v0/) queries calculate the average `temp` for blueberries in the `north` region. **Easy to query**: [*Good Tags*](#good-tags-schema) data is easily filtered by `region` tag values, as in the following example. ```js // Query *Good Tags* schema, data encoded in multiple tags from(bucket:"example-bucket") |> range(start:2016-08-30T00:00:00Z) |> filter(fn: (r) => r._measurement == "weather_sensor" and r.region == "north" and r._field == "temp") |> mean() ``` **Difficult to query**: [*Bad Tags*](#bad-tags-schema) requires regular expressions to parse the complex `location` values, as in the following example. ```js // Query *Bad Tags* schema, multiple data encoded in a single tag from(bucket:"example-bucket") |> range(start:2016-08-30T00:00:00Z) |> filter(fn: (r) => r._measurement == "weather_sensor" and r.location =~ /\.north$/ and r._field == "temp") |> mean() ``` For an overview of the InfluxDB data model, watch the following video: #### Related * [InfluxDB data elements](/influxdb/v2/reference/key-concepts/data-elements/) * [Building Blocks of the InfluxDB Data Model](/resources/videos/data-model-building-blocks/) | measurement | tag key | tag key | field key | field key | | --- | --- | --- | --- | --- | | measurement | tag key | tag key | field key | field key | | airSensor | sensorId | station | humidity | temperature | | waterQualitySensor | sensorId | station | pH | temperature | --- # Delete data Source: https://docs.influxdata.com/influxdb/v2/write-data/delete-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the InfluxDB API[`/api/v2/delete`](/influxdb/v2/api/delete/) endpoint to delete data from an InfluxDB bucket. * [Delete data using the influx CLI](#delete-data-using-the-influx-cli) * [Delete data using the API](#delete-data-using-the-api) InfluxDB 2.10 supports deleting data by the following: * time range * measurement (`_measurement`) * tag #### Cannot delete data by field InfluxDB 2.10 does not support deleting data **by field**. Once a delete request completes successfully, the deleted data is no longer queryable, but will remain on disk until the compaction service runs. ## Delete data using the influx CLI > [!Note] > Use [InfluxDB CLI connection configurations](/influxdb/v2/reference/cli/influx/config/)to provide your **InfluxDB host, organization, and API token**. 1. Use the [`influx delete` command](/influxdb/v2/reference/cli/influx/delete/) to delete points from InfluxDB. 2. Use the `--bucket` flag to specify which bucket to delete data from. 3. Use the `--start` and `--stop` flags to define the time range to delete data from. Use [RFC3339 timestamps](/influxdb/v2/reference/glossary/#rfc3339-timestamp). 4. *(Optional)* Use the `-p`, `--predicate` flag to include a [delete predicate](/influxdb/v2/reference/syntax/delete-predicate)that identifies which points to delete. Deleting data without a [delete predicate](/influxdb/v2/reference/syntax/delete-predicate)deletes all data in the specified bucket with timestamps between the specified `start` and `stop` times. ### Examples * [Delete points in a specific measurement with a specific tag value](#delete-points-in-a-specific-measurement-with-a-specific-tag-value) * [Delete all points in a specified time range](#delete-all-points-in-a-specified-time-range) ##### Delete points in a specific measurement with a specific tag value ```sh influx delete --bucket example-bucket \ --start '1970-01-01T00:00:00Z' \ --stop $(date -u +"%Y-%m-%dT%H:%M:%SZ") \ --predicate '_measurement="example-measurement" AND exampleTag="exampleTagValue"' ``` ##### Delete all points in a specified time range ```sh influx delete --bucket example-bucket \ --start 2020-03-01T00:00:00Z \ --stop 2020-11-14T00:00:00Z ``` ## Delete data using the API Use the InfluxDB API [`/api/v2/delete` endpoint](/influxdb/v2/api/delete/)to delete points from InfluxDB. ``` POST http://localhost:8086/api/v2/delete ``` Include the following: * **Request method:** `POST` * **Headers:** * **Authorization:** `Token` schema with your InfluxDB API token * **Content-type:** `application/json` * **Query parameters:** * **org** or **orgID:** organization name or [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * **bucket** or **bucketID:** bucket name or [bucket ID](/influxdb/v2/admin/buckets/view-buckets/) * **Request body:** JSON object with the following fields: \* Required * \* **start:** earliest time to delete data from ([RFC3339](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) * \* **stop:** latest time to delete data from ([RFC3339](/influxdb/v2/reference/glossary/#rfc3339-timestamp)) * **predicate:** [delete predicate](/influxdb/v2/reference/syntax/delete-predicate) statement Deleting data without a [delete predicate](/influxdb/v2/reference/syntax/delete-predicate)deletes all data in the specified bucket with timestamps between the specified `start` and `stop` times. ### Examples * [Delete points in a specific measurement with a specific tag value](#delete-points-in-a-specific-measurement-with-a-specific-tag-value-1) * [Delete all points in a specified time range](#delete-all-points-in-a-specified-time-range-1) ##### Delete points in a specific measurement with a specific tag value ```sh curl --request POST http://localhost:8086/api/v2/delete?org=example-org&bucket=example-bucket \ --header 'Authorization: Token YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "start": "2020-03-01T00:00:00Z", "stop": "2020-11-14T00:00:00Z", "predicate": "_measurement=\"example-measurement\" AND exampleTag=\"exampleTagValue\"" }' ``` ##### Delete all points in a specified time range ```sh curl --request POST http://localhost:8086/api/v2/delete?org=example-org&bucket=example-bucket \ --header 'Authorization: Token YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "start": "2020-03-01T00:00:00Z", "stop": "2020-11-14T00:00:00Z" }' ``` *For more information, see the [`/api/v2/delete` endpoint documentation](/influxdb/v2/api/delete/).* To delete a bucket see [Delete a bucket](/influxdb/v2/admin/buckets/delete-bucket/). #### Related * [Delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/) * [influx delete](/influxdb/v2/reference/cli/influx/delete/) * [Delete a bucket](/influxdb/v2/admin/buckets/delete-bucket/) [delete](/influxdb/v2/tags/delete/) --- # Write data with developer tools Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Write data to InfluxDB with developer tools. ### [Write data with third-party technologies](/influxdb/v2/write-data/developer-tools/third-party-solutions/) Write data to InfluxDB using third-party developer tools. ### [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/) Write CSV data with the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/) or Flux. Include annotations with the CSV data to determine how the data translates into [line protocol](/influxdb/v2/reference/syntax/line-protocol/). ### [Write data with client libraries](/influxdb/v2/write-data/developer-tools/client-libraries/) Use client libraries to write data to InfluxDB. ### [Scrape Prometheus metrics](/influxdb/v2/write-data/developer-tools/scrape-prometheus-metrics/) Use Telegraf, InfluxDB scrapers, or the `prometheus.scrape` Flux function to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and store them in InfluxDB. ### [Write data with the influx CLI](/influxdb/v2/write-data/developer-tools/influx-cli/) Use the `influx write` command to write data to InfluxDB from the command line. ### [Write data with the InfluxDB API](/influxdb/v2/write-data/developer-tools/api/) Use the `/api/v2/write` InfluxDB API endpoint to write data to InfluxDB. --- # Write data with the InfluxDB API Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/api/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Write data to InfluxDB using an HTTP request to the InfluxDB API `/api/v2/write` endpoint. Use the `POST` request method and include the following in your request: | Requirement | Include by | |-------------------|------------------------------------------------------------------------| | Organization | Use the `org` query parameter in your request URL. | | Bucket | Use the `bucket` query parameter in your request URL. | |Timestamp precision|Use the `precision`query parameter in your request URL. Default is `ns`.| | API token | Use the `Authorization: Token YOUR_API_TOKEN` header. | | Line protocol | Pass as plain text in your request body. | #### Send a write request The URL in the examples depends on the version and location of your InfluxDB 2.10 instance.[Customize URLs in examples](#) [cURL](#curl)[Node.js](#nodejs) ```sh curl --request POST \ "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=ns" \ --header "Authorization: Token YOUR_API_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary ' airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000 ' ``` ```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' /** Environment variables **/ const url = process.env.INFLUX_URL const token = process.env.INFLUX_TOKEN const org = process.env.INFLUX_ORG const bucket = process.env.INFLUX_BUCKET /** * Instantiate the InfluxDB client * with a configuration object. **/ const influxDB = new InfluxDB({ url, token }) /** * Create a write client from the getWriteApi method. * Provide your `org` and `bucket`. **/ const writeApi = influxDB.getWriteApi(org, bucket) /** * 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') }) ``` > [!Note] > ##### 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`. > Compression reduces network bandwidth, but increases server-side load. > > ``` > echo "airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630525358 > airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630525358" | gzip > air-sensors.gzip > > curl --request POST \ > "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=ns" \ > --header "Authorization: Token YOUR_API_TOKEN" \ > --header "Content-Encoding: gzip" \ > --header "Content-Type: text/plain; charset=utf-8" \ > --header "Accept: application/json" \ > --data-binary @air-sensors.gzip > ``` *For information about **InfluxDB API response codes**, see[InfluxDB API Write documentation](/influxdb/v2/api/write-data/).* | Requirement | Include by | | --- | --- | | Requirement | Include by | | Organization | Use the org query parameter in your request URL. | | Bucket | Use the bucket query parameter in your request URL. | | Timestamp precision | Use the precision query parameter in your request URL. Default is ns . | | API token | Use the Authorization: Token YOUR_API_TOKEN header. | | Line protocol | Pass as plain text in your request body. | --- # Write data with client libraries Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/client-libraries/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use language-specific client libraries to integrate with the InfluxDB v2 API. See [Client libraries reference](/influxdb/v2/api-guide/client-libraries/) for more information. --- # Write CSV data to InfluxDB Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/csv/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Write CSV data with the following methods: * [Upload a file or manually paste data in the UI](/influxdb/cloud/write-data/no-code/load-data/#load-data-by-uploading-a-csv-or-line-protocol-file) * [influx write command](#influx-write-command) * [Telegraf](#telegraf) * [Flux](#flux) ## influx write command Use the [`influx write` command](/influxdb/v2/reference/cli/influx/write/) to write CSV data to InfluxDB. Include [Extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended/)annotations to specify how the data translates into [line protocol](/influxdb/v2/reference/syntax/line-protocol/). Include annotations in the CSV file or inject them using the `--header` flag of the `influx write` command. ##### On this page * [CSV Annotations](#csv-annotations) * [Inject annotation headers](#inject-annotation-headers) * [Skip annotation headers](#skip-annotation-headers) * [Process input as CSV](#process-input-as-csv) * [Specify CSV character encoding](#specify-csv-character-encoding) * [Skip rows with errors](#skip-rows-with-errors) * [Advanced examples](#advanced-examples) ##### Example write command ```sh influx write -b example-bucket -f path/to/example.csv ``` ##### example.csv ``` #datatype measurement,tag,double,dateTime:RFC3339 m,host,used_percent,time mem,host1,64.23,2020-01-01T00:00:00Z mem,host2,72.01,2020-01-01T00:00:00Z mem,host1,62.61,2020-01-01T00:00:10Z mem,host2,72.98,2020-01-01T00:00:10Z mem,host1,63.40,2020-01-01T00:00:20Z mem,host2,73.77,2020-01-01T00:00:20Z ``` ##### Resulting line protocol ``` mem,host=host1 used_percent=64.23 1577836800000000000 mem,host=host2 used_percent=72.01 1577836800000000000 mem,host=host1 used_percent=62.61 1577836810000000000 mem,host=host2 used_percent=72.98 1577836810000000000 mem,host=host1 used_percent=63.40 1577836820000000000 mem,host=host2 used_percent=73.77 1577836820000000000 ``` > [!Note] > To test the CSV to line protocol conversion process, use the `influx write dryrun`command to print the resulting line protocol to stdout rather than write to InfluxDB. > [!Note] > ##### “too many open files” errors > > When attempting to write large amounts of CSV data into InfluxDB, you might see an error like the following: > > ``` > Error: Failed to write data: unexpected error writing points to database: [shard <#>] fcntl: too many open files. > ``` > > To fix this error on Linux or macOS, run the following command to increase the number of open files allowed: > > ``` > ulimit -n 10000 > ``` > > macOS users, to persist the `ulimit` setting, follow the [recommended steps](https://unix.stackexchange.com/a/221988/471569) for your operating system version. ## Telegraf Use CSV data format in Telegraf as a way to write CSV data to InfluxDB. For more information, see: * [CSV input data format](/telegraf/v1/data_formats/input/csv/) * [Use Telegraf to write data](/influxdb/v2/write-data/no-code/use-telegraf/) ## CSV Annotations Use **CSV annotations** to specify which element of line protocol each CSV column represents and how to format the data. CSV annotations are rows at the beginning of a CSV file that describe column properties. The `influx write` command supports [Extended annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/extended)which provides options for specifying how CSV data should be converted into line protocol and how data is formatted. To write data to InfluxDB, data must include the following: * [measurement](/influxdb/v2/reference/syntax/line-protocol/#measurement) * [field set](/influxdb/v2/reference/syntax/line-protocol/#field-set) * [timestamp](/influxdb/v2/reference/syntax/line-protocol/#timestamp) *(Optional but recommended)* * [tag set](/influxdb/v2/reference/syntax/line-protocol/#tag-set) *(Optional)* Use CSV annotations to specify which of these elements each column represents. ## Write raw query results back to InfluxDB Flux returns query results in [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/). These results include all annotations necessary to write the data back to InfluxDB. ## Inject annotation headers If the CSV data you want to write to InfluxDB does not contain the annotations required to properly convert the data to line protocol, use the `--header` flag to inject annotation rows into the CSV data. ```sh influx write -b example-bucket \ -f path/to/example.csv \ --header "#constant measurement,birds" \ --header "#datatype dateTime:2006-01-02,long,tag" ``` ##### example.csv ``` date,sighted,loc 2020-01-01,12,Boise 2020-06-01,78,Boise 2020-01-01,54,Seattle 2020-06-01,112,Seattle 2020-01-01,9,Detroit 2020-06-01,135,Detroit ``` ##### Resulting line protocol ``` birds,loc=Boise sighted=12i 1577836800000000000 birds,loc=Boise sighted=78i 1590969600000000000 birds,loc=Seattle sighted=54i 1577836800000000000 birds,loc=Seattle sighted=112i 1590969600000000000 birds,loc=Detroit sighted=9i 1577836800000000000 birds,loc=Detroit sighted=135i 1590969600000000000 ``` #### Use files to inject headers The `influx write` command supports importing multiple files in a single command. Include annotations and header rows in their own file and import them with the write command. Files are read in the order in which they’re provided. ```sh influx write -b example-bucket \ -f path/to/headers.csv \ -f path/to/example.csv ``` ##### headers.csv ``` #constant measurement,birds #datatype dateTime:2006-01-02,long,tag ``` ##### example.csv ``` date,sighted,loc 2020-01-01,12,Boise 2020-06-01,78,Boise 2020-01-01,54,Seattle 2020-06-01,112,Seattle 2020-01-01,9,Detroit 2020-06-01,135,Detroit ``` ##### Resulting line protocol ``` birds,loc=Boise sighted=12i 1577836800000000000 birds,loc=Boise sighted=78i 1590969600000000000 birds,loc=Seattle sighted=54i 1577836800000000000 birds,loc=Seattle sighted=112i 1590969600000000000 birds,loc=Detroit sighted=9i 1577836800000000000 birds,loc=Detroit sighted=135i 1590969600000000000 ``` ## Skip annotation headers Some CSV data may include header rows that conflict with or lack the annotations necessary to write CSV data to InfluxDB. Use the `--skipHeader` flag to specify the **number of rows to skip** at the beginning of the CSV data. ```sh influx write -b example-bucket \ -f path/to/example.csv \ --skipHeader=2 ``` You can then [inject new header rows](#inject-annotation-headers) to rename columns and provide the necessary annotations. ## Process input as CSV The `influx write` command automatically processes files with the `.csv` extension as CSV files. If your CSV file uses a different extension, use the `--format` flat to explicitly declare the format of the input file. ```sh influx write -b example-bucket \ -f path/to/example.txt \ --format csv ``` > [!Note] > The `influx write` command assumes all input files are line protocol unless they > include the `.csv` extension or you declare the `csv`. ## Specify CSV character encoding The `influx write` command assumes CSV files contain UTF-8 encoded characters. If your CSV data uses different character encoding, specify the encoding with the `--encoding`. ```sh influx write -b example-bucket \ -f path/to/example.csv \ --encoding "UTF-16" ``` ## Skip rows with errors If a row in your CSV data is missing an[element required to write to InfluxDB](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)or data is incorrectly formatted, when processing the row, the `influx write` command returns an error and cancels the write request. To skip rows with errors, use the `--skipRowOnError` flag. ```sh influx write -b example-bucket \ -f path/to/example.csv \ --skipRowOnError ``` Skipped rows are ignored and are not written to InfluxDB. Use the `--errors-file` flag to record errors to a file. The error file identifies all rows that cannot be imported and includes error messages for debugging. For example: ```error cpu,1.1 ``` ## Advanced examples * [Define constants](#define-constants) * [Annotation shorthand](#annotation-shorthand) * [Ignore columns](#ignore-columns) * [Use alternate numeric formats](#use-alternate-numeric-formats) * [Use alternate boolean format](#use-alternate-boolean-format) * [Use different timestamp formats](#use-different-timestamp-formats) ### Define constants Use the Extended annotated CSV [`#constant` annotation](/influxdb/v2/reference/syntax/annotated-csv/extended/#constant)to add a column and value to each row in the CSV data. ##### CSV with constants ``` #constant measurement,example #constant tag,source,csv #datatype long,dateTime:RFC3339 count,time 1,2020-01-01T00:00:00Z 4,2020-01-02T00:00:00Z 9,2020-01-03T00:00:00Z 18,2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example,source=csv count=1 1577836800000000000 example,source=csv count=4 1577923200000000000 example,source=csv count=9 1578009600000000000 example,source=csv count=18 1578096000000000000 ``` ### Annotation shorthand Extended annotated CSV supports [annotation shorthand](/influxdb/v2/reference/syntax/annotated-csv/extended/#annotation-shorthand), which lets you define the **column label**, **datatype**, and **default value** in the column header. ##### CSV with annotation shorthand ``` m|measurement,count|long|0,time|dateTime:RFC3339 example,1,2020-01-01T00:00:00Z example,4,2020-01-02T00:00:00Z example,,2020-01-03T00:00:00Z example,18,2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example count=1 1577836800000000000 example count=4 1577923200000000000 example count=0 1578009600000000000 example count=18 1578096000000000000 ``` #### Replace column header with annotation shorthand It’s possible to replace the column header row in a CSV file with annotation shorthand without modifying the CSV file. This lets you define column data types and default values while writing to InfluxDB. To replace an existing column header row with annotation shorthand: 1. Use the `--skipHeader` flag to ignore the existing column header row. 2. Use the `--header` flag to inject a new column header row that uses annotation shorthand. ```sh influx write -b example-bucket \ -f example.csv \ --skipHeader=1 --header="m|measurement,count|long|0,time|dateTime:RFC3339" ``` ##### Unmodified example.csv ``` m,count,time example,1,2020-01-01T00:00:00Z example,4,2020-01-02T00:00:00Z example,,2020-01-03T00:00:00Z example,18,2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example count=1i 1577836800000000000 example count=4i 1577923200000000000 example count=0i 1578009600000000000 example count=18i 1578096000000000000 ``` ### Ignore columns Use the Extended annotated CSV [`#datatype ignored` annotation](/influxdb/v2/reference/syntax/annotated-csv/extended/#ignored)to ignore columns when writing CSV data to InfluxDB. ##### CSV data with ignored column ``` #datatype measurement,long,time,ignored m,count,time,foo example,1,2020-01-01T00:00:00Z,bar example,4,2020-01-02T00:00:00Z,bar example,9,2020-01-03T00:00:00Z,baz example,18,2020-01-04T00:00:00Z,baz ``` ##### Resulting line protocol ``` m count=1i 1577836800000000000 m count=4i 1577923200000000000 m count=9i 1578009600000000000 m count=18i 1578096000000000000 ``` ### Use alternate numeric formats If your CSV data contains numeric values that use a non-default fraction separator (`.`) or contain group separators, [define your numeric format](/influxdb/v2/reference/syntax/annotated-csv/extended/#double)in the `double`, `long`, and `unsignedLong` datatype annotations. > [!Note] > If your **numeric format separators** include a comma (`,`), wrap the column annotation in double > quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. > You can also [define a custom column separator](/influxdb/v2/reference/syntax/annotated-csv/extended/#define-custom-column-separator). [Floats](#floats)[Integers](#integers)[Uintegers](#uintegers) ##### CSV with non-default float values ``` #datatype measurement,"double:.,",dateTime:RFC3339 m,lbs,time example,"1,280.7",2020-01-01T00:00:00Z example,"1,352.5",2020-01-02T00:00:00Z example,"1,862.8",2020-01-03T00:00:00Z example,"2,014.9",2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example lbs=1280.7 1577836800000000000 example lbs=1352.5 1577923200000000000 example lbs=1862.8 1578009600000000000 example lbs=2014.9 1578096000000000000 ``` ##### CSV with non-default integer values ``` #datatype measurement,"long:.,",dateTime:RFC3339 m,lbs,time example,"1,280.0",2020-01-01T00:00:00Z example,"1,352.0",2020-01-02T00:00:00Z example,"1,862.0",2020-01-03T00:00:00Z example,"2,014.9",2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example lbs=1280i 1577836800000000000 example lbs=1352i 1577923200000000000 example lbs=1862i 1578009600000000000 example lbs=2014i 1578096000000000000 ``` ##### CSV with non-default uinteger values ``` #datatype measurement,"unsignedLong:.,",dateTime:RFC3339 m,lbs,time example,"1,280.0",2020-01-01T00:00:00Z example,"1,352.0",2020-01-02T00:00:00Z example,"1,862.0",2020-01-03T00:00:00Z example,"2,014.9",2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example lbs=1280u 1577836800000000000 example lbs=1352u 1577923200000000000 example lbs=1862u 1578009600000000000 example lbs=2014u 1578096000000000000 ``` ### Use alternate boolean format Line protocol supports only [specific boolean values](/influxdb/v2/reference/syntax/line-protocol/#boolean). If your CSV data contains boolean values that line protocol does not support,[define your boolean format](/influxdb/v2/reference/syntax/annotated-csv/extended/#boolean)in the `boolean` datatype annotation. ##### CSV with non-default boolean values ``` #datatype measurement,"boolean:y,Y,1:n,N,0",dateTime:RFC3339 m,verified,time example,y,2020-01-01T00:00:00Z example,n,2020-01-02T00:00:00Z example,1,2020-01-03T00:00:00Z example,N,2020-01-04T00:00:00Z ``` ##### Resulting line protocol ``` example verified=true 1577836800000000000 example verified=false 1577923200000000000 example verified=true 1578009600000000000 example verified=false 1578096000000000000 ``` ### Use different timestamp formats The `influx write` command automatically detects **RFC3339** and **number** formatted timestamps when converting CSV to line protocol. If using a different timestamp format, [define your timestamp format](/influxdb/v2/reference/syntax/annotated-csv/extended/#datetime)in the `dateTime` datatype annotation. ##### CSV with non-default timestamps ``` #datatype measurement,dateTime:2006-01-02,field m,time,lbs example,2020-01-01,1280.7 example,2020-01-02,1352.5 example,2020-01-03,1862.8 example,2020-01-04,2014.9 ``` ##### Resulting line protocol ``` example lbs=1280.7 1577836800000000000 example lbs=1352.5 1577923200000000000 example lbs=1862.8 1578009600000000000 example lbs=2014.9 1578096000000000000 ``` ## Flux Use the [csv.from()](/flux/v0/stdlib/csv/from/) and [to()](/flux/v0/stdlib/influxdata/influxdb/to/) Flux functions to write an annotated CSV to the bucket of your choice. The experimental [csv.from()](/flux/v0/stdlib/csv/from/) function lets you write CSV from a URL. The example below writes [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data) to an example `noaa` bucket in an example organization: ```js import "experimental/csv" csv.from(url: "https://influx-testdata.s3.amazonaws.com/noaa.csv") |> to(bucket: "noaa", org: "example-org") ``` > [!Note] > #### Required annotations and columns > > To write CSV data to InfluxDB with Flux, you must include *all* of the following annotations and columns: > > * `datatype` > * `group` > * `default` > > See [annotations](/influxdb/v2/reference/syntax/annotated-csv/#annotations) for more information. > With Flux, you must also include a comma between the annotation name and the annotation values (this differs from the `influx write` command). > See an example of valid syntax for [annotated CSV in Flux](/influxdb/v2/reference/syntax/annotated-csv/#annotated-csv-in-flux). > > Required columns: > > * `_time` > * `_measurement` > * `_field` > * `_value` #### Related * [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) * [influx write](/influxdb/v2/reference/cli/influx/write/) --- # Write data with the influx CLI Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/influx-cli/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To write data from the command line, use the [`influx write` command](/influxdb/v2/reference/cli/influx/write/). Include the following in your command: |Requirement | Include by | |------------|--------------------------------------------------------------------------------------------------| |Organization| Use the `-o`,`--org`, or `--org-id` flags. | | Bucket | Use the `-b`, `--bucket`, or `--bucket-id` flags. | | Precision | Use the `-p`, `--precision` flag. | | API token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | | Data |Write data using **line protocol** or **annotated CSV**. Pass a file with the `-f`, `--file` flag.| *See [Line protocol](/influxdb/v2/reference/syntax/line-protocol/) and [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv)* #### Example influx write commands ##### Write a single line of line protocol ```sh influx write \ -b bucketName \ -o orgName \ -p s \ 'myMeasurement,host=myHost testField="testData" 1556896326' ``` ##### Write line protocol from a file ```sh influx write \ -b bucketName \ -o orgName \ -p s \ --format=lp -f /path/to/line-protocol.txt ``` ##### Write annotated CSV from a file ```sh influx write \ -b bucketName \ -o orgName \ -p s \ --format=csv -f /path/to/data.csv ``` #### Related * [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/) | Requirement | Include by | | --- | --- | | Requirement | Include by | | Organization | Use the -o , --org , or --org-id flags. | | Bucket | Use the -b , --bucket , or --bucket-id flags. | | Precision | Use the -p , --precision flag. | | API token | Set the INFLUX_TOKEN environment variable or use the t , --token flag. | | Data | Write data using line protocol or annotated CSV . Pass a file with the -f , --file flag. | --- # Scrape Prometheus metrics Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/scrape-prometheus-metrics/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use [Telegraf](/telegraf/v1/), [InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/), or the [`prometheus.scrape` Flux function](/flux/v0/stdlib/experimental/prometheus/scrape/)to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and store them in InfluxDB. * [Use Telegraf](#use-telegraf) * [Use an InfluxDB scraper](#use-an-influxdb-scraper) * [Use prometheus.scrape()](#use-prometheusscrape) ## Use Telegraf To use Telegraf to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and write them to InfluxDB , follow these steps: 1. Add the [Prometheus input plugin](/telegraf/v1/plugins/#input-prometheus) to your Telegraf configuration file. 1. Set the `urls` to scrape metrics from. 2. Set the `metric_version` configuration option to specify which[metric parsing version](/influxdb/v2/reference/prometheus-metrics/) to use*(version `2` is recommended)*. 2. Add the [InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2)to your Telegraf configuration file and configure it to write to InfluxDB . ##### Example telegraf.conf ```toml # ... ## Collect Prometheus formatted metrics [[inputs.prometheus]] urls = ["http://example.com/metrics"] metric_version = 2 ## Write Prometheus formatted metrics to InfluxDB [[outputs.influxdb_v2]] urls = ["http://localhost:8086"] token = "$INFLUX_TOKEN" organization = "example-org" bucket = "example-bucket" # ... ``` ## Use an InfluxDB scraper InfluxDB scrapers automatically scrape Prometheus-formatted metrics from an HTTP-accessible endpoint at a regular interval. For information about setting up an InfluxDB scraper, see[Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/). ## Use prometheus.scrape() To use the [`prometheus.scrape()` Flux function](/flux/v0/stdlib/experimental/prometheus/scrape/)to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and write them to InfluxDB , do the following in your Flux script: 1. Import the [`experimental/prometheus` package](/flux/v0/stdlib/experimental/prometheus/). 2. Use `prometheus.scrape()` and provide the URL to scrape metrics from. 3. Use [`to()`](/flux/v0/stdlib/influxdata/influxdb/to/) and specify the InfluxDB bucket to write the scraped metrics to. ##### Example Flux script ```js import "experimental/prometheus" prometheus.scrape(url: "http://example.com/metrics") |> to(bucket: "example-bucket") ``` 1. (Optional) To scrape Prometheus metrics at regular intervals using Flux, add your Flux scraping script as an [InfluxDB task](/influxdb/v2/process-data/). *For information about scraping Prometheus-formatted metrics with `prometheus.scrape()`, see [Scrape Prometheus metrics with Flux](/flux/v0/prometheus/scrape-prometheus/).* #### Related * [Telegraf Prometheus input plugin](/telegraf/v1/plugins/#input-prometheus) * [Scrape Prometheus metrics with Flux](/flux/v0/prometheus/scrape-prometheus/) * [prometheus.scrape() function](/flux/v0/stdlib/experimental/prometheus/scrape/) * [Work with Prometheus metric types](/flux/v0/prometheus/metric-types/) * [Prometheus metric parsing formats](/influxdb/v2/reference/prometheus-metrics/) * [Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) [prometheus](/influxdb/v2/tags/prometheus/)[scraper](/influxdb/v2/tags/scraper/) --- # Write data with third-party technologies Source: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/third-party-solutions/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Configure third-party technologies to send line protocol directly to InfluxDB. ## AWS Lambda via CloudFormation template Write to InfluxDB with AWS Lambda, Amazon Web Services’ serverless offering. This example provides a CloudFormation template that collects earthquake from the [United States Geological Survey (USGS)](https://www.usgs.gov/) every hour and outputs it as line protocol into an InfluxDB bucket. The [template](https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml) contains the following sections: * Lines 1-20: Define variables that the template asks for when it’s installed. * Lines 21-120: Handle a quirk of Lambda deployments that requires the Lambda assets to be in your region before deployment. As there is no elegant workaround, these 100 lines create an S3 bucket in your account in the region you’re creating the stack and copies in these resources. * Lines 121-132: Define a role with basic permission to run the Lambda. * Lines 133-144: Define a Python library layer. This layer packages the Python HTTP library, a Python S2 Geometry library, and the InfluxDB Python client library. * Lines 145-165: Define the Lambda function, a short Python script zipped up in a file called `geo_lambda.zip`. * Lines 166-188: Define an event rule with permission to run the Lambda every hour. ### Deploy the template 1. Log into your free AWS account and search for the CloudFormation service. Make sure you’re in the AWS region you want to deploy the Lambda to⁠. 2. Click **Create Stack**. 3. In the **Prerequisite - Prepare Template** section, select **Template is ready**. 4. In the **Specify template** section: * Under **Template source**, select **Amazon S3 URL**. * In the **Amazon S3 URL** field, enter the CloudFormation template URL: `https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml` 1. Click **Next**. 2. Enter a name in the **Stack name** field. 3. Enter the following InfluxDB details: * Organization ID * Bucket ID of the bucket the Lambda writes to * Token with permission to write to the bucket * InfluxDB URL 1. Do not alter or add to any other fields. Click **Next**. 2. Select the **I acknowledge that AWS CloudFormation might create IAM resources** check box. 3. Click **Create Stack**. After a few minutes, the stack deploys to your region. To view the new Lambda, select **Services \> AWS Lambda**. On the Lambda functions page, you should see your new Lambda. The `CopyZipsFunction` is the helper copy function, and the `GeoPythonLambda` does the data collection and writing work: GeoPythonLambda data in InfluxDB ### Verify your setup `GeoPythonLambda` should run every hour based on the AWS Rule we set up, but you should test and confirm it works. 1. Click `GeoPythonLambda`, and then click **Test**. 2. The test requires an input definition, but this Lambda has no input requirements, so click through and save the default dataset. 3. If the test is successful, a green **Execution result: succeeded** message appears. With the data points written, when you log into your InfluxDB UI, you’ll be able to explore the geolocation earthquake data: GeoPythonLambda data in InfluxDB --- # Migrate data to InfluxDB Source: https://docs.influxdata.com/influxdb/v2/write-data/migrate-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Migrate data to InfluxDB from other InfluxDB instances including by InfluxDB OSS and InfluxDB Cloud. ### [Migrate data from InfluxDB OSS to other InfluxDB instances](/influxdb/v2/write-data/migrate-data/migrate-oss/) To migrate data from an InfluxDB OSS bucket to another InfluxDB OSS or InfluxDB Cloud bucket, export your data as line protocol and write it to your other InfluxDB bucket. ### [Migrate data from InfluxDB Cloud to InfluxDB OSS](/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss/) To migrate data from InfluxDB Cloud to InfluxDB OSS, query the data from InfluxDB Cloud in time-based batches and write the data to InfluxDB OSS. --- # Migrate data from InfluxDB Cloud to InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To migrate data from InfluxDB Cloud to InfluxDB OSS, query the data from InfluxDB Cloud and write the data to InfluxDB OSS. Because full data migrations will likely exceed your organization’s limits and adjustable quotas, migrate your data in batches. The following guide provides instructions for setting up an InfluxDB OSS task that queries data from an InfluxDB Cloud bucket in time-based batches and writes each batch to an InfluxDB OSS bucket. > [!Important] > All queries against data in InfluxDB Cloud are subject to your organization’s[rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). * [Set up the migration](#set-up-the-migration) * [Migration task](#migration-task) * [Configure the migration](#configure-the-migration) * [Migration Flux script](#migration-flux-script) * [Configuration help](#configuration-help) * [Monitor the migration progress](#monitor-the-migration-progress) * [Troubleshoot migration task failures](#troubleshoot-migration-task-failures) ## Set up the migration 1. [Install and set up InfluxDB OSS](/influxdb/v2/install/). 2. **In InfluxDB Cloud**, [create an API token](/influxdb/cloud/admin/tokens/create-token/)with **read access** to the bucket you want to migrate. 3. **In InfluxDB OSS**: 1. Add your **InfluxDB Cloud API token** as a secret using the key,`INFLUXDB_CLOUD_TOKEN`.*See [Add secrets](/influxdb/v2/security/secrets/add/) for more information.* 2. [Create a bucket](/influxdb/v2/organizations/buckets/create-bucket/)**to migrate data to**. 3. [Create a bucket](/influxdb/v2/organizations/buckets/create-bucket/)**to store temporary migration metadata**. 4. [Create a new task](/influxdb/v2/process-data/manage-tasks/create-task/)using the provided [migration task](#migration-task). Update the necessary [migration configuration options](#configure-the-migration). 5. *(Optional)* Set up [migration monitoring](#monitor-the-migration-progress). 6. Save the task. > [!Note] > Newly-created tasks are enabled by default, so the data migration begins when you save the task. **After the migration is complete**, each subsequent migration task execution will fail with the following error: ``` error exhausting result iterator: error calling function "die" @41:9-41:86: Batch range is beyond the migration range. Migration is complete. ``` ## Migration task ### Configure the migration 1. Specify how often you want the task to run using the `task.every` option.*See [Determine your task interval](#determine-your-task-interval).* 2. Define the following properties in the `migration`[record](/flux/v0/data-types/composite/record/): ##### migration ##### * **start**: Earliest time to include in the migration.*See [Determine your migration start time](#determine-your-migration-start-time).* * **stop**: Latest time to include in the migration. * **batchInterval**: Duration of each time-based batch.*See [Determine your batch interval](#determine-your-batch-interval).* * **batchBucket**: InfluxDB OSS bucket to store migration batch metadata in. * **sourceHost**: [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions)to migrate data from. * **sourceOrg**: InfluxDB Cloud organization to migrate data from. * **sourceToken**: InfluxDB Cloud API token. To keep the API token secure, store it as a secret in InfluxDB OSS. * **sourceBucket**: InfluxDB Cloud bucket to migrate data from. * **destinationBucket**: InfluxDB OSS bucket to migrate data to. ### Migration Flux script ```js import "array" import "experimental" import "influxdata/influxdb/secrets" // Configure the task option task = {every: 5m, name: "Migrate data from InfluxDB Cloud"} // Configure the migration migration = { start: 2022-01-01T00:00:00Z, stop: 2022-02-01T00:00:00Z, batchInterval: 1h, batchBucket: "migration", sourceHost: "https://cloud2.influxdata.com", sourceOrg: "example-cloud-org", sourceToken: secrets.get(key: "INFLUXDB_CLOUD_TOKEN"), sourceBucket: "example-cloud-bucket", destinationBucket: "example-oss-bucket", } // batchRange dynamically returns a record with start and stop properties for // the current batch. It queries migration metadata stored in the // `migration.batchBucket` to determine the stop time of the previous batch. // It uses the previous stop time as the new start time for the current batch // and adds the `migration.batchInterval` to determine the current batch stop time. batchRange = () => { _lastBatchStop = (from(bucket: migration.batchBucket) |> range(start: migration.start) |> filter(fn: (r) => r._field == "batch_stop") |> filter(fn: (r) => r.srcOrg == migration.sourceOrg) |> filter(fn: (r) => r.srcBucket == migration.sourceBucket) |> last() |> findRecord(fn: (key) => true, idx: 0))._value _batchStart = if exists _lastBatchStop then time(v: _lastBatchStop) else migration.start return {start: _batchStart, stop: experimental.addDuration(d: migration.batchInterval, to: _batchStart)} } // Define a static record with batch start and stop time properties batch = {start: batchRange().start, stop: batchRange().stop} // Check to see if the current batch start time is beyond the migration.stop // time and exit with an error if it is. finished = if batch.start >= migration.stop then die(msg: "Batch range is beyond the migration range. Migration is complete.") else "Migration in progress" // Query all data from the specified source bucket within the batch-defined time // range. To limit migrated data by measurement, tag, or field, add a `filter()` // function after `range()` with the appropriate predicate fn. data = () => from(host: migration.sourceHost, org: migration.sourceOrg, token: migration.sourceToken, bucket: migration.sourceBucket) |> range(start: batch.start, stop: batch.stop) // rowCount is a stream of tables that contains the number of rows returned in // the batch and is used to generate batch metadata. rowCount = data() |> count() |> group(columns: ["_start", "_stop"]) |> sum() // emptyRange is a stream of tables that acts as filler data if the batch is // empty. This is used to generate batch metadata for empty batches and is // necessary to correctly increment the time range for the next batch. emptyRange = array.from(rows: [{_start: batch.start, _stop: batch.stop, _value: 0}]) // metadata returns a stream of tables representing batch metadata. metadata = () => { _input = if exists (rowCount |> findRecord(fn: (key) => true, idx: 0))._value then rowCount else emptyRange return _input |> map( fn: (r) => ({ _time: now(), _measurement: "batches", srcOrg: migration.sourceOrg, srcBucket: migration.sourceBucket, dstBucket: migration.destinationBucket, batch_start: string(v: batch.start), batch_stop: string(v: batch.stop), rows: r._value, percent_complete: float(v: int(v: r._stop) - int(v: migration.start)) / float( v: int(v: migration.stop) - int(v: migration.start), ) * 100.0, }), ) |> group(columns: ["_measurement", "srcOrg", "srcBucket", "dstBucket"]) } // Write the queried data to the specified InfluxDB OSS bucket. data() |> to(bucket: migration.destinationBucket) // Generate and store batch metadata in the migration.batchBucket. metadata() |> experimental.to(bucket: migration.batchBucket) ``` ### Configuration help [](#determine-your-task-interval) Determine your task interval The task interval determines how often the migration task runs and is defined by the [`task.every` option](/influxdb/v2/process-data/task-options/#every). InfluxDB Cloud rate limits and quotas reset every five minutes, so**we recommend a `5m` task interval**. You can do shorter task intervals and execute the migration task more often, but you need to balance the task interval with your [batch interval](#determine-your-batch-interval)and the amount of data returned in each batch. If the total amount of data queried in each five-minute interval exceeds your InfluxDB Cloud organization’s [rate limits and quotas](/influxdb/cloud/account-management/limits/), the batch will fail until rate limits and quotas reset. [](#determine-your-migration-start-time) Determine your migration start time The `migration.start` time should be at or near the same time as the earliest data point you want to migrate. All migration batches are determined using the `migration.start` time and`migration.batchInterval` settings. To find time of the earliest point in your bucket, run the following query: ```js from(bucket: "example-cloud-bucket") |> range(start: 0) |> group() |> first() |> keep(columns: ["_time"]) ``` [](#determine-your-batch-interval) Determine your batch interval The `migration.batchInterval` setting controls the time range queried by each batch. The “density” of the data in your InfluxDB Cloud bucket and your InfluxDB Cloud organization’s [rate limits and quotas](/influxdb/cloud/account-management/limits/)determine what your batch interval should be. For example, if you’re migrating data collected from hundreds of sensors with points recorded every second, your batch interval will need to be shorter. If you’re migrating data collected from five sensors with points recorded every minute, your batch interval can be longer. It all depends on how much data gets returned in a single batch. If points occur at regular intervals, you can get a fairly accurate estimate of how much data will be returned in a given time range by using the `/api/v2/query`endpoint to execute a query for the time range duration and then measuring the size of the response body. The following `curl` command queries an InfluxDB Cloud bucket for the last day and returns the size of the response body in bytes. You can customize the range duration to match your specific use case and data density. ```sh INFLUXDB_CLOUD_ORG= INFLUXDB_CLOUD_TOKEN= INFLUXDB_CLOUD_BUCKET= curl -so /dev/null --request POST \ https://cloud2.influxdata.com/api/v2/query?org=$INFLUXDB_CLOUD_ORG \ --header "Authorization: Token $INFLUXDB_CLOUD_TOKEN" \ --header "Accept: application/csv" \ --header "Content-type: application/vnd.flux" \ --data "from(bucket:\"$INFLUXDB_CLOUD_BUCKET\") |> range(start: -1d, stop: now())" \ --write-out '%{size_download}' ``` > [!Note] > You can also use other HTTP API tools like [Postman](https://www.postman.com/)that provide the size of the response body. Divide the output of this command by 1000000 to convert it to megabytes (MB). ``` batchInterval = (read-rate-limit-mb / response-body-size-mb) * range-duration ``` For example, if the response body of your query that returns data from one day is 8 MB and you’re using the InfluxDB Cloud Free Plan with a read limit of 300 MB per five minutes: ``` batchInterval = (300 / 8) * 1d // batchInterval = 37d ``` You could query 37 days of data before hitting your read limit, but this is just an estimate. We recommend setting the `batchInterval` slightly lower than the calculated interval to allow for variation between batches. So in this example, **it would be best to set your `batchInterval` to `35d`**. ##### Important things to note * This assumes no other queries are running in your InfluxDB Cloud organization. * You should also consider your network speeds and whether a batch can be fully downloaded within the [task interval](#determine-your-task-interval). ## Monitor the migration progress The [InfluxDB Cloud Migration Community template](https://github.com/influxdata/community-templates/tree/master/influxdb-cloud-oss-migration/)installs the migration task outlined in this guide as well as a dashboard for monitoring running data migrations. InfluxDB Cloud migration dashboard [Install the InfluxDB Cloud Migration template](https://github.com/influxdata/community-templates/tree/master/influxdb-cloud-oss-migration/#quick-install) ## Troubleshoot migration task failures If the migration task fails, [view your task logs](/influxdb/v2/process-data/manage-tasks/task-run-history/)to identify the specific error. Below are common causes of migration task failures. * [Exceeded rate limits](#exceeded-rate-limits) * [Invalid API token](#invalid-api-token) * [Query timeout](#query-timeout) * [Batch size is too large](#batch-size-is-too-large) ### Exceeded rate limits If your data migration causes you to exceed your InfluxDB Cloud organization’s limits and quotas, the task will return an error similar to: ``` too many requests ``` **Possible solutions**: * Update the `migration.batchInterval` setting in your migration task to use a smaller interval. Each batch will then query less data. ### Invalid API token If the API token you add as the `INFLUXDB_CLOUD_SECRET` doesn’t have read access to your InfluxDB Cloud bucket, the task will return an error similar to: ``` unauthorized access ``` **Possible solutions**: * Ensure the API token has read access to your InfluxDB Cloud bucket. * Generate a new InfluxDB Cloud API token with read access to the bucket you want to migrate. Then, update the `INFLUXDB_CLOUD_TOKEN` secret in your InfluxDB OSS instance with the new token. ### Query timeout The InfluxDB Cloud query timeout is 90 seconds. If it takes longer than this to return the data from the batch interval, the query will time out and the task will fail. **Possible solutions**: * Update the `migration.batchInterval` setting in your migration task to use a smaller interval. Each batch will then query less data and take less time to return results. ### Batch size is too large If your batch size is too large, the task returns an error similar to the following: ``` internal error: error calling function "metadata" @97:1-97:11: error calling function "findRecord" @67:32-67:69: wrong number of fields ``` **Possible solutions**: * Update the `migration.batchInterval` setting in your migration task to use a smaller interval and retrieve less data per batch. --- # Migrate data from InfluxDB OSS to other InfluxDB instances Source: https://docs.influxdata.com/influxdb/v2/write-data/migrate-data/migrate-oss/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To migrate data from an InfluxDB OSS bucket to another InfluxDB OSS or InfluxDB Cloud bucket, export your data as line protocol and write it to your other InfluxDB bucket. > [!Important] > #### InfluxDB Cloud write limits > > If migrating data from InfluxDB OSS to InfluxDB Cloud, you are subject to your[InfluxDB Cloud organization’s rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). > Consider exporting your data in time-based batches to limit the file size > of exported line protocol to match your InfluxDB Cloud organization’s limits. 1. [Find the InfluxDB OSS bucket ID](/influxdb/v2/organizations/buckets/view-buckets/)that contains data you want to migrate. 2. Use the `influxd inspect export-lp` command to export data in your bucket as[line protocol](/influxdb/v2/reference/syntax/line-protocol/). Provide the following: * **bucket ID**: (Required) ID of the bucket to migrate. * **engine path**: (Required) Path to the TSM storage files on disk. The default engine path [depends on your operating system](/influxdb/v2/reference/internals/file-system-layout/#file-system-layout), If using a [custom engine-path](/influxdb/v2/reference/config-options/#engine-path)provide your custom path. * **output path**: (Required) File path to output line protocol to. * **start time**: Earliest time to export. * **end time**: Latest time to export. * **measurement**: Export a specific measurement. By default, the command exports all measurements. * **compression**: (Recommended) Use Gzip compression to compress the output line protocol file. ``` influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --output-path path/to/export.lp --start 2022-01-01T00:00:00Z \ --end 2022-01-31T23:59:59Z \ --compress ``` 3. Write the exported line protocol to your InfluxDB OSS or InfluxDB Cloud instance. Do any of the following: * Write line protocol in the **InfluxDB UI**: * [InfluxDB Cloud UI](/influxdb/cloud/write-data/no-code/load-data/#load-csv-or-line-protocol-in-ui) * [InfluxDB OSS 2.10 UI](/influxdb/v2/write-data/no-code/load-data/#load-csv-or-line-protocol-in-ui) * [Write line protocol using the `influx write` command](/influxdb/v2/reference/cli/influx/write/) * [Write line protocol using the InfluxDB API](/influxdb/v2/write-data/developer-tools/api/) * [Bulk ingest data (InfluxDB Cloud)](/influxdb/cloud/write-data/bulk-ingest-cloud/) --- # Write data to InfluxDB without coding Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following options let you write data to InfluxDB without writing any code. Some options require a minimal amount of configuration. ### [Load data source in UI](/influxdb/v2/write-data/no-code/load-data/) Load data from sources in the InfluxDB user interface (UI). Choose from popular client libraries (such as Python, Ruby, Scala, and more!) or load data with a Telegraf plugin (like MQTT Consumer, MySQL, File, and many more!). ### [Use the Telegraf agent](/influxdb/v2/write-data/no-code/use-telegraf/) Use Telegraf to collect and write data to InfluxDB. Create Telegraf configurations in the InfluxDB UI or manually configure Telegraf. ### [Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) Scrape data from InfluxDB instances or remote endpoints using InfluxDB scrapers. Create a scraper in the InfluxDB UI to collect metrics from a specified target. ### [Write data with no-code third-party technologies](/influxdb/v2/write-data/no-code/third-party/) Write data to InfluxDB using third-party technologies that do not require coding. --- # Load data from sources in the InfluxDB user interface (UI) Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/load-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Load data from the following sources in the InfluxDB user interface (UI): * [CSV or line protocol file](#load-csv-or-line-protocol-in-ui) * [Line protocol](#load-data-using-line-protocol) * [Client libraries](#load-data-from-a-client-library-in-the-ui) * [Telegraf plugins](#load-data-from-a-telegraf-plugin-in-the-ui) ### Load CSV or line protocol in UI Load CSV or line protocol data by uploading a file or pasting the data manually into the UI. 1. In the navigation menu on the left, click **Load Data** \> **Sources**. Load Data 2. Under **File Upload**, select the type of data to upload: * **Annotated CSV**. Verify your CSV file follows the supported [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) syntax. * **Line Protocol**. Verify your line protocol file adheres to the following conventions: * Each line represents a data point. * Each data point requires a: * [*measurement*](/influxdb/cloud/reference/syntax/line-protocol/#measurement) * [*field set*](/influxdb/cloud/reference/syntax/line-protocol/#field-set) * (Optional) [*tag set*](/influxdb/cloud/reference/syntax/line-protocol/#tag-set) * [*timestamp*](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) For more information, see supported [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) syntax. 3. Select the bucket to write to. 4. Select the **Precision** in the dropdown menu. By default, the precision is set to nanoseconds. 5. Do one of the following: * To upload file, drag and drop your file onto the UI, and then click **Write Data**. * To enter data manually, select the **Enter Manually** tab, paste your data, and then click **Write Data**. ### Load data from a client library in the UI 1. In the navigation menu on the left, click **Load Data** \> **Sources**. Load Data 2. Do one of the following: * Enter a specific client library to search for in the **Search data writing methods** field. * Scroll down to browse available client libraries. 3. Click the client library to load data from. 4. Under **Code Sample Options**, you’ll see a list of your InfluxDB [tokens](/influxdb/v2/reference/glossary/#token) and [buckets](/influxdb/v2/reference/glossary/#bucket). Select both an API token and a bucket to write your data to. The selected API token and bucket are automatically added to scripts on the page that you can use to initialize a client and write data. 5. Click the **Copy to Clipboard** buttons under a script to easily paste the script into your terminal or save the script to reuse for automation. 6. Run the scripts on the page to do the following as needed: * Install the package, libraries, or client * Write data * Execute a Flux query ### Load data from a Telegraf plugin in the UI 1. In the navigation menu on the left, click **Load Data** \> **Sources**. Load Data 2. Do one of the following: * Enter a specific Telegraf plugin to search for in the **Search data writing methods** field. * Scroll down to **Telegraf Plugins** and browse available input plugins. 3. Click the plugin to load data from. The plugin details page opens. 4. Select one of the options from the **Use this plugin** dropdown: * **Create a new configuration**: Enter a configuration name and select an output bucket, and then click **Continue Configuring**. * **Add to an existing configuration**: Select an existing Telegraf configuration to add this plugin to, and then click **Add to Existing Config**. 5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. 6. Adjust configuration settings as needed. The configuration includes settings for the [InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2) to write to your bucket. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). 7. Click **Save and Test**. Your input plugin configuration is appended to the default agent settings and the InfluxDB output plugin configuration. 8. The **Test Your Configuration** page provides instructions for how to start Telegraf using the generated configuration.*See [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf) below for detailed information about what each step does.* 9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. Once confirmed, a **Connection Found!** message appears. 10. Click **Finish**. Your Telegraf configuration name and the associated bucket name appear in the list of Telegraf configurations. 11. To view or edit the configuration, click the configuration name. 12. To view default settings used to write data to InfluxDB, click **InfluxDB Output Plugin**. --- # Scrape data using InfluxDB scrapers Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB scrapers collect data from specified targets at regular intervals, then write the scraped data to an InfluxDB bucket. Scrapers can collect data from any HTTP(S)-accessible endpoint that provides data in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). > [!Important] > Scrapers are not available in InfluxDB Cloud. The following articles provide information about creating and managing InfluxDB data scrapers: ### [Manage InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/) Create, update, and delete InfluxDB data scrapers in the InfluxDB user interface. ### [Create scrapable endpoints](/influxdb/v2/write-data/no-code/scrape-data/scrapable-endpoints/) InfluxDB scrapers can collect data from any HTTP(S)-accessible endpoint that returns data in the Prometheus data format. This article provides links to information about the Prometheus data format and tools that generate Prometheus-formatted metrics. [scraper](/influxdb/v2/tags/scraper/) --- # Manage InfluxDB scrapers Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles walk through managing InfluxDB scrapers: ### [Create a scraper](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper/) Create an InfluxDB scraper that collects data from InfluxDB or a remote endpoint. ### [Update a scraper](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper/) Update an InfluxDB scraper that collects data from InfluxDB or a remote endpoint. ### [Delete a scraper](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper/) Delete an InfluxDB scraper in the InfluxDB user interface. #### Related * [Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) [scraper](/influxdb/v2/tags/scraper/)[prometheus](/influxdb/v2/tags/prometheus/) --- # Create an InfluxDB scraper Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB scrapers collect data from specified targets at regular intervals, then write the scraped data to an InfluxDB bucket. Scrapers can collect data from any HTTP(S)-accessible endpoint that provides data in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). ## Create a scraper in the InfluxDB UI 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Scrapers**. Load Data 2. Click **Create Scraper**. 3. Enter a **Name** for the scraper. 4. Select a **Bucket** to store the scraped data. 5. Enter the **Target URL** to scrape. The default URL value is `http://localhost:8086/metrics`, which provides InfluxDB-specific metrics in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). 6. Click **Create**. The new scraper will begin scraping data after approximately 10 seconds, then continue scraping in 10 second intervals. #### Related * [Scrape data using InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) [scraper](/influxdb/v2/tags/scraper/) --- # Delete an InfluxDB scraper Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Delete a scraper from the InfluxDB user interface (UI). ## Delete a scraper from the InfluxDB UI 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Scrapers**. Load Data 2. Hover over the scraper you want to delete and click the icon. 3. Click **Delete**. --- # Update an InfluxDB scraper Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Update a scraper in the InfluxDB user interface (UI). > [!Note] > Scraper **Target URLs** and **Buckets** cannot be updated. > To modify either, [create a new scraper](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper). ## Update a scraper in the InfluxDB UI 1. In the navigation menu on the left, select **Data** (**Load Data**) \> **Scrapers**. Load Data 2. Hover over the scraper you would like to update and click the that appears next to the scraper name. 3. Enter a new name for the scraper. Press Return or click out of the name field to save the change. --- # Create scrapable endpoints Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/scrape-data/scrapable-endpoints/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). InfluxDB scrapers can collect data from any HTTP(S)-accessible endpoint that returns data in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). The links below provide information about the Prometheus data format and tools and clients that generate Prometheus-formatted metrics. ## Prometheus Node Exporter The [Prometheus Node Exporter](https://github.com/prometheus/node_exporter) exposes a wide variety of hardware- and kernel-related metrics for **\*nix** systems. ##### Helpful links [Monitoring linux host metrics with the Node Exporter](https://prometheus.io/docs/guides/node-exporter/) ## Prometheus exporters and integrations [Prometheus exporters and integrations](https://prometheus.io/docs/instrumenting/exporters/)export Prometheus metrics from third-party systems or services. ##### Helpful links [List of third-party exporters](https://prometheus.io/docs/instrumenting/exporters/#third-party-exporters) [Write a custom Prometheus exporter](https://prometheus.io/docs/instrumenting/writing_exporters/) ## Prometheus client libraries [Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/)instrument applications for each of their respective languages. Application metrics are output to an HTTP(S) endpoint where they can be scraped. ##### Helpful links [Instrumenting a Go application for Prometheus](https://prometheus.io/docs/guides/go-application/) [Writing Prometheus client libraries](https://prometheus.io/docs/instrumenting/writing_clientlibs/) [scraper](/influxdb/v2/tags/scraper/)[prometheus](/influxdb/v2/tags/prometheus/) --- # Write data with no-code third-party technologies Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/third-party/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Write data to InfluxDB by configuring third-party technologies that don’t require coding. ## Prerequisites * Authentication credentials for your InfluxDB instance: your InfluxDB host URL,[organization](/influxdb/v2/admin/organizations/),[bucket](/influxdb/v2/admin/buckets/), and an [API token](/influxdb/v2/admin/tokens/)with write permission on the bucket. To setup InfluxDB and create credentials, follow the[Get started](/influxdb/v2/get-started/) guide. * Access to one of the third-party tools listed in this guide. You can configure the following third-party tools to send line protocol data directly to InfluxDB without writing code: > [!Note] > Many third-party integrations are community contributions. > If there’s an integration missing from the list below, please [open a docs issue](https://github.com/influxdata/docs-v2/issues/new/choose) to let us know. * [Vector 0.9 or later](#configure-vector) * [Apache NiFi 1.8 or later](#configure-apache-nifi) * [OpenHAB 3.0 or later](#configure-openhab) * [Apache JMeter 5.2 or later](#configure-apache-jmeter) * [Apache Pulsar](#configure-apache-pulsar) * [FluentD 1.x or later](#configure-fluentd) ## Configure Vector > > > Vector is a lightweight and ultra-fast tool for building observability pipelines. > > > > – [Vector documentation](https://vector.dev/docs/) > > Configure Vector to write metrics and log events to an InfluxDB instance. 1. Configure your [InfluxDB authentication credentials](#prerequisites) for Vector to write to your bucket. * View example configurations: * [InfluxDB metrics sink configuration](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#configuration) * [InfluxDB logs sink configuration](https://vector.dev/docs/reference/configuration/sinks/influxdb_logs/#example-configurations) * Use the following Vector configuration fields for InfluxDB v2 credentials: * [`endpoint`](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#endpoint): the URL (including scheme, host, and port) for your InfluxDB instance * [`org`](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#org): the name of your InfluxDB organization * [`bucket`](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#bucket): the name of the bucket to write data to * [`token`](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#token): an API token with write permission on the specified bucket 2. Configure the data that you want Vector to write to InfluxDB. * View [examples of metrics events and configurations](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#examples). * View [Telemetry log metrics](https://vector.dev/docs/reference/configuration/sinks/influxdb_logs/#telemetry). 3. For more detail, see the **How it works** sections: * [InfluxDB metrics sink–-How it works](https://vector.dev/docs/reference/configuration/sinks/influxdb_metrics/#how-it-works) * [InfluxDB logs sink–-How it works](https://vector.dev/docs/reference/configuration/sinks/influxdb_logs/#how-it-works) ## Configure Apache NiFi > > > [Apache NiFi](https://nifi.apache.org/documentation/v1/) is a software project from the Apache Software Foundation designed to automate the flow of data between software systems. > > > > – [Wikipedia](https://en.wikipedia.org/wiki/Apache_NiFi) > > The InfluxDB processors for Apache NiFi lets you write NiFi Record structured data into InfluxDB v2. See*[InfluxDB Processors for Apache NiFi](https://github.com/influxdata/nifi-influxdb-bundle#influxdb-processors-for-apache-nifi)*on GitHub for details. ## Configure OpenHAB > > > The open Home Automation Bus (openHAB, pronounced ˈəʊpənˈhæb) is an open source, technology agnostic home automation platform > > > > – [openHAB documentation](https://www.openhab.org/docs/) > > > > > [The InfluxDB Persistence add-on] service allows you to persist and query states using the [InfluxDB] time series database. > > > > – [openHAB InfluxDB persistence add-on](https://github.com/openhab/openhab-addons/tree/main/bundles/org.openhab.persistence.influxdb) > > See*[InfluxDB Persistence add-on](https://github.com/openhab/openhab-addons/tree/master/bundles/org.openhab.persistence.influxdb)*on GitHub for details. ## Configure Apache JMeter > > > [Apache JMeter](https://jmeter.apache.org/) is an Apache project that can be used as a load testing tool for > analyzing and measuring the performance of a variety of services, with a focus > on web applications. > > > > – [Wikipedia](https://en.wikipedia.org/wiki/Apache_JMeter) > > 1. Create a [Backend Listener](https://jmeter.apache.org/usermanual/component_reference.html#Backend_Listener) using the ***InfluxDBBackendListenerClient*** implementation. 2. In the **Backend Listener implementation** field, enter: ``` org.apache.jmeter.visualizers.backend.influxdb.influxdbBackendListenerClient ``` 3. Under **Parameters**, specify the following: * **influxdbMetricsSender**: ``` org.apache.jmeter.visualizers.backend.influxdb.HttpMetricsSender ``` * **influxdbUrl**: *(include the bucket and org you created in InfluxDB)* ``` http://localhost:8086/api/v2/write?org=my-org&bucket=jmeter ``` * **application**: `InfluxDB2` * **influxdbToken**: *your InfluxDB API token with write permission on the specified bucket* * Include additional parameters as needed. 4. Click **Add** to add the ***InfluxDBBackendListenerClient*** implementation. ## Configure Apache Pulsar > > > Apache Pulsar is an open source, distributed messaging and streaming platform > built for the cloud. > > > > The InfluxDB sink connector pulls messages from Pulsar topics and persists the > messages to InfluxDB. > > > > – [Apache Pulsar](https://pulsar.apache.org/) > > See *[InfluxDB sink connector](https://pulsar.apache.org/docs/en/io-influxdb-sink/)*for details. ## Configure FluentD > > > [Fluentd](https://www.fluentd.org/) is a cross-platform open-source data > collection software project. > > > > – [Wikipedia](https://en.wikipedia.org/wiki/Fluentd) > > See *[influxdb-plugin-fluent](https://github.com/influxdata/influxdb-plugin-fluent)*on GitHub for details. --- # Use Telegraf to write data Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) is InfluxData’s 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. This article describes how to use Telegraf to collect and store data in InfluxDB 2.10. For a list of available plugins, see [Telegraf plugins](/telegraf/v1/plugins/). #### Requirements * **Telegraf 1.9.2 or greater**.*For information about installing Telegraf, see the[Telegraf Installation instructions](/telegraf/v1//install/).* ## Configure Telegraf Telegraf input and output plugins are enabled and configured in Telegraf’s configuration file (`telegraf.conf`). You have the following options for configuring Telegraf: ### [Automatically configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/) Use the InfluxDB UI to automatically generate a Telegraf configuration, then start Telegraf using the generated configuration file. ### [Dual write to InfluxDB OSS and InfluxDB Cloud](/influxdb/v2/write-data/no-code/use-telegraf/dual-write/) Write data to both OSS and Cloud simultaneously. ### [Manually configure Telegraf](/influxdb/v2/write-data/no-code/use-telegraf/manual-config/) Update existing or create new Telegraf configurations to use the `influxdb_v2` output plugin to write to InfluxDB. Start Telegraf using the custom configuration. ### [Use Telegraf plugins](/influxdb/v2/write-data/no-code/use-telegraf/use-telegraf-plugins/) Use Telegraf plugins to capture and write metrics to InfluxDB. ![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/) --- # Automatically configure Telegraf Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/auto-config/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The InfluxDB user interface (UI) can automatically create Telegraf configuration files based on user-selected Telegraf plugins. This article describes how to create a Telegraf configuration in the InfluxDB UI and start Telegraf using the generated configuration file. > [!Note] > *View the [requirements](/influxdb/v2/write-data/no-code/use-telegraf#requirements)for using Telegraf with InfluxDB 2.10.* ## Create a Telegraf configuration 1. Open the InfluxDB UI *(default: [localhost:8086](http://localhost:8086))*. 2. In the navigation menu on the left, select **Data** (**Load Data**) \> **Telegraf**. Load Data 3. Click **Create Configuration**. 4. In the **Bucket** dropdown, select the bucket where Telegraf will store collected data. 5. Select one or more of the available plugin groups and click **Continue**. 6. Review the list of **Plugins to Configure** for configuration requirements. Plugins listed with a ✓require no additional configuration. To configure a plugin or access plugin documentation, click the plugin name. 7. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. 8. Adjust configuration settings as needed. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). 9. Click **Save and Test**. 10. The **Test Your Configuration** page provides instructions for how to start Telegraf using the generated configuration.*See [Start Telegraf](#start-telegraf) below for detailed information about what each step does.* 11. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. Once confirmed, a **Connection Found!** message appears. 12. Click **Finish**. Your Telegraf configuration name and the associated bucket name appears in the list of Telegraf configurations. ### Windows If you plan to monitor a Windows host using the System plugin, you must complete the following steps. 1. In the list of Telegraf configurations, double-click your Telegraf configuration, and then click **Download Config**. 2. Open the downloaded Telegraf configuration file and replace the `[[inputs.processes]]` plugin with one of the following Windows plugins, depending on your Windows configuration: * [`[[inputs.win_perf_counters]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_perf_counters) * [`[[inputs.win_services]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_services) 3. Save the file and place it in a directory that **telegraf.exe** can access. ## Start Telegraf Requests to the [InfluxDB v2 API](/influxdb/v2/reference/api/) must include an API token. A token identifies specific permissions to the InfluxDB instance. ### Configure your token as an environment variable 1. Find your API token. *For information about viewing tokens, see [View tokens](/influxdb/v2/admin/tokens/view-tokens/).* 2. To configure your API token as the `INFLUX_TOKEN` environment variable, run the command appropriate for your operating system and command-line tool: [macOS or Linux](#macos-or-linux)[Windows](#windows-2) ```sh export INFLUX_TOKEN=YourAuthenticationToken ``` [PowerShell](#powershell)[CMD](#cmd) ```sh $env:INFLUX_TOKEN = "YourAuthenticationToken" ``` ```sh set INFLUX_TOKEN=YourAuthenticationToken # Make sure to include a space character at the end of this command. ``` ### Start the Telegraf service Start the Telegraf service using the `-config` flag to specify the location of the generated Telegraf configuration file. * For Windows, the location is always a local file path. * For Linux and macOS, the location can be a local file path or URL. Telegraf starts using the Telegraf configuration pulled from InfluxDB API. > [!Note] > InfluxDB host URLs and ports differ between InfluxDB OSS and InfluxDB Cloud. > For the exact command, see the Telegraf configuration **Setup Instructions** in the InfluxDB UI. ```sh telegraf -config http://localhost:8086/api/v2/telegrafs/0xoX00oOx0xoX00o ``` ## Manage Telegraf configurations For more information about managing Telegraf configurations in InfluxDB, see[Telegraf configurations](/influxdb/v2/tools/telegraf-configs/). #### Related * [Create a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/create/) --- # Dual write to InfluxDB OSS and InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/dual-write/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). If you want to back up your data in two places, or if you’re migrating from OSS to Cloud, you may want to set up dual write. Use Telegraf to write to both InfluxDB OSS and InfluxDB Cloud simultaneously. The sample configuration below uses: * The [InfluxDB v2 output plugin](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2) twice: first pointing to the OSS instance and then to the cloud instance. * Two different tokens, one for OSS and one for Cloud. You’ll need to configure both tokens as environment variables (see [Configure your token as an environment variable](/influxdb/v2/write-data/no-code/use-telegraf/auto-config/#configure-your-token-as-an-environment-variable). Use the configuration below to write your data to both OSS and Cloud instances simultaneously. ## Sample configuration ``` [[inputs.cpu]] [[inputs.mem]] ## Any other inputs, processors, aggregators that you want to include in your configuration. # Send data to InfluxDB OSS v2 [[outputs.influxdb_v2]] ## The URLs of the InfluxDB instance. ## ## Multiple URLs can be specified for a single cluster, only ONE of the ## urls will be written to each interval. ## urls exp: http://127.0.0.1:9999 urls = ["http://localhost:8086"] ## OSS token for authentication. token = "$INFLUX_TOKEN_OSS" ## Organization is the name of the organization you want to write to. It must already exist. organization = "influxdata" ## Destination bucket to write to. bucket = "telegraf" # Send data to InfluxDB Cloud - AWS West cloud instance [[outputs.influxdb_v2]] ## The URLs of the InfluxDB Cloud instance. urls = ["https://us-west-2-1.aws.cloud2.influxdata.com"] ## Cloud token for authentication. token = "$INFLUX_TOKEN_CLOUD" ## Organization is the name of the organization you want to write to. It must already exist. organization = "example@domain.com" ## Destination bucket to write into. bucket = "telegraf" ``` --- # Manually configure Telegraf Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/manual-config/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use the Telegraf `influxdb_v2` output plugin to collect and write metrics into an InfluxDB 2.10 bucket. This article describes how to enable the `influxdb_v2` output plugin in new and existing Telegraf configurations, then start Telegraf using the custom configuration file. > [!Note] > *View the [requirements](/influxdb/v2/write-data/no-code/use-telegraf#requirements)for using Telegraf with InfluxDB 2.10.* ## 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. *See [Telegraf plugins](/telegraf/v1/plugins//) for a complete list of available plugins.* ### Manually add Telegraf plugins To manually 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 [here](https://github.com/influxdata/telegraf/blob/release-1.14/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 v2 output plugin To send data to an InfluxDB 2.10 instance, enable in the[`influxdb_v2` output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md)in the `telegraf.conf`. To find an example InfluxDB v2 output plugin configuration in the UI: 1. In the navigation menu on the left, select **Data (Load Data)** \> **Telegraf**. Load Data 2. Click **InfluxDB Output Plugin**. 3. Click **Copy to Clipboard** to copy the example configuration or **Download Config** to save a copy. 4. Paste the example configuration into your `telegraf.conf` and specify the options below. The InfluxDB output plugin configuration contains the following options: ##### urls An array of URLs for your InfluxDB 2.10 instances. See [InfluxDB URLs](/influxdb/v2/reference/urls/) for information about which URLs to use.**InfluxDB Cloud requires HTTPS**. ##### token Your InfluxDB 2.10 API token. For information about viewing tokens, see [View tokens](/influxdb/v2/admin/tokens/view-tokens/). > [!Note] > ###### Avoid storing tokens in `telegraf.conf` > > We recommend storing your tokens by setting the `INFLUX_TOKEN` environment variable and including the environment variable in your configuration file. > > [macOS or Linux](#macos-or-linux)[Windows](#windows) > > ``` > export INFLUX_TOKEN=YourAuthenticationToken > ``` > > [PowerShell](#powershell)[CMD](#cmd) > > ``` > $env:INFLUX_TOKEN = "YourAuthenticationToken" > ``` > > ``` > set INFLUX_TOKEN=YourAuthenticationToken > # Make sure to include a space character at the end of this command. > ``` > > *See the [example `telegraf.conf` below](#example-influxdb_v2-configuration).* ##### organization The name of the organization that owns the target bucket. ##### bucket The name of the bucket to write data to. #### Example influxdb\_v2 configuration The example below illustrates an `influxdb_v2` configuration. ```toml # ... [[outputs.influxdb_v2]] urls = ["http://localhost:8086"] token = "$INFLUX_TOKEN" organization = "example-org" bucket = "example-bucket" # ... ``` > [!Note] > ##### Write to InfluxDB v1.x and v2.x > > If a Telegraf agent is already writing to an InfluxDB v1.x database, > enabling the InfluxDB v2 output plugin will write data to both v1.x and 2.10 instances. ## Add a custom Telegraf configuration to InfluxDB To add a custom or manually configured Telegraf configuration to your collection of Telegraf configurations in InfluxDB, use the [`influx telegrafs create`](/influxdb/v2/reference/cli/influx/telegrafs/create/)or [`influx telegrafs update`](/influxdb/v2/reference/cli/influx/telegrafs/update/) commands. For more information, see: * [Create a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/create/#use-the-influx-cli) * [Update a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/update/#use-the-influx-cli) ## 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 * [Plugin directory](/telegraf/v1/plugins/) * [Create a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/create/) * [Update a Telegraf configuration](/influxdb/v2/tools/telegraf-configs/update/) [manually](/influxdb/v2/tags/manually/)[plugin](/influxdb/v2/tags/plugin/)[mqtt](/influxdb/v2/tags/mqtt/) --- # Use Telegraf plugins Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/use-telegraf-plugins/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). The following articles guide you through step-by-step Telegraf configuration examples: ### [HTTP input plugin](/influxdb/v2/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin/) Write Citi Bike data to your InfluxDB instance with the HTTP plugin. --- # Use the HTTP input plugin Source: https://docs.influxdata.com/influxdb/v2/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). This example walks through using the Telegraf HTTP input plugin to collect live metrics on Citi Bike stations in New York City. Live station data is available in JSON format from [NYC OpenData](https://data.cityofnewyork.us/NYC-BigApps/Citi-Bike-Live-Station-Feed-JSON-/p94q-8hxh). Configure [`influxdb` output plugin](/telegraf/v1/plugins//#influxdb) to write metrics to your InfluxDB 2.10 instance. ## Configure the HTTP Input plugin in your Telegraf configuration file To retrieve data from the Citi Bike URL endpoint, enable the `inputs.http` input plugin in your Telegraf configuration file. Specify the following options: ### `urls` One or more URLs to read metrics from. For this example, use `https://gbfs.citibikenyc.com/gbfs/en/station_status.json`. ### `data_format` The format of the data in the HTTP endpoints that Telegraf will ingest. For this example, use JSON. ## Add parser information to your Telegraf configuration Specify the following JSON-specific options. ### JSON #### `json_query` To parse only the relevant portion of JSON data, set the `json_query` option with a [GJSON](https://github.com/tidwall/gjson) path. The result of the query should contain a JSON object or an array of objects. In this case, we don’t want to parse the JSON query’s `executionTime` at the beginning of the data, so we’ll limit this to include only the data in the `stationBeanList` array. #### `tag_keys` List of one or more JSON keys that should be added as tags. For this example, we’ll use the tag keys `id`, `stationName`, `city`, and `postalCode`. #### `json_string_fields` List the keys of fields that are in string format so that they can be parsed as strings. Here, the string fields are `statusValue`, `stAddress1`, `stAddress2`, `location`, and `landMark`. #### `json_time_key` Key from the JSON file that creates the timestamp metric. In this case, we want to use the time that station data was last reported, or the `lastCommunicationTime`. If you don’t specify a key, the time that Telegraf reads the data becomes the timestamp. #### `json_time_format` The format used to interpret the designated `json_time_key`. This example uses [Go reference time format](https://golang.org/pkg/time/#Time.Format). For example, `Mon Jan 2 15:04:05 MST 2006`. #### `json_timezone` The timezone We’ll set this to the Unix TZ value where our bike data takes place, `America/New_York`. #### Example configuration ```toml [[inputs.http]] #URL for NYC's Citi Bike station data in JSON format urls = ["https://feeds.citibikenyc.com/stations/stations.json"] #Overwrite measurement name from default `http` to `citibikenyc` name_override = "citibikenyc" #Exclude url and host items from tags tagexclude = ["url", "host"] #Data from HTTP in JSON format data_format = "json" #Parse `stationBeanList` array only json_query = "stationBeanList" #Set station metadata as tags tag_keys = ["id", "stationName", "city", "postalCode"] #Do not include station landmark data as fields fielddrop = ["landMark"] #JSON values to set as string fields json_string_fields = ["statusValue", "stAddress1", "stAddress2", "location", "landMark"] #Latest station information reported at `lastCommunicationTime` json_time_key = "lastCommunicationTime" #Time is reported in Golang "reference time" format json_time_format = "2006-01-02 03:04:05 PM" #Time is reported in Eastern Standard Time (EST) json_timezone = "America/New_York" ``` ## Start Telegraf and verify data appears [Start the Telegraf service](/telegraf/v1/introduction/getting-started/). To test that the data is being sent to InfluxDB, run the following (replacing `telegraf.conf` with the path to your configuration file): ``` telegraf -config ~/telegraf.conf -test ``` This command should return line protocol that looks similar to the following: ``` citibikenyc,id=3443,stationName=W\ 52\ St\ &\ 6\ Ave statusKey=1,location="",totalDocks=41,availableDocks=32,latitude=40.76132983124814,longitude=-73.97982001304626,availableBikes=8,stAddress2="",stAddress1="W 52 St & 6 Ave",statusValue="In Service" 1581533519000000000 citibikenyc,id=367,stationName=E\ 53\ St\ &\ Lexington\ Ave availableBikes=8,stAddress1="E 53 St & Lexington Ave",longitude=-73.97069431,latitude=40.75828065,stAddress2="",statusKey=1,location="",statusValue="In Service",totalDocks=34,availableDocks=24 1581533492000000000 citibikenyc,id=359,stationName=E\ 47\ St\ &\ Park\ Ave totalDocks=64,availableBikes=15,statusValue="In Service",location="",latitude=40.75510267,availableDocks=49,stAddress1="E 47 St & Park Ave",longitude=-73.97498696,statusKey=1,stAddress2="" 1581533535000000000 citibikenyc,id=304,stationName=Broadway\ &\ Battery\ Pl statusValue="In Service",availableDocks=11,stAddress1="Broadway & Battery Pl",statusKey=1,stAddress2="",location="",totalDocks=33,latitude=40.70463334,longitude=-74.01361706,availableBikes=22 1581533499000000000 ``` Now, you can explore and query the Citi Bike data in InfluxDB. --- # Write data from InfluxDB OSS to InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/v2/write-data/oss-to-cloud/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). To write data from InfluxDB OSS to InfluxDB Cloud, use the Flux[`to()`](/flux/v0/stdlib/influxdata/influxdb/to/) or[`experimental.to()`](/flux/v0/stdlib/experimental/to/) functions. Write data once with a single query execution or use [InfluxDB tasks](/influxdb/v2/process-data/)to [routinely write data to InfluxDB Cloud](#automate-writing-data-from-influxdb-oss-to-influxdb-cloud). > [!Note] > #### Replicate writes to InfluxDB OSS to InfluxDB Cloud > > To replicate all writes to an InfluxDB OSS instance to an InfluxDB Cloud instance, > use [InfluxDB replication streams](/influxdb/v2/write-data/replication/). > [!Important] > #### InfluxDB Cloud rate limits > > Write requests to InfluxDB Cloud are subject to the rate limits associated with your[InfluxDB Cloud pricing plan](/influxdb/cloud/account-management/pricing-plans/). 1. Query data from InfluxDB OSS. 2. *(Optional)* [Filter](/flux/v0/stdlib/universe/filter/) or process data to write to InfluxDB Cloud. 3. Use `to` or `experimental.to` to write data to InfluxDB Cloud. For most use cases, `to()` is the correct function to use, but depending on the structure of the data you’re writing, `experimental.to` may be required. **Use the following guidelines**: * **to()**: Use to write data in field keys to the `_field` column and field values to the `_value` column. * **experimental.to()**: Use to write data in column names to corresponding field keys and column values to field values. *See [input and output examples for `to()` functions](#input-and-output-data-for-to-functions).* 4. Provide the following parameters to either function: * **bucket**: InfluxDB Cloud bucket to write to * **host**: InfluxDB Cloud region URL * **org**: InfluxDB Cloud organization * **token**: InfluxDB Cloud API Token 5. (Recommended) To keep your raw API token out of queries, store your InfluxDB Cloud API token as an [InfluxDB secret](/influxdb/v2/admin/secrets/)in your InfluxDB OSS instance and use [`secrets.get()`](/flux/v0/stdlib/influxdata/influxdb/secrets/get/)to retrieve the secret value as shown in the following example (select the function you’re using to see the correct format): [to()](#to)[experimental.to()](#experimentalto) ```js import "influxdata/influxdb/secrets" cloudToken = secrets.get(key: "INFLUX_CLOUD_API_TOKEN") from(bucket: "example-oss-bucket") |> range(start: -10m) |> filter(fn: (r) => r._measurement == "example-measurement") |> to( bucket: "example-cloud-bucket", host: "https://cloud2.influxdata.com", org: "example-org", token: cloudToken, ) ``` ```js import "experimental" import "influxdata/influxdb/secrets" cloudToken = secrets.get(key: "INFLUX_CLOUD_API_TOKEN") from(bucket: "example-oss-bucket") |> range(start: -10m) |> filter(fn: (r) => r._measurement == "example-measurement") |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value") |> experimental.to( bucket: "example-cloud-bucket", host: "https://cloud2.influxdata.com", org: "example-org", token: cloudToken, ) ``` ## Input and output data for to() functions [to()](#to-2)[experimental.to()](#experimentalto-2) * `to()` requires `_time`, `_measurement`, `_field`, and `_value` columns. * `to()` writes all other columns as tags where the column name is the tag key and the column value is the tag value. #### Input data | \_time |\_measurement|exampleTag|\_field|\_value| |--------------------|-------------|----------|-------|-------| |2021-01-01T00:00:00Z| example-m | A | temp | 80.0 | |2021-01-01T00:01:00Z| example-m | A | temp | 80.3 | |2021-01-01T00:02:00Z| example-m | A | temp | 81.1 | | \_time |\_measurement|exampleTag|\_field|\_value| |--------------------|-------------|----------|-------|-------| |2021-01-01T00:00:00Z| example-m | A | rpm | 4023 | |2021-01-01T00:01:00Z| example-m | A | rpm | 4542 | |2021-01-01T00:02:00Z| example-m | A | rpm | 4901 | #### Output line protocol ``` example-m,exampleTag=A temp=80.0,rpm=4023i 1609459200000000000 example-m,exampleTag=A temp=80.3,rpm=4542i 1609459260000000000 example-m,exampleTag=A temp=81.1,rpm=4901i 1609459320000000000 ``` * `experimental.to()` requires `_time` and `_measurement` columns. * Columns **in** the [group key](/flux/v0/get-started/data-model/#grouop-key)(other than `_measurement`) are parsed as tags where the column name is the tag key and the column value is the tag value. * Columns **not in** the group key (other than `_time_`) are parsed as fields where the column name is the field key and the column value is the field value. #### Input data Group key = [\_measurement, exampleTag] | \_time |\_measurement|exampleTag|temp|rpm | |--------------------|-------------|----------|----|----| |2021-01-01T00:00:00Z| example-m | A |80.0|4023| |2021-01-01T00:01:00Z| example-m | A |80.3|4542| |2021-01-01T00:02:00Z| example-m | A |81.1|4901| #### Output line protocol ``` example-m,exampleTag=A temp=80.0,rpm=4023i 1609459200000000000 example-m,exampleTag=A temp=80.3,rpm=4542i 1609459260000000000 example-m,exampleTag=A temp=81.1,rpm=4901i 1609459320000000000 ``` ## Examples * [Downsample and write data to InfluxDB Cloud](#downsample-and-write-data-to-influxdb-cloud) * [Write min, max, and mean values to InfluxDB Cloud](#write-min-max-and-mean-values-to-influxdb-cloud) #### Downsample and write data to InfluxDB Cloud ```js import "influxdata/influxdb/secrets" cloudToken = secrets.get(key: "INFLUX_CLOUD_API_TOKEN") from(bucket: "example-oss-bucket") |> range(start: -10m) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1m, fn: last) |> to( bucket: "example-cloud-bucket", host: "https://cloud2.influxdata.com", org: "example-org", token: cloudToken, ) ``` #### Write min, max, and mean values to InfluxDB Cloud ```js import "influxdata/influxdb/secrets" cloudToken = secrets.get(key: "INFLUX_CLOUD_API_TOKEN") data = from(bucket: "example-oss-bucket") |> range(start: -30m) |> filter(fn: (r) => r._measurement == "example-measurement") min = data |> aggregateWindow(every: 10m, fn: min) |> map(fn: (r) => ({ r with _field: "{$r._field}_min" })) max = data |> aggregateWindow(every: 10m, fn: max) |> map(fn: (r) => ({ r with _field: "{$r._field}_max" })) mean = data |> aggregateWindow(every: 10m, fn: mean) |> map(fn: (r) => ({ r with _field: "{$r._field}_mean" })) union(tables: [min, max, mean]) |> to( bucket: "example-cloud-bucket", host: "https://cloud2.influxdata.com", org: "example-org", token: cloudToken, ) ``` ## Automate writing data from InfluxDB OSS to InfluxDB Cloud To automatically and routinely write data from InfluxDB OSS to InfluxDB Cloud,[create a task](/influxdb/v2/process-data/manage-tasks/create-task/) in your InfluxDB OSS instance that regularly queries, processes, and writes data to InfluxDB Cloud. ```js import "influxdata/influxdb/tasks" option task = {name: "Downsample to InfluxDB Cloud", every: 1h} from(bucket: "example-oss-bucket") |> range(start: -10m) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1m, fn: last) |> to( bucket: "example-cloud-bucket", host: "https://cloud2.influxdata.com", org: "example-org", token: cloudToken, ) ``` [write](/influxdb/v2/tags/write/) | _time | _measurement | exampleTag | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | exampleTag | _field | _value | | 2021-01-01T00:00:00Z | example-m | A | temp | 80.0 | | 2021-01-01T00:01:00Z | example-m | A | temp | 80.3 | | 2021-01-01T00:02:00Z | example-m | A | temp | 81.1 | | _time | _measurement | exampleTag | _field | _value | | --- | --- | --- | --- | --- | | _time | _measurement | exampleTag | _field | _value | | 2021-01-01T00:00:00Z | example-m | A | rpm | 4023 | | 2021-01-01T00:01:00Z | example-m | A | rpm | 4542 | | 2021-01-01T00:02:00Z | example-m | A | rpm | 4901 | | _time | _measurement | exampleTag | temp | rpm | | --- | --- | --- | --- | --- | | _time | _measurement | exampleTag | temp | rpm | | 2021-01-01T00:00:00Z | example-m | A | 80.0 | 4023 | | 2021-01-01T00:01:00Z | example-m | A | 80.3 | 4542 | | 2021-01-01T00:02:00Z | example-m | A | 81.1 | 4901 | --- # Edge Data Replication Source: https://docs.influxdata.com/influxdb/v2/write-data/replication/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Running [InfluxDB OSS](/influxdb/v2/install/) at the edge lets you collect, process, transform, and analyze high-precision data locally.**Edge Data Replication** lets you replicate data from distributed edge environments to [InfluxDB Cloud](/influxdb/cloud/sign-up/), aggregating and storing data for long-term management and analysis. > [!Note] > While replicating data from InfluxDB OSS to InfluxDB Cloud is the most common use case, you may also replicate data from any InfluxDB bucket to a bucket in another InfluxDB instance, for example, InfluxDB OSS, InfluxDB Cloud, or InfluxDB Enterprise. ### [Replicate data from InfluxDB OSS](/influxdb/v2/write-data/replication/replicate-data/) Replicate data from select InfluxDB OSS buckets to remote buckets in InfluxDB Cloud, InfluxDB OSS, or InfluxDB Enterprise instances. --- # Replicate data from InfluxDB OSS Source: https://docs.influxdata.com/influxdb/v2/write-data/replication/replicate-data/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Use InfluxDB replication streams (InfluxDB Edge Data Replication) to replicate the incoming data of select buckets to one or more buckets on a remote InfluxDB OSS, InfluxDB Cloud, or InfluxDB Enterprise v1 instance. Replicate data from InfluxDB OSS to InfluxDB Cloud, InfluxDB OSS, or InfluxDB Enterprise v1. * [Configure a replication stream](#configure-a-replication-stream) * [Replicate downsampled or processed data](#replicate-downsampled-or-processed-data) * [View replication service metrics](#view-influxdb-oss-replication-service-metrics) ## Configure a replication stream Use the [`influx` CLI](/influxdb/v2/tools/influx-cli/) or the[InfluxDB 2.10 API](/influxdb/v2/reference/api/) to configure a replication stream. > [!Note] > To replicate data to InfluxDB OSS or InfluxDB Enterprise v1, adjust the > remote connection values accordingly. [CLI](#cli)[API](#api) ### Step 1: Create or find a remote connection * [Create a remote connection](#create-a-remote-connection-cli) * [Use an existing remote connection](#use-an-existing-remote-connection-cli) #### Create a remote connection (CLI) In your local InfluxDB OSS instance, use the `influx remote create` command and provide the following arguments for the remote instance: * Remote connection name * Remote InfluxDB instance URL * Remote InfluxDB API token *(API token must have write access to the target bucket)* * Remote InfluxDB organization ID ```sh influx remote create \ --name example-remote-name \ --remote-url https://cloud2.influxdata.com \ --remote-api-token mYsuP3r5Ecr37t0k3n \ --remote-org-id 00xoXXoxXX00 ``` #### Use an existing remote connection (CLI) Alternatively, you can use an existing connection that you have already configured. To retrieve existing connections, run `influx remote list`. ### Step 2: Create a replication stream (CLI) In your local InfluxDB OSS instance, use the`influx replication create` command and provide the following arguments: * Replication stream name * Remote connection ID (created in the previous step) * Local bucket ID to replicate writes from * Remote bucket name or ID to replicate writes to. If replicating to **InfluxDB Enterprise v1**, use the `db-name/rp-name` bucket name syntax. ```sh influx replication create \ --name REPLICATION_STREAM_NAME \ --remote-id REPLICATION_REMOTE_ID \ --local-bucket-id INFLUX_BUCKET_ID \ --remote-bucket REMOTE_INFLUX_BUCKET_NAME ``` After you create the replication stream, InfluxDB OSS replicates all writes to the specified local bucket to the remote InfluxDB bucket. Use the `influx replication list` command to view information such as the current queue size, max queue size, and latest status code. ### Step 1: Create or find a remote connection (API) * [Create a remote connection](#create-a-remote-connection-api) * [Use an existing remote connection](#use-an-existing-remote-connection-api) #### Create a remote connection (API) To create a remote connection to replicate data to, send a `POST` request to your local InfluxDB OSS `/api/v2/remotes` endpoint: ``` POST localhost:8086/api/v2/remotes ``` Include the following parameters in your request: * **Request method:** `POST` * **Headers:** * **Authorization:** `Token` scheme with your local InfluxDB OSS [API token](/influxdb/v2/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields: \* Required * \* **allowInsecureTLS:** All insecure TLS connections * **description:** Remote description * \* **name:** Remote connection name * \* **orgID:** local InfluxDB OSS organization ID * \* **remoteAPIToken:** Remote InfluxDB API token *(API token must have write access to the target bucket)* * \* **remoteOrgID:** Remote InfluxDB organization ID * \* **remoteURL:** Remote InfluxDB instance URL ```sh curl --request POST http://localhost:8086/api/v2/remotes \ --header 'Authorization: Token INFLUX_OSS_TOKEN' \ --data '{ "allowInsecureTLS": false, "description": "Example remote description", "name": "Example remote name", "orgID": "INFLUX_OSS_ORG_ID", "remoteAPIToken": "REMOTE_INFLUX_TOKEN", "remoteOrgID": "REMOTE_INFLUX_ORG_ID", "remoteURL": "https://cloud2.influxdata.com" }' ``` #### Use an existing remote connection (API) Alternatively, you can use an existing connection that you have already configured. To retrieve existing connections, use the `/api/v2/remotes`endpoint with the `GET` request method: ``` GET localhost:8086/api/v2/remotes ``` Include the following parameters in your request: * **Headers:** * **Authorization:** `Token` scheme with your local InfluxDB OSS [API token](/influxdb/v2/admin/tokens/) * **Query parameters:** * **orgID:** Local InfluxDB OSS organization ID ```sh curl --request GET \ http://localhost:8086/api/v2/remotes?orgID=INFLUX_OSS_ORG_ID \ --header 'Authorization: Token INFLUX_OSS_TOKEN' \ ``` ### Step 2: Create a replication stream (API) Send a `POST` request to your local InfluxDB OSS`/api/v2/replications` endpoint to create a replication stream. ``` POST localhost:8086/api/v2/remotes ``` Include the following parameters in your request: * **Headers:** * **Authorization:** `Token` scheme with your local InfluxDB OSS [API token](/influxdb/v2/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields:\* Required * **dropNonRetryableData:** Drop data when a non-retryable error is encountered. * \* **localBucketID:** Local InfluxDB OSS bucket ID to replicate writes from. * \* **maxAgeSeconds:** Maximum age of data in seconds before it is dropped (default is `604800`, must be greater than or equal to `0`). * \* **maxQueueSizeBytes:** Maximum replication queue size in bytes (default is `67108860`, must be greater than or equal to `33554430`). * \* **name:** Replication stream name. * \* **orgID:** Local InfluxDB OSS organization ID. * \* **remoteBucketID:** Remote bucket ID to replicate writes to. * \* **remoteBucketName:** Remote bucket name to replicate writes to. If replicating to **InfluxDB Enterprise v1**, use the `db-name/rp-name` bucket name syntax. > [!Note] > `remoteBucketID` and `remoteBucketName` are mutually exclusive. > If replicating to **InfluxDB Enterprise v1**, use `remoteBucketName` with the `db-name/rp-name` bucket name syntax. ```sh curl --request POST http://localhost:8086/api/v2/replications \ --header 'Authorization: Token INFLUX_OSS_TOKEN' \ --data '{ "dropNonRetryableData": false, "localBucketID": "INFLUX_OSS_BUCKET_ID", "maxAgeSeconds": 604800, "maxQueueSizeBytes": 67108860, "name": "Example replication stream name", "orgID": "INFLUX_OSS_ORG_ID", "remoteBucketName": "REMOTE_INFLUX_BUCKET_NAME", "remoteID": "REMOTE_ID", }' ``` After you create a replication stream, InfluxDB OSS replicates all writes from the specified local bucket to the remote InfluxDB bucket. To get information such as the current queue size, max queue size, and latest status code for each replication stream, send a `GET` request to your local InfluxDB OSS `/api/v2/replications` endpoint: ``` GET localhost:8086/api/v2/replications ``` Include the following parameters in your request: * **Headers:** * **Authorization:** `Token` scheme with your local InfluxDB OSS [API token](/influxdb/v2/admin/tokens/) * **Query parameters:** * **orgID:** Local InfluxDB OSS organization ID ```sh curl --request GET \ http://localhost:8086/api/v2/replications?orgID=INFLUX_OSS_ORG_ID \ --header 'Authorization: Token INFLUX_OSS_TOKEN' \ ``` > [!Note] > #### Important things to note > > * Only write operations are replicated. Other data operations (like deletes or restores) are not replicated. > * In InfluxDB OSS, large write request bodies are written entirely. > When replicated, write requests are sent to the remote bucket in batches. > The maximum batch size is 500 kB (typically between 250 to 500 lines of line protocol). > This may result in scenarios where some batches succeed and others fail. ## Replicate downsampled or processed data In some cases, you may not want to write raw, high-precision data to a remote InfluxDB instance. To replicate only downsampled or processed data: 1. Create a bucket in your InfluxDB OSS instance to store downsampled or processed data in. 2. Create an InfluxDB task that downsamples or processes data and stores it in the new bucket. For example: ``` import "influxdata/influxdb/tasks" import "types" // omit this line if adding task via the UI option task = {name: "Downsample raw data", every: 10m} data = () => from(bucket: "example-bucket") |> range(start: tasks.lastSuccess(orTime: -task.every)) numeric = data() |> filter(fn: (r) => types.isType(v: r._value, type: "float") or types.isType(v: r._value, type: "int") or types.isType(v: r._value, type: "uint")) |> aggregateWindow(every: task.every, fn: mean) nonNumeric = data() |> filter(fn: (r) => types.isType(v: r._value, type: "string") or types.isType(v: r._value, type: "bool")) |> aggregateWindow(every: task.every, fn: last) union(tables: [numeric, nonNumeric]) |> to(bucket: "example-downsampled-bucket") ``` 3. [Create a replication stream](#configure-a-replication-stream) to replicate data from the downsampled bucket to the remote InfluxDB instance. ## View InfluxDB OSS replication service metrics In addition to replication stream information that you can access using the [CLI](?t=CLI#configure-a-replication-stream) or [API](?t=API#configure-a-replication-stream), you can view replication service-level metrics for your InfluxDB OSS instance, such as `/api/v2/write` error details, the number and duration of calls to the service, and the total number of points queued. To view replication service-level metrics send a `GET` request to your local InfluxDB OSS `/metrics` endpoint. For more information, see [InfluxDB OSS metrics](/influxdb/v2/reference/internals/metrics/). #### Related * [influx remote](/influxdb/v2/reference/cli/influx/remote/) * [influx replication](/influxdb/v2/reference/cli/influx/replication/) [write](/influxdb/v2/tags/write/)[replication](/influxdb/v2/tags/replication/) --- # Troubleshoot issues writing data Source: https://docs.influxdata.com/influxdb/v2/write-data/troubleshoot/ This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. > [!Important] > #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 > > Stronger token security: tokens are stored as hashes on disk, so a > copy of the database file doesn’t expose usable tokens. Existing > tokens are hashed on first startup and the original strings can’t > be recovered afterward — **capture any plaintext tokens you still > need before you upgrade**. > > For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Learn how to avoid unexpected results and recover from errors when writing to InfluxDB. * [Handle `write` and `delete` responses](#handle-write-and-delete-responses) * [Troubleshoot failures](#troubleshoot-failures) * [Troubleshoot rejected points](#troubleshoot-rejected-points) ## Handle `write` and `delete` responses InfluxDB does the following when you send a write request: 1. Validates the request. 2. If successful, attempts to [ingest data](/influxdb/v2/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes). 3. Ingests or rejects data from the batch and returns one of the following HTTP status codes: * `204 No Content`: All of the data is ingested and queryable. * `422 Unprocessable Entity`: 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). 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 uses conventional HTTP status codes to indicate the success or failure of a request. Write requests return the following status codes: * `204` **Success**: All request data was written to the bucket. * `400` **Bad request**: The response body contains the first malformed line in the data. All request data was rejected and not written. * `401` **Unauthorized**: May indicate one of the following: * [`Authorization: Token` header](/influxdb/v2/api-guide/api_intro/#authentication) is missing or malformed. * [API token](/influxdb/v2/api-guide/api_intro/#authentication) value is missing from the header. * API token does not have sufficient permissions to write to the organization and the bucket. For more information about token types and permissions, see [Manage API tokens](/influxdb/v2/admin/tokens/). * `404` **Not found**: A requested resource, such as an organization or bucket, was not found. The response body contains the requested resource type (for example, “organization”) and resource name. * `413` **Request entity too large**: All request data was rejected and not written. InfluxDB OSS only returns this error if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. * `422` **Unprocessable entity**: The request was well-formed, but some or all the points were rejected due to semantic errors–for example, schema conflicts or retention policy violations. * `500` **Internal server error**: Default HTTP status for an error. * `503` **Service unavailable**: Server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. The `message` property of the response body may contain additional details about the error. If some of your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). ## Troubleshoot failures If you notice data is missing in your bucket, do the following: * Check the [HTTP status code](#review-http-status-codes) in the response. * Check the `message` property in the response body for details about the error–for example, `partial write` indicates [rejected points](#troubleshoot-rejected-points). * Verify all lines contain valid syntax ([line protocol](/influxdb/v2/reference/syntax/line-protocol/) or [CSV](/influxdb/v2/reference/syntax/annotated-csv/)). * Verify the timestamps match the [precision parameter](/influxdb/v2/write-data/#timestamp-precision) in your request. * Minimize payload size and network errors by [optimizing writes](/influxdb/v2/write-data/best-practices/optimize-writes/). ## Troubleshoot rejected points When writing points from a batch, InfluxDB rejects points that have syntax errors or schema conflicts. If InfluxDB processes the data in your batch and then rejects points, the [HTTP response](#handle-write-responses) body contains the following properties that describe rejected points: * `code`: `"unprocessable entity"` * `message`: a string that describes the reason points were rejected and may provide details, such as database, retention policy, and which bound was violated. For example, the following `message` indicates that points were rejected because the timestamps fall outside the `1d` retention policy: ```text failure writing points to database: partial write: dropped 4 points outside retention policy of duration 24h0m0s - oldest point home,room=Living\\ Room at 1970-01-01T00:00:01.541Z dropped because it violates a Retention Policy Lower Bound at 2025-05-20T19:06:17.612973Z, newest point home,room=Living\\ Room at 1970-01-01T00:00:01.5410006Z dropped because it violates a Retention Policy Lower Bound at 2025-05-20T19:06:17.612973Z dropped=4 for database: 9f282d63c7d3a5c0 for retention policy: autogen ``` InfluxDB rejects points for the following reasons: * a line protocol parsing error * an invalid timestamp * a schema conflict * retention policy violation Schema conflicts occur when you try to write data that contains any of the following: * The **batch** contains another point with the same series, but one of the fields has a different value type. * The **bucket** contains another point with the same series, but one of the fields has a different value type. Check for [field type](/influxdb/v2/reference/key-concepts/data-elements/#field-value) differences between the missing data point and other points that have the same [series](/influxdb/v2/reference/key-concepts/data-elements/#series)–for example, did you attempt to write `string` data to an `int` field? #### Related * [InfluxDB v1 API /write endpoint](/influxdb/v2/api/write-data-v1-compatible/#operation/PostLegacyWrite) * [InfluxDB API /api/v2/write endpoint](/influxdb/v2/api/write-data/#operation/PostWrite) * [InfluxDB internals](/influxdb/v2/reference/internals/) * [influx write](/influxdb/v2/reference/cli/influx/write/) [write](/influxdb/v2/tags/write/)[line protocol](/influxdb/v2/tags/line-protocol/)[errors](/influxdb/v2/tags/errors/)