# InfluxDB Cloud (TSM) — full Markdown corpus > Generated 2026-10-31T04:19:00.191Z from https://docs.influxdata.com/influxdb/cloud/ > 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 Cloud Source: https://docs.influxdata.com/influxdb/cloud/ --- # Manage your InfluxDB Cloud Account Source: https://docs.influxdata.com/influxdb/cloud/account-management/ ### [InfluxDB Cloud plans](/influxdb/cloud/account-management/pricing-plans/) InfluxDB Cloud provides two pricing plans to fit your needs – the Free Plan and the Usage-based Plan. ### [Manage billing](/influxdb/cloud/account-management/billing/) Upgrade to the InfluxDB Cloud Usage-Based Plan and manage your billing information. ### [View data usage](/influxdb/cloud/account-management/data-usage/) View your InfluxDB Cloud data usage and rate limit notifications. ### [Change your password](/influxdb/cloud/account-management/change-password/) To update your InfluxDB Cloud password, click the **Forgot Password** link on the [InfluxDB Cloud login page](https://cloud2.influxdata.com/login). Passwords must be at least 8 characters in length, and must not contain common words, personal information, or previous passwords. ### [Switch InfluxDB Cloud accounts](/influxdb/cloud/account-management/switch-account/) Switch from one InfluxDB Cloud account to another and set a default account. ### [Switch InfluxDB Cloud organizations](/influxdb/cloud/account-management/switch-org/) Switch from one InfluxDB Cloud organization to another. ### [Cancel your InfluxDB Cloud subscription](/influxdb/cloud/account-management/offboarding/) Cancel your InfluxDB Cloud account at any time by stopping all read and write requests, and backing up data. ### [Limits and adjustable quotas](/influxdb/cloud/account-management/limits/) InfluxDB Cloud has adjustable service quotas and global (non-adjustable) system limits. --- # Manage InfluxDB Cloud billing Source: https://docs.influxdata.com/influxdb/cloud/account-management/billing/ Learn how to upgrade your plan, access billing details, and review and resolve plan limit overages: * [Upgrade to Usage-Based Plan](#upgrade-to-usage-based-plan) * [Access billing details](#access-billing-details): * [Add or update your payment method](#add-or-update-your-payment-method) * [Add or update your contact information](#add-or-update-your-contact-information) * [Send notifications when usage exceeds an amount](#send-notifications-when-usage-exceeds-an-amount#send-notifications-when-usage-exceeds-an-amount) * [View Usage-based Plan information](#view-usage-based-plan-information) * [View Free Plan information](#view-free-plan-information) * [Review and resolve plan limit overages](#review-and-resolve-plan-limit-overages) * [Billing cycle](#billing-cycle) * [Declined or late payments](#declined-or-late-payments) ## Upgrade to Usage-Based Plan 1. Click **Upgrade Now** in the upper right corner of the InfluxDB Cloud user interface (UI). 2. Set your limits (opt to receive an email when your usage exceeds the amount you enter in the **Limit ($1 minimum)** field). All service updates, security notifications, and other important information are sent to the email address you provide. 3. Enter your payment information and billing address, and then click **Upgrade**. A Ready To Rock confirmation appears; click **Start building your team**. Your plan will be upgraded and InfluxDB Cloud (TSM) opens with a default organization and bucket (both created from your email address). ## Access billing details 1. In the top navigation menu, click the drop-down menu with the same of your account. 2. Click **Billing**. 3. Do one of the following: * If you subscribed to an InfluxDB Cloud plan through [**AWS Marketplace**](https://aws.amazon.com/marketplace/pp/B08234JZPS), [**Azure Marketplace**](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/influxdata.influxdb-cloud), or [**GCP Marketplace**](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod?pli=1), click the **AWS**, **Microsoft**, or **GCP** link to access your billing and subscription information. * If you subscribed to an InfluxDB Cloud plan through **InfluxData**, complete the following procedures as needed: * [Add or update your payment method](#add-or-update-your-payment-method) * [Add or update your contact information](#add-or-update-your-contact-information) * [Send notifications when usage exceeds an amount](#send-notifications-when-usage-exceeds-an-amount) 4. View information about: * [Usage-Based Plan](#view-usage-based-plan-information) * [Free Plan](#view-free-plan-information) * [Exceeded rate limits](#review-and-resolve-plan-limit-overages) * [Billing cycle](#billing-cycle) * [Declined or late payments](#declined-or-late-payments) ### Add or update your payment method * On the **Billing page**: * To update your card, click the **Change Payment** button on the Billing page. * In the **Payment Method** section: * Enter your cardholder name and number * Select your expiration month and year * Enter your CVV code and select your card type ### Add or update your contact information 1. On the **Billing page**: * To update, click the **Edit Information** button. * In the **Contact Information** section, enter your name, company, and address. 2. Click **Save Contact Info**. ### Send notifications when usage exceeds an amount 1. On the **Billing page**, click **Notification Settings**. 2. Select the **Send email notification** toggle, and then enter the email address to notify. 3. Enter the dollar amount to trigger a notification email. By default, an email is triggered when the amount exceeds $10. (Whole dollar amounts only. For example, $10.50 is not a supported amount.) ### View Usage-based Plan information On the **Billing page**, view your billing information, including: * Account balance * Last billing update (updated hourly) * Past invoices * Payment method * Contact information * Notification settings ### View Free Plan information On the **Billing page**, view the total limits available for the Free Plan. ## Review and resolve plan limit overages If you exceed your plan’s [adjustable quotas or limits](/influxdb/cloud/account-management/limits/), you’ll receive a notification in the InfluxDB Cloud user interface (UI) **Usage** page. If you exceed the series cardinality limit, InfluxDB adds a rate limit event warning on the **Usage** page, and begins to reject write requests with new series. To start processing write requests again, do the following as needed: * **Series cardinality limits**: If you exceed the series cardinality limit, see how to [resolve high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/). * **Free plan**: To raise rate limits, [upgrade to a Usage-based Plan](#upgrade-to-usage-based-plan). #### Write and query limits (HTTP response code) When a request exceeds your plan’s write requests (Data In) or query requests (Reads) within a five minute window, the InfluxDB API returns the following response: ``` HTTP 429 “Too Many Requests” Retry-After: xxx (seconds to wait before retrying the request) ``` ## Billing cycle Billing occurs on the first day of the month for the previous month. For example, if you start the Usage-based Plan on September 15, you’re billed on October 1 for your usage from September 15-30. ### Declined or late payments | Timeline | Action | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |**Initial declined payment**| We’ll retry charge every 72 hours. During this period, update your payment method to successfully process your payment. | | **One week later** | Account disabled except data writes. Update your payment method to successfully process your payment and enable your account. | | **10-14 days later** |Account completely disabled. During this period, you must contact [InfluxData Support](https://support.influxdata.com/) to process your payment and enable your account.| | **21 days later** | Account suspended. Contact [InfluxData Support](https://support.influxdata.com/) to settle your final bill and discuss options for resuming service. | | Timeline | Action | | --- | --- | | Timeline | Action | | Initial declined payment | We’ll retry charge every 72 hours. During this period, update your payment method to successfully process your payment. | | One week later | Account disabled except data writes. Update your payment method to successfully process your payment and enable your account. | | 10-14 days later | Account completely disabled. During this period, you must contact InfluxData Support to process your payment and enable your account. | | 21 days later | Account suspended. Contact InfluxData Support to settle your final bill and discuss options for resuming service. | --- # Change your password Source: https://docs.influxdata.com/influxdb/cloud/account-management/change-password/ To change or reset your InfluxDB Cloud password: 1. Click the **Forgot Password** link on the [InfluxDB Cloud login page](https://cloud2.influxdata.com/login). 2. Open the **InfluxCloud: Password Change Requested** email sent to the email address associated with your InfluxDB Cloud account, click the **Reset Password**button, and then enter and confirm a new password. ### Password requirements Passwords must meet the following requirements: * Must be longer than 8 characters. * Must not contain personal information. * Must not be a common or previous password. These requirements follow the National Institute of Standards and Technology (NIST) standards for 2021. --- # View InfluxDB Cloud data usage Source: https://docs.influxdata.com/influxdb/cloud/account-management/data-usage/ View the statistics of your data usage and rate limits (reads, writes, and delete limits) on the Usage page. Some usage data affects monthly costs ([pricing vectors](/influxdb/cloud/account-management/pricing-plans/#pricing-vectors)) and other usage data (for example, delete limits), does not affect pricing. For more information, see the [InfluxDB Cloud limits and adjustable quotas](/influxdb/cloud/account-management/limits/). To view your InfluxDB Cloud (TSM) data usage, do the following: 1. Click on your email address in the upper left hand corner. 2. Select **Usage** from the dropdown menu. 3. Select a time range to review data usage (by default, `Past 24h`), and then select one of the following: * **Data In:** Total data in MB written to your InfluxDB Cloud instance. Data in and write requests do not count towards your query count. * **Query Count:** Total number of individual query operations, which include queries, tasks (alerts, notifications) and Data Explorer activity. Note, a script that includes multiple requests (for example, has multiple `from()...` lines) counts as one query. * **Storage:** Total disk usage in gigabytes. * **Data Out:** Total data in MB sent as responses to queries from your InfluxDB Cloud instance. A line graph displays usage for the selected vector for the specified time period. #### Related * [usage.from() function](/flux/v0/stdlib/experimental/usage/from/) * [usage.limits() function](/flux/v0/stdlib/experimental/usage/limits/) --- # InfluxDB Cloud limits and adjustable quotas Source: https://docs.influxdata.com/influxdb/cloud/account-management/limits/ InfluxDB Cloud applies (non-adjustable) global system limits and adjustable service quotas on a per organization basis. All **rates** (data-in (writes), queries (reads), and deletes) are accrued within a fixed five-minute window. Once a rate is exceeded, an error response is returned until the current five-minute window resets. Review adjustable service quotas and global limits to plan for your bandwidth needs: * [Adjustable service quotas](#adjustable-service-quotas) * [Global limits](#global-limits) * [UI error messages](#ui-error-messages) * [API error responses](#api-error-responses) ## Adjustable service quotas To reduce the chance of unexpected charges and protect the service for all users, InfluxDB Cloud has adjustable service quotas applied per account. ### Free Plan * **Data-in**: Rate of 5 MB per 5 minutes (average of 17 kb/s) * Uncompressed bytes of normalized [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * **Read**: Rate of 300 MB per 5 minutes (average of 1000 kb/s) * Bytes in HTTP in response payload * **Cardinality**: 10k series (see [how to measure and resolve high cardinality](/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/)) * **Available resources**: * 2 buckets (excluding `_monitoring` and `_tasks` buckets) * 5 dashboards * 5 tasks * **Alerts**: * 2 checks * 2 notification rules * Unlimited Slack notification endpoints * **Storage**: 30 days of data retention (see [retention period](/influxdb/cloud/reference/glossary/#retention-period)) > [!Note] > To write historical data older than 30 days, retain data for more than 30 days, increase rate limits, or create additional organizations, upgrade to the Cloud [Usage-Based Plan](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan). ### Usage-Based Plan * **Data-in**: Rate of 300 MB per 5 minutes * Uncompressed bytes of normalized [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * **Read**: Rate of 3 GB data per 5 minutes * Bytes in HTTP in response payload * **Cardinality**: 1M series (see [how to measure and resolve high cardinality](/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/)) * **Unlimited resources** * dashboards * tasks * buckets * users * **Alerts** * Unlimited checks * Unlimited notification rules * Unlimited notification endpoints for [all endpoints](/flux/v0/tags/notification-endpoints/) * **Storage**: Set your retention period to unlimited or up to 1 year by [updating a bucket’s retention period in the InfluxDB UI](/influxdb/cloud/admin/buckets/update-bucket/#update-a-buckets-retention-period-in-the-influxdb-ui), or [set a custom retention period](/influxdb/cloud/admin/buckets/update-bucket/#update-a-buckets-retention-period) using the [`influx` CLI](/influxdb/cloud/reference/cli/influx/). ## Global limits InfluxDB Cloud applies global (non-adjustable) system limits to all accounts, which protects the InfluxDB Cloud infrastructure for all users. As the service continues to evolve, we’ll continue to review these global limits and adjust them as appropriate. Limits include: * **Write request limits**: * 50 MB maximum HTTP request batch size (compressed or uncompressed–defined in the `Content-Encoding` header) * 250 MB maximum HTTP request batch size after decompression * **Query processing time**: 90 seconds * **Total query time**: 1500 seconds of *total* query time every 30 seconds * **Task processing time**: 150 seconds * **Total task time**: 1500 seconds of *total* task time every 30 seconds * **Delete request limit**: Rate of 300 every 5 minutes > [!Note] > **Tip:**Combine delete predicate expressions (if possible) into a single request. InfluxDB limits delete requests by number of requests (not points per request). ## UI error messages The InfluxDB Cloud (TSM) UI displays a notification message when service quotas or limits are exceeded. The error messages correspond with the relevant [API error responses](#api-error-responses). Errors can also be viewed in the [Usage page](/influxdb/cloud/account-management/data-usage/) under **Limit Events**, for example: `event_type_limited_query`, `event_type_limited_write`,`event_type_limited_cardinality`, or `event_type_limited_delete_rate`. ## API error responses The following API error responses occur when your plan’s service quotas are exceeded. | HTTP response code | Error message | Description | |------------------------------|--------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`HTTP 413 "Request Too Large"`| cannot read data: points in batch is too large | If a **write** request exceeds the maximum [global limit](#global-limits) | |`HTTP 429 "Too Many Requests"`|Retry-After: xxx (seconds to wait before retrying the request)|If a **read** or **write** request exceeds your plan’s [adjustable service quotas](#adjustable-service-quotas) or if a **delete** request exceeds the maximum [global limit](#global-limits)| |`HTTP 429 "Too Many Requests"`| Series cardinality exceeds your plan’s service quota | If **series cardinality** exceeds your plan’s [adjustable service quotas](#adjustable-service-quotas) | #### Related * [usage.from() function](/flux/v0/stdlib/experimental/usage/from/) * [usage.limits() function](/flux/v0/stdlib/experimental/usage/limits/) * [Resolve high series cardinality](/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/) | HTTP response code | Error message | Description | | --- | --- | --- | | HTTP response code | Error message | Description | | HTTP 413 "Request Too Large" | cannot read data: points in batch is too large | If a write request exceeds the maximum global limit | | HTTP 429 "Too Many Requests" | Retry-After: xxx (seconds to wait before retrying the request) | If a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit | | HTTP 429 "Too Many Requests" | Series cardinality exceeds your plan’s service quota | If series cardinality exceeds your plan’s adjustable service quotas | --- # Cancel your InfluxDB Cloud subscription Source: https://docs.influxdata.com/influxdb/cloud/account-management/offboarding/ To cancel your InfluxDB Cloud (TSM) subscription, complete the following steps: 1. [Stop reading and writing data](#stop-reading-and-writing-data). 2. [Export data and other artifacts](#export-data-and-other-artifacts). 3. [Cancel service](#cancel-service). ### Stop reading and writing data To stop being charged for InfluxDB Cloud, pause all writes and queries. ### Export data and other artifacts To export data and artifacts, follow the steps below. > [!Note] > Exported data and artifacts can be used in an InfluxDB OSS instance. #### Export tasks For details, see [Export a task](/influxdb/cloud/process-data/manage-tasks/export-task/). #### Export dashboards For details, see [Export a dashboard](/influxdb/cloud/visualize-data/dashboards/export-dashboard/). #### Save Telegraf configurations 1. Click the **Load Data** icon in the navigation bar. Load Data 2. Select the **Telegraf** tab. A list of existing Telegraf configurations appears. 3. Click the name of a Telegraf configuration. 4. Click **Download Config** to save. #### Export data To export all your data, query your data out in time-based batches and store it in to an external system or an InfluxDB OSS instance. For information about automatically exporting and migrating data from InfluxDB Cloud to InfluxDB OSS, see: [Migrate data from InfluxDB Cloud to InfluxDB OSS](/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-oss/). ### Cancel service > [!Note] > Cancelling your usage-based plan will delete your organization. 1. Click the account name in the header of your InfluxDB Cloud user interface (UI) and select **Billing**. 2. Do one of the following: * If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **AWS Marketplace**, click the **AWS** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. * If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **GCP Marketplace**, click the **GCP** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. * If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **InfluxData**, click **Cancel Service**. Select **I understand and agree to these conditions**, and then click **I understand, Cancel Service.** Click **Confirm and Cancel Service**. Your payment method is charged your final balance immediately upon cancellation of service. --- # InfluxDB Cloud plans Source: https://docs.influxdata.com/influxdb/cloud/account-management/pricing-plans/ InfluxDB Cloud offers a [Free Plan](#free-plan), a [Usage-Based Plan](#usage-based-plan) to pay as you go, and a discounted [Annual Plan](#annual-plan). ## Free Plan All new InfluxDB Cloud (TSM) accounts start with Free Plan that provides a limited number of resources and data usage. See [plan limits](/influxdb/cloud/account-management/limits/). ## Usage-Based Plan The Usage-Based Plan offers more flexibility and ensures you only pay for what you [use](/influxdb/cloud/account-management/data-usage/). Usage-Based Plans are based on consumption as measured by usage on the [pricing vectors](#pricing-vectors). Usage-Based Plans also offer access to all notification endpoints such as PagerDuty, Slack, HTTP, and [endpoints available in Flux](/flux/v0/tags/notification-endpoints/). ### Pricing vectors The Usage-Based Plan uses the following pricing vectors to calculate InfluxDB Cloud billing costs: * **Data out** is the total sum of the data (measured in GB) returned to the user to answer a query, also known as data transfer costs. * **Query count** is the total number of individual query operations: * Each individual operation—including queries, tasks, alerts, notifications, and Data Explorer activity—is one billable query operation. * Refreshing a dashboard with multiple cells will incur multiple query operations. * Failed operations aren’t counted. * **Data In** is the amount of data you’re writing into InfluxDB (measured in MB). * **Storage** is the amount of data you’re storing in InfluxDB (measured in GB/hour). Discover how to [manage InfluxDB Cloud billing](/influxdb/cloud/account-management/billing/). ## Annual Plan An Annual Plan offers a discount for a commitment to a specific amount of usage over set period of time. This plan uses the same pricing vectors and calculation methodology as Usage-Based Plans. **Interested in an Annual Plan? Reach out to [InfluxData Sales](https://www.influxdata.com/contact-sales/).** --- # Switch InfluxDB Cloud accounts Source: https://docs.influxdata.com/influxdb/cloud/account-management/switch-account/ If you belong to more than one InfluxDB Cloud (TSM) account with the same email address, you can switch from one account to another while staying logged in. An account can contain multiple organizations. You can also set a default account. The default account is the account automatically used when the user logs in. To switch InfluxDB Cloud accounts: 1. In the InfluxDB Cloud UI, click the account name drop-down list in the upper left. 2. Select **Switch Account**. If this option doesn’t appear, your email address is only associated with one account. 3. Select the account you want to switch to. To set an account as the default: 1. Click the user avatar in the upper-right and select **Profile**. 2. Select a **Default Account** from the drop-down list. 3. Click **Save Changes**. --- # Switch InfluxDB Cloud organizations Source: https://docs.influxdata.com/influxdb/cloud/account-management/switch-org/ If you belong to more than one InfluxDB Cloud (TSM) organization with the same email address, you can switch from one organization to another while staying logged in. To switch InfluxDB Cloud organizations: 1. (Optional) To switch to an organization in a different account, [switch accounts](/influxdb/cloud/account-management/switch-account/). 2. In the InfluxDB Cloud UI, click the organization name in the header and select **Switch Organizations**. 3. Select the organization you want to switch to from the drop-down list. > [!Note] > #### Migrate to InfluxDB Cloud Serverless > > To unlock the benefits of the InfluxDB 3 storage engine, including unlimited > cardinality and SQL, [migrate your data to an InfluxDB Cloud Serverless organization](/influxdb3/cloud-serverless/write-data/migrate-data/migrate-tsm-to-serverless/). > > All InfluxDB Cloud [accounts](/influxdb3/cloud-serverless/admin/accounts/) and[organizations](/influxdb3/cloud-serverless/admin/organizations/) created through[cloud2.influxdata.com](https://cloud2.influxdata.com) on or after **January 31, 2023**are on InfluxDB Cloud Serverless and are powered by the InfluxDB 3 storage engine. > > To see which storage engine your organization uses, find the **InfluxDB Cloud powered by**link in your [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com)version information. If your organization is using TSM, you’ll see **TSM**followed by the version number. If Serverless, you’ll see **InfluxDB Cloud Serverless**followed by the version number. #### Related * [Switch InfluxDB Cloud accounts](/influxdb/cloud/account-management/switch-account/) --- # Administer InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/admin/ Use the InfluxDB API, user interface (UI), and CLIs to perform administrative tasks in InfluxDB Cloud (TSM). ### [Identify InfluxDB Cloud (TSM) version](/influxdb/cloud/admin/identify-version/) Learn how to identify your InfluxDB Cloud (TSM) instance through URL patterns, account settings, and HTTP headers. ### [Manage organizations](/influxdb/cloud/admin/organizations/) Manage organizations in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage API tokens](/influxdb/cloud/admin/tokens/) Manage API tokens in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage buckets](/influxdb/cloud/admin/buckets/) Manage buckets in InfluxDB using the InfluxDB UI or the influx CLI. ### [Manage secrets](/influxdb/cloud/admin/secrets/) Manage and use secrets in InfluxDB Cloud. --- # Manage buckets Source: https://docs.influxdata.com/influxdb/cloud/admin/buckets/ 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/cloud/admin/buckets/create-bucket/) Create buckets to store time series data in InfluxDB Cloud using the InfluxDB UI, influx CLI, or InfluxDB HTTP API. ### [Update a bucket](/influxdb/cloud/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/cloud/admin/buckets/view-buckets/) View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI, influx CLI, or InfluxDB HTTP API. ### [Delete a bucket](/influxdb/cloud/admin/buckets/delete-bucket/) Delete a bucket from InfluxDB using the InfluxDB UI or the influx CLI ### [Manage bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema/) Manage explicit bucket schemas using the influx CLI or InfluxDB HTTP API. Optionally, ensure data you write follows a specific schema. [buckets](/influxdb/cloud/tags/buckets/) --- # Manage bucket schemas Source: https://docs.influxdata.com/influxdb/cloud/admin/buckets/bucket-schema/ Use [**explicit bucket schemas**](/influxdb/cloud/reference/key-concepts/data-elements/#bucket-schema) to enforce [column names](/influxdb/cloud/reference/glossary/#column), [tags](/influxdb/cloud/reference/glossary/#tag), [fields](/influxdb/cloud/reference/glossary/#field), and[data types](/influxdb/cloud/reference/glossary/#data-type) for your data. Explicit bucket schemas ensure that measurements have specific columns and data types and prevent non-conforming write requests. After you create a bucket schema, you’re ready to [write data](/influxdb/cloud/write-data/) to your bucket. > [!Note] > #### Before you begin > > The examples below reference [**InfluxDB data elements**](/influxdb/cloud/reference/key-concepts/data-elements/). We recommend reviewing data elements, [**InfluxDB key concepts**](/influxdb/cloud/reference/key-concepts/), and [**elements of line protocol**](/influxdb/cloud/reference/syntax/line-protocol/#elements-of-line-protocol) if you aren’t familiar with these concepts. * [Create an explicit bucket and schema](#create-an-explicit-bucket-and-schema) * [Create a bucket schema using the influx CLI](#create-a-bucket-schema-using-the-influx-cli) * [Create a bucket schema using the InfluxDB HTTP API](#create-a-bucket-schema-using-the-influxdb-http-api) * [Write valid schemas](#write-valid-schemas) * [View bucket schema type and schemas](#view-bucket-schema-type-and-schemas) * [View schema type and schemas in the InfluxDB UI](#view-schema-type-and-schemas-in-the-influxdb-ui) * [View schema type and schemas using the influx CLI](#view-schema-type-and-schemas-using-the-influx-cli) * [View schema type and schemas using the InfluxDB HTTP API](#view-schema-type-and-schemas-using-the-influxdb-http-api) * [Update a bucket schema](#update-a-bucket-schema) * [Update a bucket schema using the influx CLI](#update-a-bucket-schema-using-the-influx-cli) * [Update a bucket schema using the InfluxDB HTTP API](#update-a-bucket-schema-using-the-influxdb-http-api) * [Troubleshoot bucket schema errors](#troubleshoot-bucket-schema-errors) * [Troubleshoot write errors](#troubleshoot-write-errors) ## Create an explicit bucket and schema To create an explicit bucket and schemas for your data, do the following: 1. If you haven’t already, [create a bucket that enforces explicit schemas](/influxdb/cloud/admin/organizations/buckets/create-bucket/#create-a-bucket-that-enforces-explicit-schemas). 2. [Create a bucket schema](#create-a-bucket-schema). ### Create a bucket schema With an `explicit` bucket, you predefine *measurement schemas* with column names, tags, fields, and data types for measurements. A measurement schema has the following properties: * `name`: the measurement name. The name must match the [measurement column](/influxdb/cloud/reference/key-concepts/data-elements/#measurement) in your data, obey [naming rules](#write-valid-schemas), and be unique within the bucket. * `columns`: a list of *column definitions* for the measurement. To learn more about rules for measurement *names* and *columns*, see how to [write valid schemas](#write-valid-schemas). Use the [**`influx` CLI**](/influxdb/cloud/reference/cli/influx/) or [**InfluxDB HTTP API**](/influxdb/cloud/api) to create an explicit bucket schema for a measurement. * [Create a bucket schema using the influx CLI](#create-a-bucket-schema-using-the-influx-cli) * [Create a bucket schema using the InfluxDB HTTP API](#create-a-bucket-schema-using-the-influxdb-http-api) #### Create a bucket schema using the influx CLI 1. Use your text editor to create a schema columns file for each measurement you want to add. Format the file as CSV, JSON, or [Newline delimited JSON (NDJSON)](https://jsonlines.org/), as in the following examples: [usage-resources.csv](#usage-resourcescsv)[usage-cpu.json](#usage-cpujson)[sensor.ndjson](#sensorndjson) ``` name,type,dataType time,timestamp, host,tag, service,tag, fsRead,field,float fsWrite,field,float ``` ``` [ {"name": "time", "type": "timestamp"}, {"name": "service", "type": "tag"}, {"name": "host", "type": "tag"}, {"name": "usage_user", "type": "field", "dataType": "float"}, {"name": "usage_system", "type": "field", "dataType": "float"} ] ``` ``` {"name": "time", "type": "timestamp"} {"name": "service", "type": "tag"} {"name": "sensor", "type": "tag"} {"name": "temperature", "type": "field", "dataType": "float"} {"name": "humidity", "type": "field", "dataType": "float"} ``` 2. Use the [`influx bucket-schema create` command](/influxdb/cloud/reference/cli/influx/bucket-schema/create) to define an *explicit* bucket measurement schema. In your command, specify values for the following flags: * `--name`: the measurement name. * `--columns-file`: the location of the file that contains *column definitions* for your measurement. For example, each of the following commands adds a unique measurement schema to the bucket: ``` influx bucket-schema create \ --bucket my_explicit_bucket \ --name usage_resources \ --columns-file usage-resources.csv influx bucket-schema create \ --bucket my_explicit_bucket \ --name usage_cpu \ --columns-file usage-cpu.json influx bucket-schema create \ --bucket my_explicit_bucket \ --name sensor \ --columns-file sensor.ndjson ``` #### Create a bucket schema using the InfluxDB HTTP API Send a request to the HTTP API [`/api/v2/buckets/{BUCKET_ID}/schema/measurements` endpoint](/influxdb/cloud/api/buckets//-bucketID-/schema/measurements)and set the following properties in the request body: * `name`: the measurement name. * `columns`: an array of *column definitions* for your measurement. For example, the following request defines the *explicit* bucket measurement schema for `airSensors` measurements: ``` POST https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements ``` ```json { "name": "airSensors", "columns": [ {"name": "time", "type": "timestamp"}, {"name": "sensorId", "type": "tag"}, {"name": "temperature", "type": "field"}, {"name": "humidity", "type": "field", "dataType": "float"} ] } ``` > [!Note] > #### Test your schema > > After you create an explicit schema, test that it works as you expect. > To start, we recommend trying to write data that doesn’t conform to the schema and that the bucket should reject. > > For more information about errors to expect in your tests, see [explicit schema rejections](/influxdb/cloud/write-data/troubleshoot/#troubleshoot-rejected-points). ### Write valid schemas To ensure your schema is valid, review [InfluxDB data elements](/influxdb/cloud/reference/key-concepts/data-elements/). Follow these rules when creating your schema columns file: 1. Use valid measurement and column names that: * Are unique within the schema * Are 1 to 128 characters long * Contain only [Unicode](https://www.unicode.org/charts/) characters * Don’t start with underscore `_` * Don’t start with a number `0-9` * Don’t contain single quote `'` or double quote `"` 2. Include a column with the [`timestamp`](/influxdb/cloud/reference/key-concepts/data-elements/#timestamp) type. 3. Include at least one column with the [`field`](/influxdb/cloud/reference/key-concepts/data-elements/#fields) type (without a field, there is no time-series data), as in the following example: **Valid**: a schema with [`timestamp`]() and [`field`]() columns. ```json [ {"name":"time","type":"timestamp"}, {"name":"fsWrite","type":"field"} ] ``` **Not valid**: a schema without a `field` column. ```json [ {"name":"time","type":"timestamp"}, {"name":"host","type":"tag"} ] ``` The default [field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) is `string`. To set the data type of a field column, provide the `dataType` property and a valid[field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) (`string`, `float`, `integer`, or `boolean`), as in the following example: ```json [ {"name":"time","type":"timestamp"}, {"name":"fsWrite","type":"field","dataType":"float"} ] ``` ## View bucket schema type and schemas Use the **InfluxDB UI**, [**`influx` CLI**](/influxdb/cloud/reference/cli/influx/), or [**InfluxDB HTTP API**](/influxdb/cloud/api) to view schema type and schemas for buckets. ### View schema type and schemas in the InfluxDB UI 1. [View buckets](/influxdb/cloud/admin/organizations/buckets/view-buckets/). 2. In the list of buckets, see the **Schema Type** in the metadata that follows each bucket name. 3. Buckets with **Schema Type: Explicit** display the Show Schema button. Click Show Schema to view measurement schemas for the bucket. ### View schema type and schemas using the influx CLI To list schemas for a bucket, use the [`influx bucket-schema list` command](/influxdb/cloud/reference/cli/influx/bucket-schema/list/). To view schema column definitions and metadata, specify the `--json` flag. ### View schema type and schemas using the InfluxDB HTTP API To list schemas for a bucket, send a request to the InfluxDB HTTP [`/api/v2/buckets/{BUCKET_ID}/schema/measurements` endpoint](/influxdb/cloud/api/buckets//-bucketID-/schema/measurements): ``` GET https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements ``` ## Update a bucket schema Use the **`influx` CLI** or the **InfluxDB HTTP API** to add new columns to an explicit bucket schema. You can’t modify or delete columns in bucket schemas. * [Update a bucket schema using the influx CLI](#update-a-bucket-schema-using-the-influx-cli) * [Update a bucket schema using the InfluxDB HTTP API](#update-a-bucket-schema-using-the-influxdb-http-api) ### Update a bucket schema using the influx CLI 1. [View the existing measurement schema](#view-schema-type-and-schemas-using-the-influx-cli) and save the `columns` list to a file. 2. In your text editor or terminal, append new columns to the list from the previous step. The following example appends column `CO2` to the original *sensor.ndjson* schema file: ``` # sensor.ndjson {"name": "time", "type": "timestamp"} {"name": "service", "type": "tag"} {"name": "sensor", "type": "tag"} {"name": "temperature", "type": "field", "dataType": "float"} {"name": "humidity", "type": "field", "dataType": "float"} ``` ``` echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson ``` 3. To update the bucket schema, use the [`influx bucket-schema update` command](/influxdb/cloud/reference/cli/influx/bucket-schema/update) and specify the columns file with the `--columns-file` flag. ``` influx bucket-schema update \ --bucket my_explicit_bucket \ --name sensor \ --columns-file sensor.ndjson ``` ### Update a bucket schema using the InfluxDB HTTP API 1. [View the existing measurement schema](#view-schema-type-and-schemas-using-the-influxdb-http-api) and copy the `columns` list. 2. Send a request to the HTTP API [`/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}` endpoint](/influxdb/cloud/api/bucket-schemas/). In the request body, set the `columns` property to a list of old and new column definitions for the measurement schema–for example, the following request appends the new column `CO2` to `columns` retrieved in the previous step: ``` PATCH https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID} ``` ``` { "columns": [ {"name": "time", "type": "timestamp"}, {"name": "sensorId", "type": "tag"}, {"name": "temperature", "type": "field"}, {"name": "humidity", "type": "field", "dataType": "float"}, {"name": "CO2", "type": "field", "dataType": "float"} ] } ``` ## Troubleshoot bucket schema errors ### Bucket not found Creating and updating bucket schema requires `WRITE` permission for the bucket. If your [API token](/influxdb/cloud/admin/tokens/) doesn’t have `WRITE` permission for the bucket, InfluxDB returns the following error: ```sh Error: bucket "my_explicit_bucket" not found ``` #### Failed to create measurement Each measurement in a bucket can have one schema. If you attempt to create a schema for an existing measurement, InfluxDB rejects the new schema and returns the following error: ```sh Error: failed to create measurement: 422 Unprocessable Entity ``` ## Troubleshoot write errors InfluxDB returns an error for the following reasons: * data in the write request doesn’t conform to a defined schema. * data in the write request doesn’t have a schema defined for the bucket. * data in the write request has invalid syntax. To resolve failures and partial writes, see how to [troubleshoot writes](/influxdb/cloud/write-data/troubleshoot/). #### Related * [InfluxDB key concepts](/influxdb/cloud/reference/key-concepts/) * [InfluxDB data schema](/influxdb/cloud/reference/key-concepts/data-schema/) * [InfluxDB data elements](/influxdb/cloud/reference/key-concepts/data-elements/) * [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/) [buckets](/influxdb/cloud/tags/buckets/)[bucket-schema](/influxdb/cloud/tags/bucket-schema/)[bucket schemas](/influxdb/cloud/tags/bucket-schemas/)[explicit bucket schemas](/influxdb/cloud/tags/explicit-bucket-schemas/)[schema](/influxdb/cloud/tags/schema/) --- # Create a bucket Source: https://docs.influxdata.com/influxdb/cloud/admin/buckets/create-bucket/ Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB HTTP API to create a bucket. By default, buckets have an `implicit` **schema-type** and a schema that conforms to your data. To require measurements to have specific columns and data types and prevent non-conforming write requests,[create a bucket with the `explicit` schema-type](#create-a-bucket-that-enforces-explicit-schemas). * [Create a bucket](#create-a-bucket) * [Create a bucket that enforces explicit schemas](#create-a-bucket-that-enforces-explicit-schemas) * [Bucket naming restrictions](#bucket-naming-restrictions) [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 **Load Data** \> **Buckets**. Load Data 1. Click **Create Bucket** in the upper right. 2. Enter a **Name** for the bucket*(see [Bucket naming restrictions](#bucket-naming-restrictions))*. 3. Select when to **Delete Data**: * **Never** to retain data forever. * **Older than** to choose a specific retention period. 4. 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 1. In the **From** panel in the Flux Builder, select `+ Create Bucket`. 2. Enter a **Name** for the bucket *(see [Bucket naming restrictions](#bucket-naming-restrictions))*. 3. Select when to **Delete Data**: * **Never** to retain data forever. * **Older than** to choose a specific retention period. 4. Click **Create** to create the bucket. ## Create a bucket using the influx CLI To create a bucket with the `influx` CLI, use the [`influx bucket create` command](/influxdb/cloud/reference/cli/influx/bucket/create)and specify values for the following flags: * `-o`, `--org`: Organization name * `-n`, `--name`: Bucket name*(see [Bucket naming restrictions](#bucket-naming-restrictions))* * `-r`, `--retention`: Retention period duration The following example creates a bucket with a retention period of `72` hours: ```sh influx bucket create \ --name my-bucket \ --org {INFLUX_ORG} \ --retention 72h ``` To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint: ``` POST https://cloud2.influxdata.com/api/v2/buckets ``` Include the following in your request: * **Headers:** * **Authorization:** `Token` scheme with your InfluxDB [API token](/influxdb/cloud/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields: \* Required * \* **name:** Bucket name * **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)* The following example creates a bucket with a retention period of `86,400` seconds, or 24 hours: ```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 reference documentation](/influxdb3/cloud-serverless/api/buckets/#operation/PostBuckets).* ## Create a bucket that enforces explicit schemas A bucket with the `explicit` schema-type enforces [measurement schemas that you define for the bucket](/influxdb/cloud/admin/organizations/buckets/bucket-schema/) and rejects writes that don’t conform to any of the schemas. Use the **`influx` CLI** or **InfluxDB HTTP API** to create a bucket with the `explicit` schema-type. [influx CLI](#influx-cli-2)[InfluxDB API](#influxdb-api-2) Use the `influx bucket create` command and specify the `--schema-type=explicit` flag: ```sh influx bucket create \ --name my_schema_bucket \ --schema-type explicit ``` Use the HTTP API [`/api/v2/buckets`](/influxdb/cloud/api/buckets/)endpoint and set the `schemaType` property value to `explicit` in the request body–for example: ``` POST https://cloud2.influxdata.com/api/v2/buckets ``` ```json { "orgID": "{INFLUX_ORG_ID}", "name": "my-explicit-bucket", "description": "My Explicit Bucket", "rp": "string", "retentionRules": [ { "type": "expire", "everySeconds": 86400, "shardGroupDurationSeconds": 0 } ], "schemaType": "explicit" } ``` Next, see how to [create an explicit bucket schema](/influxdb/cloud/admin/organizations/buckets/bucket-schema/) for a measurement. ## 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 (`"`) --- # Delete a bucket Source: https://docs.influxdata.com/influxdb/cloud/admin/buckets/delete-bucket/ 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 **Load Data** \> **Buckets**. Load Data 1. Find the bucket that you would like to delete. 2. Click the icon located far right of the bucket name. 3. Click **Confirm** to delete the bucket. ## Delete a bucket using the influx CLI Use the [`influx bucket delete` command](/influxdb/cloud/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/cloud/admin/buckets/update-bucket/ Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB HTTP API to update a bucket. Note that updating a bucket’s name will affect any resources 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 name in the above places and any resources that reference it. ## Update a bucket’s name in the InfluxDB UI 1. In the navigation menu on the left, select **Load Data** \> **Buckets**. Load Data 2. Click **Settings** to the right of 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] > For information about permitted bucket names, see[bucket naming restrictions](/influxdb/cloud/admin/organizations/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 **Load Data** \> **Buckets**. Load Data 2. Click **Settings** next to the bucket you want to update. 3. In the window that appears, under **Delete data**, select a retention period: * **Never**: data in the bucket is retained indefinitely. * **Older Than**: select a predefined retention period from the dropdown menu. > [!Note] > Use the [`influx bucket update` command](#update-a-buckets-retention-period)or the [InfluxDB HTTP API `PATCH /api/v2/buckets` endpoint](/influxdb/cloud/api/buckets/) to set a custom retention period. 4. Click **Save Changes**. ## Update a bucket using the influx CLI Use the [`influx bucket update` command](/influxdb/cloud/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`)* > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/cloud/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/cloud/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token ##### Update the name of a bucket ```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 ``` ## Update a bucket using the HTTP API Use the InfluxDB HTTP API [`PATCH /api/v2/buckets` endpoint](/influxdb/cloud/api/buckets/)to update a bucket. Updating a bucket requires the following: * The bucket ID *(provided in the output of the `GET /api/v2/buckets/` endpoint)* You can update the following bucket properties: * name *(see [bucket naming restrictions](/influxdb/cloud/admin/organizations/buckets/create-bucket/#bucket-naming-restrictions))* * description * retention rules 1. To find the bucket ID, send a request to the HTTP API [`GET /api/v2/buckets/` endpoint](/influxdb/cloud/api/buckets/) to retrieve the list of buckets. ``` GET https://cloud2.influxdata.com/api/v2/buckets ``` 2. Send a request to the HTTP API [PATCH `/api/v2/buckets/{BUCKET_ID}` endpoint](/influxdb/cloud/api/buckets/). In the URL path, specify the ID of the bucket from the previous step that you want to update. In the request body, set the properties that you want to update–for example: ``` PATCH https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID} ``` ``` { "name": "air_sensor", "description": "bucket holding air sensor data", "retentionRules": [ { "type": "expire", "everySeconds": 2592000 } ] } ``` --- # View buckets Source: https://docs.influxdata.com/influxdb/cloud/admin/buckets/view-buckets/ ## View buckets in the InfluxDB UI 1. In the navigation menu on the left, select **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/cloud/reference/cli/influx/bucket/list)to view buckets in an organization. ```sh influx bucket list ``` Other filtering options such as filtering by a name or ID are available. See the [`influx bucket list` documentation](/influxdb/cloud/reference/cli/influx/bucket/list)for information about other available flags. ## View buckets using the InfluxDB HTTP API Send a request to the InfluxDB HTTP API [`/api/v2/buckets` endpoint](/influxdb/cloud/api/buckets/) to view buckets in an organization. ``` GET https://cloud2.influxdata.com/api/v2/buckets ``` --- # Identify InfluxDB Cloud (TSM) version Source: https://docs.influxdata.com/influxdb/cloud/admin/identify-version/ Identifying which InfluxDB product and version you’re using is essential for accessing the correct documentation, troubleshooting issues, and planning upgrades. > [!Note] > #### Identify your InfluxDB version > > If you are unsure which InfluxDB product you are using, use our interactive version detector to help identify it: > > [Detect my InfluxDB version](#) > *(Interactive feature in HTML: Opens version detector modal)* ## Quick detection methods ### InfluxDB Cloud (TSM) detection **InfluxDB Cloud (TSM)** can be identified by: **URL patterns** (regional cloud2.influxdata.com URLs, excluding Serverless regions): * `us-west-2-1.aws.cloud2.influxdata.com` * `us-west-2-2.aws.cloud2.influxdata.com` * `us-east-1-2.aws.cloud2.influxdata.com` (note: different from Serverless) * `us-central1-1.gcp.cloud2.influxdata.com` * `westeurope-1.azure.cloud2.influxdata.com` * `eastus-1.azure.cloud2.influxdata.com` **Account settings**: Check your InfluxDB Cloud account dashboard for product details. **HTTP headers**: API responses include version information in response headers. ## 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 Cloud](/influxdb/cloud/get-started/) * [Administer InfluxDB Cloud](/influxdb/cloud/admin/) --- # Manage organizations Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/ An **organization** is a workspace for a group of users. All dashboards, tasks, buckets, members, etc., belong to an organization. An **account** can contain multiple organizations. You can use organizations to separate data, environments (dev, staging, prod), teams, providers, and regions within the same account. The following articles provide information about managing organizations: ### [View organization](/influxdb/cloud/admin/organizations/view-orgs/) Review a list of organizations in InfluxDB using the InfluxDB UI or the influx CLI. ### [Update an organization](/influxdb/cloud/admin/organizations/update-org/) Update an organization’s name and assets in InfluxDB using the InfluxDB UI or the influx CLI. ### [Delete your organization](/influxdb/cloud/admin/organizations/delete-org/) Delete your InfluxDB Cloud organization and all associated data. ### [Manage users](/influxdb/cloud/admin/organizations/users/) Learn how to invite, view, and manage users in your InfluxDB Cloud organization. ### [Replicate an organization](/influxdb/cloud/admin/organizations/migrate-org/) Replicate the state of an organization in InfluxDB Cloud > [!Note] > #### Migrate to InfluxDB Cloud Serverless > > To unlock the benefits of the InfluxDB 3 storage engine, including unlimited > cardinality and SQL, [migrate your data to an InfluxDB Cloud Serverless organization](/influxdb3/cloud-serverless/write-data/migrate-data/migrate-tsm-to-serverless/). > > All InfluxDB Cloud [accounts](/influxdb3/cloud-serverless/admin/accounts/) and[organizations](/influxdb3/cloud-serverless/admin/organizations/) created through[cloud2.influxdata.com](https://cloud2.influxdata.com) on or after **January 31, 2023**are on InfluxDB Cloud Serverless and are powered by the InfluxDB 3 storage engine. > > To see which storage engine your organization uses, find the **InfluxDB Cloud powered by**link in your [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com)version information. If your organization is using TSM, you’ll see **TSM**followed by the version number. If Serverless, you’ll see **InfluxDB Cloud Serverless**followed by the version number. #### Related * [Manage your InfluxDB Cloud Account](/influxdb/cloud/account-management/) [organizations](/influxdb/cloud/tags/organizations/) --- # Delete your organization Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/delete-org/ The process of deleting your organization from InfluxDB Cloud (TSM) depends on your[InfluxDB Cloud pricing plan](/influxdb/cloud/account-management/pricing-plans/). * [Free plan](#free-plan) * [Usage-based plan](#usage-based-plan) Deleting an organization from InfluxDB Cloud cannot be undone. Once deleted, all data associated with the organization is removed. ## Free plan To delete an organization using the **Free plan**, do the following: 1. Log in to your InfluxDB Cloud account and click on your email address in the upper left hand corner. 2. Select **Settings** from the dropdown menu. 3. Navigate to **Delete Organization** at the bottom of the page. 4. Under **Delete Organization**, click **Delete**. 5. Provide the requested information and then select **I understand and agree to these conditions**. 6. Click **Delete organization**. ## Usage-based plan 1. [Export your data and cancel your subscription](/influxdb/cloud/account-management/offboarding/). 2. Click your user avatar in the left navigation bar and select **About**. u u username org-name 3. Under **Delete Organization**, click **Delete**. 4. Provide the requested information and then select **I understand and agree to these conditions**. 5. Click **Delete organization**. --- # Replicate an organization Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/migrate-org/ The state of an organization consists of metadata (dashboards, buckets, and other resources) and data (time-series). An organization’s state at a point in time can be replicated to another organization by copying both metadata and data. To replicate the state of an organization: 1. Create a new organization using the [InfluxDB Cloud sign up page](https://cloud2.influxdata.com/signup). Use a different email address for the new organization. 2. **Replicate metadata**. Use an [InfluxDB template](/influxdb/cloud/tools/influxdb-templates/create/) to migrate metadata resources. Export all resources, like dashboards and buckets, to a template manifest with [`influx export all`](/influxdb/cloud/tools/influxdb-templates/create/#export-all-resources). Then, [apply the template](/influxdb/cloud/reference/cli/influx/apply/#examples-how-to-apply-a-template-or-stack)to the new organization. 3. **Replicate data**. Use one of the methods below to copy data to the new organization: * [Export data to CSV](#export-data-to-csv) * [Write data with Flux](#write-data-with-flux) 4. Re-invite users. ### Export data to CSV 1. Perform a query to return all specified data. 2. Save the results as CSV (to a location outside of InfluxDB Cloud). 3. Write the CSV data into a bucket in the new organization using the [`influx write`](/influxdb/cloud/reference/cli/influx/write/) command. ### Write data with Flux Perform a query to return all specified data. Write results directly to a bucket in the new organization with the Flux[`to()` function](/flux/v0/stdlib/influxdata/influxdb/to/). > [!Note] > If writes are prevented by rate limiting, > use the [`influx write --rate-limit`](/influxdb/cloud/reference/cli/influx/write/#write-annotated-csv-data-using-rate-limiting)flag to control the rate of writes. > For more information on rate limits in InfluxDB Cloud, > see [Exceeded rate limits](/influxdb/cloud/account-management/data-usage/#exceeded-rate-limits). --- # Update an organization Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/update-org/ 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**. User Icon 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/cloud/reference/cli/influx/org/update)to update an organization. Updating an organization requires the following: * The org ID *(provided in the output of `influx org list`)* ##### Update the name of a organization ```sh # Syntax influx org update -i -n # Example influx org update -i 034ad714fdd6f000 -n my-new-org ``` --- # Manage users Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/users/ InfluxDB Cloud (TSM) lets you invite and collaborate with multiple users in your organization. By default, each user has full permissions on resources in your organization. * [Users management page](#users-management-page) * [Invite a user to your organization](#invite-a-user-to-your-organization) * [Resend an invitation](#resend-an-invitation) * [Withdraw an invitation](#withdraw-an-invitation) * [Remove a user from your organization](#remove-a-user-from-your-organization) > [!Note] > If you have multiple users, we recommend creating a system account for administrative purposes. > For example, if you have applications writing to InfluxDB, ensure the applications > use the system account credentials. ## Members page Manage your organization’s users from your organization’s **Members page**. In the InfluxDB Cloud user interface (UI), click the drop down menu with your organization’s name in the top navigation menu and select **Members**. ## Invite a user to your organization 1. Navigate to your organization’s [Members page](#members-page). 2. Under **Add a new user to your organization**, enter the email address of the user to invite and select their role in your organization. #### Available roles #### Currently, InfluxDB Cloud has only one permission level for users: **Owner**. With Owner permissions, a user can delete resources and other users from your organization. Take care when inviting a user. *Users must be invited one at a time.* 3. Click **Add**. An invitation with an activation link is sent to the specified email address. The activation link expires after 72 hours. Once activated, the new user is added as an **Owner** with permissions to read and write all resources. Accounts can have up to 50 pending invitations at one time. ### Resend an invitation 1. Navigate to your organization’s [Members page](#members-page). 2. Click the icon next to the invitation you want to resend. ### Withdraw an invitation 1. Navigate to your organization’s [Members page](#members-page). 2. Click the icon next to the invitation you want to withdraw. 3. Click **Withdraw Invitation**. ## Remove a user from your organization For security purposes, once an InfluxDB user account is deleted, the user (and their token) cannot be reactivated. 1. Navigate to your organization’s [Members page](#members-page). 2. Click the icon next to the user you want to remove. 3. Click **Remove user access**. --- # View organization Source: https://docs.influxdata.com/influxdb/cloud/admin/organizations/view-orgs/ Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to view organizations. ## View organizations using the influx CLI Use the [`influx org list` command](/influxdb/cloud/reference/cli/influx/org/list)to view organizations. ```sh influx org list ``` Filtering options such as filtering by name or ID are available. See the [`influx org list` documentation](/influxdb/cloud/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 https://cloud2.influxdata.com/orgs/03a2bbf46249a000/... ``` ### Organization ID in the CLI Use [`influx org list`](#view-organizations-using-the-influx-cli) to view your organization ID. ```sh > influx org list ID Name 03a2bbf46249a000 org-1 03ace3a859669000 org-2 ``` --- # Manage secrets Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/ Manage secrets using any of the following: * InfluxDB Cloud UI * [`influx` command line interface (CLI)](/influxdb/cloud/reference/cli/influx/) * InfluxDB API All secrets belong to an organization and are stored in InfluxDB Cloud using [Vault](https://www.vaultproject.io/). ### [Add secrets](/influxdb/cloud/admin/secrets/add/) Add secrets using the InfluxDB Cloud UI, `influx` CLI, or the InfluxDB API. ### [View secret keys](/influxdb/cloud/admin/secrets/view/) View secret keys using the InfluxDB Cloud UI, `influx` CLI, or the InfluxDB API. ### [Update secrets](/influxdb/cloud/admin/secrets/update/) Update secrets using the InfluxDB Cloud UI, `influx` CLI, or the InfluxDB API. ### [Delete secrets](/influxdb/cloud/admin/secrets/delete/) Delete secrets using the InfluxDB Cloud UI, `influx` CLI, or the InfluxDB API. ### [Use secrets](/influxdb/cloud/admin/secrets/use/) Use secrets in queries with Flux. [secrets](/influxdb/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # Add secrets Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/add/ Add secrets using the InfluxDB Cloud UI, `influx` command line interface (CLI) or the InfluxDB API. * [Add a secret using the InfluxDB Cloud UI](#add-a-secret-using-the-influxdb-cloud-ui) * [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 InfluxDB Cloud UI 1. In the InfluxDB Cloud UI, click **Settings**. Settings 2. Click the **Secrets** tab. 3. Click **Add Secret**. 4. Enter a *key* and a *value*. Once the value is set, you will not be able to view the secret value again. It will only be accessible to your code through the secrets library. 5. Click **Add Secret**. ## Add a secret using the influx CLI Use the [`influx secret update` command](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/cloud/admin/tokens/view-tokens/) in the `Authorization` header * The secret key-value pair in the request body ```sh curl -XPATCH https://cloud2.influxdata.com/api/v2/orgs//secrets \ -H 'Authorization: Token YOUR_API_TOKEN' \ -H 'Content-type: application/json' \ --data '{ "": "" }' ``` [secrets](/influxdb/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # Delete secrets Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/delete/ Delete secrets using the InfluxDB Cloud UI, `influx` command line interface (CLI) or the InfluxDB API. * [Delete a secret using the InfluxDB Cloud UI](#delete-a-secret-using-the-influxdb-cloud-ui) * [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 InfluxDB Cloud UI 1. In the InfluxDB Cloud UI, click **Settings**. Settings 2. Click the **Secrets** tab. 3. Hover over the secret you want to delete. 4. Click the button. ## Delete a secret using the influx CLI Use the [`influx secret delete` command](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/cloud/admin/tokens/view-tokens/) in the `Authorization` header * An array of secret keys to delete in the request body ```bash curl -XGET https://cloud2.influxdata.com/api/v2/orgs//secrets/delete \ --H 'Authorization: Token YOUR_API_TOKEN' --data '{ "secrets": [ "" ] }' ``` [secrets](/influxdb/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # Update secrets Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/update/ Update secrets using the InfluxDB Cloud UI, `influx` command line interface (CLI) or the InfluxDB API. * [Update a secret using the InfluxDB Cloud UI](#update-a-secret-using-the-influxdb-cloud-ui) * [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 InfluxDB Cloud UI 1. In the InfluxDB Cloud UI, click **Settings**. Settings 2. Click the **Secrets** tab. 3. Click on the secret key whose value you want to update. 4. Enter the new value, and click **Edit Secret**. ## Update a secret using the influx CLI Use the [`influx secret update` command](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/cloud/admin/tokens/view-tokens/) in the `Authorization` header * The updated secret key-value pair in the request body ```sh curl -XPATCH https://cloud2.influxdata.com/api/v2/orgs//secrets \ -H 'Authorization: Token YOUR_API_TOKEN' \ -H 'Content-type: application/json' \ --data '{ "": "" }' ``` [secrets](/influxdb/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # Use secrets Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/use/ Use secrets in a Flux query to pass sensitive data like credentials. 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/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # View secret keys Source: https://docs.influxdata.com/influxdb/cloud/admin/secrets/view/ View secret keys using the InfluxDB Cloud UI, `influx` command line interface (CLI) or the InfluxDB API. * [View secret keys using the InfluxDB Cloud UI](#view-secret-keys-using-the-influxdb-cloud-ui) * [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 InfluxDB Cloud UI Follow the steps below to view a list of secret keys. Only the keys will be shown, not the values. 1. In the InfluxDB Cloud UI, click **Settings**. Settings 2. Click on the **Secrets** tab. From here, you can [add](/influxdb/cloud/admin/secrets/manage-secrets/add/#add-a-secret-using-the-influxdb-cloud-ui),[update](/influxdb/cloud/admin/secrets/manage-secrets/update/#update-a-secret-using-the-influxdb-cloud-ui), and [delete](/influxdb/cloud/admin/secrets/manage-secrets/delete/#delete-a-secret-using-the-influxdb-cloud-ui) secrets. ## View secret keys using the influx CLI Use the [`influx secret list` command](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) in the request URL * Your [API token](/influxdb/cloud/admin/tokens/view-tokens/) in the `Authorization` header ```sh curl -XGET https://cloud2.influxdata.com/api/v2/orgs//secrets \ -H 'Authorization: Token YOUR_API_TOKEN' ``` [secrets](/influxdb/cloud/tags/secrets/)[security](/influxdb/cloud/tags/security/) --- # Manage API tokens Source: https://docs.influxdata.com/influxdb/cloud/admin/tokens/ InfluxDB **API tokens** ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization. Learn how to create, view, update, or delete an API token. ## API token types * [All-Access token](#all-access-token) * [Read/Write token](#readwrite-token) #### 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. ## [Create a token](/influxdb/cloud/admin/tokens/create-token/) Create an API token in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. ## [View tokens](/influxdb/cloud/admin/tokens/view-tokens/) View API tokens in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. ## [Update a token](/influxdb/cloud/admin/tokens/update-tokens/) Update API tokens’ descriptions in InfluxDB using the InfluxDB UI. ## [Delete a token](/influxdb/cloud/admin/tokens/delete-token/) Delete an API token from InfluxDB using the InfluxDB UI or the `influx` CLI. ## [Use tokens](/influxdb/cloud/admin/tokens/use-tokens/) Use an API token in the InfluxDB UI, the `influx` CLI, or the InfluxDB API. [tokens](/influxdb/cloud/tags/tokens/)[authentication](/influxdb/cloud/tags/authentication/)[security](/influxdb/cloud/tags/security/) --- # Create a token Source: https://docs.influxdata.com/influxdb/cloud/admin/tokens/create-token/ 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 **Load Data** \> **API Tokens**. Load Data ## Create a token in the InfluxDB UI ### Create an All Access token 1. From the [API Tokens management page](#manage-tokens-in-the-influxdb-ui), click the **Generate API Token** button. 2. Select **All Access API Token**. ### Create a custom token 1. From the [API Tokens management page](#manage-tokens-in-the-influxdb-ui), click the **Generate API Token** button. 2. Select **Custom API Token**. 3. When the **Generate a Personal API Token** window appears, enter a description. If you don’t provide a description for the token, InfluxDB will generate a description from the permissions you assign. For example, if you select **Read** for a bucket named “\_monitoring” and **Write** for a bucket named “\_tasks”, InfluxDB will generate the description “Read buckets \_monitoring Write buckets \_tasks”. 4. Select the check boxes in the **Read** and **Write** columns to assign access permissions for the token. You can enable access to all buckets, individual buckets, Telegraf configurations, and other InfluxDB resources. By default, the new token has no access permissions. 5. When you’re finished, click **Generate**. 6. When InfluxDB displays the token value, click **Copy to Clipboard**. This is your only chance to access and copy the token value from InfluxDB. 7. (Optional) Store the API token value in a secure password vault. ### Clone a token To create a token with the same authorizations as an existing token, clone the existing token. 1. From the [API Tokens management page](#manage-tokens-in-the-influxdb-ui), find the token you want to clone and click the icon located far right of the token description. 2. Select **Clone**. 3. When InfluxDB UI displays the created token, click **Copy to Clipboard**. This is your only chance to access and copy the token value from InfluxDB. 4. (Optional) Store the API token value in a secure password vault. ## Create a token using the influx CLI Use the [`influx auth create` command](/influxdb/cloud/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/cloud/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 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/cloud/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/cloud/api/authorizations-api-tokens/) permission| Use the `Authorization` header and the | | `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/cloud/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 | | 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/cloud/admin/tokens/delete-token/ 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 **Load Data** \> **API Tokens**. Load Data 1. Find the token that you would like to delete. 2. Click the icon located far right of the token description. 3. Click **Confirm** to delete the token. ## Delete a token using the influx CLI Use the [`influx auth delete` command](/influxdb/cloud/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/cloud/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/cloud/admin/tokens/update-tokens/ 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 **Load Data** \> **API Tokens**. Load Data 2. Find the token that you would like to enable or disable. 3. Click the token description. 4. Click the **Status** toggle. ## Enable a token using the influx CLI Use the [`influx auth active` command](/influxdb/cloud/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/cloud/reference/cli/influx/auth/list). ```sh influx auth find --json ``` ### Disable a token using the influx CLI Use the [`influx auth inactive` command](/influxdb/cloud/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/cloud/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/cloud/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/cloud/admin/tokens/use-tokens/ Use tokens to authenticate requests to InfluxDB, including requests to write, query, and manage data and resources. Authenticate requests using the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/config/). ### Use a token in an API request Use tokens in [API requests](/influxdb/cloud/api-guide/api_intro/#authentication). ### Use a token in Postman Make authenticated requests with tokens [using Postman](/influxdb/cloud/tools/postman/). --- # View tokens Source: https://docs.influxdata.com/influxdb/cloud/admin/tokens/view-tokens/ View API tokens and permissions 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 Cloud enforces access restrictions on API tokens. > > * InfluxDB Cloud UI 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. ## View tokens in the InfluxDB UI 1. In the navigation menu on the left, select **Load Data** \> **API Tokens**. Load Data 1. Click a token description in the list to view the token status and a list of access permissions. ## View tokens using the influx CLI Use the [`influx auth list` command](/influxdb/cloud/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/cloud/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/cloud/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' ``` See the [`/authorizations` endpoint documentation](/influxdb/cloud/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. | --- # Develop with the InfluxDB API Source: https://docs.influxdata.com/influxdb/cloud/api-guide/ The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. ## InfluxDB client libraries InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. For information about supported client libraries, see [InfluxDB client libraries](/influxdb/cloud/api-guide/client-libraries/). ## InfluxDB Cloud API documentation [InfluxDB Cloud API documentation](/influxdb/cloud/api/) ## InfluxDB v1 compatibility API documentation The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/cloud/reference/api/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/cloud/api/v1-compatibility/) ![InfluxDB University](/svgs/influxdbu-full-white.svg) #### Building IoT Apps with InfluxDB Learn the basics of how to build an IoT application with InfluxDB with this **free** InfluxDB University course. [Take the course](https://university.influxdata.com/courses/building-iot-apps-with-influxdb-tutorial/) [api](/influxdb/cloud/tags/api/) --- # API Quick Start Source: https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/ InfluxDB offers a rich API and [client libraries](/influxdb/cloud/api-guide/client-libraries) ready to integrate with your application. Use popular tools like Curl and [Postman](/influxdb/cloud/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/cloud/api/). > [!Tip] > #### Use InfluxDB 1.x API clients with Cloud > > If you need to use InfluxDB Cloud with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility guide](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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://cloud2.influxdata.com/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: 'cloud2.influxdata.com', 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/cloud/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/cloud/admin/tokens/). * `ORG_ID` - the ID of the [organization](/influxdb/cloud/admin/organizations/) that owns the bucket. * `BUCKET_NAME` - the name of the [bucket](/influxdb/cloud/admin/buckets/) to create. * Optional: `RETENTION_PERIOD_SECONDS` - the [retention period](/influxdb/cloud/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/cloud/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api). ## Write API [Write data to InfluxDB](/influxdb/cloud/write-data/developer-tools/api/) using an HTTP request to the InfluxDB API `/api/v2/write` endpoint. ## Query API [Query from InfluxDB](/influxdb/cloud/query-data/execute-queries/influx-api/) using an HTTP request to the `/api/v2/query` endpoint. [api](/influxdb/cloud/tags/api/) --- # Invoke custom scripts as API endpoints Source: https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/ Use API invokable scripts to create custom InfluxDB API endpoints that query, process, and shape data. API invokable scripts let you assign scripts to API endpoints and then execute them as standard REST operations in InfluxDB Cloud. Learn how to manage API invokable scripts and invoke them with runtime parameters. Use the `/api/v2/scripts` InfluxDB API endpoint to: * [Create a script](#create-an-invokable-script) * [Invoke a script](#invoke-a-script) * [List scripts](#list-invokable-scripts) * [Update a script](#update-an-invokable-script) * [Delete a script](#delete-an-invokable-script) ## Create an invokable script To create an API-invokable script for your [organization](/influxdb/v2/reference/glossary/#organization), send a request using the `POST` method to the `/api/v2/scripts` InfluxDB API endpoint. ``` POST https://cloud2.influxdata.com/api/v2/scripts ``` 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: * **script** : [Flux](/flux/v0) script as a string. * **language** : language of your script (“flux”) * **name** : script name, unique within your organization * **description** : script description * **orgID**: your [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) ### Use parameters in a script To create an invokable script that accepts parameters (variables), reference the parameters as properties of the `params` object, e.g. `params.firstparam`.`params` is an InfluxDB object that defines runtime variables. You provide values for `params` when you [invoke a script](#invoke-a-script). If you don’t provide a value for a referenced parameter, InfluxDB returns the following error: ```json { "code":"invalid", "message":"invalid parameters provided" } ``` ## Examples ### Create an invokable Flux script The following example creates a new Flux script that references the `params.mybucket` parameter and returns the last point from the [bucket](/influxdb/v2/reference/glossary/#bucket). ```sh curl -X 'POST' \ "https://cloud2.influxdata.com/api/v2/scripts" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --data-binary @- << EOF | jq . { "name": "getLastPoint", "description": "getLastPoint finds the last point in a bucket", "orgID": "${INFLUX_ORG_ID}", "script": "from(bucket: params.mybucket) \ |> range(start: -7d) \ |> limit(n:1)", "language": "flux" } EOF ``` Replace the following: * *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) * *`INFLUX_ORG_ID`*: your [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) InfluxDB returns the newly created script. Next, see how to [invoke a script](#invoke-a-script). ```json { "id": "084d693d93048000", "orgID": "INFLUX_ORG_ID", "name": "getLastPoint", "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)", "description": "getLastPoint finds the last point in a bucket", "language": "flux", "createdAt": "2021-10-15T20:32:04.172938Z", "updatedAt": "2021-10-15T20:32:04.172938Z" } ``` ## Invoke a script To invoke a script, send a request using the `POST` method to the `/api/v2/scripts/SCRIPT_ID/invoke` InfluxDB API endpoint. ``` POST https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/invoke ``` Replace *`SCRIPT_ID`* with the ID of the script you want to execute. To find the script ID, see how to [list scripts](#list-scripts). Provide the following in your request: ### Request headers * **Content-Type**: application/json * **Accept**: application/csv * **Authorization**: Token *`INFLUX_API_TOKEN`* ### Request body JSON object that contains a `params` object. In `params`, provide key-value pairs for parameters referenced in your script. The [create](#create-an-invokable-script) example references the parameter `params.mybucket`. ``` "from(bucket: params.mybucket) \ |> range(start: -7d) \ |> limit(n:1)" ``` The following example invokes the created script and passes “air\_sensor” as the value for `params.mybucket`. ```sh SCRIPT_ID=085138a111448000 curl -X 'POST' \ "${INFLUX_URL}/api/v2/scripts/${SCRIPT_ID}/invoke" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Accept: application/csv' \ --header 'Content-Type: application/json' \ --data-binary '{ "params": { "mybucket": "air_sensor" } }' ``` InfluxDB returns query results in [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) from the `air_sensor` bucket. ### Pass multiple parameter values to a script If the script references multiple parameters, provide values for all parameters. To provide values for multiple parameters, send an object that contains a `params` object. In `params`, add the parameter names as keys and define a value for each key. The following **invokable script** object references four parameters: ``` { "name": "filter-and-group", "description": "Filters and groups points in a bucket. Expects parameters bucket, filterField, filterField2, and groupColumn.", "orgID": "${INFLUX_ORG_ID}", "script": "from(bucket: params.bucket) \ |> range(start: -30d) \ |> filter(fn: (r) => r._field == params.filterField or r._field == params.filterField2) \ |> group(columns: [params.groupColumn])", "language": "flux" } ``` The Flux script references the following parameters: * `params.bucket` * `params.filterField` * `params.filterField2` * `params.groupColumn` To provide values for the parameters, send a `POST` request to `/api/v2/scripts/SCRIPT_ID/invoke` and provide a [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) object that contains a `params` object. Inside the params object, define a key-value pair for each parameter referenced in the script. The object must be valid [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON). Consider an `air_sensor` bucket that contains `airSensors` measurements. Each point has a `temperature`, `humidity`, or `co` field. ```csv ,result,table,_start,_stop,_time,_value,_field,_measurement,sensor_id ,_result,0,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,75.30007505999716,temperature,airSensors,TLM0202 ,_result,1,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,73,temperature,airSensors,TLM0201 ,_result,2,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,35,humidity,airSensors,TLM0201 ,_result,3,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,0.5141876544505826,co,airSensors,TLM0202 ,_result,4,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,0.48445310567793615,co,airSensors,TLM0201 ,_result,5,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,35.651929918691714,humidity,airSensors,TLM0202 ``` The following `params` object provides a key-value pair for each parameter referenced in the script. ```json { "params": { "bucket": "air_sensor", "filterField": "temperature", "filterField2": "humidity", "groupColumn": "_time" } } ``` The following example uses the `/api/v2/scripts` InfluxDB API endpoint to create the script and invoke the new script ID with `params`. ``` new_script_id=$( curl -v -X 'POST' \ "${INFLUX_URL}/api/v2/scripts" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-binary @- << EOF | jq -r '.id' { "name": "filter-and-group", "description": "Filters and groups points in a bucket. Expects parameters bucket, filterField, filterField2, and groupColumn.", "orgID": "${INFLUX_ORG_ID}", "script": "from(bucket: params.bucket) \ |> range(start: -30d) \ |> filter(fn: (r) => r._field == params.filterField or r._field == params.filterField2) \ |> group(columns: [params.groupColumn])", "language": "flux" } EOF ) curl -vv -X 'POST' \ "${INFLUX_URL}/api/v2/scripts/${new_script_id}/invoke" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Accept: application/csv' \ --header 'Content-Type: application/json' \ --data-binary @- << EOF { "params": { "bucket": "air_sensor", "filterField": "temperature", "filterField2": "humidity", "groupColumn": "_time" } } EOF ``` InfluxDB returns points from `air_sensor` that have `temperature` or `humidity` fields. Points are grouped by the `_time` column. Each unique `table` value represents a group. ```sh ,result,table,_start,_stop,_time,_value,_field,_measurement,sensor_id ,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,73,temperature,airSensors,TLM0201 ,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,75.30007505999716,temperature,airSensors,TLM0202 ,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,35,humidity,airSensors,TLM0201 ,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,35.651929918691714,humidity,airSensors,TLM0202 ,_result,1,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:57:57Z,75.30007505999716,temperature,airSensors,TLM0202 ,_result,1,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:57:57Z,35.651929918691714,humidity,airSensors,TLM0202 ``` ## List invokable scripts To list scripts for an organization, send a request using the `GET` method to the `/api/v2/scripts` InfluxDB API endpoint. Provide the following in your request: #### Request headers * **Content-Type**: application/json * **Authorization**: Token *`INFLUX_API_TOKEN`* #### Request query parameters * **org**: your organization name (mutually exclusive with **orgID**) * **orgID**: your organization ID (mutually exclusive with **org**) * **limit**: (Optional) number of scripts to return * **offset**: (Optional) number to offset the pagination ```sh curl -X 'GET' \ "${INFLUX_URL}/api/v2/scripts" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --data-urlencode "org=${INFLUX_ORG}" \ --data-urlencode "limit=10" ``` To find a specific script for an organization, send a request using the `GET` method to the `/api/v2/scripts/SCRIPT_ID` InfluxDB API endpoint. ``` GET https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID ``` Replace *`SCRIPT_ID`* with the ID of the script you want to find. Provide the following in your request: #### Request headers * **Authorization**: Token *`INFLUX_API_TOKEN`* * **Accept**: application/json ```sh curl -X 'GET' \ "${INFLUX_URL}/api/v2/scripts/${SCRIPT_ID}" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'accept: application/json' \ --header 'Content-Type: application/json' ``` ## Update an invokable script Use the API to replace the following properties of an invokable script: * name * description * script To update an existing script for an organization, send a request using the `PATCH` method to the `/api/v2/scripts/SCRIPT_ID` InfluxDB API endpoint. Replace *`SCRIPT_ID`* with the ID of the script you want to update. ``` PATCH https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID ``` Provide the following in your request: #### Request headers * **Authorization**: Token *`INFLUX_API_TOKEN`* * **Content-Type**: application/json * **Accept**: application/json' #### Request body * A modified **invokable script** as a JSON object. The following example finds an invokable script containing a numeric date range, replaces the date with a new parameter, and updates the invokable script. ```sh find_and_update() { script=$(curl -X 'GET' \ "https://cloud2.influxdata.com/api/v2/scripts" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-urlencode "org=${INFLUX_ORG}&limit=10" \ | jq '[.scripts[] | select(.script | test("start: -?\\d\\w"))]' \ | jq '.[0]') new_script=$(jq '.script |= sub("start: .*d"; "start: params.myrangestart")' <<< "${script}") script_id=$(jq -r '.id' <<< "${new_script}") curl -X 'PATCH' \ "${INFLUX_URL}/api/v2/scripts/${script_id}" \ --header "Authorization: Token ${INFLUX_TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data "${new_script}" | jq . } find_and_update ``` 1. Use `GET /api/v2/scripts` to retrieve an object that contains a list of scripts. 2. With the scripts array, use [`jq`](https://stedolan.github.io/jq/) to find the first **invokable script** object that has a `script` property that contains a hard-coded numeric date range. 3. Replace the hard-coded date range in the `script` property with a new `params.myrangestart` dynamic parameter and assign the object to a `new_script` variable. 4. Assign the script ID to a `script_id` variable. 5. Update the script by sending a request to `PATCH /api/v2/scripts/` with `$script_id` in the URL path and `$new_script` as data (in the request body). InfluxDB returns the updated invokable script. ## Delete an invokable script To delete a script, send a request using the `DELETE` method to the `/api/v2/scripts/SCRIPT_ID` InfluxDB API endpoint. Replace *`SCRIPT_ID`* with the ID of the script you want to update. ``` DELETE https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID ``` Provide the following in your request: #### Request headers * **Authorization**: Token *`INFLUX_API_TOKEN`* * **Accept**: application/json' [api guides](/influxdb/cloud/tags/api-guides/) --- # Use InfluxDB client libraries Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/ 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/cloud/api-guide/client-libraries/go/) * [Java](https://github.com/influxdata/influxdb-client-java) * [JavaScript for browsers](/influxdb/cloud/api-guide/client-libraries/browserjs/) * [Kotlin](https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin) * [Node.js](/influxdb/cloud/api-guide/client-libraries/nodejs/) * [PHP](https://github.com/influxdata/influxdb-client-php) * [Python](/influxdb/cloud/api-guide/client-libraries/python/) * [Ruby](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/cloud/tags/client-libraries/) --- # Arduino client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/arduino/ 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/cloud/api-guide/client-libraries/browserjs/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/urls/), [bucket](/influxdb/cloud/admin/buckets/), [organization](/influxdb/cloud/admin/organizations/), and [token](/influxdb/cloud/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 * [Write data with the InfluxDB JavaScript client library](/influxdb/cloud/api-guide/client-libraries/nodejs/write/) * [Query with the InfluxDB JavaScript client library](/influxdb/cloud/api-guide/client-libraries/nodejs/query/) --- # C# client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/csharp/ 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/cloud/api-guide/client-libraries/dart/ 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/cloud/api-guide/client-libraries/go/ 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/cloud/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/cloud/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/cloud/admin/buckets/), [organization](/influxdb/cloud/admin/organizations/), and [token](/influxdb/cloud/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/cloud/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/cloud/tags/client-libraries/)[Go](/influxdb/cloud/tags/go/) --- # Java client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/java/ 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/cloud/api-guide/client-libraries/kotlin/ 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/cloud/api-guide/client-libraries/nodejs/ 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/cloud/api-guide/client-libraries/nodejs/install/) Install the JavaScript client library to interact with InfluxDB in Node.js. ### [Write data with the InfluxDB JavaScript client library](/influxdb/cloud/api-guide/client-libraries/nodejs/write/) Use the JavaScript client library to write data with the InfluxDB API in Node.js. ### [Query with the InfluxDB JavaScript client library](/influxdb/cloud/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/cloud/tags/client-libraries/)[JavaScript](/influxdb/cloud/tags/javascript/) --- # Install the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/nodejs/install/ ## 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/cloud/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/cloud/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/cloud/admin/buckets/), [organization](/influxdb/cloud/admin/organizations/), [token](/influxdb/cloud/admin/tokens/), and [URL](/influxdb/cloud/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/cloud/tags/client-libraries/)[JavaScript](/influxdb/cloud/tags/javascript/) --- # Query with the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/nodejs/query/ 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/cloud/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/cloud/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/cloud/tags/client-libraries/)[nodejs](/influxdb/cloud/tags/nodejs/)[JavaScript](/influxdb/cloud/tags/javascript/) --- # Write data with the InfluxDB JavaScript client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/nodejs/write/ 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/cloud/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/cloud/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/cloud/reference/glossary/#point). 1. Call the constructor and provide a [measurement](/influxdb/cloud/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/cloud/write-data/troubleshoot/) [client libraries](/influxdb/cloud/tags/client-libraries/)[nodejs](/influxdb/cloud/tags/nodejs/)[JavaScript](/influxdb/cloud/tags/javascript/) --- # PHP client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/php/ 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/cloud/api-guide/client-libraries/python/ 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/cloud/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/cloud/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/cloud/admin/buckets/), [organization](/influxdb/cloud/admin/organizations/), and [token](/influxdb/cloud/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/cloud/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/cloud/tags/client-libraries/)[python](/influxdb/cloud/tags/python/) --- # Ruby client library Source: https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/r/ 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/cloud/api-guide/client-libraries/ruby/ 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/cloud/api-guide/client-libraries/scala/ 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/cloud/api-guide/client-libraries/swift/ 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/cloud/api-guide/influxdb-1x/ 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/cloud/api/v1-compatibility/) ## Authentication InfluxDB 1.x compatibility endpoints require all query and write requests to be authenticated with an[API token](/influxdb/cloud/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/cloud/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**: InfluxDB Cloud username (Use the email address you signed up with as your username–for example, `exampleuser@influxdata.com`.) * **password**: InfluxDB Cloud [API token](/influxdb/cloud/admin/tokens/) #### 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 exampleuser@influxdata.com:INFLUX_API_TOKEN ``` ##### Example [curl](#curl-2)[Node.js](#nodejs-2) ```sh ####################################### # Use an InfluxDB 1.x compatible username # and password with Basic Authentication # to query the InfluxDB 1.x compatibility API ####################################### # Use default retention policy ####################################### # Use the --user option with `--user INFLUX_USERNAME:INFLUX_API_TOKEN` syntax # or the `--user INFLUX_USERNAME` interactive syntax to ensure your credentials are # encoded in the header. ####################################### curl --get "http://localhost:8086/query" \ --user "exampleuser@influxdata.com":"INFLUX_API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ```js /** * Use an InfluxDB Cloud username and token * with Basic Authentication * to query the InfluxDB 1.x compatibility API */ 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: 'exampleuser@influxdata.com:INFLUX_API_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(); } ``` Replace the following: * `exampleuser@influxdata.com`: the email address that you signed up with * `INFLUX_API_TOKEN`: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) #### 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 ```http /query/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN /write/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN ``` ##### Example [curl](#curl-4)[Node.js](#nodejs-4) ```sh ####################################### # Use an InfluxDB 1.x compatible username # and password with Basic Authentication # to query the InfluxDB 1.x compatibility API ####################################### # Use default retention policy ####################################### # Use the --user option with `--user INFLUX_USERNAME:INFLUX_API_TOKEN` syntax # or the `--user INFLUX_USERNAME` interactive syntax to ensure your credentials are # encoded in the header. ####################################### curl --get "http://localhost:8086/query" \ --user "exampleuser@influxdata.com":"INFLUX_API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` ```js /** * Use an InfluxDB Cloud username and token * with Basic Authentication * to query the InfluxDB 1.x compatibility API */ 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: 'exampleuser@influxdata.com:INFLUX_API_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(); } ``` Replace the following: * `exampleuser@influxdata.com`: the email address that you signed up with * `INFLUX_API_TOKEN`: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) ### 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/cloud/api-guide/influxdb-1x/query/) The `/query` 1.x compatibility endpoint queries InfluxDB Cloud using **InfluxQL**. ``` GET https://cloud2.influxdata.com/query ``` [Read more ](/influxdb/cloud/api-guide/influxdb-1x/query/) ### [/write](/influxdb/cloud/api-guide/influxdb-1x/write/) The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud using patterns from the InfluxDB 1.x `/write` API endpoint. ``` POST https://cloud2.influxdata.com/write ``` [Read more ](/influxdb/cloud/api-guide/influxdb-1x/write/) ### [Database and retention policy mapping](/influxdb/cloud/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 buckets. #### Related * [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) [influxql](/influxdb/cloud/tags/influxql/)[query](/influxdb/cloud/tags/query/)[write](/influxdb/cloud/tags/write/) --- # Database and retention policy mapping Source: https://docs.influxdata.com/influxdb/cloud/api-guide/influxdb-1x/dbrp/ #### Related * [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) --- # /query 1.x compatibility API Source: https://docs.influxdata.com/influxdb/cloud/api-guide/influxdb-1x/query/ #### Related * [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) [influxql](/influxdb/cloud/tags/influxql/)[query](/influxdb/cloud/tags/query/) --- # /write 1.x compatibility API Source: https://docs.influxdata.com/influxdb/cloud/api-guide/influxdb-1x/write/ #### Related * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) [write](/influxdb/cloud/tags/write/) --- # InfluxDB API client library starter Source: https://docs.influxdata.com/influxdb/cloud/api-guide/tutorials/ 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/cloud/api-guide/tutorials/python/) Build an application that writes, queries, and manages devices with the InfluxDB client library for Python. ### [JavaScript](/influxdb/cloud/api-guide/tutorials/nodejs/) Build a JavaScript application that writes, queries, and manages devices with the InfluxDB client library. [api](/influxdb/cloud/tags/api/) --- # JavaScript client library starter Source: https://docs.influxdata.com/influxdb/cloud/api-guide/tutorials/nodejs/ 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/cloud/admin/organizations/view-orgs/) * An [API token](/influxdb/cloud/admin/tokens/create-token/) (for example, an **All Access token**) that has read and write permissions for the buckets * A [bucket](/influxdb/cloud/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center` for storing time series data from devices * A [bucket](/influxdb/cloud/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 > custom > > 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/cloud/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/cloud/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/cloud/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/cloud/tags/api/)[javascript](/influxdb/cloud/tags/javascript/)[nodejs](/influxdb/cloud/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/cloud/api-guide/tutorials/python/ 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/cloud/admin/organizations/view-orgs/) * An [API token](/influxdb/cloud/admin/tokens/create-token/) (for example, an **All Access token**) that has read and write permissions for the buckets * A [bucket](/influxdb/cloud/admin/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) named `iot_center` for storing time series data from devices * A [bucket](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/tags/api/)[python](/influxdb/cloud/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/cloud/api/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Use the InfluxDB Cloud (TSM) HTTP API to write data, query data, and manage databases, tables, and tokens. ### [Quick start](/influxdb/cloud/api/quick-start/) Authenticate, write, and query with the InfluxDB Cloud API: ### [Authentication](/influxdb/cloud/api/authentication/) Use one of the following schemes to authenticate to the InfluxDB Cloud API: ### [Common parameters](/influxdb/cloud/api/common-parameters/) Most InfluxDB Cloud API endpoints require parameters in the request–for example, to specify the bucket or organization. ### [Headers](/influxdb/cloud/api/headers/) InfluxDB Cloud API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB Cloud API endpoints. Some endpoints may use other headers… ### [Pagination](/influxdb/cloud/api/pagination/) List endpoints in the InfluxDB Cloud API support pagination via query parameters. Use these parameters to page through large result sets. ### [Response codes](/influxdb/cloud/api/response-codes/) InfluxDB Cloud API endpoints return standard HTTP status codes. The following table summarizes the most common response codes. ### [Supported operations](/influxdb/cloud/api/supported-operations/) The InfluxDB Cloud API supports create, read, update, and delete operations on resources. Most endpoints follow standard HTTP method conventions: ### [Authorizations (API tokens)](/influxdb/cloud/api/authorizations-api-tokens/) Create and manage API token authorizations that grant read and write permissions to InfluxDB Cloud organization resources. ### [Bucket Schemas](/influxdb/cloud/api/bucket-schemas/) Manage explicit schemas for InfluxDB Cloud buckets to enforce column names and data types for measurement data. ### [Buckets](/influxdb/cloud/api/buckets/) Create and manage named storage locations (buckets) in InfluxDB Cloud, each with a configurable retention period. ### [Cells](/influxdb/cloud/api/cells/) Manage cells within InfluxDB Cloud dashboards. ### [Checks](/influxdb/cloud/api/checks/) Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB Cloud. ### [Config](/influxdb/cloud/api/config/) Retrieve configuration information for an InfluxDB Cloud instance. ### [Dashboards](/influxdb/cloud/api/dashboards/) Create and manage dashboards in InfluxDB Cloud. ### [Data I/O endpoints](/influxdb/cloud/api/data-i-o-endpoints/) API reference for Data I/O endpoints ### [DBRPs](/influxdb/cloud/api/dbrps/) Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB Cloud buckets. ### [Delete](/influxdb/cloud/api/delete/) Delete time series data from an InfluxDB Cloud bucket by specifying a time range and optional tag predicate. ### [Invokable Scripts](/influxdb/cloud/api/invokable-scripts/) Store, manage, and execute custom Flux scripts in InfluxDB Cloud. Scripts accept runtime parameters and can be invoked via dedicated endpoints. ### [Labels](/influxdb/cloud/api/labels/) Create and manage labels for organizing InfluxDB Cloud resources such as dashboards, tasks, and buckets. ### [Legacy Authorizations](/influxdb/cloud/api/legacy-authorizations/) Manage legacy (v1-compatible) authorization credentials in InfluxDB Cloud. ### [Legacy Query](/influxdb/cloud/api/legacy-query/) Query data using InfluxQL via the v1-compatible `/query` endpoint in InfluxDB Cloud. ### [Legacy Write](/influxdb/cloud/api/legacy-write/) Write data using the v1-compatible `/write` endpoint in InfluxDB Cloud. ### [Limits](/influxdb/cloud/api/limits/) Retrieve rate limits and usage quotas for an InfluxDB Cloud organization. ### [NotificationEndpoints](/influxdb/cloud/api/notificationendpoints/) Create and manage notification endpoints that receive alert notifications from InfluxDB Cloud monitoring checks. ### [NotificationRules](/influxdb/cloud/api/notificationrules/) Create and manage notification rules that define when and how InfluxDB Cloud sends notifications to configured endpoints. ### [Organizations](/influxdb/cloud/api/organizations/) View and manage InfluxDB Cloud organizations, which are workspaces that group users, buckets, and resources. ### [Ping](/influxdb/cloud/api/ping/) Check the availability of the InfluxDB Cloud instance. ### [Query](/influxdb/cloud/api/query/) Retrieve data, analyze queries, and get query suggestions. ### [Resources](/influxdb/cloud/api/resources/) Retrieve a list of top-level resource types available in the InfluxDB Cloud API. ### [Routes](/influxdb/cloud/api/routes/) Retrieve top-level routes for the InfluxDB Cloud API. ### [Rules](/influxdb/cloud/api/rules/) Manage notification rules in InfluxDB Cloud. ### [Secrets](/influxdb/cloud/api/secrets/) Create and manage secrets (key-value pairs) for use in InfluxDB Cloud Flux scripts and tasks. ### [Security and access endpoints](/influxdb/cloud/api/security-and-access-endpoints/) Endpoints for managing authentication and access control in InfluxDB Cloud. ### [Setup](/influxdb/cloud/api/setup/) Check whether an InfluxDB instance allows initial setup. ### [Signin](/influxdb/cloud/api/signin/) Create a user session by signing in with username and password credentials. ### [Signout](/influxdb/cloud/api/signout/) End a user session by signing out. ### [System information endpoints](/influxdb/cloud/api/system-information-endpoints/) Endpoints for retrieving system-level information about the InfluxDB Cloud instance. ### [Tasks](/influxdb/cloud/api/tasks/) Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB Cloud. ### [Telegraf Plugins](/influxdb/cloud/api/telegraf-plugins/) Retrieve available Telegraf plugin configuration templates for use with InfluxDB Cloud. ### [Telegrafs](/influxdb/cloud/api/telegrafs/) Create and manage Telegraf agent configurations that collect and write data to InfluxDB Cloud. ### [Templates](/influxdb/cloud/api/templates/) Export and apply InfluxDB templates, and manage template stacks for InfluxDB Cloud. ### [Usage](/influxdb/cloud/api/usage/) Retrieve usage metrics and cardinality data for an InfluxDB Cloud organization. ### [Users](/influxdb/cloud/api/users/) View specific users that are members of your InfluxDB Cloud organization. ### [Variables](/influxdb/cloud/api/variables/) Create and manage variables for use in InfluxDB Cloud dashboards. ### [Views](/influxdb/cloud/api/views/) Manage cell views within InfluxDB Cloud dashboards. ### [Write](/influxdb/cloud/api/write/) Write time series data to [buckets](/influxdb/cloud/reference/glossary/). --- # All endpoints Source: https://docs.influxdata.com/influxdb/cloud/api/all-endpoints/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) All InfluxDB Cloud (TSM) API endpoints, sorted by path. ## v2-compatible API [GET`/api/v2`List all top level routes](/influxdb/cloud/api/routes/#operation/GetRoutes)[GET`/api/v2`List all top level routes](/influxdb/cloud/api/system-information-endpoints/#operation/GetRoutes)[GET`/api/v2/authorizations`List authorizations](/influxdb/cloud/api/authorizations-api-tokens/#operation/GetAuthorizations)[GET`/api/v2/authorizations`List authorizations](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetAuthorizations)[POST`/api/v2/authorizations`Create an authorization](/influxdb/cloud/api/authorizations-api-tokens/#operation/PostAuthorizations)[POST`/api/v2/authorizations`Create an authorization](/influxdb/cloud/api/security-and-access-endpoints/#operation/PostAuthorizations)[DELETE`/api/v2/authorizations/{authID}`Delete an authorization](/influxdb/cloud/api/authorizations-api-tokens/#operation/DeleteAuthorizationsID)[DELETE`/api/v2/authorizations/{authID}`Delete an authorization](/influxdb/cloud/api/security-and-access-endpoints/#operation/DeleteAuthorizationsID)[GET`/api/v2/authorizations/{authID}`Retrieve an authorization](/influxdb/cloud/api/authorizations-api-tokens/#operation/GetAuthorizationsID)[GET`/api/v2/authorizations/{authID}`Retrieve an authorization](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetAuthorizationsID)[PATCH`/api/v2/authorizations/{authID}`Update an API token to be active or inactive](/influxdb/cloud/api/authorizations-api-tokens/#operation/PatchAuthorizationsID)[PATCH`/api/v2/authorizations/{authID}`Update an API token to be active or inactive](/influxdb/cloud/api/security-and-access-endpoints/#operation/PatchAuthorizationsID)[GET`/api/v2/buckets`List buckets](/influxdb/cloud/api/buckets/#operation/GetBuckets)[POST`/api/v2/buckets`Create a bucket](/influxdb/cloud/api/buckets/#operation/PostBuckets)[DELETE`/api/v2/buckets/{bucketID}`Delete a bucket](/influxdb/cloud/api/buckets/#operation/DeleteBucketsID)[GET`/api/v2/buckets/{bucketID}`Retrieve a bucket](/influxdb/cloud/api/buckets/#operation/GetBucketsID)[PATCH`/api/v2/buckets/{bucketID}`Update a bucket](/influxdb/cloud/api/buckets/#operation/PatchBucketsID)[GET`/api/v2/buckets/{bucketID}/labels`List all labels for a bucket](/influxdb/cloud/api/buckets/#operation/GetBucketsIDLabels)[POST`/api/v2/buckets/{bucketID}/labels`Add a label to a bucket](/influxdb/cloud/api/buckets/#operation/PostBucketsIDLabels)[DELETE`/api/v2/buckets/{bucketID}/labels/{labelID}`Delete a label from a bucket](/influxdb/cloud/api/buckets/#operation/DeleteBucketsIDLabelsID)[GET`/api/v2/buckets/{bucketID}/members`List all users with member privileges for a bucket](/influxdb/cloud/api/buckets/#operation/GetBucketsIDMembers)[POST`/api/v2/buckets/{bucketID}/members`Add a member to a bucket](/influxdb/cloud/api/buckets/#operation/PostBucketsIDMembers)[DELETE`/api/v2/buckets/{bucketID}/members/{userID}`Remove a member from a bucket](/influxdb/cloud/api/buckets/#operation/DeleteBucketsIDMembersID)[GET`/api/v2/buckets/{bucketID}/owners`List all owners of a bucket](/influxdb/cloud/api/buckets/#operation/GetBucketsIDOwners)[POST`/api/v2/buckets/{bucketID}/owners`Add an owner to a bucket](/influxdb/cloud/api/buckets/#operation/PostBucketsIDOwners)[DELETE`/api/v2/buckets/{bucketID}/owners/{userID}`Remove an owner from a bucket](/influxdb/cloud/api/buckets/#operation/DeleteBucketsIDOwnersID)[GET`/api/v2/buckets/{bucketID}/schema/measurements`List measurement schemas of a bucket](/influxdb/cloud/api/bucket-schemas/#operation/getMeasurementSchemas)[POST`/api/v2/buckets/{bucketID}/schema/measurements`Create a measurement schema for a bucket](/influxdb/cloud/api/bucket-schemas/#operation/createMeasurementSchema)[GET`/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}`Retrieve a measurement schema](/influxdb/cloud/api/bucket-schemas/#operation/getMeasurementSchema)[PATCH`/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}`Update a measurement schema](/influxdb/cloud/api/bucket-schemas/#operation/updateMeasurementSchema)[GET`/api/v2/checks`List all checks](/influxdb/cloud/api/checks/#operation/GetChecks)[POST`/api/v2/checks`Add new check](/influxdb/cloud/api/checks/#operation/CreateCheck)[DELETE`/api/v2/checks/{checkID}`Delete a check](/influxdb/cloud/api/checks/#operation/DeleteChecksID)[GET`/api/v2/checks/{checkID}`Retrieve a check](/influxdb/cloud/api/checks/#operation/GetChecksID)[PATCH`/api/v2/checks/{checkID}`Update a check](/influxdb/cloud/api/checks/#operation/PatchChecksID)[PUT`/api/v2/checks/{checkID}`Update a check](/influxdb/cloud/api/checks/#operation/PutChecksID)[GET`/api/v2/checks/{checkID}/labels`List all labels for a check](/influxdb/cloud/api/checks/#operation/GetChecksIDLabels)[POST`/api/v2/checks/{checkID}/labels`Add a label to a check](/influxdb/cloud/api/checks/#operation/PostChecksIDLabels)[DELETE`/api/v2/checks/{checkID}/labels/{labelID}`Delete label from a check](/influxdb/cloud/api/checks/#operation/DeleteChecksIDLabelsID)[GET`/api/v2/checks/{checkID}/query`Retrieve a check query](/influxdb/cloud/api/checks/#operation/GetChecksIDQuery)[GET`/api/v2/dashboards`List dashboards](/influxdb/cloud/api/dashboards/#operation/GetDashboards)[POST`/api/v2/dashboards`Create a dashboard](/influxdb/cloud/api/dashboards/#operation/PostDashboards)[DELETE`/api/v2/dashboards/{dashboardID}`Delete a dashboard](/influxdb/cloud/api/dashboards/#operation/DeleteDashboardsID)[GET`/api/v2/dashboards/{dashboardID}`Retrieve a dashboard](/influxdb/cloud/api/dashboards/#operation/GetDashboardsID)[PATCH`/api/v2/dashboards/{dashboardID}`Update a dashboard](/influxdb/cloud/api/dashboards/#operation/PatchDashboardsID)[POST`/api/v2/dashboards/{dashboardID}/cells`Create a dashboard cell](/influxdb/cloud/api/cells/#operation/PostDashboardsIDCells)[POST`/api/v2/dashboards/{dashboardID}/cells`Create a dashboard cell](/influxdb/cloud/api/dashboards/#operation/PostDashboardsIDCells)[PUT`/api/v2/dashboards/{dashboardID}/cells`Replace cells in a dashboard](/influxdb/cloud/api/cells/#operation/PutDashboardsIDCells)[PUT`/api/v2/dashboards/{dashboardID}/cells`Replace cells in a dashboard](/influxdb/cloud/api/dashboards/#operation/PutDashboardsIDCells)[DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Delete a dashboard cell](/influxdb/cloud/api/cells/#operation/DeleteDashboardsIDCellsID)[DELETE`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Delete a dashboard cell](/influxdb/cloud/api/dashboards/#operation/DeleteDashboardsIDCellsID)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Update the non-positional information related to a cell](/influxdb/cloud/api/cells/#operation/PatchDashboardsIDCellsID)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}`Update the non-positional information related to a cell](/influxdb/cloud/api/dashboards/#operation/PatchDashboardsIDCellsID)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/cloud/api/cells/#operation/GetDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/cloud/api/dashboards/#operation/GetDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Retrieve the view for a cell](/influxdb/cloud/api/views/#operation/GetDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/cloud/api/cells/#operation/PatchDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/cloud/api/dashboards/#operation/PatchDashboardsIDCellsIDView)[PATCH`/api/v2/dashboards/{dashboardID}/cells/{cellID}/view`Update the view for a cell](/influxdb/cloud/api/views/#operation/PatchDashboardsIDCellsIDView)[GET`/api/v2/dashboards/{dashboardID}/labels`List all labels for a dashboard](/influxdb/cloud/api/dashboards/#operation/GetDashboardsIDLabels)[POST`/api/v2/dashboards/{dashboardID}/labels`Add a label to a dashboard](/influxdb/cloud/api/dashboards/#operation/PostDashboardsIDLabels)[DELETE`/api/v2/dashboards/{dashboardID}/labels/{labelID}`Delete a label from a dashboard](/influxdb/cloud/api/dashboards/#operation/DeleteDashboardsIDLabelsID)[GET`/api/v2/dashboards/{dashboardID}/members`List all dashboard members](/influxdb/cloud/api/dashboards/#operation/GetDashboardsIDMembers)[POST`/api/v2/dashboards/{dashboardID}/members`Add a member to a dashboard](/influxdb/cloud/api/dashboards/#operation/PostDashboardsIDMembers)[DELETE`/api/v2/dashboards/{dashboardID}/members/{userID}`Remove a member from a dashboard](/influxdb/cloud/api/dashboards/#operation/DeleteDashboardsIDMembersID)[GET`/api/v2/dashboards/{dashboardID}/owners`List all dashboard owners](/influxdb/cloud/api/dashboards/#operation/GetDashboardsIDOwners)[POST`/api/v2/dashboards/{dashboardID}/owners`Add an owner to a dashboard](/influxdb/cloud/api/dashboards/#operation/PostDashboardsIDOwners)[DELETE`/api/v2/dashboards/{dashboardID}/owners/{userID}`Remove an owner from a dashboard](/influxdb/cloud/api/dashboards/#operation/DeleteDashboardsIDOwnersID)[GET`/api/v2/dbrps`List database retention policy mappings](/influxdb/cloud/api/dbrps/#operation/GetDBRPs)[POST`/api/v2/dbrps`Add a database retention policy mapping](/influxdb/cloud/api/dbrps/#operation/PostDBRP)[DELETE`/api/v2/dbrps/{dbrpID}`Delete a database retention policy](/influxdb/cloud/api/dbrps/#operation/DeleteDBRPID)[GET`/api/v2/dbrps/{dbrpID}`Retrieve a database retention policy mapping](/influxdb/cloud/api/dbrps/#operation/GetDBRPsID)[PATCH`/api/v2/dbrps/{dbrpID}`Update a database retention policy mapping](/influxdb/cloud/api/dbrps/#operation/PatchDBRPID)[POST`/api/v2/delete`Delete data](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostDelete)[POST`/api/v2/delete`Delete data](/influxdb/cloud/api/delete/#operation/PostDelete)[GET`/api/v2/flags`Retrieve feature flags](/influxdb/cloud/api/config/#operation/GetFlags)[GET`/api/v2/labels`List all labels](/influxdb/cloud/api/labels/#operation/GetLabels)[POST`/api/v2/labels`Create a label](/influxdb/cloud/api/labels/#operation/PostLabels)[DELETE`/api/v2/labels/{labelID}`Delete a label](/influxdb/cloud/api/labels/#operation/DeleteLabelsID)[GET`/api/v2/labels/{labelID}`Retrieve a label](/influxdb/cloud/api/labels/#operation/GetLabelsID)[PATCH`/api/v2/labels/{labelID}`Update a label](/influxdb/cloud/api/labels/#operation/PatchLabelsID)[GET`/api/v2/me`Retrieve the currently authenticated user](/influxdb/cloud/api/users/#operation/GetMe)[PUT`/api/v2/me/password`Update a password](/influxdb/cloud/api/users/#operation/PutMePassword)[GET`/api/v2/notificationEndpoints`List all notification endpoints](/influxdb/cloud/api/notificationendpoints/#operation/GetNotificationEndpoints)[POST`/api/v2/notificationEndpoints`Add a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/CreateNotificationEndpoint)[DELETE`/api/v2/notificationEndpoints/{endpointID}`Delete a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/DeleteNotificationEndpointsID)[GET`/api/v2/notificationEndpoints/{endpointID}`Retrieve a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/GetNotificationEndpointsID)[PATCH`/api/v2/notificationEndpoints/{endpointID}`Update a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/PatchNotificationEndpointsID)[PUT`/api/v2/notificationEndpoints/{endpointID}`Update a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/PutNotificationEndpointsID)[GET`/api/v2/notificationEndpoints/{endpointID}/labels`List all labels for a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/GetNotificationEndpointsIDLabels)[POST`/api/v2/notificationEndpoints/{endpointID}/labels`Add a label to a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/PostNotificationEndpointIDLabels)[DELETE`/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}`Delete a label from a notification endpoint](/influxdb/cloud/api/notificationendpoints/#operation/DeleteNotificationEndpointsIDLabelsID)[GET`/api/v2/notificationRules`List all notification rules](/influxdb/cloud/api/notificationrules/#operation/GetNotificationRules)[POST`/api/v2/notificationRules`Add a notification rule](/influxdb/cloud/api/notificationrules/#operation/CreateNotificationRule)[DELETE`/api/v2/notificationRules/{ruleID}`Delete a notification rule](/influxdb/cloud/api/notificationrules/#operation/DeleteNotificationRulesID)[GET`/api/v2/notificationRules/{ruleID}`Retrieve a notification rule](/influxdb/cloud/api/notificationrules/#operation/GetNotificationRulesID)[PATCH`/api/v2/notificationRules/{ruleID}`Update a notification rule](/influxdb/cloud/api/notificationrules/#operation/PatchNotificationRulesID)[PUT`/api/v2/notificationRules/{ruleID}`Update a notification rule](/influxdb/cloud/api/notificationrules/#operation/PutNotificationRulesID)[GET`/api/v2/notificationRules/{ruleID}/labels`List all labels for a notification rule](/influxdb/cloud/api/notificationrules/#operation/GetNotificationRulesIDLabels)[POST`/api/v2/notificationRules/{ruleID}/labels`Add a label to a notification rule](/influxdb/cloud/api/notificationrules/#operation/PostNotificationRuleIDLabels)[DELETE`/api/v2/notificationRules/{ruleID}/labels/{labelID}`Delete label from a notification rule](/influxdb/cloud/api/notificationrules/#operation/DeleteNotificationRulesIDLabelsID)[GET`/api/v2/notificationRules/{ruleID}/query`Retrieve a notification rule query](/influxdb/cloud/api/rules/#operation/GetNotificationRulesIDQuery)[GET`/api/v2/orgs`List organizations](/influxdb/cloud/api/organizations/#operation/GetOrgs)[GET`/api/v2/orgs`List organizations](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetOrgs)[POST`/api/v2/orgs`Create an organization](/influxdb/cloud/api/organizations/#operation/PostOrgs)[DELETE`/api/v2/orgs/{orgID}`Delete an organization](/influxdb/cloud/api/organizations/#operation/DeleteOrgsID)[GET`/api/v2/orgs/{orgID}`Retrieve an organization](/influxdb/cloud/api/organizations/#operation/GetOrgsID)[GET`/api/v2/orgs/{orgID}`Retrieve an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetOrgsID)[PATCH`/api/v2/orgs/{orgID}`Update an organization](/influxdb/cloud/api/organizations/#operation/PatchOrgsID)[GET`/api/v2/orgs/{orgID}/limits`Retrieve limits for an organization](/influxdb/cloud/api/limits/#operation/GetOrgLimitsID)[GET`/api/v2/orgs/{orgID}/members`List all members of an organization](/influxdb/cloud/api/organizations/#operation/GetOrgsIDMembers)[GET`/api/v2/orgs/{orgID}/members`List all members of an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetOrgsIDMembers)[POST`/api/v2/orgs/{orgID}/members`Add a member to an organization](/influxdb/cloud/api/organizations/#operation/PostOrgsIDMembers)[DELETE`/api/v2/orgs/{orgID}/members/{userID}`Remove a member from an organization](/influxdb/cloud/api/organizations/#operation/DeleteOrgsIDMembersID)[DELETE`/api/v2/orgs/{orgID}/members/{userID}`Remove a member from an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/DeleteOrgsIDMembersID)[GET`/api/v2/orgs/{orgID}/owners`List all owners of an organization](/influxdb/cloud/api/organizations/#operation/GetOrgsIDOwners)[GET`/api/v2/orgs/{orgID}/owners`List all owners of an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetOrgsIDOwners)[POST`/api/v2/orgs/{orgID}/owners`Add an owner to an organization](/influxdb/cloud/api/organizations/#operation/PostOrgsIDOwners)[DELETE`/api/v2/orgs/{orgID}/owners/{userID}`Remove an owner from an organization](/influxdb/cloud/api/organizations/#operation/DeleteOrgsIDOwnersID)[DELETE`/api/v2/orgs/{orgID}/owners/{userID}`Remove an owner from an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/DeleteOrgsIDOwnersID)[GET`/api/v2/orgs/{orgID}/secrets`List all secret keys for an organization](/influxdb/cloud/api/secrets/#operation/GetOrgsIDSecrets)[GET`/api/v2/orgs/{orgID}/secrets`List all secret keys for an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetOrgsIDSecrets)[PATCH`/api/v2/orgs/{orgID}/secrets`Update secrets in an organization](/influxdb/cloud/api/secrets/#operation/PatchOrgsIDSecrets)[DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}`Delete a secret from an organization](/influxdb/cloud/api/secrets/#operation/DeleteOrgsIDSecretsID)[DELETE`/api/v2/orgs/{orgID}/secrets/{secretID}`Delete a secret from an organization](/influxdb/cloud/api/security-and-access-endpoints/#operation/DeleteOrgsIDSecretsID)[POST`/api/v2/orgs/{orgID}/secrets/delete`Delete secrets from an organizationDeprecated](/influxdb/cloud/api/secrets/#operation/PostOrgsIDSecrets)[POST`/api/v2/orgs/{orgID}/secrets/delete`Delete secrets from an organizationDeprecated](/influxdb/cloud/api/security-and-access-endpoints/#operation/PostOrgsIDSecrets)[GET`/api/v2/orgs/{orgID}/usage`Retrieve usage for an organization](/influxdb/cloud/api/usage/#operation/GetOrgUsageID)[POST`/api/v2/query`Query data](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostQuery)[POST`/api/v2/query`Query data](/influxdb/cloud/api/query/#operation/PostQuery)[POST`/api/v2/query/analyze`Analyze a Flux query](/influxdb/cloud/api/query/#operation/PostQueryAnalyze)[POST`/api/v2/query/ast`Generate a query Abstract Syntax Tree (AST)](/influxdb/cloud/api/query/#operation/PostQueryAst)[GET`/api/v2/query/suggestions`List Flux query suggestions](/influxdb/cloud/api/query/#operation/GetQuerySuggestions)[GET`/api/v2/query/suggestions/{name}`Retrieve a query suggestion for a branching suggestion](/influxdb/cloud/api/query/#operation/GetQuerySuggestionsName)[GET`/api/v2/resources`List all known resources](/influxdb/cloud/api/resources/#operation/GetResources)[GET`/api/v2/resources`List all known resources](/influxdb/cloud/api/system-information-endpoints/#operation/GetResources)[GET`/api/v2/scripts`List scripts](/influxdb/cloud/api/data-i-o-endpoints/#operation/GetScripts)[GET`/api/v2/scripts`List scripts](/influxdb/cloud/api/invokable-scripts/#operation/GetScripts)[POST`/api/v2/scripts`Create a script](/influxdb/cloud/api/invokable-scripts/#operation/PostScripts)[DELETE`/api/v2/scripts/{scriptID}`Delete a script](/influxdb/cloud/api/invokable-scripts/#operation/DeleteScriptsID)[GET`/api/v2/scripts/{scriptID}`Retrieve a script](/influxdb/cloud/api/data-i-o-endpoints/#operation/GetScriptsID)[GET`/api/v2/scripts/{scriptID}`Retrieve a script](/influxdb/cloud/api/invokable-scripts/#operation/GetScriptsID)[PATCH`/api/v2/scripts/{scriptID}`Update a script](/influxdb/cloud/api/invokable-scripts/#operation/PatchScriptsID)[POST`/api/v2/scripts/{scriptID}/invoke`Invoke a script](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostScriptsIDInvoke)[POST`/api/v2/scripts/{scriptID}/invoke`Invoke a script](/influxdb/cloud/api/invokable-scripts/#operation/PostScriptsIDInvoke)[GET`/api/v2/scripts/{scriptID}/params`Find script parameters.](/influxdb/cloud/api/invokable-scripts/#operation/GetScriptsIDParams)[GET`/api/v2/setup`Retrieve setup status](/influxdb/cloud/api/setup/#operation/GetSetup)[POST`/api/v2/setup`Create an initial user, organization, and bucket](/influxdb/cloud/api/setup/#operation/PostSetup)[POST`/api/v2/setup/user`Create a new user, organization, and bucket](/influxdb/cloud/api/setup/#operation/PostSetupUser)[POST`/api/v2/signin`Create a user session.](/influxdb/cloud/api/security-and-access-endpoints/#operation/PostSignin)[POST`/api/v2/signin`Create a user session.](/influxdb/cloud/api/signin/#operation/PostSignin)[POST`/api/v2/signout`Expire a user session](/influxdb/cloud/api/security-and-access-endpoints/#operation/PostSignout)[POST`/api/v2/signout`Expire a user session](/influxdb/cloud/api/signout/#operation/PostSignout)[GET`/api/v2/stacks`List installed stacks](/influxdb/cloud/api/templates/#operation/ListStacks)[POST`/api/v2/stacks`Create a stack](/influxdb/cloud/api/templates/#operation/CreateStack)[DELETE`/api/v2/stacks/{stack_id}`Delete a stack and associated resources](/influxdb/cloud/api/templates/#operation/DeleteStack)[GET`/api/v2/stacks/{stack_id}`Retrieve a stack](/influxdb/cloud/api/templates/#operation/ReadStack)[PATCH`/api/v2/stacks/{stack_id}`Update a stack](/influxdb/cloud/api/templates/#operation/UpdateStack)[POST`/api/v2/stacks/{stack_id}/uninstall`Uninstall a stack](/influxdb/cloud/api/templates/#operation/UninstallStack)[GET`/api/v2/tasks`List all tasks](/influxdb/cloud/api/data-i-o-endpoints/#operation/GetTasks)[GET`/api/v2/tasks`List all tasks](/influxdb/cloud/api/tasks/#operation/GetTasks)[POST`/api/v2/tasks`Create a task](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostTasks)[POST`/api/v2/tasks`Create a task](/influxdb/cloud/api/tasks/#operation/PostTasks)[DELETE`/api/v2/tasks/{taskID}`Delete a task](/influxdb/cloud/api/tasks/#operation/DeleteTasksID)[GET`/api/v2/tasks/{taskID}`Retrieve a task](/influxdb/cloud/api/data-i-o-endpoints/#operation/GetTasksID)[GET`/api/v2/tasks/{taskID}`Retrieve a task](/influxdb/cloud/api/tasks/#operation/GetTasksID)[PATCH`/api/v2/tasks/{taskID}`Update a task](/influxdb/cloud/api/tasks/#operation/PatchTasksID)[GET`/api/v2/tasks/{taskID}/labels`List labels for a task](/influxdb/cloud/api/tasks/#operation/GetTasksIDLabels)[POST`/api/v2/tasks/{taskID}/labels`Add a label to a task](/influxdb/cloud/api/tasks/#operation/PostTasksIDLabels)[DELETE`/api/v2/tasks/{taskID}/labels/{labelID}`Delete a label from a task](/influxdb/cloud/api/tasks/#operation/DeleteTasksIDLabelsID)[GET`/api/v2/tasks/{taskID}/logs`Retrieve all logs for a task](/influxdb/cloud/api/tasks/#operation/GetTasksIDLogs)[GET`/api/v2/tasks/{taskID}/members`List all task membersDeprecated](/influxdb/cloud/api/tasks/#operation/GetTasksIDMembers)[POST`/api/v2/tasks/{taskID}/members`Add a member to a taskDeprecated](/influxdb/cloud/api/tasks/#operation/PostTasksIDMembers)[DELETE`/api/v2/tasks/{taskID}/members/{userID}`Remove a member from a taskDeprecated](/influxdb/cloud/api/tasks/#operation/DeleteTasksIDMembersID)[GET`/api/v2/tasks/{taskID}/owners`List all owners of a taskDeprecated](/influxdb/cloud/api/tasks/#operation/GetTasksIDOwners)[POST`/api/v2/tasks/{taskID}/owners`Add an owner for a taskDeprecated](/influxdb/cloud/api/tasks/#operation/PostTasksIDOwners)[DELETE`/api/v2/tasks/{taskID}/owners/{userID}`Remove an owner from a taskDeprecated](/influxdb/cloud/api/tasks/#operation/DeleteTasksIDOwnersID)[GET`/api/v2/tasks/{taskID}/runs`List runs for a task](/influxdb/cloud/api/tasks/#operation/GetTasksIDRuns)[POST`/api/v2/tasks/{taskID}/runs`Start a task run, overriding the schedule](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostTasksIDRuns)[POST`/api/v2/tasks/{taskID}/runs`Start a task run, overriding the schedule](/influxdb/cloud/api/tasks/#operation/PostTasksIDRuns)[DELETE`/api/v2/tasks/{taskID}/runs/{runID}`Cancel a running task](/influxdb/cloud/api/tasks/#operation/DeleteTasksIDRunsID)[GET`/api/v2/tasks/{taskID}/runs/{runID}`Retrieve a run for a task.](/influxdb/cloud/api/tasks/#operation/GetTasksIDRunsID)[GET`/api/v2/tasks/{taskID}/runs/{runID}/logs`Retrieve all logs for a run](/influxdb/cloud/api/tasks/#operation/GetTasksIDRunsIDLogs)[POST`/api/v2/tasks/{taskID}/runs/{runID}/retry`Retry a task run](/influxdb/cloud/api/tasks/#operation/PostTasksIDRunsIDRetry)[GET`/api/v2/telegraf/plugins`List all Telegraf plugins](/influxdb/cloud/api/telegraf-plugins/#operation/GetTelegrafPlugins)[GET`/api/v2/telegrafs`List all Telegraf configurations](/influxdb/cloud/api/telegrafs/#operation/GetTelegrafs)[POST`/api/v2/telegrafs`Create a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/PostTelegrafs)[DELETE`/api/v2/telegrafs/{telegrafID}`Delete a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/DeleteTelegrafsID)[GET`/api/v2/telegrafs/{telegrafID}`Retrieve a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/GetTelegrafsID)[PUT`/api/v2/telegrafs/{telegrafID}`Update a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/PutTelegrafsID)[GET`/api/v2/telegrafs/{telegrafID}/labels`List all labels for a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/GetTelegrafsIDLabels)[POST`/api/v2/telegrafs/{telegrafID}/labels`Add a label to a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/PostTelegrafsIDLabels)[DELETE`/api/v2/telegrafs/{telegrafID}/labels/{labelID}`Delete a label from a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/DeleteTelegrafsIDLabelsID)[GET`/api/v2/telegrafs/{telegrafID}/members`List all users with member privileges for a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/GetTelegrafsIDMembers)[POST`/api/v2/telegrafs/{telegrafID}/members`Add a member to a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/PostTelegrafsIDMembers)[DELETE`/api/v2/telegrafs/{telegrafID}/members/{userID}`Remove a member from a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/DeleteTelegrafsIDMembersID)[GET`/api/v2/telegrafs/{telegrafID}/owners`List all owners of a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/GetTelegrafsIDOwners)[POST`/api/v2/telegrafs/{telegrafID}/owners`Add an owner to a Telegraf configuration](/influxdb/cloud/api/telegrafs/#operation/PostTelegrafsIDOwners)[DELETE`/api/v2/telegrafs/{telegrafID}/owners/{userID}`Remove an owner from a Telegraf config](/influxdb/cloud/api/telegrafs/#operation/DeleteTelegrafsIDOwnersID)[POST`/api/v2/templates/apply`Apply or dry-run a template](/influxdb/cloud/api/templates/#operation/ApplyTemplate)[POST`/api/v2/templates/export`Export a new template](/influxdb/cloud/api/templates/#operation/ExportTemplate)[GET`/api/v2/users`List users](/influxdb/cloud/api/security-and-access-endpoints/#operation/GetUsers)[GET`/api/v2/users`List users](/influxdb/cloud/api/users/#operation/GetUsers)[POST`/api/v2/users`Create a user](/influxdb/cloud/api/users/#operation/PostUsers)[DELETE`/api/v2/users/{userID}`Delete a user](/influxdb/cloud/api/users/#operation/DeleteUsersID)[GET`/api/v2/users/{userID}`Retrieve a user](/influxdb/cloud/api/users/#operation/GetUsersID)[PATCH`/api/v2/users/{userID}`Update a user](/influxdb/cloud/api/users/#operation/PatchUsersID)[POST`/api/v2/users/{userID}/password`Update a password](/influxdb/cloud/api/security-and-access-endpoints/#operation/PostUsersIDPassword)[POST`/api/v2/users/{userID}/password`Update a password](/influxdb/cloud/api/users/#operation/PostUsersIDPassword)[PUT`/api/v2/users/{userID}/password`Update a password](/influxdb/cloud/api/security-and-access-endpoints/#operation/PutUsersIDPassword)[PUT`/api/v2/users/{userID}/password`Update a password](/influxdb/cloud/api/users/#operation/PutUsersIDPassword)[GET`/api/v2/variables`List all variables](/influxdb/cloud/api/variables/#operation/GetVariables)[POST`/api/v2/variables`Create a variable](/influxdb/cloud/api/variables/#operation/PostVariables)[DELETE`/api/v2/variables/{variableID}`Delete a variable](/influxdb/cloud/api/variables/#operation/DeleteVariablesID)[GET`/api/v2/variables/{variableID}`Retrieve a variable](/influxdb/cloud/api/variables/#operation/GetVariablesID)[PATCH`/api/v2/variables/{variableID}`Update a variable](/influxdb/cloud/api/variables/#operation/PatchVariablesID)[PUT`/api/v2/variables/{variableID}`Replace a variable](/influxdb/cloud/api/variables/#operation/PutVariablesID)[GET`/api/v2/variables/{variableID}/labels`List all labels for a variable](/influxdb/cloud/api/variables/#operation/GetVariablesIDLabels)[POST`/api/v2/variables/{variableID}/labels`Add a label to a variable](/influxdb/cloud/api/variables/#operation/PostVariablesIDLabels)[DELETE`/api/v2/variables/{variableID}/labels/{labelID}`Delete a label from a variable](/influxdb/cloud/api/variables/#operation/DeleteVariablesIDLabelsID)[POST`/api/v2/write`Write data](/influxdb/cloud/api/data-i-o-endpoints/#operation/PostWrite)[POST`/api/v2/write`Write data](/influxdb/cloud/api/write/#operation/PostWrite) ## v1-compatible API [GET`/ping`Get the status of the instance](/influxdb/cloud/api/ping/#operation/GetPing)[GET`/ping`Get the status of the instance](/influxdb/cloud/api/system-information-endpoints/#operation/GetPing)[HEAD`/ping`Get the status of the instance](/influxdb/cloud/api/ping/#operation/HeadPing)[GET`/query`Query with the 1.x compatibility API](/influxdb/cloud/api/legacy-query/#operation/GetLegacyQuery)[POST`/write`Write time series data into InfluxDB in a V1-compatible format](/influxdb/cloud/api/legacy-write/#operation/PostLegacyWrite) ## Management API [GET`/legacy/authorizations`List all legacy authorizations](/influxdb/cloud/api/legacy-authorizations/#operation/GetLegacyAuthorizations)[POST`/legacy/authorizations`Create a legacy authorization](/influxdb/cloud/api/legacy-authorizations/#operation/PostLegacyAuthorizations)[DELETE`/legacy/authorizations/{authID}`Delete a legacy authorization](/influxdb/cloud/api/legacy-authorizations/#operation/DeleteLegacyAuthorizationsID)[GET`/legacy/authorizations/{authID}`Retrieve a legacy authorization](/influxdb/cloud/api/legacy-authorizations/#operation/GetLegacyAuthorizationsID)[PATCH`/legacy/authorizations/{authID}`Update a legacy authorization to be active or inactive](/influxdb/cloud/api/legacy-authorizations/#operation/PatchLegacyAuthorizationsID)[POST`/legacy/authorizations/{authID}/password`Set a legacy authorization password](/influxdb/cloud/api/legacy-authorizations/#operation/PostLegacyAuthorizationsIDPassword) --- # Authentication Source: https://docs.influxdata.com/influxdb/cloud/api/authentication/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Use one of the following schemes to authenticate to the InfluxDB Cloud 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: * **`EMAIL_ADDRESS`**: InfluxDB Cloud username (the email address the user signed up with) * **`PASSWORD`**: InfluxDB Cloud [API token](/influxdb/cloud/reference/glossary/#token) * **`INFLUX_URL`**: your InfluxDB Cloud 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 "EMAIL_ADDRESS":"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('EMAIL_ADDRESS: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 Cloud URL * *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) ### Related endpoints * [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides * [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication) * [Manage API tokens](/influxdb/cloud/security/tokens/) --- # Authorizations (API tokens) Source: https://docs.influxdata.com/influxdb/cloud/api/authorizations-api-tokens/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage API token authorizations that grant read and write permissions to InfluxDB Cloud 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/cloud/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/cloud/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `token`string An API [token](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#token) values in clear text. * If the request uses an *[operator token](/influxdb/cloud/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/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/cloud/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides * [View tokens](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/security/tokens/) * [View tokens](/influxdb/cloud/security/tokens/view-tokens/) --- # Bucket Schemas Source: https://docs.influxdata.com/influxdb/cloud/api/bucket-schemas/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage explicit schemas for InfluxDB Cloud buckets to enforce column names and data types for measurement data. GET`/api/v2/buckets/{bucketID}/schema/measurements` ### List measurement schemas of a bucket Lists *explicit*[schemas](/influxdb/cloud/reference/glossary/#schema)(`"schemaType": "explicit"`) for a bucket. *Explicit* schemas are used to enforce column names, tags, fields, and data types for your data. By default, buckets have an *implicit* schema-type (`"schemaType": "implicit"`) that conforms to your data. #### Related guides * [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/) #### Parameters ##### Path parameters `bucketID`requiredstring A bucket ID. Lists measurement schemas for the specified bucket. ##### Query parameters `org`string An organization name. Specifies the organization that owns the schema. `orgID`string An organization ID. Specifies the organization that owns the schema. `name`string A measurement name. Only returns measurement schemas with the specified name. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200A list of measurement schemas returning summary information. `measurementSchemas`requiredobject[] `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ Example request body ```json { "measurementSchemas": [ { "bucketID": "ba3c5e7f9b0a0010", "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8642", "name": "cpu", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" }, { "bucketID": "ba3c5e7f9b0a0010", "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8643", "name": "memory", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" }, { "bucketID": "ba3c5e7f9b0a0010", "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8644", "name": "disk", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" } ] } ``` 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. 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. POST`/api/v2/buckets/{bucketID}/schema/measurements` ### Create a measurement schema for a bucket Creates an *explict* measurement [schema](/influxdb/cloud/reference/glossary/#schema)for a bucket. *Explicit* schemas are used to enforce column names, tags, fields, and data types for your data. By default, buckets have an *implicit* schema-type (`"schemaType": "implicit"`) that conforms to your data. Use this endpoint to create schemas that prevent non-conforming write requests. #### Limitations * Buckets must be created with the “explict” `schemaType` in order to use schemas. #### Related guides * [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). * [Create a bucket with an explicit schema](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) #### Parameters ##### Path parameters `bucketID`requiredstring A bucket ID. Adds a schema for the specified bucket. ##### Query parameters `org`string An organization name. Specifies the organization that owns the schema. `orgID`string An organization ID. Specifies the organization that owns the schema. #### Request bodyrequired Content-Type:`application/json` `columns`requiredobject[] Ordered collection of column definitions. `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` `name`requiredstring The [measurement](/influxdb/cloud/reference/glossary/#measurement)name. Example request body ```json { "columns": [ { "format": "unix timestamp", "name": "time", "type": "integer" }, { "name": "host", "type": "tag" }, { "name": "region", "type": "tag" }, { "dataType": "float", "name": "usage_user", "type": "field" }, { "dataType": "float", "name": "usage_user", "type": "field" } ], "name": "cpu" } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"columns":[{"format":"unix timestamp","name":"time","type":"integer"},{"name":"host","type":"tag"},{"name":"region","type":"tag"},{"dataType":"float","name":"usage_user","type":"field"},{"dataType":"float","name":"usage_user","type":"field"}],"name":"cpu"}' ``` #### Responses 201The current version of the measurement schema. `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ Example request body ```json { "bucketID": "ba3c5e7f9b0a0010", "columns": [ { "format": "unix timestamp", "name": "time", "type": "integer" }, { "name": "host", "type": "tag" }, { "name": "region", "type": "tag" }, { "dataType": "float", "name": "usage_user", "type": "field" }, { "dataType": "float", "name": "usage_user", "type": "field" } ], "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8642", "name": "cpu", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" } ``` 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. 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. GET`/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}` ### Retrieve a measurement schema Retrieves an explicit measurement [schema](/influxdb/cloud/reference/glossary/#schema). #### Parameters ##### Path parameters `bucketID`requiredstring A bucket ID. Retrieves schemas for the specified bucket. `measurementID`requiredstring The measurement schema ID. Specifies the measurement schema to retrieve. ##### Query parameters `org`string Organization name. Specifies the organization that owns the schema. `orgID`string Organization ID. Specifies the organization that owns the schema. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Schema definition for a single measurement `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ Example request body ```json { "bucketID": "ba3c5e7f9b0a0010", "columns": [ { "format": "unix timestamp", "name": "time", "type": "integer" }, { "name": "host", "type": "tag" }, { "name": "region", "type": "tag" }, { "dataType": "float", "name": "usage_user", "type": "field" }, { "dataType": "float", "name": "usage_user", "type": "field" } ], "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8642", "name": "cpu", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" } ``` 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. PATCH`/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}` ### Update a measurement schema Updates a measurement [schema](/influxdb/cloud/reference/glossary/#schema). Use this endpoint to update the fields (`name`, `type`, and `dataType`) of a measurement schema. #### Limitations * You can’t update the `name` of a measurement. #### Related guides * [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). * [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). #### Parameters ##### Path parameters `bucketID`requiredstring A bucket ID. Specifies the bucket to retrieve schemas for. `measurementID`requiredstring A measurement schema ID. Retrieves the specified measurement schema. ##### Query parameters `org`string An organization name. Specifies the organization that owns the schema. `orgID`string An organization ID. Specifies the organization that owns the schema. #### Request bodyrequired Content-Type:`application/json` `columns`requiredobject[] An ordered collection of column definitions `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` Example request body ```json { "columns": [ { "format": "unix timestamp", "name": "time", "type": "integer" }, { "name": "host", "type": "tag" }, { "name": "region", "type": "tag" }, { "dataType": "float", "name": "usage_user", "type": "field" }, { "dataType": "float", "name": "usage_user", "type": "field" } ] } ``` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"columns":[{"format":"unix timestamp","name":"time","type":"integer"},{"name":"host","type":"tag"},{"name":"region","type":"tag"},{"dataType":"float","name":"usage_user","type":"field"},{"dataType":"float","name":"usage_user","type":"field"}]}' ``` #### Responses 200Success. The response body contains the measurement schema. `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `dataType`string Allowed:`integer`, `float`, `boolean`, `string`, `unsigned` `name`requiredstring `type`requiredstring Allowed:`timestamp`, `tag`, `field` `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ Example request body ```json { "bucketID": "ba3c5e7f9b0a0010", "columns": [ { "format": "unix timestamp", "name": "time", "type": "integer" }, { "name": "host", "type": "tag" }, { "name": "region", "type": "tag" }, { "dataType": "float", "name": "usage_user", "type": "field" }, { "dataType": "float", "name": "usage_user", "type": "field" } ], "createdAt": "2021-01-21T00:48:40.993Z", "id": "1a3c5e7f9b0a8642", "name": "cpu", "orgID": "0a3c5e7f9b0a0001", "updatedAt": "2021-01-21T00:48:40.993Z" } ``` 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. 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. --- # Buckets Source: https://docs.influxdata.com/influxdb/cloud/api/buckets/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage named storage locations (buckets) in InfluxDB Cloud, each with a configurable retention period. GET`/api/v2/buckets` ### List buckets Lists [buckets](/influxdb/cloud/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the[organization](/influxdb/cloud/reference/glossary/#organization)associated with the authorization ([API token](/influxdb/cloud/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/cloud/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/cloud/reference/internals/system-buckets/)| `read-orgs` | #### Related Guides * [Manage buckets](/influxdb/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/reference/glossary/#bucket)and returns the bucket resource. The default data[retention period](/influxdb/cloud/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/cloud/organizations/buckets/create-bucket/) * [Create bucket CLI reference](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/internals/shards/#shard-group-duration). #### Related guides * InfluxDB [shards and shard groups](/influxdb/cloud/reference/internals/shards/) `type`string Allowed:`expire` Default:`expire` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/cloud/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/cloud/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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. #### Related * [Manage buckets](/influxdb/cloud/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/cloud/api/cells/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage cells within InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/api/checks/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB Cloud. 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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/common-parameters/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Most InfluxDB Cloud 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 Cloud 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). | --- # Config Source: https://docs.influxdata.com/influxdb/cloud/api/config/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve configuration information for an InfluxDB Cloud instance. 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/cloud/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/cloud/reference/config-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/dashboards/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage dashboards in InfluxDB Cloud. GET`/api/v2/dashboards` ### List dashboards Lists [dashboards](/influxdb/cloud/reference/glossary/#dashboard). #### Related guides * [Manage dashboards](/influxdb/cloud/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/cloud/api/#tag/Pagination). `descending`boolean `limit`integer The maximum number of [dashboards](/influxdb/cloud/reference/glossary/#dashboard) to return. Default is `20`. The minimum is `-1` and the maximum is `100`. Default:`20` `owner`string A user ID. Only returns [dashboards](/influxdb/cloud/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/cloud/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. `orgID`string An organization ID. Only returns [dashboards](/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified[organization](/influxdb/cloud/reference/glossary/#organization). `org`string An organization name. Only returns [dashboards](/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified[organization](/influxdb/cloud/reference/glossary/#organization). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/data-i-o-endpoints/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-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/cloud/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/cloud/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/cloud/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). Content-Type:`application/json` `predicate`string An expression in [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). Example:`"tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"` `start`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. `stop`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/cloud/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/scripts` ### List scripts Lists [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Related guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/Pagination). `limit`integer The maximum number of scripts to return. Default is `100`. Default:`100` `name`string The script name. Lists scripts with the specified name. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of scripts. `scripts`object[] `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 400Bad request. InfluxDB is unable to parse the 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. 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/scripts/{scriptID}` ### Retrieve a script Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Related Guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Retrieves the specified script. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the script. `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 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. POST`/api/v2/scripts/{scriptID}/invoke` ### Invoke a script Runs a script and returns the result. When the script runs, InfluxDB replaces `params` keys referenced in the script with`params` key-values passed in the request body–for example: The following sample script contains a *`mybucket`* parameter : ```json "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)" ``` The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body passes a value for the *`mybucket`* parameter: ```json { "params": { "mybucket": "air_sensor" } } ``` #### Related guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Runs the specified script. #### Request body Content-Type:`application/json` `params`object The script parameters.`params` contains key-value pairs that map values to the **params.keys**in a script. When you invoke a script with `params`, InfluxDB passes the values as invocation parameters to the script. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/invoke" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "params": {} }' ``` #### Responses 200Success. The response body contains the result of the script execution. 400Bad request. InfluxDB is unable to parse the 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. 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. 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` ### List all tasks Retrieves a list of [tasks](/influxdb/cloud/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`. #### Parameters ##### Query parameters `name`string A [task](/influxdb/cloud/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. `after`string A [task](/influxdb/cloud/reference/glossary/#task) ID. Only returns tasks created after the specified task. `user`string A [user](/influxdb/cloud/reference/glossary/#user) ID. Only returns tasks owned by the specified user. `org`string An [organization](/influxdb/cloud/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. `orgID`string An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. `status`string A [task](/influxdb/cloud/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/cloud/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` `offset`integer The number of records to skip. `sortBy`string The sort field. Only `name` is supported. Specifies the field used to sort records in the list. Allowed values:`name` `type`string A [task](/influxdb/cloud/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` `scriptID`string A [script](#tag/Invokable-Scripts) ID. Only returns tasks that use the specified invokable script. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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/cloud/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a Flux script. #### InfluxDB Cloud * You can use either `flux` or `scriptID` to provide the task script. * `flux`: a string of “raw” Flux that contains task options and the script–for example: ``` { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "status": "active", "description": "This task downsamples CPU data every hour" } ``` * `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body–for example: ``` { "name": "CPU Total 1 Hour New", "description": "This task downsamples CPU data every hour", "every": "1h", "scriptID": "SCRIPT_ID", "scriptParameters": { "rangeStart": "-1h", "bucket": "telegraf", "filterField": "cpu-total" } } ``` #### Limitations: * You can’t use `flux` and `scriptID` for the same task. #### Related guides * [Get started with tasks](/influxdb/cloud/process-data/get-started/) * [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task/) * [Common tasks](/influxdb/cloud/process-data/common-tasks/) * [Task configuration options](/influxdb/cloud/process-data/task-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The task to create Content-Type:`application/json` `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time. `description`string The description of the task. `every`string The interval ([duration literal](/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs.`every` also determines when the task first runs, depending on the specified time. `flux`string The Flux script that the task runs. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `name`string 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 The name of the organization that owns the task. `orgID`string The ID of the organization that owns the task. `scriptID`string The ID of the script that the task runs. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. `scriptParameters`object The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. #### Limitations * `scriptParameters` requires `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cron": "CRON", "description": "DESCRIPTION", "every": "EVERY", "flux": "FLUX", "name": "NAME", "offset": "OFFSET", "org": "ORG", "orgID": "ORGID", "scriptID": "SCRIPTID", "scriptParameters": {}, "status": "active" }' ``` #### Responses 201Success. The response body contains a `tasks` list with the new 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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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 Cloud * Returns this error if the task doesn’t contain one of *`flux`* or *`scriptID`*. * Returns this error if the task contains *`flux`* *and* *`scriptID`*. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of 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/cloud/reference/glossary/#task). #### Parameters ##### Path parameters `taskID`requiredstring A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/write-data/developer-tools/api) * [Optimize writes to InfluxDB](/influxdb/cloud/write-data/best-practices/optimize-writes/) * [Troubleshoot issues writing data](/influxdb/cloud/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/cloud/write-data/troubleshoot/) Allowed values:`application/json` Default:`application/json` #### Request bodyrequired In the request body, provide data in [line protocol format](/influxdb/cloud/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/cloud/write-data/best-practices/optimize-writes/) Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/api/dbrps/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB Cloud buckets. GET`/api/v2/dbrps` ### List database retention policy mappings Lists database retention policy (DBRP) mappings. #### Related guide * [Database and retention policy mapping](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#organization) that owns the mapping. `orgID`string An organization ID. Identifies the [organization](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/api/influxdb-1x/dbrp/) --- # Delete Source: https://docs.influxdata.com/influxdb/cloud/api/delete/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Delete time series data from an InfluxDB Cloud 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/cloud/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/cloud/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/cloud/write-data/delete-data/) * Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). Content-Type:`application/json` `predicate`string An expression in [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). Example:`"tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"` `start`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. `stop`requiredstring \ A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/headers/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) InfluxDB Cloud API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB Cloud 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. | --- # Invokable Scripts Source: https://docs.influxdata.com/influxdb/cloud/api/invokable-scripts/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Store, manage, and execute custom Flux scripts in InfluxDB Cloud. Scripts accept runtime parameters and can be invoked via dedicated endpoints. GET`/api/v2/scripts` ### List scripts Lists [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Related guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Query parameters `offset`integer The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/Pagination). `limit`integer The maximum number of scripts to return. Default is `100`. Default:`100` `name`string The script name. Lists scripts with the specified name. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the list of scripts. `scripts`object[] `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 400Bad request. InfluxDB is unable to parse the 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. 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/scripts` ### Create a script Creates an [invokable script](/resources/videos/api-invokable-scripts/)and returns the script. #### Related guides * [Invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) * [Creating custom InfluxDB endpoints](/resources/videos/api-invokable-scripts/) #### Request bodyrequired The script to create. Content-Type:`application/json` `description`requiredstring Script description. A description of the script. `language`requiredstring Allowed:`flux`, `sql`, `influxql` `name`requiredstring Script name. The name must be unique within the organization. `script`requiredstring The script to execute. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "language": "flux", "name": "NAME", "script": "SCRIPT" }' ``` #### Responses 201Success. The response body contains the script and its metadata. `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 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. 422Unprocessable entity. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of 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/scripts/{scriptID}` ### Retrieve a script Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Related Guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Retrieves the specified script. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the script. `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 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/scripts/{scriptID}` ### Update a script Updates an invokable script. Use this endpoint to modify values for script properties (`description` and `script`). To update a script, pass an object that contains the updated key-value pairs. #### Limitations * If you send an empty request body, the script will neither update nor store an empty script, but InfluxDB will respond with an HTTP `200` status code. #### Related Guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Updates the specified script. #### Request bodyrequired An object that contains the updated script properties to apply. Content-Type:`application/json` `description`string A description of the script. `script`string The script to execute. Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "script": "SCRIPT" }' ``` #### Responses 200Success. The response body contains the updated script. `createdAt`string \ `description`string `id`string `language`string Allowed:`flux`, `sql`, `influxql` `name`requiredstring `orgID`requiredstring `script`requiredstring The script to execute. `updatedAt`string \ `url`string The invocation endpoint address. 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. DELETE`/api/v2/scripts/{scriptID}` ### Delete a script Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. #### Limitations * You can delete only one script per request. * If the script ID you provide doesn’t exist for the organization, InfluxDB responds with an HTTP `204` status code. #### Related Guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Deletes the specified script. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The script is queued for deletion. 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/scripts/{scriptID}/invoke` ### Invoke a script Runs a script and returns the result. When the script runs, InfluxDB replaces `params` keys referenced in the script with`params` key-values passed in the request body–for example: The following sample script contains a *`mybucket`* parameter : ```json "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)" ``` The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body passes a value for the *`mybucket`* parameter: ```json { "params": { "mybucket": "air_sensor" } } ``` #### Related guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. Runs the specified script. #### Request body Content-Type:`application/json` `params`object The script parameters.`params` contains key-value pairs that map values to the **params.keys**in a script. When you invoke a script with `params`, InfluxDB passes the values as invocation parameters to the script. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/invoke" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "params": {} }' ``` #### Responses 200Success. The response body contains the result of the script execution. 400Bad request. InfluxDB is unable to parse the 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. 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. 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/scripts/{scriptID}/params` ### Find script parameters. Analyzes a script and determines required parameters. Find all `params` keys referenced in a script and return a list of keys. If it is possible to determine the type of the value from the context then the type is also returned – for example: The following sample script contains a *`mybucket`* parameter : ```json "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)" ``` Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params`returns the following: ```json { "params": { "mybucket": "string" } } ``` The type name returned for a parameter will be one of: * `any` * `bool` * `duration` * `float` * `int` * `string` * `time` * `uint` The type name `any` is used when the type of a parameter cannot be determined from the context, or the type is determined to be a structured type such as an array or record. #### Related guides * [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID`requiredstring A script ID. The script to analyze for params. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/params" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the parameters found, along with their types. `params`object The `params` keys and value type defined in the script. 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. 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. --- # Labels Source: https://docs.influxdata.com/influxdb/cloud/api/labels/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage labels for organizing InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/legacy-authorizations/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage legacy (v1-compatible) authorization credentials in InfluxDB Cloud. 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/cloud/reference/glossary/#user). `user`string A user name. Only returns legacy authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `orgID`string An organization ID. Only returns legacy authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `org`string An organization name. Only returns legacy authorizations that belong to the specified [organization](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/legacy-query/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Query data using InfluxQL via the v1-compatible `/query` endpoint in InfluxDB Cloud. 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/cloud/reference/glossary/#bucket). For more information, see [Database and retention policy mapping](/influxdb/cloud/api/influxdb-1x/dbrp/). `rp`string The retention policy to query data from. This is mapped to an InfluxDB [bucket](/influxdb/cloud/reference/glossary/#bucket). For more information, see [Database and retention policy mapping](/influxdb/cloud/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/cloud/reference/glossary/#unix-timestamp) the specified precision instead of [RFC3339 timestamps](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/cloud/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/cloud/api/legacy-write/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Write data using the v1-compatible `/write` endpoint in InfluxDB Cloud. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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. --- # Limits Source: https://docs.influxdata.com/influxdb/cloud/api/limits/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve rate limits and usage quotas for an InfluxDB Cloud organization. GET`/api/v2/orgs/{orgID}/limits` ### Retrieve limits for an organization #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/orgs/{orgID}/limits" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Limits defined for the organization. `limits`object These are org limits similar to those configured in/by quartz. `bucket`requiredobject `maxBuckets`requiredinteger `maxRetentionDuration`requiredinteger Max bucket retention duration in nanoseconds. 0 is unlimited. `check`requiredobject `maxChecks`requiredinteger `dashboard`requiredobject `maxDashboards`requiredinteger `features`object `allowDelete`boolean allow delete predicate endpoint `ioxQuery`object `parquetFiles`requiredinteger `partitions`requiredinteger `notificationEndpoint`requiredobject `blockedNotificationEndpoints`string comma separated list of notification endpoints Example:`"http,pagerduty"` `notificationRule`requiredobject `blockedNotificationRules`string comma separated list of notification rules Example:`"http,pagerduty"` `maxNotifications`requiredinteger `orgID`string `rate`requiredobject `cardinality`requiredinteger Allowed organization total cardinality. 0 is unlimited. `concurrentDeleteRequests`integer Allowed organization concurrent outstanding delete requests. `concurrentReadRequests`requiredinteger Allowed concurrent queries. 0 is unlimited. `concurrentWriteRequests`requiredinteger Allowed concurrent writes. 0 is unlimited. `deleteRequestsPerSecond`integer Allowed organization delete request rate. `queryTime`requiredinteger Query Time in nanoseconds `readKBs`requiredinteger Query limit in kb/sec. 0 is unlimited. `writeKBs`requiredinteger Write limit in kb/sec. 0 is unlimited. `stack`object `enabled`requiredboolean `task`requiredobject `maxTasks`requiredinteger `timeout`object `queryUnconditionalTimeoutSeconds`requiredinteger `queryidleWriteTimeoutSeconds`requiredinteger `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. --- # NotificationEndpoints Source: https://docs.influxdata.com/influxdb/cloud/api/notificationendpoints/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage notification endpoints that receive alert notifications from InfluxDB Cloud 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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/notificationrules/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage notification rules that define when and how InfluxDB Cloud 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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/organizations/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) View and manage InfluxDB Cloud organizations, which are workspaces that group users, buckets, and resources. GET`/api/v2/orgs` ### List organizations Lists [organizations](/influxdb/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/cloud/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/cloud/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 * [View and manage organizations](/influxdb/cloud/organizations/) --- # Pagination Source: https://docs.influxdata.com/influxdb/cloud/api/pagination/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) List endpoints in the InfluxDB Cloud 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/cloud/api/ping/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Check the availability of the InfluxDB Cloud 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/cloud/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request HEAD \ "https://us-east-1-1.aws.cloud2.influxdata.com/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. Headers contain InfluxDB version information. --- # Query Source: https://docs.influxdata.com/influxdb/cloud/api/query/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/quick-start/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Authenticate, write, and query with the InfluxDB Cloud API: 1. Create an API token with write and read permissions for a bucket. Create tokens in the InfluxDB Cloud UI or via the Authorizations (API tokens) endpoints. 2. Check the status of your InfluxDB Cloud region. ``` curl "https://REGION.aws.cloud2.influxdata.com/health" ``` 3. Write data to a bucket using the `/api/v2/write` endpoint and[line protocol](/influxdb/cloud/reference/syntax/line-protocol/). ``` curl --request POST \ "https://REGION.aws.cloud2.influxdata.com/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 \ "https://REGION.aws.cloud2.influxdata.com/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 "https://REGION.aws.cloud2.influxdata.com/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 Cloud](/influxdb/cloud/get-started/). #### Related * [Get started with InfluxDB Cloud](/influxdb/cloud/get-started/) * [Write data](/influxdb/cloud/write-data/) * [Query data with Flux](/influxdb/cloud/query-data/) --- # Resources Source: https://docs.influxdata.com/influxdb/cloud/api/resources/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve a list of top-level resource types available in the InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/response-codes/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) InfluxDB Cloud 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. | --- # Routes Source: https://docs.influxdata.com/influxdb/cloud/api/routes/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve top-level routes for the InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ `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 \ `query`object `analyze`string \ `ast`string \ `self`string \ `suggestions`string \ `signin`string \ `signout`string \ `tasks`string \ `telegraf`object `plugins`string \ `telegrafs`string \ `users`string \ `variables`string \ `write`string \ --- # Rules Source: https://docs.influxdata.com/influxdb/cloud/api/rules/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage notification rules in InfluxDB Cloud. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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. --- # Secrets Source: https://docs.influxdata.com/influxdb/cloud/api/secrets/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage secrets (key-value pairs) for use in InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/security-and-access-endpoints/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Endpoints for managing authentication and access control in InfluxDB Cloud. 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/cloud/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/cloud/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `token`string An API [token](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#token) values in clear text. * If the request uses an *[operator token](/influxdb/cloud/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/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/cloud/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides * [View tokens](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](/influxdb/cloud/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/cloud/users/) * [Manage members](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user). To limit which users are returned, pass query parameters in your request. #### InfluxDB Cloud * InfluxDB Cloud doesn’t allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action | Permission required | Restriction | |--------------------|-----------------------------------|----------------------------| | List all users | Operator token |InfluxData internal use only| |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 * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Query parameters `name`string A user name. Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). `id`string A user id. Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response contains a list of `users`. #### InfluxDB Cloud * Returns an empty `users` list if you don’t pass *`id`* or *`name`* parameters and don’t use an*operator token*. Only InfluxData can access InfluxDB Cloud operator tokens. `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/{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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/security/tokens/view-tokens/) | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | List all users | Operator token | InfluxData internal use only | | List a specific user | read-users or read-user USER_ID | | --- # Setup Source: https://docs.influxdata.com/influxdb/cloud/api/setup/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Check whether an InfluxDB instance allows initial setup. InfluxDB Cloud doesn’t support initial setup. Every InfluxDB Cloud account already has a user and an organization, so `GET /api/v2/setup` always returns `{"allowed": false}`, and the `POST` setup endpoints don’t apply to InfluxDB Cloud. To set up an InfluxDB OSS 2.x instance, see the[InfluxDB OSS v2 setup endpoints](/influxdb/v2/api/setup/). GET`/api/v2/setup` ### Retrieve setup status Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Setup is allowed, true or false `allowed`boolean If `true`, the InfluxDB instance hasn’t had initial setup;`false` otherwise. POST`/api/v2/setup` ### Create an initial user, organization, and bucket Post an onboarding request to create an initial user, organization, and bucket. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Source to create Content-Type:`application/json` `bucket`requiredstring `limit`object These are org limits similar to those configured in/by quartz. `bucket`requiredobject `maxBuckets`requiredinteger `maxRetentionDuration`requiredinteger Max bucket retention duration in nanoseconds. 0 is unlimited. `check`requiredobject `maxChecks`requiredinteger `dashboard`requiredobject `maxDashboards`requiredinteger `features`object `allowDelete`boolean allow delete predicate endpoint `ioxQuery`object `parquetFiles`requiredinteger `partitions`requiredinteger `notificationEndpoint`requiredobject `blockedNotificationEndpoints`string comma separated list of notification endpoints Example:`"http,pagerduty"` `notificationRule`requiredobject `blockedNotificationRules`string comma separated list of notification rules Example:`"http,pagerduty"` `maxNotifications`requiredinteger `orgID`string `rate`requiredobject `cardinality`requiredinteger Allowed organization total cardinality. 0 is unlimited. `concurrentDeleteRequests`integer Allowed organization concurrent outstanding delete requests. `concurrentReadRequests`requiredinteger Allowed concurrent queries. 0 is unlimited. `concurrentWriteRequests`requiredinteger Allowed concurrent writes. 0 is unlimited. `deleteRequestsPerSecond`integer Allowed organization delete request rate. `queryTime`requiredinteger Query Time in nanoseconds `readKBs`requiredinteger Query limit in kb/sec. 0 is unlimited. `writeKBs`requiredinteger Write limit in kb/sec. 0 is unlimited. `stack`object `enabled`requiredboolean `task`requiredobject `maxTasks`requiredinteger `timeout`object `queryUnconditionalTimeoutSeconds`requiredinteger `queryidleWriteTimeoutSeconds`requiredinteger `org`requiredstring `password`string `retentionPeriodHrs`integer `retentionPeriodSeconds`integer `username`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucket": "BUCKET", "limit": { "bucket": { "maxBuckets": 0, "maxRetentionDuration": 0 }, "check": { "maxChecks": 0 }, "dashboard": { "maxDashboards": 0 }, "features": { "allowDelete": false }, "ioxQuery": { "parquetFiles": 0, "partitions": 0 }, "notificationEndpoint": { "blockedNotificationEndpoints": "http,pagerduty" }, "notificationRule": { "blockedNotificationRules": "http,pagerduty", "maxNotifications": 0 }, "orgID": "ORGID", "rate": { "cardinality": 0, "concurrentDeleteRequests": 0, "concurrentReadRequests": 0, "concurrentWriteRequests": 0, "deleteRequestsPerSecond": 0, "queryTime": 0, "readKBs": 0, "writeKBs": 0 }, "stack": { "enabled": false }, "task": { "maxTasks": 0 }, "timeout": { "queryUnconditionalTimeoutSeconds": 0, "queryidleWriteTimeoutSeconds": 0 } }, "org": "ORG", "password": "PASSWORD", "retentionPeriodHrs": 0, "retentionPeriodSeconds": 0, "username": "USERNAME" }' ``` #### Responses 201The created default user, bucket, and organization `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/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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. POST`/api/v2/setup/user` ### Create a new user, organization, and bucket Post an onboarding request to create a new user, organization, and bucket. #### Request bodyrequired Source to create Content-Type:`application/json` `bucket`requiredstring `limit`object These are org limits similar to those configured in/by quartz. `bucket`requiredobject `maxBuckets`requiredinteger `maxRetentionDuration`requiredinteger Max bucket retention duration in nanoseconds. 0 is unlimited. `check`requiredobject `maxChecks`requiredinteger `dashboard`requiredobject `maxDashboards`requiredinteger `features`object `allowDelete`boolean allow delete predicate endpoint `ioxQuery`object `parquetFiles`requiredinteger `partitions`requiredinteger `notificationEndpoint`requiredobject `blockedNotificationEndpoints`string comma separated list of notification endpoints Example:`"http,pagerduty"` `notificationRule`requiredobject `blockedNotificationRules`string comma separated list of notification rules Example:`"http,pagerduty"` `maxNotifications`requiredinteger `orgID`string `rate`requiredobject `cardinality`requiredinteger Allowed organization total cardinality. 0 is unlimited. `concurrentDeleteRequests`integer Allowed organization concurrent outstanding delete requests. `concurrentReadRequests`requiredinteger Allowed concurrent queries. 0 is unlimited. `concurrentWriteRequests`requiredinteger Allowed concurrent writes. 0 is unlimited. `deleteRequestsPerSecond`integer Allowed organization delete request rate. `queryTime`requiredinteger Query Time in nanoseconds `readKBs`requiredinteger Query limit in kb/sec. 0 is unlimited. `writeKBs`requiredinteger Write limit in kb/sec. 0 is unlimited. `stack`object `enabled`requiredboolean `task`requiredobject `maxTasks`requiredinteger `timeout`object `queryUnconditionalTimeoutSeconds`requiredinteger `queryidleWriteTimeoutSeconds`requiredinteger `org`requiredstring `password`string `retentionPeriodHrs`integer `retentionPeriodSeconds`integer `username`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup/user" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucket": "BUCKET", "limit": { "bucket": { "maxBuckets": 0, "maxRetentionDuration": 0 }, "check": { "maxChecks": 0 }, "dashboard": { "maxDashboards": 0 }, "features": { "allowDelete": false }, "ioxQuery": { "parquetFiles": 0, "partitions": 0 }, "notificationEndpoint": { "blockedNotificationEndpoints": "http,pagerduty" }, "notificationRule": { "blockedNotificationRules": "http,pagerduty", "maxNotifications": 0 }, "orgID": "ORGID", "rate": { "cardinality": 0, "concurrentDeleteRequests": 0, "concurrentReadRequests": 0, "concurrentWriteRequests": 0, "deleteRequestsPerSecond": 0, "queryTime": 0, "readKBs": 0, "writeKBs": 0 }, "stack": { "enabled": false }, "task": { "maxTasks": 0 }, "timeout": { "queryUnconditionalTimeoutSeconds": 0, "queryidleWriteTimeoutSeconds": 0 } }, "org": "ORG", "password": "PASSWORD", "retentionPeriodHrs": 0, "retentionPeriodSeconds": 0, "username": "USERNAME" }' ``` #### Responses 201The created default user, bucket, and organization. `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/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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. --- # Signin Source: https://docs.influxdata.com/influxdb/cloud/api/signin/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/signout/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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. --- # Supported operations Source: https://docs.influxdata.com/influxdb/cloud/api/supported-operations/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) The InfluxDB Cloud 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/cloud/api/system-information-endpoints/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Endpoints for retrieving system-level information about the InfluxDB Cloud instance. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ `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 \ `query`object `analyze`string \ `ast`string \ `self`string \ `suggestions`string \ `signin`string \ `signout`string \ `tasks`string \ `telegraf`object `plugins`string \ `telegrafs`string \ `users`string \ `variables`string \ `write`string \ 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/cloud/reference/cli/influx/ping/) Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/ping" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. Headers contain InfluxDB version information. --- # Tasks Source: https://docs.influxdata.com/influxdb/cloud/api/tasks/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB Cloud. GET`/api/v2/tasks` ### List all tasks Retrieves a list of [tasks](/influxdb/cloud/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`. #### Parameters ##### Query parameters `name`string A [task](/influxdb/cloud/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. `after`string A [task](/influxdb/cloud/reference/glossary/#task) ID. Only returns tasks created after the specified task. `user`string A [user](/influxdb/cloud/reference/glossary/#user) ID. Only returns tasks owned by the specified user. `org`string An [organization](/influxdb/cloud/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. `orgID`string An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. `status`string A [task](/influxdb/cloud/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/cloud/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` `offset`integer The number of records to skip. `sortBy`string The sort field. Only `name` is supported. Specifies the field used to sort records in the list. Allowed values:`name` `type`string A [task](/influxdb/cloud/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` `scriptID`string A [script](#tag/Invokable-Scripts) ID. Only returns tasks that use the specified invokable script. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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/cloud/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a Flux script. #### InfluxDB Cloud * You can use either `flux` or `scriptID` to provide the task script. * `flux`: a string of “raw” Flux that contains task options and the script–for example: ``` { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "status": "active", "description": "This task downsamples CPU data every hour" } ``` * `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body–for example: ``` { "name": "CPU Total 1 Hour New", "description": "This task downsamples CPU data every hour", "every": "1h", "scriptID": "SCRIPT_ID", "scriptParameters": { "rangeStart": "-1h", "bucket": "telegraf", "filterField": "cpu-total" } } ``` #### Limitations: * You can’t use `flux` and `scriptID` for the same task. #### Related guides * [Get started with tasks](/influxdb/cloud/process-data/get-started/) * [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task/) * [Common tasks](/influxdb/cloud/process-data/common-tasks/) * [Task configuration options](/influxdb/cloud/process-data/task-options/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The task to create Content-Type:`application/json` `cron`string A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time. `description`string The description of the task. `every`string The interval ([duration literal](/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs.`every` also determines when the task first runs, depending on the specified time. `flux`string The Flux script that the task runs. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `name`string 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 The name of the organization that owns the task. `orgID`string The ID of the organization that owns the task. `scriptID`string The ID of the script that the task runs. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. `scriptParameters`object The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. #### Limitations * `scriptParameters` requires `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "cron": "CRON", "description": "DESCRIPTION", "every": "EVERY", "flux": "FLUX", "name": "NAME", "offset": "OFFSET", "org": "ORG", "orgID": "ORGID", "scriptID": "SCRIPTID", "scriptParameters": {}, "status": "active" }' ``` #### Responses 201Success. The response body contains a `tasks` list with the new 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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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 Cloud * Returns this error if the task doesn’t contain one of *`flux`* or *`scriptID`*. * Returns this error if the task contains *`flux`* *and* *`scriptID`*. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of 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/cloud/reference/glossary/#task). #### Parameters ##### Path parameters `taskID`requiredstring A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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](/influxdb/cloud/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or 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. #### InfluxDB Cloud * Use either `flux` or `scriptID` to provide the task script. * `flux`: a string of “raw” Flux that contains task options and the script–for example: ``` { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "status": "active", "description": "This task downsamples CPU data every hour" } ``` * `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body–for example: ``` { "name": "CPU Total 1 Hour New", "description": "This task downsamples CPU data every hour", "every": "1h", "scriptID": "SCRIPT_ID", "scriptParameters": { "rangeStart": "-1h", "bucket": "telegraf", "filterField": "cpu-total" } } ``` #### Limitations: * You can’t use `flux` and `scriptID` for the same task. #### Parameters ##### Path parameters `taskID`requiredstring A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired An task update 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 Update 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. `scriptID`string Update the ‘scriptID’ of the task. `scriptParameters`object Update the ‘scriptParameters’ of the 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 PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/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", "scriptID": "SCRIPTID", "scriptParameters": {}, "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/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. `flux`string \ The Flux script that the task executes. #### Limitations * If you use the `flux` property, you can’t use the `scriptID` and `scriptParameters` properties. `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/cloud/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/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. `orgID`requiredstring An [organization](/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. `ownerID`string A [user](/influxdb/cloud/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. `scriptID`string A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations * If you use the `scriptID` property, you can’t use the `flux` property. #### Related guides * [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) `scriptParameters`object Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations * To use `scriptParameters`, you must provide a `scriptID`. * If you use the `scriptID` and `scriptParameters` properties, you can’t use the `flux` property. `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](/influxdb/cloud/reference/glossary/#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 A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The task and task 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. `beforeTime`string \ A timestamp ([RFC3339 date/time format](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/reference/glossary/#task) ID. Specifies the task to retry. `runID`requiredstring A [task](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/process-data/get-started/) --- # Telegraf Plugins Source: https://docs.influxdata.com/influxdb/cloud/api/telegraf-plugins/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve available Telegraf plugin configuration templates for use with InfluxDB Cloud. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/telegrafs/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage Telegraf agent configurations that collect and write data to InfluxDB Cloud. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/templates/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Export and apply InfluxDB templates, and manage template stacks for InfluxDB Cloud. 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/cloud/influxdb-templates/stacks/). #### Parameters ##### Query parameters `orgID`requiredstring An organization ID. Only returns stacks owned by the specified [organization](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/influxdb-templates/stacks/init/). * [Use InfluxDB templates](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/influxdb-templates/stacks/) of InfluxDB[resources](/influxdb/cloud/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/cloud/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/cloud/influxdb-templates/use/#define-environment-references). * Some templates may contain queries that use[secrets](/influxdb/cloud/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/cloud/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/cloud/influxdb-templates/use/) * [Stacks](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/influxdb-templates/stacks/) * [View stacks](/influxdb/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/influxdb-templates/) --- # Usage Source: https://docs.influxdata.com/influxdb/cloud/api/usage/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Retrieve usage metrics and cardinality data for an InfluxDB Cloud organization. GET`/api/v2/orgs/{orgID}/usage` ### Retrieve usage for an organization #### Parameters ##### Path parameters `orgID`requiredstring The ID of the organization. ##### Query parameters `start`requiredinteger \ Earliest time to include in results. For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). `stop`integer \ Latest time to include in results. For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). `raw`boolean return raw usage data Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/orgs/{orgID}/usage?start=START" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Usage data 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. --- # Users Source: https://docs.influxdata.com/influxdb/cloud/api/users/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) View specific users that are members of your InfluxDB Cloud organization. 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/reference/glossary/#user). To limit which users are returned, pass query parameters in your request. #### InfluxDB Cloud * InfluxDB Cloud doesn’t allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action | Permission required | Restriction | |--------------------|-----------------------------------|----------------------------| | List all users | Operator token |InfluxData internal use only| |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 * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Query parameters `name`string A user name. Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). `id`string A user id. Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response contains a list of `users`. #### InfluxDB Cloud * Returns an empty `users` list if you don’t pass *`id`* or *`name`* parameters and don’t use an*operator token*. Only InfluxData can access InfluxDB Cloud operator tokens. `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 (InfluxData internal use only) Creates and returns a [user](/influxdb/cloud/reference/glossary/#user)that can access InfluxDB. #### InfluxDB Cloud * InfluxDB Cloud Doesn’t let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action |Permission required| Restriction | |-----------|-------------------|----------------------------| |Create user| Operator token |InfluxData internal use only| #### Related guides * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired In the request body, provide the user. Content-Type:`application/json` `id`string `name`requiredstring `org_id`string `role`string Allowed:`owner`, `member` `status`string If inactive the user is inactive. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME", "org_id": "ORG_ID", "role": "owner", "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` 401 Unauthorized. #### InfluxDB Cloud * Returns this error if the request doesn’t use an *operator token*. Only InfluxData can access InfluxDB Cloud operator tokens. `code`requiredstring code is the machine-readable error code. Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type` `err`string Stack of errors that occurred during processing of 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/cloud/reference/glossary/#user). #### Related guides * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Retrieves the specified [user](/influxdb/cloud/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 (InfluxData internal use only) Updates a [user](/influxdb/cloud/reference/glossary/#user) and returns the user. #### InfluxDB Cloud * Doesn’t let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action |Permission required| Restriction | |-----------|-------------------|----------------------------| |Update user| Operator token |InfluxData internal use only| #### Related guides * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Updates the specified [user](/influxdb/cloud/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The user update to apply. Content-Type:`application/json` `id`string `name`requiredstring `org_id`string `role`string Allowed:`owner`, `member` `status`string If inactive the user is inactive. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME", "org_id": "ORG_ID", "role": "owner", "status": "active" }' ``` #### Responses 200Success. The response body contains the updated 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 (InfluxData internal use only) Deletes a [user](/influxdb/cloud/reference/glossary/#user). For security purposes, once an InfluxDB user account is deleted from an organization, the user (and their token) cannot be reactivated. #### InfluxDB Cloud * Doesn’t let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions | Action |Permission required| Restriction | |-----------|-------------------|----------------------------| |Delete user| Operator token |InfluxData internal use only| #### Related guides * [Manage users](/influxdb/cloud/organizations/users/) #### Parameters ##### Path parameters `userID`requiredstring A user ID. Deletes the specified [user](/influxdb/cloud/reference/glossary/#user). ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The user 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. 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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/organizations/users/) | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | List all users | Operator token | InfluxData internal use only | | List a specific user | read-users or read-user USER_ID | | | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | Create user | Operator token | InfluxData internal use only | | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | Update user | Operator token | InfluxData internal use only | | Action | Permission required | Restriction | | --- | --- | --- | | Action | Permission required | Restriction | | Delete user | Operator token | InfluxData internal use only | --- # Variables Source: https://docs.influxdata.com/influxdb/cloud/api/variables/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage variables for use in InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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[] `sort_order`integer `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[] `sort_order`integer `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/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" ], "sort_order": 0, "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[] `sort_order`integer `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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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[] `sort_order`integer `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[] `sort_order`integer `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://us-east-1-1.aws.cloud2.influxdata.com/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" ], "sort_order": 0, "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[] `sort_order`integer `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[] `sort_order`integer `updatedAt`string \ Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/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" ], "sort_order": 0, "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[] `sort_order`integer `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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/api/views/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage cell views within InfluxDB Cloud 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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/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/cloud/api/write/ [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Write time series data to [buckets](/influxdb/cloud/reference/glossary/#bucket). POST`/api/v2/write` ### Write data Writes data to a bucket. Use this endpoint to send data in [line protocol](/influxdb/cloud/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/cloud/write-data/developer-tools/api) * [Optimize writes to InfluxDB](/influxdb/cloud/write-data/best-practices/optimize-writes/) * [Troubleshoot issues writing data](/influxdb/cloud/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/cloud/write-data/troubleshoot/) Allowed values:`application/json` Default:`application/json` #### Request bodyrequired In the request body, provide data in [line protocol format](/influxdb/cloud/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/cloud/write-data/best-practices/optimize-writes/) Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/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/cloud/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 Cloud Source: https://docs.influxdata.com/influxdb/cloud/get-started/ InfluxDB Cloud 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 Cloud, 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/cloud/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 values, and field key*. ##### 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 | | \_time |\_measurement| city |country|\_field |\_value| |:-------------------|:------------|:-----|:------|:-------|------:| |2022-01-01T12:00:00Z| weather |London| UK |humidity| 88.4 | |2022-02-01T12:00:00Z| weather |London| UK |humidity| 94.0 | |2022-03-01T12:00:00Z| weather |London| UK |humidity| 82.1 | |2022-04-01T12:00:00Z| weather |London| UK |humidity| 87.6 | | \_time |\_measurement| city |country|\_field |\_value| |:-------------------|:------------|:------|:------|:-------|------:| |2022-01-01T12:00:00Z| weather |Cologne| DE |humidity| 88.5 | |2022-02-01T12:00:00Z| weather |Cologne| DE |humidity| 87.8 | |2022-03-01T12:00:00Z| weather |Cologne| DE |humidity| 76.4 | |2022-04-01T12:00:00Z| weather |Cologne| DE |humidity| 93.3 | ## Tools to use Throughout this tutorial, there are multiple tools you can use to interact with InfluxDB Cloud. 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. To access the InfluxDB Cloud UI, [log into your InfluxDB Cloud account](https://cloud2.influxdata.com). ### `influx` CLI The `influx` CLI lets you interact with and manage InfluxDB Cloud from a command line. For detailed CLI installation instructions, see[Use the influx CLI](/influxdb/cloud/tools/influx-cli/). ### InfluxDB HTTP API The [InfluxDB API](/influxdb/cloud/reference/api/) provides a simple way to interact with the InfluxDB Cloud 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/cloud/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 Cloud requires authentication** using [API tokens](/influxdb/cloud/admin/tokens/). Each API token is associated with a user and a specific set of permissions for InfluxDB resources. [Set up InfluxDB](/influxdb/cloud/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/cloud/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 | | _time | _measurement | city | country | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | city | country | _field | _value | | 2022-01-01T12:00:00Z | weather | London | UK | humidity | 88.4 | | 2022-02-01T12:00:00Z | weather | London | UK | humidity | 94.0 | | 2022-03-01T12:00:00Z | weather | London | UK | humidity | 82.1 | | 2022-04-01T12:00:00Z | weather | London | UK | humidity | 87.6 | | _time | _measurement | city | country | _field | _value | | --- | --- | --- | --- | --- | --- | | _time | _measurement | city | country | _field | _value | | 2022-01-01T12:00:00Z | weather | Cologne | DE | humidity | 88.5 | | 2022-02-01T12:00:00Z | weather | Cologne | DE | humidity | 87.8 | | 2022-03-01T12:00:00Z | weather | Cologne | DE | humidity | 76.4 | | 2022-04-01T12:00:00Z | weather | Cologne | DE | humidity | 93.3 | --- # Get started processing data Source: https://docs.influxdata.com/influxdb/cloud/get-started/process/ * 4 / 5 Now that you know the [basics of querying data from InfluxDB](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/get-started/query/)[Visualize data](/influxdb/cloud/get-started/visualize/) #### Related * [Process data with InfluxDB tasks](/influxdb/cloud/process-data/) * [Get started with InfluxDB tasks](/influxdb/cloud/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/cloud/get-started/query/ * 3 / 5 InfluxDB supports many different tools for querying data, including: * InfluxDB user interface (UI) * [InfluxDB HTTP API](/influxdb/cloud/reference/api/) * [`influx` CLI](/influxdb/cloud/tools/influx-cli/) * [Chronograf](/chronograf/v1/) * [Grafana](/influxdb/cloud/tools/grafana/) * [InfluxDB client libraries](/influxdb/cloud/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/cloud/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/cloud/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 [cloud2.influxdata.com](https://cloud2.influxdata.com) 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/cloud/tools/influx-cli/). 2. Use the [`influx query` command](/influxdb/cloud/reference/cli/influx/query/)to query InfluxDB using Flux. **Provide the following**: * String-encoded Flux query. * [Connection and authentication credentials](/influxdb/cloud/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/cloud/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/cloud/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/cloud/get-started/#data-organization) in InfluxDB Cloud. > To use InfluxQL with InfluxDB Cloud, first[map database and retention policy (DBRP) combinations to an InfluxDB bucket](/influxdb/cloud/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/cloud/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 Cloud 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/cloud/tools/chronograf/) or[Grafana](/influxdb/cloud/tools/grafana/) with InfluxDB Cloud. > [!Note] > #### Authentication credentials > > The examples below assume your InfluxDB **host**, **organization**, and **token** are > provided by either the [active `influx` CLI configuration](/influxdb/cloud/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/cloud/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/cloud/tools/influx-cli/). 2. Use the [`influx v1 shell` command](/influxdb/cloud/reference/cli/influx/v1/shell/)to start an InfluxQL shell and query InfluxDB using InfluxQL. Provide the following: * [Connection and authentication credentials](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#unix-timestamp) of a specified precision instead of [RFC3339 timestamps](/influxdb/cloud/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/cloud/query-data/) section of documentation. Let’s move on to more advanced data processing queries and automating queries with InfluxDB tasks. [Write data](/influxdb/cloud/get-started/write/)[Process data](/influxdb/cloud/get-started/process/) #### Related * [Query data in InfluxDB](/influxdb/cloud/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/cloud/get-started/setup/ * 1 / 5 As you get started with this tutorial, do the following to make sure everything you need is in place. 1. (Optional) **Download, install, and configure the `influx` CLI**. The `influx` CLI provides a simple way to interact with InfluxDB from a command line. For detailed installation and setup instructions, see [Use the influx CLI](/influxdb/cloud/tools/influx-cli/). 2. **Create an All-Access API token.** 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 [cloud2.influxdata.com](https://cloud2.influxdata.com) 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/cloud/tools/influx-cli/). 2. Use the [`influx auth create` command](/influxdb/cloud/reference/cli/influx/auth/create/)to create an All-Access token. **Provide the following**: * `--all-access` flag * `--host` flag with your [InfluxDB region URL](/influxdb/cloud/reference/regions/) * `-o, --org` or `--org-id` flags with your InfluxDB organization name or[ID](/influxdb/cloud/admin/organizations/view-orgs/#view-your-organization-id) * `-t, --token` flag with your Operator token ``` influx auth create \ --all-access \ --host http://cloud2.influxdata.com \ --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://cloud2.influxdata.com/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/cloud/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/cloud/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/cloud/api/resources/).* The following example uses cURL and the InfluxDB API to generate an All-Access token: ``` export INFLUX_HOST=http://cloud2.influxdata.com 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 Cloud require your InfluxDB **host**, **organization name or ID**, and your **API token**. There are different methods for providing these credentials depending on which client you use to interact with InfluxDB. > [!Note] > When configuring your token, use the [All-Access token you created](#create-an-all-access-api-token). [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. Use the [`influx config create` command](/influxdb/cloud/reference/cli/influx/config/create/)to create a new CLI connection configuration. Include the following flags: * `-n, --config-name`: Connection configuration name. This examples uses `get-started`. * `-u, --host-url`: [InfluxDB region URL](/influxdb/cloud/reference/regions/). * `-o, --org`: InfluxDB organization name. * `-t, --token`: InfluxDB API token. ``` influx config create \ --config-name get-started \ --host-url http://cloud2.influxdata.com \ --org \ --token ``` *For more information about CLI connection configurations, see[Install and use the `influx` CLI](/influxdb/cloud/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 region URL](/influxdb/cloud/reference/urls/). * `INFLUX_ORG`: InfluxDB organization name. * `INFLUX_ORG_ID`: InfluxDB [organization ID](/influxdb/cloud/admin/organizations/view-orgs/#view-your-organization-id). * `INFLUX_TOKEN`: InfluxDB API token. ``` export INFLUX_HOST=http://cloud2.influxdata.com export INFLUX_ORG= export INFLUX_ORG_ID= export INFLUX_TOKEN= ``` [](#command-flags) Command flags Use the following `influx` CLI flags to provide required credentials to commands: * `--host`: [InfluxDB region URL](/influxdb/cloud/reference/regions/). * `-o`, `--org` or `--org-id`: InfluxDB organization name or[ID](/influxdb/cloud/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/cloud/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**: Your [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/). * **InfluxDB API Token**: Include an `Authorization` header that uses either`Bearer` or `Token` scheme and your InfluxDB API token. 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://cloud2.influxdata.com export INFLUX_ORG= export INFLUX_ORG_ID= export INFLUX_TOKEN= ``` 4. **Create a bucket**. 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 [cloud2.influxdata.com](https://cloud2.influxdata.com) 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/cloud/reference/glossary/#retention-period). 5. Click **Create**. 1. If you haven’t already, [download, install, and configure the `influx` CLI](/influxdb/cloud/tools/influx-cli/). 2. Use the [`influx bucket create` command](/influxdb/cloud/reference/cli/influx/bucket/create/)to create a new 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://cloud2.influxdata.com/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. ``` export INFLUX_HOST=http://cloud2.influxdata.com 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/cloud/get-started/)[Write data](/influxdb/cloud/get-started/write/) #### Related * [Manage API tokens](/influxdb/cloud/admin/tokens/) * [Install and use the influx CLI](/influxdb/cloud/tools/influx-cli/) --- # Get started visualizing data Source: https://docs.influxdata.com/influxdb/cloud/get-started/visualize/ * 5 / 5 There are many tools you can use to visualize your time series data including the InfluxDB user interface (UI), [Chronograf](/influxdb/cloud/tools/chronograf/), and[Grafana](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/visualize-data/variables/).* [Process data](/influxdb/cloud/get-started/process/) ## Congratulations! You have walked through the[basics of setting up, writing, querying, processing, and visualizing](/influxdb/cloud/get-started/)data with InfluxDB Cloud. Feel free to dive in deeper to each of these topics: * [Write data to InfluxDB](/influxdb/cloud/write-data/) * [Query data in InfluxDB](/influxdb/cloud/query-data/) * [Process data with InfluxDB](/influxdb/cloud/process-data/) * [Visualize data with the InfluxDB UI](/influxdb/cloud/visualize-data/) #### Related * [Visualize data with the InfluxDB UI](/influxdb/cloud/visualize-data/) * [Visualization types](/influxdb/cloud/visualize-data/visualization-types/) * [Use Chronograf with InfluxDB Cloud](/influxdb/cloud/tools/chronograf/) * [Use Grafana with InfluxDB Cloud](/influxdb/cloud/tools/grafana/) --- # Get started writing data Source: https://docs.influxdata.com/influxdb/cloud/get-started/write/ * 2 / 5 InfluxDB provides many different options for ingesting or writing data, including the following: * Influx user interface (UI) * [InfluxDB HTTP API](/influxdb/cloud/reference/api/) * [`influx` CLI](/influxdb/cloud/tools/influx-cli/) * [Telegraf](/telegraf/v1/) * [InfluxDB client libraries](/influxdb/cloud/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/cloud/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/cloud/reference/syntax/line-protocol/#string) (quoted),[floats](/influxdb/cloud/reference/syntax/line-protocol/#float),[integers](/influxdb/cloud/reference/syntax/line-protocol/#integer),[unsigned integers](/influxdb/cloud/reference/syntax/line-protocol/#uinteger), or [booleans](/influxdb/cloud/reference/syntax/line-protocol/#boolean). * **timestamp**: [Unix timestamp](/influxdb/cloud/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/cloud/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 [cloud2.influxdata.com](https://cloud2.influxdata.com) 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/cloud/tools/influx-cli/). 2. Use the [`influx write` command](/influxdb/cloud/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/cloud/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/cloud/write-data/no-code/) * [Write data to InfluxDB using developer tools](/influxdb/cloud/write-data/developer-tools/) With data now stored in InfluxDB, let’s query it. [Set up InfluxDB](/influxdb/cloud/get-started/setup/)[Query data](/influxdb/cloud/get-started/query/) #### Related * [Write data to InfluxDB](/influxdb/cloud/write-data/) * [Best practices for writing data](/influxdb/cloud/write-data/best-practices/) * [Line protocol](/influxdb/cloud/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 | --- # Migrate to an account in a new region Source: https://docs.influxdata.com/influxdb/cloud/migrate-regions/ The following guide provides instructions on migrating data and resources from an existing InfluxDB Cloud account to a new InfluxDB account in another InfluxDB Cloud region. ## Create a new account in a new region InfluxDB organizations are bound to a specific cloud provider and region.[Create a new InfluxDB Cloud account](/influxdb/cloud/sign-up/) in the region you want to migrate to. ## Migrate Data If you want to migrate data from your current InfluxDB Cloud account to your new destination InfluxDB Cloud account, there is documentation available that walks through the migration. The specific process varies depending on whether your destination account is powered by our current database engine,[Time-Structured Merge Tree (TSM)](/influxdb/v2/reference/internals/storage-engine/#time-structured-merge-tree-tsm)or [our new database engine, InfluxDB 3](/blog/announcing-general-availability-new-database-engine/). To benefit from the InfluxDB 3 storage engine’s unlimited cardinality and support for SQL, migrate your data to InfluxDB Cloud Serverless. * [Migrate data TSM to Serverless](/influxdb3/cloud-serverless/write-data/migrate-data/migrate-tsm-to-serverless/) * [Migrate data from TSM to TSM](/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud/). To see which storage engine your organization uses, find the **InfluxDB Cloud powered by**link in your [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com)version information. If your organization is using TSM, you’ll see **TSM**followed by the version number. If Serverless, you’ll see **InfluxDB Cloud Serverless**followed by the version number. > [!Note] > #### Dual write into both organizations > > Depending on the duration of your retention policy for storing data it may be > easier to temporarily dual write into both the source and destination accounts > for an overlapping period until the destination account holds all desired data. ## Migrate Resources Resources include, but are not limited to the following: * buckets * dashboards * notification rules * tasks * labels * variables If you have resources that you want to migrate to your destination account (rather than recreating these resources in the destination account) you can do the following: 1. [Download and install the 2.x `influx` CLI](/influxdb/cloud/tools/influx-cli/). 2. [Set up InfluxDB connection configurations](/influxdb/cloud/tools/influx-cli/#provide-required-authentication-credentials)for both your **source** and **destination** InfluxDB Cloud accounts. Use the [`influx config create` command](/influxdb/cloud/reference/cli/influx/config/create/)and provide the following for each connection: * Connection configuration name * [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) * [InfluxDB organization name](/influxdb/cloud/admin/organizations/) * [InfluxDB API token](/influxdb/cloud/admin/tokens/) ``` # Create your source connection configuration and set it to active $ influx config create \ --config-name source \ --host-url https://cloud2.influxdata.com \ --org \ --token \ --active # Create your destination connection configuration $ influx config create \ --config-name destination \ --host-url https://cloud2.influxdata.com \ --org \ --token ``` 3. Use the [`influx export all` command](/influxdb/cloud/reference/cli/influx/export/all/#export-all-resources-in-an-organization-as-a-template)to export all resources from your **source account** to an[InfluxDB template](/influxdb/cloud/tools/influxdb-templates/use/). ``` influx export all ``` 4. Use the [`influx config` command](/influxdb/cloud/reference/cli/influx/config/)to switch to your **destination** connection configuration. Provide the name of the configuration to switch to: ``` influx config destination ``` 5. Use [`influx template apply` command](/influxdb/cloud/reference/cli/influx/apply/#apply-a-template-from-a-file)to apply the exported InfluxDB template created in the previous step to your destination account: ``` influx apply --file path/to/template.json ``` --- # Monitor data and send alerts Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/ Monitor your time series data and send alerts by creating checks, notification rules, and notification endpoints. Or use [community templates to monitor](/influxdb/cloud/monitor-alert/templates/) supported environments. ## Overview 1. A [check](/influxdb/cloud/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/cloud/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/cloud/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/cloud/monitor-alert/checks/create/) to monitor data and assign a status. 2. [Add notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/create/)to send notifications to third parties. 3. [Create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create) to check statuses and send notifications to your notifications endpoints. ## Manage your monitoring and alerting pipeline ### [Manage checks](/influxdb/cloud/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/cloud/monitor-alert/notification-endpoints/) Create, read, update, and delete endpoints in the InfluxDB UI. ### [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) Manage notification rules in InfluxDB. ### [Monitor with templates](/influxdb/cloud/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/cloud/monitor-alert/send-email/) Send an alert email. ### [Create custom checks](/influxdb/cloud/monitor-alert/custom-checks/) Create custom checks with a Flux task. [monitor](/influxdb/cloud/tags/monitor/)[alert](/influxdb/cloud/tags/alert/)[checks](/influxdb/cloud/tags/checks/)[notification](/influxdb/cloud/tags/notification/)[endpoints](/influxdb/cloud/tags/endpoints/) --- # Manage checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/checks/ 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/cloud/monitor-alert/checks/create/) Create a check in the InfluxDB UI. ### [View checks](/influxdb/cloud/monitor-alert/checks/view/) View check details and statuses and notifications generated by checks in the InfluxDB UI. ### [Update checks](/influxdb/cloud/monitor-alert/checks/update/) Update, rename, enable or disable checks in the InfluxDB UI. ### [Delete checks](/influxdb/cloud/monitor-alert/checks/delete/) Delete checks in the InfluxDB UI. #### Related * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) [monitor](/influxdb/cloud/tags/monitor/)[checks](/influxdb/cloud/tags/checks/)[notifications](/influxdb/cloud/tags/notifications/)[alert](/influxdb/cloud/tags/alert/) --- # Create checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/checks/create/ 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/cloud/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/cloud/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Delete checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/checks/delete/ 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/cloud/monitor-alert/checks/update/#enable-or-disable-a-check)without having to delete it. #### Related * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Update checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/checks/update/ 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/cloud/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/cloud/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # View checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/checks/view/ 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/cloud/monitor-alert/notification-rules/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Create custom checks Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/custom-checks/ In the UI, you can create two kinds of [checks](/influxdb/cloud/reference/glossary/#check):[`threshold`](/influxdb/cloud/monitor-alert/checks/create/#threshold-check) and[`deadman`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/monitor-alert/notification-endpoints/create),[Create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create), > and [Send alert email](/influxdb/cloud/monitor-alert/send-email/) [alerts](/influxdb/cloud/tags/alerts/)[checks](/influxdb/cloud/tags/checks/)[tasks](/influxdb/cloud/tags/tasks/)[Flux](/influxdb/cloud/tags/flux/) --- # Manage notification endpoints Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-endpoints/ Notification endpoints store information to connect to a third party service. If you’re using the Free Plan, create a Slack endpoint. If you’re using the Usage-based Plan, create a connection to a HTTP, Slack, or PagerDuty endpoint. ### [Create notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/create/) Create notification endpoints to send alerts on your time series data. ### [View notification endpoint history](/influxdb/cloud/monitor-alert/notification-endpoints/view/) View notification endpoint details and history in the InfluxDB UI. ### [Update notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/update/) Update notification endpoints in the InfluxDB UI. ### [Delete notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/delete/) Delete a notification endpoint in the InfluxDB UI. #### Related * [Manage checks](/influxdb/cloud/monitor-alert/checks/) * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) [monitor](/influxdb/cloud/tags/monitor/)[endpoints](/influxdb/cloud/tags/endpoints/)[notifications](/influxdb/cloud/tags/notifications/)[alert](/influxdb/cloud/tags/alert/) --- # Create notification endpoints Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-endpoints/create/ 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/cloud/monitor-alert/notification-rules/create) to send alerts to third-party services on [check statuses](/influxdb/cloud/monitor-alert/checks/create). #### Endpoints available in InfluxDB Cloud The following endpoints are available for the InfluxDB Cloud Free Plan and Usage-based Plan: | Endpoint |Free Plan|Usage-based Plan| |-------------|---------|----------------| | **Slack** | **✓** | **✓** | |**PagerDuty**| | **✓** | | **HTTP** | | **✓** | ## 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.*See [available endpoints](#endpoints-available-in-influxdb-cloud).* 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/cloud/monitor-alert/checks/) * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) | Endpoint | Free Plan | Usage-based Plan | | --- | --- | --- | | Endpoint | Free Plan | Usage-based Plan | | Slack | ✓ | ✓ | | PagerDuty | | ✓ | | HTTP | | ✓ | --- # Delete notification endpoints Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-endpoints/delete/ If notifications are no longer sent to an endpoint, complete the steps below to delete the endpoint, and then [update notification rules](/influxdb/cloud/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/cloud/monitor-alert/checks/) * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) --- # Update notification endpoints Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-endpoints/update/ Complete the following steps to update notification endpoint details. To update the notification endpoint selected for a notification rule, see [update notification rules](/influxdb/cloud/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/cloud/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/cloud/monitor-alert/checks/) * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) --- # View notification endpoint history Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-endpoints/view/ 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/cloud/monitor-alert/checks/) * [Manage notification rules](/influxdb/cloud/monitor-alert/notification-rules/) --- # Manage notification rules Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-rules/ The following articles provide information on managing your notification rules: ### [Create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create/) Create notification rules to send alerts on your time series data. ### [View notification rules](/influxdb/cloud/monitor-alert/notification-rules/view/) Update notification rules to update the notification message or change the schedule or conditions. ### [Update notification rules](/influxdb/cloud/monitor-alert/notification-rules/update/) Update notification rules to update the notification message or change the schedule or conditions. ### [Delete notification rules](/influxdb/cloud/monitor-alert/notification-rules/delete/) If you no longer need to receive an alert, delete the associated notification rule. #### Related * [Manage checks](/influxdb/cloud/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) [monitor](/influxdb/cloud/tags/monitor/)[notifications](/influxdb/cloud/tags/notifications/)[alert](/influxdb/cloud/tags/alert/) --- # Create notification rules Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-rules/create/ Once you’ve set up checks and notification endpoints, create notification rules to alert you.*For details, see [Manage checks](/influxdb/cloud/monitor-alert/checks/) and[Manage notification endpoints](/influxdb/cloud/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/cloud/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Delete notification rules Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-rules/delete/ 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/cloud/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Update notification rules Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-rules/update/ 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/cloud/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # View notification rules Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/notification-rules/view/ 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/cloud/monitor-alert/checks/) * [Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/) --- # Send alert email Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/send-email/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/monitor-alert/checks/) [alert](/influxdb/cloud/tags/alert/)[email](/influxdb/cloud/tags/email/)[notifications](/influxdb/cloud/tags/notifications/)[check](/influxdb/cloud/tags/check/) --- # Monitor with templates Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/templates/ 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/cloud/monitor-alert/templates/monitor/) Monitor your InfluxDB OSS instance using InfluxDB Cloud and a pre-built InfluxDB template. ### [Monitor infrastructure](/influxdb/cloud/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/cloud/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/cloud/tags/monitor/)[templates](/influxdb/cloud/tags/templates/) --- # Monitor infrastructure Source: https://docs.influxdata.com/influxdb/cloud/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 Amazon Web Services (AWS)](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/tags/monitor/)[templates](/influxdb/cloud/tags/templates/)[infrastructure](/influxdb/cloud/tags/infrastructure/) --- # Monitor Amazon Web Services (AWS) Source: https://docs.influxdata.com/influxdb/cloud/monitor-alert/templates/infrastructure/aws/ 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/cloud/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/cloud/reference/glossary/#bucket): `kubernetes` and `cloudwatch` * two labels: `inputs.cloudwatch`, `AWS` * one variable: `v.bucket` * one [Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/): [AWS CloudWatch input plugin](/telegraf/v1/plugins//#cloudwatch) ## Apply the template 1. Use the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/monitor-alert/templates/infrastructure/docker/ 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/cloud/reference/glossary/#dashboard): **Docker** * one [bucket](/influxdb/cloud/reference/glossary/#bucket): `docker, 7d retention` * labels: Docker input plugin labels * one [Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/): Docker input plugin * one variable: `bucket` * four [checks](/influxdb/cloud/reference/glossary/#check): `Container cpu`, `mem`, `disk`, `non-zero exit` * one [notification endpoint](/influxdb/cloud/reference/glossary/#notification-endpoint): `Http Post` * one [notification rule](/influxdb/cloud/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/cloud/monitor-alert/). ## Apply the template 1. Use the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/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/cloud/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/admin/organizations/view-orgs/). * INFLUX\_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/cloud/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/cloud/monitor-alert/templates/infrastructure/raspberry-pi/ 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/cloud/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/cloud/tools/telegraf-configs/) * one [dashboard](/influxdb/cloud/reference/glossary/#dashboard): Raspberry Pi System * two variables: `bucket` and `linux_host` ## Apply the template 1. Use the [`influx` CLI](/influxdb/cloud/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/cloud/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 Cloud API](/influxdb/cloud/reference/api/). 3. Add the following environment variables to your Telegraf environment: * `INFLUX_HOST`: Your [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) * `INFLUX_TOKEN`: Your [InfluxDB Cloud API token](/influxdb/cloud/admin/tokens/) * `INFLUX_ORG`: Your InfluxDB Cloud organization name. ``` export INFLUX_HOST=http://localhost:8086 export INFLUX_TOKEN=mY5uP3rS3cr3T70keN export INFLUX_ORG=example-org ``` 4. [Start Telegraf](/influxdb/cloud/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/cloud/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. 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/cloud/reference/glossary/#dashboard): **vsphere** * one [bucket](/influxdb/cloud/reference/glossary/#bucket): `vsphere` * label: vsphere * one [Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/): InfluxDB v2 output plugin, vSphere input plugin * one variable: `bucket` ## Apply the template 1. Use the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/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/cloud/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/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/cloud/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/cloud/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. 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/cloud/reference/glossary/#dashboard): **Windows System** * one [bucket](/influxdb/cloud/reference/glossary/#bucket): `telegraf`, 7d retention * label: `Windows System Template`, Telegraf plugin labels: `outputs.influxdb_v2` * one [Telegraf configuration](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/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/cloud/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/admin/organizations/view-orgs/). * INFLUX\_URL: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/cloud/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/cloud/monitor-alert/templates/monitor/ 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/cloud/tags/templates/)[monitor](/influxdb/cloud/tags/monitor/) --- # Monitor networks Source: https://docs.influxdata.com/influxdb/cloud/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 HAProxy](/influxdb/cloud/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/cloud/tags/monitor/)[templates](/influxdb/cloud/tags/templates/)[networks](/influxdb/cloud/tags/networks/)[networking](/influxdb/cloud/tags/networking/) --- # Monitor HAProxy Source: https://docs.influxdata.com/influxdb/cloud/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 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/cloud/reference/glossary/#dashboard): **HAProxy** * one [bucket](/influxdb/cloud/reference/glossary/#bucket): `haproxy` * label: `haproxy` * one [Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/): HAProxy input plugin, InfluxDB v2 output plugin * one variable: `bucket` ## Apply the template 1. Use the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/api/). 3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/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/cloud/admin/tokens/view-tokens/). * INFLUX\_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/admin/organizations/view-orgs/). * INFLUX\_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. 4. [Start Telegraf](/influxdb/cloud/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/cloud/process-data/ 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) and the `influx` command line interface (CLI). Find examples of data downsampling, anomaly detection *(Coming)*, alerting*(Coming)*, and other common tasks. > [!Note] > Tasks replace InfluxDB v1.x continuous queries. ### [Get started with tasks](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/tags/tasks/) --- # Common data processing tasks Source: https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/ The following articles walk through common task use cases. ### [Downsample data with InfluxDB](/influxdb/cloud/process-data/common-tasks/downsample-data/) How to create a task that downsamples data much like continuous queries in previous versions of InfluxDB. ### [Downsample data with Python and Quix Streams](/influxdb/cloud/process-data/common-tasks/downsample-data-quix/) Use Quix Streams to create a Python service that downsamples data stored in InfluxDB. > [!Note] > This list will continue to grow. > If you have suggestions, please [submit them to the InfluxData Community](https://community.influxdata.com/c/influxdb2). [tasks](/influxdb/cloud/tags/tasks/) --- # Downsample data with Python and Quix Streams Source: https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/downsample-data-quix/ Use [Quix Streams](https://github.com/quixio/quix-streams) to query time series data stored in InfluxDB and written to Kafka at regular intervals, continuously downsample it, and then write the downsampled data back to InfluxDB. Quix Streams is an open source Python library for building containerized stream processing applications with Apache Kafka. It is designed to run as a service that continuously processes a stream of data while streaming the results to a Kafka topic. You can try it locally, with a local Kafka installation, or run it in [Quix Cloud](https://quix.io/) with a free trial. 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 and then downsample and publish the data to another InfluxDB v2 bucket. By aggregating data within windows of time and 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` (Quixstreams 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/cloud/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 Cloud (TSM) region URL](/influxdb/cloud/reference/regions)*(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 Cloud (TSM) region URL](/influxdb/cloud/reference/regions)*(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=influx_host, token=influx_token, org=influx_org) ## ... 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. --- # Downsample data with InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/downsample-data/ 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/cloud/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/cloud/tags/tasks/) --- # Get started with InfluxDB tasks Source: https://docs.influxdata.com/influxdb/cloud/process-data/get-started/ 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/cloud/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/cloud/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. ### Task options for invokable scripts Use the InfluxDB Cloud API to create tasks that reference and run [invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). When you create or update the task, pass task options as properties in the request body–for example: ```json { "name": "30-day-avg-temp", "description": "IoT Center 30d environment average.", "every": "1d", "offset": "0m" } ``` To learn more about creating tasks that run invokable scripts, see how to [create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). ## 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 Cloud . 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/cloud/process-data/common-tasks) for examples of tasks commonly used with InfluxDB.* ### Process data with invokable scripts In InfluxDB Cloud, you can create tasks that run invokable scripts. You can use invokable scripts to manage and reuse scripts for your organization. You can use tasks to schedule script runs with options and parameters. The following sample `POST /api/v2/scripts` request body defines a new invokable script with the Flux from the previous example: ```text { "name": "aggregate-intervals", "description": "Group points into 5 minute windows and calculate the average of each window.", "script": "from(bucket: "example-bucket")\ |> range(start: -task.every)\ |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost")\ |> aggregateWindow(every: 5m, fn: mean)", "language": "flux" } ``` Note that the script doesn’t contain task options. Once you create the invokable script, you can use `POST /api/v2/tasks` to create a task that runs the script. The following sample request body defines a task with the script ID and options: ```json { "every": "1h", "description": "Downsample host with 5 min precision.", "name": "downsample_5m_precision", "scriptID": "09b2136232083000" } ``` To create a script and a task that use parameters, see how to [create a task to run an invokable script](/influxdb/cloud/process-data/manage-tasks/create-task/). ## 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") ``` ## Full example task with invokable script The following sample code combines the components described in this guide into a `POST /api/v2/scripts` request body. The Flux for the `script` field: ```js 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") ``` The full request body, with the script encoded as a JSON string (inner quotes escaped as `\"`, line breaks as `\n`): ```json { "name": "aggregate-intervals-and-export", "description": "Group points into 5 minute windows and calculate the average of each window.", "script": "from(bucket: \"example-bucket\")\n |> range(start: -task.every)\n |> filter(fn: (r) => r._measurement == \"mem\" and r.host == \"myHost\")\n // Data processing\n |> aggregateWindow(every: 5m, fn: mean)\n // Data destination\n |> to(bucket: \"example-downsampled\")", "language": "flux" } ``` The following sample code shows a `POST /api/v2/tasks` request body to schedule the script: ```json { "every": "1h", "description": "Downsample host with 5 min precision.", "name": "downsample_5m_precision", "scriptID": "SCRIPT_ID" } ``` To learn more about InfluxDB tasks and how they work, watch the following video: #### Related * [Manage tasks in InfluxDB](/influxdb/cloud/process-data/manage-tasks/) * [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task/) * [Tasks & InfluxDB](/resources/videos/influxdb-tasks/) [tasks](/influxdb/cloud/tags/tasks/) --- # Manage tasks in InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/ 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/cloud/process-data/manage-tasks/create-task/) Create a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. ### [View tasks](/influxdb/cloud/process-data/manage-tasks/view-tasks/) View existing data processing tasks using the InfluxDB UI or the `influx` CLI. ### [Run a task](/influxdb/cloud/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/cloud/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/cloud/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/cloud/process-data/manage-tasks/export-task/) Export a data processing task from InfluxDB using the InfluxDB UI. ### [Delete a task](/influxdb/cloud/process-data/manage-tasks/delete-task/) Delete a task from InfluxDB using the InfluxDB UI or the `influx` CLI. [tasks](/influxdb/cloud/tags/tasks/) --- # Create a task Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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 An InfluxDB Cloud task can run either an [invokable script](/influxdb/cloud/api-guide/api-invokable-scripts/) or raw Flux stored in the task. * [Create a task that references a script](#create-a-task-that-references-a-script) * [Create a task that contains a Flux script](#create-a-task-that-contains-a-flux-script) ### Create a task that references a script With InfluxDB Cloud invokable scripts, you can manage, reuse, and invoke scripts as API endpoints. You can use tasks to pass script parameters and schedule runs. Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/cloud/api/tasks/) to create a task that references a script ID. ``` 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: * **cron** or **every**: task schedule * **name**: task name * **scriptID**: [invokable script](/influxdb/cloud/api-guide/api-invokable-scripts/) ID ```sh curl --request POST 'https://cloud2.influxdata.com/api/v2/tasks' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' \ "cron": "0 * * * *", "name": "downsample cpu", "scriptID": "085a2960eaa20000", "description": "This task downsamples CPU data every hour" }' ``` To create a task that passes parameters when invoking the script, pass the *`scriptParameters`*property in the request body. The following sample code creates a script with parameters, and then creates a task to run the new script daily: ```sh SCRIPT_ID=$( curl https://cloud2.influxdata.com/api/v2/scripts \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-binary @- << EOF | jq -r '.id' { "name": "filter-and-group19", "description": "Returns filtered and grouped points from a bucket.", "script": "from(bucket: params.bucket)\ |> range(start: duration(v: params.rangeStart))\ |> filter(fn: (r) => r._field == params.filterField)\ |> group(columns: [params.groupColumn])", "language": "flux" } EOF ) echo $SCRIPT_ID curl https://cloud2.influxdata.com/api/v2/tasks \ --header "Content-type: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data @- << EOF { "name": "30-day-avg-temp", "description": "IoT Center 30d temperature average.", "every": "1d", "scriptID": "${SCRIPT_ID}", "scriptParameters": { "rangeStart": "-30d", "bucket": "air_sensor", "filterField": "temperature", "groupColumn": "_time" } } EOF ``` Replace **`INFLUX_API_TOKEN`** with your InfluxDB API token. ### Create a task that contains a Flux script Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/cloud/api/tasks/) to create a task that contains a Flux script with task options. ``` POST https://cloud2.influxdata.com/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 [`options`](/flux/v0/spec/options/) and the query. * **status**: task status (“active” or “inactive”) * **description**: task description ```sh curl --request POST 'https://cloud2.influxdata.com/api/v2/tasks' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --data-binary @- << EOF { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "orgID": "INFLUX_ORG_ID", "status": "active", "description": "This task downsamples CPU data every hour" } EOF ``` Replace the following: * **`INFLUX_API_TOKEN`**: your InfluxDB [API token](/influxdb/cloud/admin/tokens/view-tokens/) * **`INFLUX_ORG`**: your InfluxDB organization name * **`INFLUX_ORG_ID`**: your InfluxDB organization ID #### Related * [influx task create](/influxdb/cloud/reference/cli/influx/task/create/) --- # Delete a task Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/delete-task/ ## 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/cloud/process-data/manage-tasks/view-tasks/)* ## Delete a task using the InfluxDB API Use the [`/tasks/TASK_ID` InfluxDB API endpoint](/influxdb/cloud/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/cloud/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/cloud/process-data/manage-tasks/update-task/) to `inactive`. #### Related * [influx task delete](/influxdb/cloud/reference/cli/influx/task/delete/) --- # Export a task Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/export-task/ 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/cloud/process-data/manage-tasks/run-task/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/task/run/) --- # View task run history and logs Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/task-run-history/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/process-data/manage-tasks/run-task/). #### Related --- # Update a task Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/update-task/ ## 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/task/update/) --- # View tasks Source: https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/view-tasks/ ## View tasks in the InfluxDB UI Click the **Tasks** icon in the left navigation to view the lists of tasks. 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 created 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/cloud/reference/cli/influx/task/list)for information about other available flags. #### Related * [influx task list](/influxdb/cloud/reference/cli/influx/task/list/) --- # Task configuration options Source: https://docs.influxdata.com/influxdb/cloud/process-data/task-options/ Task options define specific information about a task. They are set in a Flux script , in the InfluxDB API, 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", // ... } ``` In a `/api/v2/tasks` request body with `scriptID`: ```json { "scriptID": "SCRIPT_ID", "name": "TASK_NAME" } ``` Replace `SCRIPT_ID` with the ID of your InfluxDB invokable script. ## 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, } ``` In a `/api/v2/tasks` request body with `scriptID`: ```json { "scriptID": "SCRIPT_ID", "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 * * * *", } ``` In a `/api/v2/tasks` request body with `scriptID`: ```json { "scriptID": "SCRIPT_ID", "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, } ``` In a `/api/v2/tasks` request body with `scriptID`: ```json { "scriptID": "SCRIPT_ID", "offset": "10m" } ``` [tasks](/influxdb/cloud/tags/tasks/)[flux](/influxdb/cloud/tags/flux/) --- # Query data in InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/query-data/ 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](/influxdb/cloud/query-data/get-started/) Get started with Flux, InfluxData’s functional data scripting language. This step-by-step guide through the basics of writing a Flux query. ### [Query data with Flux](/influxdb/cloud/query-data/flux/) Guides that walk through both common and complex queries and use cases for Flux. ### [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) Use the [InfluxDB 1.x `/query` compatibility endpoint](/influxdb/cloud/reference/api/influxdb-1x/query) to query data in InfluxDB Cloud and InfluxDB OSS 2.4 with **InfluxQL**. ### [Execute queries](/influxdb/cloud/query-data/execute-queries/) There are multiple ways to query data from InfluxDB including the InfluxDB UI, CLI, and API. ### [Common queries](/influxdb/cloud/query-data/common-queries/) This collection of articles walks through common use cases for Flux queries. ### [Optimize Flux queries](/influxdb/cloud/query-data/optimize-queries/) Optimize your Flux queries to reduce their memory and compute (CPU) requirements. ### [Use parameterized Flux queries](/influxdb/cloud/query-data/parameterized-queries/) Use parameterized queries to re-use Flux queries and dynamically populate variables and prevent injection attacks. [query](/influxdb/cloud/tags/query/)[flux](/influxdb/cloud/tags/flux/) --- # Common queries Source: https://docs.influxdata.com/influxdb/cloud/query-data/common-queries/ The following articles walk through common queries using the[NOAA water database data](/influxdb/cloud/reference/sample-data/#noaa-water-sample-data). ### [Operate on columns](/influxdb/cloud/query-data/common-queries/operate-on-columns/) Find and count unique values, recalculate the `_value` column, and use values to calculate a new column. ### [Comparing values from different buckets](/influxdb/cloud/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. ### [Use multiple fields in a calculation](/influxdb/cloud/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. ### [IoT sensor common queries](/influxdb/cloud/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/cloud/tags/queries/) --- # Comparing values from different buckets Source: https://docs.influxdata.com/influxdb/cloud/query-data/common-queries/compare-values/ > [!Note] > This example uses [NOAA water sample data](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/common-queries/iot-common-queries/ 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/cloud/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`. #### Related * [IoT Monitoring with InfluxDB](/resources/videos/iot-monitoring-with-influxdb/) [queries](/influxdb/cloud/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/cloud/query-data/common-queries/multiple-fields-in-calculations/ 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/cloud/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/cloud/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/cloud/query-data/common-queries/operate-on-columns/ 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/cloud/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/cloud/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/cloud/query-data/execute-queries/ There are multiple ways to execute queries with InfluxDB. Choose from the following options: ### [Query sample data](/influxdb/cloud/query-data/execute-queries/query-sample-data/) Explore InfluxDB Cloud with our sample data buckets. ### [Query in Data Explorer](/influxdb/cloud/query-data/execute-queries/data-explorer/) Query your data in the InfluxDB user interface (UI) Data Explorer. ### [Query with the InfluxDB API](/influxdb/cloud/query-data/execute-queries/influx-api/) Use the InfluxDB API to query InfluxDB data. ### [Query in the Flux REPL](/influxdb/cloud/query-data/execute-queries/flux-repl/) Use the Flux REPL to query InfluxDB data. ### [Use the influx query command](/influxdb/cloud/query-data/execute-queries/influx-query/) Use the influx CLI to query InfluxDB data. [query](/influxdb/cloud/tags/query/) --- # Query in Data Explorer Source: https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/data-explorer/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/execute-queries/flux-repl/ The [Flux REPL](/influxdb/cloud/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/cloud/tools/flux-repl/). [query](/influxdb/cloud/tags/query/) --- # Query with the InfluxDB API Source: https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/ The [InfluxDB v2 API](/influxdb/cloud/reference/api) provides a programmatic interface for all interactions with InfluxDB. To query InfluxDB Cloud, 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 Cloud: [Without compression](#without-compression)[With compression](#with-compression) ```bash curl \ --request POST \ http://cloud2.influxdata.com/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://cloud2.influxdata.com/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/cloud/admin/organizations/) that owns the bucket. * `API_TOKEN` - your [token](/influxdb/cloud/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/cloud/admin/buckets/) to query. ## Send an InfluxQL query request To query InfluxDB Cloud 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 Cloud 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://cloud2.influxdata.com/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://cloud2.influxdata.com/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/cloud/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/cloud/admin/buckets/) to query. [Without compression](#without-compression-2)[With compression](#with-compression-2) ```bash curl --get "http://cloud2.influxdata.com/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://cloud2.influxdata.com/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/cloud/admin/tokens/). * `BUCKET_NAME` - the name of the [bucket](/influxdb/cloud/admin/buckets/) to query. InfluxDB returns the query results in [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/). [query](/influxdb/cloud/tags/query/) --- # Use the influx query command Source: https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-query/ Use the [`influx query` command](/influxdb/cloud/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/cloud/reference/cli/influx/query/) [query](/influxdb/cloud/tags/query/) --- # Query sample data Source: https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/query-sample-data/ Use **InfluxDB Cloud** sample datasets to quickly access data that lets you explore and familiarize yourself with InfluxDB Cloud without requiring you to have to 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/cloud/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, magnitude, 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. In the navigation menu on the left, select **Settings** \> **Templates**. Settings 2. Paste the Sample Data community temple URL in **resource manifest file** field: 3. Paste the [Sample Data community template URL](https://github.com/influxdata/community-templates/blob/master/sample-data/sample-data.yml) in the **resource manifest file** field and click the **Lookup Template** button. #### Sample Data community template URL ``` 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 **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/cloud/query-data/flux/ 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/cloud/query-data/flux/query-fields/) Use the [`filter()` function](/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. ```js from(bucket: "example-bucket") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field" and r.tag == "example-tag") ``` [Read more ](/influxdb/cloud/query-data/flux/query-fields/) ### [Group](/influxdb/cloud/query-data/flux/group-data/) Use the [`group()` function](/flux/v0/stdlib/universe/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/cloud/query-data/flux/group-data/) ### [Sort and limit](/influxdb/cloud/query-data/flux/sort-limit/) Use the [`sort()`function](/flux/v0/stdlib/universe/sort) to order records within each table by specific columns and the [`limit()` function](/flux/v0/stdlib/universe/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/cloud/query-data/flux/sort-limit/) ### [Window & aggregate](/influxdb/cloud/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/cloud/query-data/flux/window-aggregate/) ### [Explore your schema](/influxdb/cloud/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/cloud/query-data/flux/explore-schema/) ### [Transform data with math](/influxdb/cloud/query-data/flux/mathematic-operations/) Use the [`map()` function](/flux/v0/stdlib/universe/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/cloud/query-data/flux/mathematic-operations/) ### [Calculate percentages](/influxdb/cloud/query-data/flux/calculate-percentages/) Use [`pivot()` or `join()`](/influxdb/cloud/query-data/flux/mathematic-operations/#pivot-vs-join) and the [`map()` function](/flux/v0/stdlib/universe/map/) 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/cloud/query-data/flux/calculate-percentages/) ### [Increase](/influxdb/cloud/query-data/flux/increase/) Use the [`increase()` function](/flux/v1/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() ``` ###### 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/cloud/query-data/flux/increase/) ### [Moving Average](/influxdb/cloud/query-data/flux/moving-average/) Use the [`movingAverage()`](/flux/v0/stdlib/universe/movingaverage/) or [`timedMovingAverage()`](/flux/v0/stdlib/universe/timedmovingaverage/) functions 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/cloud/query-data/flux/moving-average/) ### [Rate](/influxdb/cloud/query-data/flux/rate/) Use the [`derivative()` function](/flux/v0/stdlib/universe/derivative/) to calculate the rate of change between subsequent values or the [`aggregate.rate()` function](/influxdb/cloud/reference/flux/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. ```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/cloud/query-data/flux/rate/) ### [Histograms](/influxdb/cloud/query-data/flux/histograms/) Use the [`histogram()` function](/flux/v0/stdlib/universe/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/cloud/query-data/flux/histograms/) ### [Fill](/influxdb/cloud/query-data/flux/fill/) Use the [`fill()` function](/flux/v1/stdlib/universe/fill/) 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/cloud/query-data/flux/fill/) ### [Median](/influxdb/cloud/query-data/flux/median/) 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. ```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/cloud/query-data/flux/median/) ### [Percentile & quantile](/influxdb/cloud/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/cloud/query-data/flux/percentile-quantile/) ### [Join](/influxdb/cloud/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/cloud/query-data/flux/join/) ### [Cumulative sum](/influxdb/cloud/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/cloud/query-data/flux/cumulativesum/) ### [First and last](/influxdb/cloud/query-data/flux/first-last/) Use the [`first()`](/flux/v0/stdlib/universe/first/) or [`last()`](/flux/v0/stdlib/universe/last/) functions 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/cloud/query-data/flux/first-last/) ### [Exists](/influxdb/cloud/query-data/flux/exists/) Use the Flux `exists` operator to check if a record contains a key or if that key’s value is `null`. ##### Filter null values ```js data |> filter(fn: (r) => exists r._value) ``` [Read more ](/influxdb/cloud/query-data/flux/exists/) ### [Custom functions](/influxdb/cloud/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/cloud/query-data/flux/custom-functions/) ### [Extract scalar values](/influxdb/cloud/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/cloud/query-data/flux/scalar-values/) ### [Monitor states](/influxdb/cloud/query-data/flux/monitor-states/) Flux provides several functions to help monitor states and state changes in your data. ### [Operate on timestamps](/influxdb/cloud/query-data/flux/operate-on-timestamps/) Use Flux to operate on timestamps timestamps. ### [Query SQL data](/influxdb/cloud/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/cloud/query-data/flux/sql/) ### [Conditional logic](/influxdb/cloud/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/cloud/query-data/flux/conditional-logic/) ### [Regular expressions](/influxdb/cloud/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/cloud/query-data/flux/regular-expressions/) ### [Geo-temporal data](/influxdb/cloud/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/cloud/query-data/flux/geo/) ### [Query the Flux version](/influxdb/cloud/query-data/flux/flux-version/) Use `runtime.version()` to return the version of Flux installed in InfluxDB Cloud. ```js import "array" import "runtime" array.from(rows: [{version: runtime.version()}]) ``` [Read more ](/influxdb/cloud/query-data/flux/flux-version/) [flux](/influxdb/cloud/tags/flux/)[query](/influxdb/cloud/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/cloud/query-data/flux/calculate-percentages/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/flux/conditional-logic/ 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/cloud/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/cloud/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/cloud/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/cloud/tags/conditionals/)[flux](/influxdb/cloud/tags/flux/) --- # Query cumulative sum Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/cumulativesum/ 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/cloud/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/cloud/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/cloud/tags/query/)[cumulative sum](/influxdb/cloud/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/cloud/query-data/flux/custom-functions/ 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/cloud/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/cloud/tags/functions/)[custom](/influxdb/cloud/tags/custom/)[flux](/influxdb/cloud/tags/flux/) --- # Create custom aggregate functions Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/custom-functions/custom-aggregate/ 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/cloud/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 * [reduce() function](/flux/v0/stdlib/universe/reduce/) [functions](/influxdb/cloud/tags/functions/)[custom](/influxdb/cloud/tags/custom/)[flux](/influxdb/cloud/tags/flux/)[aggregates](/influxdb/cloud/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/cloud/query-data/flux/exists/ 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/cloud/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/cloud/query-data/flux/query-fields/) * [filter() function](/flux/v0/stdlib/universe/filter/) [exists](/influxdb/cloud/tags/exists/) --- # Explore your data schema with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/explore-schema/ 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/cloud/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.measurements() function](/flux/v0/stdlib/influxdata/influxdb/schema/measurements/) * [schema.fieldKeys() function](/flux/v0/stdlib/influxdata/influxdb/schema/fieldkeys/) * [schema.measurementFieldKeys() function](/flux/v0/stdlib/influxdata/influxdb/schema/measurementfieldkeys/) * [schema.tagKeys() function](/flux/v0/stdlib/influxdata/influxdb/schema/tagkeys/) * [schema.measurementTagKeys() function](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagkeys/) * [schema.tagValues() function](/flux/v0/stdlib/influxdata/influxdb/schema/tagvalues/) * [schema.measurementTagValues() function](/flux/v0/stdlib/influxdata/influxdb/schema/measurementtagvalues/) [schema](/influxdb/cloud/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/cloud/query-data/flux/fill/ 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/cloud/tags/query/)[fill](/influxdb/cloud/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/cloud/query-data/flux/first-last/ 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/cloud/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/cloud/query-data/flux/flux-version/ InfluxDB Cloud 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/cloud/visualize-data/visualization-types/single-stat/) * [Table](/influxdb/cloud/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/cloud/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/cloud/api/query-data/). ``` POST http://localhost:8086/api/v2/query ``` Provide the following: * InfluxDB Cloud 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/cloud/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/cloud/tags/query/) --- # Work with geo-temporal data Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/geo/ 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/cloud/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 |> map( fn: (r) => ({r with _field: if r._field == "latitude" then "lat" else if r._field == "longitude" then "lon" else r._field, }), ) |> map(fn: (r) => ({r with s2_cell_id: geo.s2CellIDToken(point: {lon: r.lon, lat: r.lat}, level: 10)})) ``` ### [Filter geo-temporal data by region](/influxdb/cloud/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/cloud/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"],orderBy: ["_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/cloud/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/). #### Related * [Using Geolocation data with InfluxDB](/resources/videos/geolocation-and-influxdb/) --- # Filter geo-temporal data by region Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/geo/filter-by-region/ 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/cloud/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/cloud/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. * [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/cloud/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/cloud/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/cloud/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/cloud/query-data/flux/geo/shape-geo-data/ 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/cloud/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/) * [geo.s2CellIDToken() function](/flux/v0/stdlib/experimental/geo/s2cellidtoken/) --- # Group data in InfluxDB with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/group-data/ 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/cloud/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/cloud/tags/group/) --- # Create histograms with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/histograms/ 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/cloud/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/cloud/visualize-data/visualization-types/histogram/)automatically converts query results into a binned and segmented histogram. Histogram visualization Use the [Histogram visualization controls](/influxdb/cloud/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/cloud/tags/histogram/) --- # Calculate the increase Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/increase/ 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/cloud/tags/query/)[increase](/influxdb/cloud/tags/increase/)[counters](/influxdb/cloud/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/cloud/query-data/flux/join/ 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/cloud/tags/join/)[flux](/influxdb/cloud/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/cloud/query-data/flux/mathematic-operations/ [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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/flux/calculate-percentages/) [math](/influxdb/cloud/tags/math/)[flux](/influxdb/cloud/tags/flux/) --- # Find median values Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/median/ 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/cloud/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/cloud/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/cloud/query-data/flux/percentile-quantile/) * [median() function](/flux/v0/stdlib/universe/median/) * [quantile() function](/flux/v0/stdlib/universe/quantile/) [query](/influxdb/cloud/tags/query/)[median](/influxdb/cloud/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/cloud/query-data/flux/monitor-states/ 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/cloud/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/cloud/tags/states/)[monitor](/influxdb/cloud/tags/monitor/)[flux](/influxdb/cloud/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/cloud/query-data/flux/moving-average/ 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/cloud/tags/query/)[moving average](/influxdb/cloud/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/cloud/query-data/flux/operate-on-timestamps/ 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/cloud/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/cloud/reference/glossary/#unix-timestamp)to an [RFC3339 timestamp](/influxdb/cloud/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/) * [experimental.addDuration() function](/flux/v0/stdlib/experimental/addduration/) * [experimental.subDuration() function](/flux/v0/stdlib/experimental/subduration/) | _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/cloud/query-data/flux/percentile-quantile/ 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/cloud/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/cloud/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/cloud/tags/query/)[percentile](/influxdb/cloud/tags/percentile/)[quantile](/influxdb/cloud/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/cloud/query-data/flux/query-fields/ 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/cloud/reference/glossary/#predicate-function), an anonymous function comprised of one or more [predicate expressions](/influxdb/cloud/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/cloud/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/cloud/query-data/flux/conditional-logic/) * [Use regular expressions in Flux](/influxdb/cloud/query-data/flux/regular-expressions/) [query](/influxdb/cloud/tags/query/)[select](/influxdb/cloud/tags/select/)[where](/influxdb/cloud/tags/where/) --- # Calculate the rate of change Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/rate/ 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/cloud/tags/query/)[rate](/influxdb/cloud/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/cloud/query-data/flux/regular-expressions/ 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/cloud/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/cloud/query-data/flux/query-fields/) * [regexp package](/flux/v0/stdlib/regexp/) [regex](/influxdb/cloud/tags/regex/) --- # Extract scalar values in Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/scalar-values/ 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/cloud/tags/scalar/) | output | | --- | | output | | [ 65.1, 66.2, 66.3, 66.8 ] | --- # Sort and limit data with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/sort-limit/ 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/cloud/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/cloud/tags/sort/)[limit](/influxdb/cloud/tags/limit/) --- # Query SQL data sources Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/sql/ The [Flux](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/admin/secrets/use-vault/). ### Store your database credentials as secrets Use the [InfluxDB API](/influxdb/cloud/reference/api/) or the [`influx` CLI](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) * [your API token](/influxdb/cloud/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/cloud/admin/buckets/create-bucket/) to store the data. 2. [Create an InfluxDB task](/influxdb/cloud/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/cloud/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/cloud/visualize-data/dashboards/create-dashboard).* #### Related * [sql package](/flux/v0/stdlib/sql/) [query](/influxdb/cloud/tags/query/)[flux](/influxdb/cloud/tags/flux/)[sql](/influxdb/cloud/tags/sql/) --- # Window and aggregate data with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/flux/window-aggregate/ 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/cloud/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/cloud/tags/flux/)[aggregates](/influxdb/cloud/tags/aggregates/) --- # Get started with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/get-started/ 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/cloud/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/cloud/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/cloud/tags/query/)[flux](/influxdb/cloud/tags/flux/)[get-started](/influxdb/cloud/tags/get-started/) --- # Query InfluxDB with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/get-started/query-influxdb/ 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](/influxdb/cloud/query-data/get-started/)[Transform data with Flux](/influxdb/cloud/query-data/get-started/transform-data/) #### Related * [Flux query basics](/flux/v0/get-started/query-basics/) * [Query data with Flux](/influxdb/cloud/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/cloud/tags/query/)[flux](/influxdb/cloud/tags/flux/) --- # Transform data with Flux Source: https://docs.influxdata.com/influxdb/cloud/query-data/get-started/transform-data/ When [querying data from InfluxDB](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/flux/window-aggregate) guide.* [Query InfluxDB with Flux](/influxdb/cloud/query-data/get-started/query-influxdb/) #### Related * [aggregateWindow() function](/flux/v0/stdlib/universe/aggregatewindow/) * [window() function](/flux/v0/stdlib/universe/window/) [flux](/influxdb/cloud/tags/flux/)[transform](/influxdb/cloud/tags/transform/)[query](/influxdb/cloud/tags/query/) --- # Query data with InfluxQL Source: https://docs.influxdata.com/influxdb/cloud/query-data/influxql/ 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 Cloud, data is stored in [buckets](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/) or the [InfluxDB API](/influxdb/cloud/reference/api/).*For examples, see [List DBRP mappings](/influxdb/cloud/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/cloud/query-data/influxql/dbrp/#create-dbrp-mappings) to map the unmapped bucket. ## Create DBRP mappings for unmapped buckets * Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) or the [InfluxDB API](/influxdb/cloud/reference/api/)to manually create DBRP mappings for unmapped buckets.*For examples, see [Create DBRP mappings](/influxdb/cloud/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/cloud/reference/cli/influx/) provides an [InfluxQL shell](/influxdb/cloud/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/cloud/tools/influx-cli/#install-the-influx-cli) * [Configure your authentication credentials](/influxdb/cloud/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/cloud/tools/influxql-shell/). For more information about DBRP mappings, see [Manage DBRP mappings](/influxdb/cloud/query-data/influxql/dbrp/). The [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) supports all InfluxDB 1.x client libraries and integrations in InfluxDB Cloud. 1. To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/cloud/reference/api/influxdb-1x/query/), and include the following in your request: * **Request method:** `GET` * **Headers:** * **Authorization:** *See [compatibility API authentication](/influxdb/cloud/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/cloud/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/cloud/tools/influxql-shell/) [influxql](/influxdb/cloud/tags/influxql/)[query](/influxdb/cloud/tags/query/) --- # Manage DBRP mappings Source: https://docs.influxdata.com/influxdb/cloud/query-data/influxql/dbrp/ InfluxQL requires a database and retention policy (DBRP) combination in order to query data. In InfluxDB Cloud, databases and retention policies have been combined and replaced by InfluxDB [buckets](/influxdb/cloud/reference/glossary/#bucket). To query InfluxDB Cloud with InfluxQL, the specified DBRP combination must be mapped to a bucket. * [Automatic DBRP mapping](#automatic-dbrp-mapping) * [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 Cloud will automatically create DBRP mappings for you during the following operations: * Writing to the [`/write` v1 compatibility endpoint](/influxdb/cloud/reference/api/influxdb-1x/write/) * [Upgrading from InfluxDB 1.x to InfluxDB Cloud](/influxdb/cloud/upgrade/v1-to-cloud/) For more information, see [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/). ## Create DBRP mappings Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) or the[InfluxDB API](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/config/set/). * \* **database name** to map * \* **retention policy** name to map * \* [Bucket ID](/influxdb/cloud/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/cloud/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/cloud/admin/tokens/) * **Content-type:** `application/json` * **Request body:** JSON object with the following fields: \* Required * \* **bucketID:** [bucket ID](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/) or the [InfluxDB API](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/admin/tokens/) * **Query parameters:** \* Required * \* **orgID:** [organization ID](/influxdb/cloud/admin/organizations/view-orgs/#view-your-organization-id) * **bucketID:** [bucket ID](/influxdb/cloud/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/cloud/reference/cli/influx/) or the[InfluxDB API](/influxdb/cloud/reference/api/) to update a DBRP mapping. [influx CLI](#influx-cli-3)[InfluxDB API](#influxdb-api-3) Use the [`influx v1 dbrp update` command](/influxdb/cloud/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/cloud/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/cloud/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/cloud/admin/tokens/) * **Path parameters:** * \* **id:** DBRP mapping ID to update * **Query parameters:** * \* **orgID:** [organization ID](/influxdb/cloud/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/cloud/reference/cli/influx/) or the[InfluxDB API](/influxdb/cloud/reference/api/) to delete a DBRP mapping. [influx CLI](#influx-cli-4)[InfluxDB API](#influxdb-api-4) Use the [`influx v1 dbrp delete` command](/influxdb/cloud/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/cloud/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/cloud/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/cloud/admin/tokens/) * **Path parameters:** * \* **id:** DBRP mapping ID to update * **Query parameters:** * \* **orgID:** [organization ID](/influxdb/cloud/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/cloud/tags/influxql/)[dbrp](/influxdb/cloud/tags/dbrp/) --- # Explore data using InfluxQL Source: https://docs.influxdata.com/influxdb/cloud/query-data/influxql/explore-data/ 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/cloud/query-data/influxql/dbrp/#list-dbrp-mappings). If not, [create a new DBRP mapping](/influxdb/cloud/query-data/influxql/dbrp/#create-dbrp-mappings). 2. [Configure timestamps in the InfluxQL shell](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/select/) Use the `SELECT` statement to query data from a particular [measurement](/influxdb/cloud/reference/glossary/#measurement) or measurements. ```sql SELECT [,,] FROM [,] ``` [Read more ](/influxdb/cloud/query-data/influxql/explore-data/select/) ### [WHERE clause](/influxdb/cloud/query-data/influxql/explore-data/where/) Use the `WHERE` clause to filter data based on [fields](/influxdb/cloud/reference/glossary/#field), [tags](/influxdb/cloud/reference/glossary/#tag), and/or [timestamps](/influxdb/cloud/reference/glossary/#timestamp). ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` [Read more ](/influxdb/cloud/query-data/influxql/explore-data/where/) ### [GROUP BY clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/) Use the `GROUP BY` clause to group query results by one or more specified [tags](/influxdb/cloud/reference/glossary/#tag) and/or a specified time interval. ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, ``` [Read more ](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/) ### [OFFSET and SOFFSET clauses](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/) Use the `OFFSET` and `SOFFSET` clauses to paginate [points](/influxdb/cloud/reference/glossary/#point) and [series](/influxdb/cloud/reference/glossary/#series). ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` [Read more ](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/) ### [Time and timezone queries](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/time-and-timezone/) ### [Subqueries](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/subqueries/) ### [Regular expressions](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement)occurs at six-minute time intervals. This measurement has one [tag key](/influxdb/cloud/reference/glossary/#tag-key)(`location`) which has two [tag values](/influxdb/cloud/reference/glossary/#tag-value):`coyote_creek` and `santa_monica`. The measurement also has two [fields](/influxdb/cloud/reference/glossary/#field):`level description` stores string [field values](/influxdb/cloud/reference/glossary/#field-value)and `water_level` stores float field values. ### Configure timestamps in the InfluxQL shell By default, the [InfluxQL shell](/influxdb/cloud/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/cloud/tools/influxql-shell/#precision) ` to configure the timestamp format: ```sql precision rfc3339 ``` The [InfluxDB API](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/ Use the `GROUP BY` clause to group query results by one or more specified [tags](/influxdb/cloud/reference/glossary/#tag) and/or a specified time interval. `GROUP BY` requires an [aggregate](/influxdb/cloud/query-data/influxql/functions/aggregates/) or [selector](/influxdb/cloud/query-data/influxql/functions/selectors/) function in the `SELECT` statement. `GROUP BY` supports [regular expressions](/influxdb/cloud/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/cloud/reference/glossary/#tag). ### Syntax ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [,]] ``` * `GROUP BY *` - Groups results by all [tags](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/)to calculate the average `water_level` for each[tag value](/influxdb/cloud/reference/glossary/#tag-value) of `location` in the `h2o_feet` [measurement](/influxdb/cloud/reference/glossary/#measurement). InfluxDB returns results in two [series](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean) to calculate the average `index` for every possible[tag](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#series) of results: one for each[tag value](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/limit-and-slimit/ Use `LIMIT` and `SLIMIT` to limit the number of [points](/influxdb/cloud/reference/glossary/#point) and [series](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean) and a `GROUP BY` clause to calculate the average `water_level` for each [tag](/influxdb/cloud/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/cloud/reference/glossary/#point) from `N` [series](//influxdb/cloud/reference/glossary/#series) in the specified [measurement](/influxdb/cloud/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/cloud/reference/glossary/#point) from one of the [series](/influxdb/cloud/reference/glossary/#series) associated with the `h2o_feet` [measurement](/influxdb/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean)and a time interval in the [GROUP BY clause](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/offset-and-soffset/ Use `OFFSET` and `SOFFSET` to paginate [points](/influxdb/cloud/reference/glossary/#point) and [series](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/select/) specifies the InfluxQL [MEAN() function](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean). * The [`FROM clause`] (/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. * The [`WHERE` clause](/influxdb/cloud/query-data/influxql/explore-data/where/) specifies the time range for the query. * The [`GROUP BY` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. * The [`ORDER BY time DESC` clause](/influxdb/cloud/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. * The [`LIMIT 2` clause](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#series) to paginate. The `SOFFSET` clause requires an [`SLIMIT` clause](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/select/) specifies an InfluxQL [function](/influxdb/cloud/query-data/influxql/functions/). * The [`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. * The [`WHERE` clause](/influxdb/cloud/query-data/influxql/explore-data/where/) specifies the time range for the query. * The [`GROUP BY` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. * The [`ORDER BY time DESC` clause](/influxdb/cloud/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. * The [`LIMIT 2` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/) limits the number of points returned to two. * The [`OFFSET 2` clause](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/) excludes the first two averages from the query results. * The [`SLIMIT 1` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/) limits the number of series returned to one. * The [`SOFFSET 1`](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/order-by/ 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/cloud/reference/glossary/#point)returned has the oldest [timestamp](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean)and a time interval in the [GROUP BY clause](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/ InfluxQL supports using regular expressions when specifying: * [field keys](/influxdb/cloud/reference/glossary/#field-key) and [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/cloud/query-data/influxql/explore-data/select/). * [measurements](/influxdb/cloud/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause). * [tag values](/influxdb/cloud/reference/glossary/#tag-value) and string [field values](/influxdb/cloud/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/cloud/query-data/influxql/explore-data/where/). * [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/) Regular expressions in InfluxQL only support string comparisons and can only evaluate [fields](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean) to calculate the average `degrees` for every [measurement](/influxdb/cloud/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/cloud/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level` where the [tag value](/influxdb/cloud/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/cloud/reference/glossary/#tag) has no value. Every data [point](/influxdb/cloud/reference/glossary/#point) in the [NOAA water sample data](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/select/ Use the `SELECT` statement to query data from a particular [measurement](/influxdb/cloud/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/cloud/reference/glossary/#field) and [tags](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/) * [Basic cast operations](#data-types-and-cast-operations) * [Regular expressions](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/line-protocol/#quotes). > Please review the [rules for single and double-quoting](/influxdb/cloud/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/cloud/reference/glossary/#field) and[tags](/influxdb/cloud/reference/glossary/#tag) from the `h2o_feet`[measurement](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#field-key)in the `SELECT` clause to return data. If the `SELECT` clause only includes a single [tag key](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/) when specifying: * [field keys](/influxdb/cloud/reference/glossary/#field-key) and [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/cloud/query-data/influxql/explore-data/select/) * [measurements](/influxdb/cloud/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause) * [tag values](/influxdb/cloud/reference/glossary/#tag-value) and string [field values](/influxdb/cloud/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/cloud/query-data/influxql/explore-data/where/). * [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/) ## Syntax ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` See [regular expressions](/influxdb/cloud/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/cloud/reference/glossary/#field) type and basic cast operations with the `::` syntax. * [Data types](#data-types) * [Cast operations](#cast-operations) ### Data types [Field values](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/select/). In most cases, InfluxDB rejects any writes that attempt to write a [field value](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#series) automatically. ### Example [](#merge-behavior) Merge behavior The `h2o_feet` [measurement](/influxdb/cloud/reference/glossary/#measurement) in the `noaa` is part of two [series](/influxdb/cloud/reference/glossary/#series). The first series is made up of the `h2o_feet` measurement and the `location = coyote_creek` [tag](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/subqueries/ 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/cloud/query-data/influxql/explore-data/select/) and the [`FROM` clause](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/time-and-timezone/ InfluxQL is designed for working with time series data and includes features specifically for working with time. You can review the following ways to work with time and timestamps in your InfluxQL queries: * [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/cloud/tools/influxql-shell/) returns timestamps in nanosecond UNIX epoch format by default. Specify alternative formats with the[`precision ` command](/influxdb/cloud/tools/influxql-shell/#precision). If you are using the [InfluxQL shell](/influxdb/cloud/tools/influxql-shell/), use the precision helper command `precision rfc3339` to view results in human readable format. The [InfluxDB API](/influxdb/cloud/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/cloud/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/cloud/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/), the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/cloud/reference/glossary/#now). The following sections detail how to specify alternative time ranges in the `SELECT`statement’s [`WHERE` clause](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#now) to query data with [timestamps](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/where/ Use the `WHERE` clause to filter data based on[fields](/influxdb/cloud/reference/glossary/#field),[tags](/influxdb/cloud/reference/glossary/#tag), and/or[timestamps](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/). #### Tags ```sql tag_key ['tag_value'] ``` Single quote [tag values](/influxdb/cloud/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/cloud/reference/faq/#what-are-the-minimum-and-maximum-integers-that-influxdb-can-store). For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/cloud/query-data/influxql/explore-data/group-by/), the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/cloud/reference/glossary/#now). See [Time Syntax](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#timestamp)within the past seven days. See [Time Syntax](/influxdb/cloud/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/cloud/query-data/influxql/explore-schema/ 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/cloud/reference/sample-data/#noaa-water-sample-data). ## SHOW SERIES Return a list of [series](/influxdb/cloud/reference/glossary/#series) for the specified [database](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/cloud/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/cloud/reference/syntax/line-protocol/) format. Everything before the first comma is the [measurement](/influxdb/cloud/reference/glossary/#measurement) name. Everything after the first comma is either a [tag key](/influxdb/cloud/reference/glossary/#tag-key) or a [tag value](/influxdb/cloud/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/cloud/reference/glossary/#measurement)for the specified [database](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/cloud/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/cloud/reference/glossary/#tag-key)associated with the specified [database](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/cloud/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/cloud/reference/glossary/#tag-value)for the specified [tag key(s)](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/) for documentation on the[`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause),[`LIMIT` clause](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/),[`OFFSET` clause](/influxdb/cloud/query-data/influxql/explore-data/offset-and-soffset/), and [Regular Expressions](/influxdb/cloud/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/cloud/reference/glossary/#field-key) and the[data type](/influxdb/cloud/reference/glossary/#data-type) of their[field values](/influxdb/cloud/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/cloud/tools/influxql-shell/)or with the `db` query string parameter in the[InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) request. * The `FROM` clause is optional. See the Data Exploration page for documentation on the[`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause). > [!Note] > **Note:** A field’s data type [can differ](/influxdb/cloud/reference/faq/#how-does-influxdb-handle-field-type-discrepancies-across-shards) across[shards](/influxdb/cloud/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/cloud/reference/glossary/#data-type)cannot differ within a [shard](/influxdb/cloud/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/cloud/query-data/influxql/functions/ 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/cloud/query-data/influxql/). ## InfluxQL functions (by type) * [Aggregates](/influxdb/cloud/query-data/influxql/functions/aggregates/) * [COUNT()](/influxdb/cloud/query-data/influxql/functions/aggregates/#count) * [DISTINCT()](/influxdb/cloud/query-data/influxql/functions/aggregates/#distinct) * [INTEGRAL()](/influxdb/cloud/query-data/influxql/functions/aggregates/#integral) * [MEAN()](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean) * [MEDIAN()](/influxdb/cloud/query-data/influxql/functions/aggregates/#median) * [MODE()](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode) * [SPREAD()](/influxdb/cloud/query-data/influxql/functions/aggregates/#spread) * [STDDEV()](/influxdb/cloud/query-data/influxql/functions/aggregates/#stddev) * [SUM()](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum) * [Selectors](/influxdb/cloud/query-data/influxql/functions/selectors/) * [BOTTOM()](/influxdb/cloud/query-data/influxql/functions/selectors/#bottom) * [FIRST()](/influxdb/cloud/query-data/influxql/functions/selectors/#first) * [LAST()](/influxdb/cloud/query-data/influxql/functions/selectors/#last) * [MAX()](/influxdb/cloud/query-data/influxql/functions/selectors/#max) * [MIN()](/influxdb/cloud/query-data/influxql/functions/selectors/#min) * [PERCENTILE()](/influxdb/cloud/query-data/influxql/functions/selectors/#percentile) * [SAMPLE()](/influxdb/cloud/query-data/influxql/functions/selectors/#sample) * [TOP()](/influxdb/cloud/query-data/influxql/functions/selectors/#top) * [Transformations](/influxdb/cloud/query-data/influxql/functions/transformations/) * [ABS()](/influxdb/cloud/query-data/influxql/functions/transformations/#abs) * [ACOS()](/influxdb/cloud/query-data/influxql/functions/transformations/#acos) * [ASIN()](/influxdb/cloud/query-data/influxql/functions/transformations/#asin) * [ATAN()](/influxdb/cloud/query-data/influxql/functions/transformations/#atan) * [ATAN2()](/influxdb/cloud/query-data/influxql/functions/transformations/#atan2) * [CEIL()](/influxdb/cloud/query-data/influxql/functions/transformations/#ceil) * [COS()](/influxdb/cloud/query-data/influxql/functions/transformations/#cos) * [CUMULATIVE\_SUM()](/influxdb/cloud/query-data/influxql/functions/transformations/#cumulative_sum) * [DERIVATIVE()](/influxdb/cloud/query-data/influxql/functions/transformations/#derivative) * [DIFFERENCE()](/influxdb/cloud/query-data/influxql/functions/transformations/#difference) * [ELAPSED()](/influxdb/cloud/query-data/influxql/functions/transformations/#elapsed) * [EXP()](/influxdb/cloud/query-data/influxql/functions/transformations/#exp) * [FLOOR()](/influxdb/cloud/query-data/influxql/functions/transformations/#floor) * [HISTOGRAM()](/influxdb/cloud/query-data/influxql/functions/transformations/#histogram) * [LN()](/influxdb/cloud/query-data/influxql/functions/transformations/#ln) * [LOG()](/influxdb/cloud/query-data/influxql/functions/transformations/#log) * [LOG2()](/influxdb/cloud/query-data/influxql/functions/transformations/#log2) * [LOG10()](/influxdb/cloud/query-data/influxql/functions/transformations/#log10) * [MOVING\_AVERAGE()](/influxdb/cloud/query-data/influxql/functions/transformations/#moving_average) * [NON\_NEGATIVE\_DERIVATIVE()](/influxdb/cloud/query-data/influxql/functions/transformations/#non_negative_derivative) * [NON\_NEGATIVE\_DIFFERENCE()](/influxdb/cloud/query-data/influxql/functions/transformations/#non_negative_difference) * [POW()](/influxdb/cloud/query-data/influxql/functions/transformations/#pow) * [ROUND()](/influxdb/cloud/query-data/influxql/functions/transformations/#round) * [SIN()](/influxdb/cloud/query-data/influxql/functions/transformations/#sin) * [SQRT()](/influxdb/cloud/query-data/influxql/functions/transformations/#sqrt) * [TAN()](/influxdb/cloud/query-data/influxql/functions/transformations/#tan) * [Technical analysis](/influxdb/cloud/query-data/influxql/functions/technical-analysis/) * (Predictive analysis) [HOLT\_WINTERS()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#holt_winters) * [CHANDE\_MOMENTUM\_OSCILLATOR()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#chande_momentum_oscillator) * [EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#exponential_moving_average) * [DOUBLE\_EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#double_exponential_moving_average) * [KAUFMANS\_EFFICIENCY\_RATIO()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) * [KAUFMANS\_ADAPTIVE\_MOVING\_AVERAGE()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) * [TRIPLE\_EXPONENTIAL\_MOVING\_AVERAGE()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#triple_exponential_moving_average) * [TRIPLE\_EXPONENTIAL\_DERIVATIVE()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#triple_exponential_derivative) * [RELATIVE\_STRENGTH\_INDEX()](/influxdb/cloud/query-data/influxql/functions/technical-analysis/#relative_strength_index) --- # InfluxQL aggregate functions Source: https://docs.influxdata.com/influxdb/cloud/query-data/influxql/functions/aggregates/ Use aggregate functions to assess, aggregate, and return values in your data. Aggregate functions return one row containing the aggregate values from each InfluxQL group. 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/cloud/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/cloud/reference/glossary/#field-value). Supports all field value [data types](/influxdb/cloud/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/cloud/reference/glossary/#measurement). `COUNT(field_key)` Returns the number of field values associated with the [field key](/influxdb/cloud/reference/glossary/#field-key). `COUNT(/regular_expression/)` Returns the number of field values associated with each field key that matches the [regular expression](/influxdb/cloud/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/cloud/reference/glossary/#field-value). Supports all field value [data types](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-value). > [!Note] > `INTEGRAL()` does not support [`fill()`](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill). `INTEGRAL()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/#regular-expressions). `INTEGRAL(*)` Returns the average field value associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). #### Examples The following examples use a subset of the [NOAA water sample data](/influxdb/cloud/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/cloud/query-data/influxql/explore-data/time-and-timezone/#time-syntax) between`2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z`, [grouped](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 12-minute intervals, and[limit](/influxdb/cloud/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/cloud/reference/glossary/#field-value). `MEAN()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `MEAN(/regular\_expression/) Returns the average field value associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/#regular-expressions). `MEAN(*)`Returns the average field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01` and[limit](/influxdb/influxdb/cloud/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/cloud/reference/glossary/#field-value). `MEDIAN()` supports int64 and float64 field value [data types](/influxdb/cloud/reference/glossary/#data-type). > [!Note] > **Note:** `MEDIAN()` is nearly equivalent to [`PERCENTILE(field_key, 50)`](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `MEDIAN(/regular_expression/)` Returns the middle field value associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/#regular-expressions). `MEDIAN(*)` Returns the middle field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `700 `, [limit](/influxdb/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to seven and one, and [offset](/influxdb/cloud/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/cloud/reference/glossary/#field-value). `MODE()` supports all field value [data types](/influxdb/cloud/reference/glossary/#data-type). > [!Note] > **Note:** `MODE()` returns the field value with the earliest [timestamp](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `MODE(/regular_expression/)` Returns the most frequent field value associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/#regular-expressions). `MODE(*)` Returns the most frequent field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [limits](/influxdb/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to three and one, and it [offsets](/influxdb/cloud/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/cloud/reference/glossary/#field-value). `SPREAD()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `18`, [lim ts](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to three and one, and [offsets](/influxdb/cloud/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/cloud/reference/glossary/#field-value). `STDDEV()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/#regular-expressions). `STDDEV(*)` Returns the standard deviation of field values associated with each field key in the [measurement](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `18000`, [limit](/influxdb/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points and series returned to two and one, and [offsets](/influxdb/cloud/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/cloud/reference/glossary/#field-value). `SUM()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `SUM(/regular_expression/)` Returns the sum of field values associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/#regular-expressions). `SUM(*)` Returns the sums of field values associated with each field key in the [measurement](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/)results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with 18000, and [limit](/influxdb/influxdb/cloud/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/cloud/query-data/influxql/functions/selectors/ Use selector functions to assess, select, and return values in your data. Selector functions return one or more rows with the selected values from each InfluxQL group. 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/cloud/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/cloud/reference/glossary/#field-value). `BOTTOM()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `BOTTOM(field_key,tag_key,N)` Returns the smallest field value for N tag values of the [tag key](/influxdb/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `FIRST()` supports all field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `LAST()` supports all field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `MAX(/regular_expression/)` Returns the greatest field value associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/regular-expressions/). `MAX(*)` Returns the greatest field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `MAX()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `MIN(/regular_expression/)` Returns the lowest field value associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/regular-expressions/). `MIN(*)` Returns the lowest field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `MIN()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/) results into 12-minute time intervals and per tag. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `9.01`, and it [limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/). `PERCENTILE(*,N)` Returns the Nth percentile field value associated with each field key in the [measurement](/influxdb/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 24-minute intervals. Then [fill](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill)empty time intervals with `15` and [limit](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/). `SAMPLE(*,N)` Returns N randomly selected field values associated with each field key in the [measurement](/influxdb/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `N` must be an integer.`SAMPLE()` supports all field value [data types](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#tag) and/or [field](/influxdb/cloud/reference/glossary/#field). `TOP()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/technical-analysis/ 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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#field-key). The `N` predicted values occur at the same interval as the [`GROUP BY time()` interval](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/transformations/ 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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not [group by time](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `ABS(*)` Returns the absolute values of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `ABS()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but does not support [group by time](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `ACOS(*)` Returns the arccosine of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `ACOS()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `ASIN(*)` Returns the arcsine of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `ASIN()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/reference/glossary/#field-key). `ATAN(*)` Returns the arctangent of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `ATAN()` supports int64 and float64 field value [data types](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement)divided by field values associated with `field_key_x`. `ATAN2()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/query-data/influxql/functions/selectors/#percentile). #### Examples [](#calculate-arctangents-of-mean-values) Calculate arctangents of mean values Return the arctangents of [mean](/influxdb/cloud/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/cloud/reference/glossary/#field-key) rounded up to the nearest integer. `CEIL(*)` Returns the field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) rounded up to the nearest integer. `CEIL()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `COS(*)` Returns the cosine of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `COS()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement). `CUMULATIVE_SUM()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement). `DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to one and [offsets](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/regular-expressions/). `DIFFERENCE(*)` Returns the difference between subsequent field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). They query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to two and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `ELAPSED(/regular_expression/)` Returns the difference between subsequent timestamps associated with each field key that matches the [regular expression](/influxdb/cloud/query-data/influxql/explore-data/regular-expressions/). `ELAPSED(*)` Returns the difference between subsequent timestamps associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `ELAPSED()` supports all field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). #### Examples The examples use the following subsample of the [NOAA water sample data](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to one and [offsets](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/selectors/#first) or [`MAX()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `EXP(*)` Returns the exponential of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `EXP()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) rounded down to the nearest integer. `FLOOR(*)` Returns the field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) rounded down to the nearest integer. `FLOOR()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `LN(*)` Returns the natural logarithm of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `LN()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) with base `b`. `LOG(*, b)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) with base `b`. `LOG()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) to the base 2. `LOG2(*)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) to the base 2. `LOG2()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) to the base 10. `LOG10(*)` Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) to the base 10. `LOG10()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement). `MOVING_AVERAGE()` int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to two and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement). `NON_NEGATIVE_DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#measurement). `NON_NEGATIVE_DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/reference/glossary/#field-key) to the power of `x`. `POW(*, x)` Returns the field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) to the power of `x`. `POW()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) rounded to the nearest integer. `ROUND(*)` Returns the field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement) rounded to the nearest integer. `ROUND()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/. 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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `SIN(*)` Returns the sine of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `SIN()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `SQRT(*)` Returns the square root field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `SQRT()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key). `TAN(*)` Returns the tangent of field values associated with each field key in the [measurement](/influxdb/cloud/reference/glossary/#measurement). `TAN()` supports int64 and float64 field value [data types](/influxdb/cloud/query-data/influxql/explore-data/select/#data-types). Supports `GROUP BY` clauses that [group by tags](/influxdb/cloud/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/cloud/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/cloud/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/cloud/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/cloud/query-data/influxql/explore-data/order-by/). The query also [limits](/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/)the number of points returned to four and [offsets](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/functions/aggregates/#count),[`MEAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mean),[`MEDIAN()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#median),[`MODE()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#mode),[`SUM()`](/influxdb/cloud/query-data/influxql/functions/aggregates/#sum),[`FIRST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#first),[`LAST()`](/influxdb/cloud/query-data/influxql/functions/selectors/#last),[`MIN()`](/influxdb/cloud/query-data/influxql/functions/selectors/#min),[`MAX()`](/influxdb/cloud/query-data/influxql/functions/selectors/#max), and[`PERCENTILE()`](/influxdb/cloud/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/cloud/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/cloud/query-data/influxql/manage-data/ 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/cloud/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/cloud/tools/influxql-shell/)or with the `db` query string parameter in the[InfluxDB 1.x compatibility API](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#series) in a database. ### Syntax ```sql DELETE FROM WHERE [=''] | [

InfluxDB Cloud data durability

InfluxDB Cloud ensures the durability of all stored data by replicating data across multiple availability zones in a cloud region, automatically creating backups, and verifying that replicated data is consistent and readable.

InfluxDB Cloud security

InfluxDB Cloud is built on industry-standard security practices and principles.

InfluxDB Cloud system buckets

InfluxDB system buckets contain time series data used by and generated from the InfluxDB monitoring and alerting system and the task engine.

``` ### [Sample data](/influxdb/cloud/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/cloud/reference/prometheus-metrics/) When scraping [Prometheus-formatted metrics](https://prometheus.io/docs/concepts/data_model/) and writing them to InfluxDB Cloud, metrics are parsed and stored in InfluxDB in different formats. ### [Frequently asked questions](/influxdb/cloud/reference/faq/) Find answers to common questions related to InfluxDB OSS. ### [Policies and procedures](/influxdb/cloud/reference/policies/) InfluxData product policies and procedures. ### [Glossary](/influxdb/cloud/reference/glossary/) Terms related to InfluxData products and platforms. ### [InfluxDB Cloud (TSM) service notices](/influxdb/cloud/reference/service-notices/) Important service notices related to the InfluxDB Cloud (TSM) platform. --- # Command line tools Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/ 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/cloud/reference/cli/influx/) The `influx` CLI includes commands to manage many aspects of InfluxDB, including buckets, organizations, users, tasks, etc. [cli](/influxdb/cloud/tags/cli/) --- # influx - InfluxDB command line interface Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/ The `influx` command line interface (CLI) includes commands to manage many aspects of InfluxDB, including buckets, organizations, users, tasks, etc. * [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 ``` ### 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/cloud/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/cloud/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/cloud/reference/cli/influx/apply/) | Apply an InfluxDB template | | [auth](/influxdb/cloud/reference/cli/influx/auth/) | API token management commands | | [backup](/influxdb/cloud/reference/cli/influx/backup/) | Back up data *(InfluxDB OSS only)* | | [bucket](/influxdb/cloud/reference/cli/influx/bucket/) | Bucket management commands | |[bucket-schema](/influxdb/cloud/reference/cli/influx/bucket-schema/)| Manage InfluxDB bucket schemas *(InfluxDB Cloud only)* | | [completion](/influxdb/cloud/reference/cli/influx/completion/) | Generate completion scripts | | [config](/influxdb/cloud/reference/cli/influx/config/) | Configuration management commands | | [dashboards](/influxdb/cloud/reference/cli/influx/dashboards/) | List dashboards | | [delete](/influxdb/cloud/reference/cli/influx/delete/) | Delete points from InfluxDB | | [export](/influxdb/cloud/reference/cli/influx/export/) | Export resources as a template | | [help](/influxdb/cloud/reference/cli/influx/help/) | Help about any command | | [org](/influxdb/cloud/reference/cli/influx/org/) | Organization management commands | | [ping](/influxdb/cloud/reference/cli/influx/ping/) | Check the InfluxDB `/health` endpoint | | [query](/influxdb/cloud/reference/cli/influx/query/) | Execute a Flux query | | [restore](/influxdb/cloud/reference/cli/influx/restore/) | Restore backup data *(InfluxDB OSS only)* | | [scripts](/influxdb/cloud/reference/cli/influx/scripts) | Scripts management commands *(InfluxDB Cloud only)* | | [secret](/influxdb/cloud/reference/cli/influx/secret/) | Manage secrets | | [setup](/influxdb/cloud/reference/cli/influx/setup/) |Create default username, password, org, bucket, etc. *(InfluxDB OSS only)*| | [stacks](/influxdb/cloud/reference/cli/influx/stacks/) | Manage InfluxDB stacks | | [task](/influxdb/cloud/reference/cli/influx/task/) | Task management commands | | [telegrafs](/influxdb/cloud/reference/cli/influx/telegrafs/) | Telegraf configuration management commands | | [template](/influxdb/cloud/reference/cli/influx/template/) | Summarize and validate an InfluxDB template | | [user](/influxdb/cloud/reference/cli/influx/user/) | User management commands | | [v1](/influxdb/cloud/reference/cli/influx/v1/) | Work with the v1 compatibility API | | [version](/influxdb/cloud/reference/cli/influx/version/) | Print the influx CLI version | | [write](/influxdb/cloud/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 [cli](/influxdb/cloud/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/cloud/reference/cli/influx/apply/ * influx CLI 2.0.0+ The `influx apply` command applies InfluxDB templates.*For information about finding and using InfluxDB templates, see[Use InfluxDB templates](/influxdb/cloud/tools/influxdb-templates/use/).* ## Usage ``` influx apply [flags] ``` ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/auth/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/auth/active) | Activate API token | | [create](/influxdb/cloud/reference/cli/influx/auth/create) | Create API token | | [delete](/influxdb/cloud/reference/cli/influx/auth/delete) | Delete API token | | [list](/influxdb/cloud/reference/cli/influx/auth/list) | List API tokens | |[inactive](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authentication](/influxdb/cloud/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/cloud/reference/cli/influx/auth/active/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/auth/create/ * influx CLI 2.0.0+ * Updated in CLI v2.2.0 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/cloud/tools/influx-cli/) of the influx cli. ## Usage ``` influx auth create [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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) * [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 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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/auth/delete/ * influx CLI 2.0.0+ The `influx auth delete` command deletes an API token from InfluxDB. ## Usage ``` influx auth delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/auth/inactive/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/auth/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/backup/ * influx CLI 2.0.0+ * InfluxDB OSS only * Updated in CLI v2.0.2 > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx backup` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. > For information about backing up data in InfluxDB Cloud, see[InfluxDB Cloud durability](/influxdb/cloud/reference/internals/durability/). 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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [backup](/influxdb/cloud/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/cloud/reference/cli/influx/bucket-schema/ * influx CLI 2.1.0+ 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/cloud/reference/cli/influx/bucket-schema/create)|Create a bucket schema| | [list](/influxdb/cloud/reference/cli/influx/bucket-schema/list) | List bucket schemas | |[update](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [buckets](/influxdb/cloud/tags/buckets/)[bucket-schema](/influxdb/cloud/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/cloud/reference/cli/influx/bucket-schema/create/ * influx CLI 2.1.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/bucket-schema/list/ * influx CLI 2.1.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/bucket-schema/update/ * influx CLI 2.1.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/bucket/ * influx CLI 2.0.0+ The `influx bucket` command and its subcommands manage buckets in InfluxDB. ## Usage ``` influx bucket [flags] influx bucket [command] ``` ## Subcommands | Subcommand | Description | |------------------------------------------------------------|-------------| |[create](/influxdb/cloud/reference/cli/influx/bucket/create)|Create bucket| |[delete](/influxdb/cloud/reference/cli/influx/bucket/delete)|Delete bucket| | [list](/influxdb/cloud/reference/cli/influx/bucket/list) |List buckets | |[update](/influxdb/cloud/reference/cli/influx/bucket/update)|Update bucket| ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [buckets](/influxdb/cloud/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/cloud/reference/cli/influx/bucket/create/ * influx CLI 2.0.0+ * Updated in CLI v2.1.0 The `influx bucket create` command creates a bucket in InfluxDB. ## Usage ```sh influx bucket create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/bucket/delete/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/bucket/list/ * influx CLI 2.0.0+ * Updated in CLI v2.2.0 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/bucket/update/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/completion/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [cli](/influxdb/cloud/tags/cli/)[tools](/influxdb/cloud/tags/tools/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the completion command | --- # influx config Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/config/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/config/create/)| Create a connection configuration | | [list](/influxdb/cloud/reference/cli/influx/config/list/) | List connection configurations | | [delete](/influxdb/cloud/reference/cli/influx/config/rm/) | Delete a connection configuration | | [set](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [config](/influxdb/cloud/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/cloud/reference/cli/influx/config/create/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/config/list/). > [!Note] > **Note:** If you create multiple connection configurations (for example, separate admin and user configurations), use [`influx config `](/influxdb/cloud/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/cloud/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 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 ``` #### Related * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/config/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/config/rm/ * influx CLI 2.0.0+ 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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/config/set/ * influx CLI 2.0.0+ 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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/dashboards/ * influx CLI 2.0.0+ The `influx dashboards` command lists existing InfluxDB dashboards. ## Usage ```sh influx dashboards [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [telegraf](/influxdb/cloud/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/cloud/reference/cli/influx/delete/ * influx CLI 2.0.3+ * Updated in CLI v2.2.0 The `influx delete` command deletes [points](/influxdb/cloud/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/cloud/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. ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/write-data/delete-data/) * [Delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [delete](/influxdb/cloud/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/cloud/reference/cli/influx/export/ * influx CLI 2.0.0+ The `influx export` command exports existing resources as an InfluxDB template.*For detailed examples of exporting InfluxDB templates, see[Create an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/create/).* ## Usage ``` influx export [flags] influx export [command] ``` ## Available subcommands | Subcommand | Description | |-----------------------------------------------------------|----------------------------------------------------------| | [all](/influxdb/cloud/reference/cli/influx/export/all/) | Export all resources in an organization as a template | |[stack](/influxdb/cloud/reference/cli/influx/export/stack/)|Export all resources associated with a stack as a template| ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/create/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/export/all/ * influx CLI 2.0.0+ 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/cloud/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/cloud/admin/tokens/create-token/). ## Usage ``` influx export all [flags] ``` ## Flags |Flag| | Description |Input Type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/create/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/export/stack/ * influx CLI 2.0.0+ 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/cloud/admin/tokens/create-token/). ## Usage ``` influx export stack [flags] ``` ## Flags |Flag| | Description |Input Type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [Create an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/create/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/help/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/org/create) | Create an organization | | [delete](/influxdb/cloud/reference/cli/influx/org/delete) | Delete an organization | | [list](/influxdb/cloud/reference/cli/influx/org/list) | List organizations | |[members](/influxdb/cloud/reference/cli/influx/org/members)|Organization membership commands| | [update](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [organizations](/influxdb/cloud/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/cloud/reference/cli/influx/org/create/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx org create` command works with **InfluxDB OSS 2.x**, but does > not work with **InfluxDB Cloud**. > New organizations are created for each new InfluxDB account. > For information about creating an InfluxDB Cloud account, see[sign up for InfluxDB Cloud](/influxdb/cloud/sign-up/). The `influx org create` creates an organization in InfluxDB. ## Usage ``` influx org create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/delete/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx org delete` command works with **InfluxDB OSS 2.x**, but does > not work with **InfluxDB Cloud**. > An organization is associated with your InfluxDB account. > For information about removing your InfluxDB Cloud account and its organization, > see [Cancel your InfluxDB Cloud subscription](/influxdb/cloud/account-management/offboarding/). The `influx org delete` command deletes an organization in InfluxDB. ## Usage ``` influx org delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/members/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx org members` command works with **InfluxDB OSS 2.x**, but does > not work with **InfluxDB Cloud**. > For information about managing users in your InfluxDB Cloud organization, see > [Manage users](/influxdb/cloud/admin/organizations/users/). 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/cloud/reference/cli/influx/org/members/add) | Add organization member | | [list](/influxdb/cloud/reference/cli/influx/org/members/list) |List organization members | |[remove](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) | 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/cloud/reference/cli/influx/org/members/add/ * influx CLI 2.0.0+ * InfluxDB OSS only * Updated in CLI v2.4.0 > [!Note] > #### Available with InfluxDB OSS 2.x only > > The `influx org members add` command adds members to organizations in **InfluxDB OSS 2.x**, > but cannot add organization members to **InfluxDB Cloud**. > For information about inviting users into your InfluxDB Cloud organization, see > [Manage users](/influxdb/cloud/admin/organizations/users/). 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) | 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/cloud/reference/cli/influx/org/members/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/members/remove/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Available with InfluxDB OSS 2.x only > > The `influx org members remove` command removes organization members in **InfluxDB OSS 2.x**, > but cannot remove organization members in **InfluxDB Cloud**. > For information about removing a user from your InfluxDB Cloud organization, see > [Remove a user](/influxdb/cloud/admin/organizations/users/#remove-a-user-from-your-organization/). 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/org/update/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/ping/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx ping` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. 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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [ping](/influxdb/cloud/tags/ping/)[health](/influxdb/cloud/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/cloud/reference/cli/influx/query/ * influx CLI 2.0.0+ * Updated in CLI v2.0.5 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/cloud/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/cloud/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/cloud/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/cloud/query-data/) * [Use the influx query command](/influxdb/cloud/query-data/execute-queries/influx-query/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [query](/influxdb/cloud/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/cloud/reference/cli/influx/remote/ > [!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/cloud/reference/cli/influx/remote/create)|Create a new remote connection| |[`delete`](/influxdb/cloud/reference/cli/influx/remote/delete)| Delete a remote connection | | [`list`](/influxdb/cloud/reference/cli/influx/remote/list) | List remote connections | |[`update`](/influxdb/cloud/reference/cli/influx/remote/update)| Update a remote connection | ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `remote` command| #### Related * [influx replication](/influxdb/cloud/reference/cli/influx/replication/) * [Edge Data Replication](/influxdb/cloud/write-data/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/remote/create/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/remote/delete/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/remote/list/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/remote/update/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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 replication Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/replication/ The `influx replication` command and its subcommands manage InfluxDB Edge Data Replication. ## Usage ``` influx replication [command options] [arguments...] ``` ## Subcommands | Subcommand | Description | |-----------------------------------------------------------------|----------------------------------------| |[create](/influxdb/cloud/reference/cli/influx/replication/create)| Create a new replication stream | |[delete](/influxdb/cloud/reference/cli/influx/replication/delete)| Delete a replication stream | | [list](/influxdb/cloud/reference/cli/influx/replication/list) |List all replication streams and metrics| |[update](/influxdb/cloud/reference/cli/influx/replication/update)| Update a replication stream | ## Flags |Flag| | Description | |----|--------|----------------------------------| |`-h`|`--help`|Help for the `replication` command| #### Related * [influx remote](/influxdb/cloud/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/cloud/write-data/replication/replicate-data/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/replication/create/ > [!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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/cloud/write-data/replication/replicate-data/) [write](/influxdb/cloud/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/cloud/reference/cli/influx/replication/delete/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/cloud/write-data/replication/replicate-data/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/replication/list/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/cloud/write-data/replication/replicate-data/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/replication/update/ > [!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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/remote/) * [Replicate data from InfluxDB OSS](/influxdb/cloud/write-data/replication/replicate-data/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/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/cloud/reference/cli/influx/restore/ * influx CLI 2.0.0+ * Updated in CLI v2.0.7 > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx restore` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. > For information about restoring data in InfluxDB Cloud, see [InfluxDB Cloud durability](/influxdb/cloud/reference/internals/durability/) and contact [InfluxData Support](https://support.influxdata.com/). 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/cloud/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/cloud/admin/buckets/delete-bucket/)and then begin the restore process. ## Usage ``` influx restore [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [restore](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/ * influx CLI 2.4.0+ * InfluxDB Cloud only 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/cloud/reference/cli/influx/scripts/create) | Create script | | [delete](/influxdb/cloud/reference/cli/influx/scripts/delete) | Delete script | | [invoke](/influxdb/cloud/reference/cli/influx/scripts/invoke) | Invoke script | | [list](/influxdb/cloud/reference/cli/influx/scripts/list) | List scripts | |[retrieve](/influxdb/cloud/reference/cli/influx/scripts/retrieve)|Retrieve script| | [update](/influxdb/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) * [Invoke custom scripts as API endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) [scripts](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/create/ * influx CLI 2.4.0+ * InfluxDB Cloud only The `influx scripts create` command creates an invokable script in InfluxDB. ## Usage ``` influx scripts create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/delete/ * influx CLI 2.4.0+ * InfluxDB Cloud only The `influx scripts delete` command deletes an invokable script in InfluxDB. ## Usage ``` influx scripts delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/invoke/ * influx CLI 2.4.0+ * InfluxDB Cloud only The `influx scripts invoke` command executes an invokable script in InfluxDB. ## Usage ``` influx scripts invoke [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/list/ * influx CLI 2.4.0+ * InfluxDB Cloud only 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/retrieve/ * influx CLI 2.4.0+ * InfluxDB Cloud only The `influx scripts retrieve` command retrieves invokable script information from InfluxDB. ## Usage ``` influx scripts retrieve [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/scripts/update/ * influx CLI 2.4.0+ * InfluxDB Cloud only 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/secret/ * influx CLI 2.0.0+ The `influx secret` command manages [secrets](/influxdb/cloud/reference/glossary/#secret). ## Usage ``` influx secret [flags] influx secret [subcommand] ``` ## Subcommands | Subcommand | Description | |-------------------------------------------------------------|----------------------| |[delete](/influxdb/cloud/reference/cli/influx/secret/delete/)| Delete a secret | | [list](/influxdb/cloud/reference/cli/influx/secret/list/) | List secrets | |[update](/influxdb/cloud/reference/cli/influx/secret/update/)|Add or update a secret| ## Flags |Flag| | Description | |----|--------|-----------------------------| |`-h`|`--help`|Help for the `secret` command| #### Related * [Manage secrets](/influxdb/cloud/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/cloud/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/cloud/reference/cli/influx/secret/delete/ * influx CLI 2.0.0+ The `influx secret delete` command deletes secrets. ## Usage ``` influx secret delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/cloud/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/cloud/reference/cli/influx/secret/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/cloud/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/cloud/reference/cli/influx/secret/update/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/admin/secrets/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [secrets](/influxdb/cloud/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 setup Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/setup/ * influx CLI 2.0.0+ * InfluxDB OSS only * Updated in CLI v2.0.3 > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx setup` command initiates the setup process for **InfluxDB OSS 2.x** instances. > The command does not work with **InfluxDB Cloud**. > Every InfluxDB Cloud account already has a user and an organization, > so the Cloud [`GET /api/v2/setup` endpoint](/influxdb/cloud/api/setup/) always returns `{"allowed": false}`. > The command checks that endpoint first, > and then exits with the error `instance has already been set up`. 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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [get-started](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/ * influx CLI 2.0.1+ 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/cloud/reference/cli/influx/stacks/init/) |Initialize a stack| |[remove](/influxdb/cloud/reference/cli/influx/stacks/remove/)| Remove a stack | ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/init/ * influx CLI 2.0.1+ The `influx stacks init` command initializes an InfluxDB stack. ## Usage ``` influx stacks init [flags] ``` ## Flags |Flag| | Description | Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/remove/ * influx CLI 2.0.1+ 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/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/update/ * influx CLI 2.0.1+ * Updated in CLI v2.0.4 The `influx stacks update` command updates an InfluxDB stack. ## Usage ``` influx stacks update [flags] ``` ## Flags |Flag| | Description | Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/stacks/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/task/ * influx CLI 2.0.0+ The `influx task` command and its subcommands manage tasks in InfluxDB. ### Usage ``` influx task [flags] influx task [command] ``` ### Subcommands | Subcommand | Description | |----------------------------------------------------------------------|----------------------| | [create](/influxdb/cloud/reference/cli/influx/task/create) | Create task | | [delete](/influxdb/cloud/reference/cli/influx/task/delete) | Delete task | | [list](/influxdb/cloud/reference/cli/influx/task/list) | List tasks | | [log](/influxdb/cloud/reference/cli/influx/task/log) | Log related commands | |[retry-failed](/influxdb/cloud/reference/cli/influx/task/retry-failed)|Retry failed task runs| | [run](/influxdb/cloud/reference/cli/influx/task/run) | Run related commands | | [update](/influxdb/cloud/reference/cli/influx/task/update) | Update task | ### Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `task` command| #### Related * [Process data with InfluxDB tasks](/influxdb/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [tasks](/influxdb/cloud/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/cloud/reference/cli/influx/task/create/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/delete/ * influx CLI 2.0.0+ The `influx task delete` command deletes a task in InfluxDB. ## Usage ``` influx task delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/log/ * influx CLI 2.0.0+ 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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [logs](/influxdb/cloud/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/cloud/reference/cli/influx/task/log/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/retry-failed/ * influx CLI 2.0.5+ 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/cloud/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/cloud/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/cloud/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token > [!Note] > #### Required permissions > > Use an [**All Access** token](/influxdb/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/run/ * influx CLI 2.0.0+ 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/cloud/reference/cli/influx/task/run/list) |List runs for a task| |[retry](/influxdb/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/run/list/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/run/retry/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/reference/urls/) > * `-o, --org` or `--org-id`: InfluxDB organization name or ID > * `-t, --token`: InfluxDB API token > [!Note] > #### Required permissions > > Use an [**All Access** token](/influxdb/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/task/update/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/process-data/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/telegrafs/ * influx CLI 2.0.0+ The `influx telegrafs` command lists Telegraf configurations. Subcommands manage Telegraf configurations. ## Usage ```sh influx telegrafs [flags] influx telegrafs [command] ``` ## Subcommands | Subcommand | Description | |---------------------------------------------------------------|-------------------------------| |[create](/influxdb/cloud/reference/cli/influx/telegrafs/create)|Create a Telegraf configuration| | [rm](/influxdb/cloud/reference/cli/influx/telegrafs/rm) |Remove a Telegraf configuration| |[update](/influxdb/cloud/reference/cli/influx/telegrafs/update)|Update a Telegraf configuration| ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [telegraf](/influxdb/cloud/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/cloud/reference/cli/influx/telegrafs/create/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/telegrafs/rm/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/telegrafs/update/ * influx CLI 2.0.0+ 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/cloud/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/cloud/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/cloud/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/cloud/tools/telegraf-configs/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/template/ * influx CLI 2.0.1+ 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/cloud/reference/cli/influx/template/validate)|Validate a template| ## Flags |Flag| | Description |Input Type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/tools/influxdb-templates/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [templates](/influxdb/cloud/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/cloud/reference/cli/influx/template/validate/ * influx CLI 2.0.1+ 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/cloud/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/cloud/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/cloud/tools/influxdb-templates/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/transpile/ * influx CLI 2.0.0 – 2.0.5 > [!Warning] > ### Removed in influx CLI v2.0.5 > > The `influx transpile` command was removed in **v2.0.5** of the `influx` CLI.[Use InfluxQL to query InfluxDB](/influxdb/cloud/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/cloud/query-data/flux/) > * [Migrate continuous queries to Flux tasks](/influxdb/cloud/upgrade/v1-to-cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/user/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user` command and its subcommands manage **InfluxDB OSS 2.x** users, > but do not manage users in **InfluxDB Cloud**. > Use the InfluxDB Cloud user interface to manage account information. The `influx user` command and its subcommands manage user information in InfluxDB. ## Usage ``` influx user [flags] influx user [command] ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------|------------------------| | [create](/influxdb/cloud/reference/cli/influx/user/create) | Create a user | | [delete](/influxdb/cloud/reference/cli/influx/user/delete) | Delete a user | | [list](/influxdb/cloud/reference/cli/influx/user/list) | List users | |[password](/influxdb/cloud/reference/cli/influx/user/password)|Update a user’s password| | [update](/influxdb/cloud/reference/cli/influx/user/update) | Update a user | ## Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `user` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [users](/influxdb/cloud/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/cloud/reference/cli/influx/user/create/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user create` command creates users in **InfluxDB OSS 2.x**, > but does not create users in **InfluxDB Cloud**. > For information about inviting users into your InfluxDB Cloud organization, see > [Manage users](/influxdb/cloud/admin/organizations/users/). The `influx user create` command creates a user in InfluxDB. ## Usage ``` influx user create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/user/delete/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user delete` command deletes users from **InfluxDB OSS 2.x**, > but does not delete users from **InfluxDB Cloud**. > For information about removing a user from your InfluxDB Cloud organization, see > [Remove a user](/influxdb/cloud/admin/organizations/users/#remove-a-user-from-your-organization). The `influx user delete` command deletes a specified user in InfluxDB. ## Usage ``` influx user delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/user/list/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user list` command lists users in **InfluxDB OSS 2.x**, > but does not list users in **InfluxDB Cloud**. > For information about managing InfluxDB Cloud users, see > [Manage users](/influxdb/cloud/admin/organizations/users/). 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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/user/password/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user password` command updates passwords for **InfluxDB OSS 2.x** users, > but does not update passwords for **InfluxDB Cloud** accounts. > To change your InfluxDB Cloud account password, see > [Change your password](/influxdb/cloud/account-management/change-password/). The `influx user` command and its subcommands manage user information in InfluxDB. ## Usage ``` influx user [flags] influx user [command] ``` ## Subcommands | Subcommand | Description | |--------------------------------------------------------------|------------------------| | [create](/influxdb/cloud/reference/cli/influx/user/create) | Create a user | | [delete](/influxdb/cloud/reference/cli/influx/user/delete) | Delete a user | | [list](/influxdb/cloud/reference/cli/influx/user/list) | List users | |[password](/influxdb/cloud/reference/cli/influx/user/password)|Update a user’s password| | [update](/influxdb/cloud/reference/cli/influx/user/update) | Update a user | ## Flags |Flag| | Description | |----|--------|---------------------------| |`-h`|`--help`|Help for the `user` command| #### Related * [Change your password](/influxdb/cloud/account-management/change-password/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) | 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 update Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/user/update/ * influx CLI 2.0.0+ * InfluxDB OSS only > [!Note] > #### Works with InfluxDB OSS 2.x > > The `influx user update` command updates users in **InfluxDB OSS 2.x**, > but does not update users in **InfluxDB Cloud**. > Use the InfluxDB Cloud user interface to update account information. 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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/v1/ * influx CLI 2.0.0+ The `influx v1` command provides commands for working with the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) in InfluxDB Cloud. ## Usage ``` influx v1 [flags] influx v1 [command] ``` ## Subcommands | Subcommand | Description | |-------------------------------------------------------|-----------------------------------------------------------------| | [auth](/influxdb/cloud/reference/cli/influx/v1/auth/) | Authorization management commands for v1 APIs | | [dbrp](/influxdb/cloud/reference/cli/influx/v1/dbrp/) |Database retention policy mapping management commands for v1 APIs| |[shell](/influxdb/cloud/reference/cli/influx/v1/shell/)| Start an InfluxQL shell | ## Flags |Flag| | Description | |----|--------|-------------------------| |`-h`|`--help`|Help for the `v1` command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/ * influx CLI 2.0.0+ > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth` subcommands provide authorization management for the[InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). InfluxDB Cloud uses [API tokens](/influxdb/cloud/admin/tokens/) to authorize API requests. The [1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) lets clients authenticate with InfluxDB Cloud 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/cloud/reference/cli/influx/v1/auth/create/) | Create authorization | | [delete](/influxdb/cloud/reference/cli/influx/v1/auth/delete/) | Delete authorization | | [list](/influxdb/cloud/reference/cli/influx/v1/auth/list/) | List authorizations | | [set-active](/influxdb/cloud/reference/cli/influx/v1/auth/set-active/) | Activate an authorization | |[set-inactive](/influxdb/cloud/reference/cli/influx/v1/auth/set-inactive/)| Deactivate an authorization | |[set-password](/influxdb/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/create/ * influx CLI 2.0.0+ * Updated in CLI v2.0.3 > [!Important] > #### Not supported in InfluxDB Cloud Serverless > > **InfluxDB Cloud (TSM)** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth create` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use[InfluxDB token authentication](/influxdb3/cloud-serverless/admin/tokens/). The `influx v1 auth create` command creates a legacy authorization with the[InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth create [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/delete/ * influx CLI 2.0.0+ > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth delete` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth delete` command deletes an authorization in the[InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/list/ * influx CLI 2.0.0+ > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth list` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth list` command lists and searches authorizations in the[InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth list [flags] ``` #### Command aliases `list`, `ls`, `find` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/set-active/ * influx CLI 2.0.0+ > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth set-active` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth set-active` command activates an authorization in the[InfluxDB 1.x compatibility API](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/set-inactive/ * influx CLI 2.0.0+ > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth set-inactive` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth set-inactive` command deactivates an authorization in the[InfluxDB 1.x compatibility API](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/auth/set-password/ * influx CLI 2.0.0+ * Updated in CLI v2.0.3 > [!Important] > #### Not supported in InfluxDB Cloud > > **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. > Using the `influx v1 auth set-password` command with InfluxDB Cloud will result in an error. > To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). The `influx v1 auth set-password` command sets a password for an existing authorization in the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 auth set-password [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [authorization](/influxdb/cloud/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/cloud/reference/cli/influx/v1/dbrp/ * influx CLI 2.0.2+ The `influx v1 dbrp` subcommands manage database and retention policy mappings (DBRP) for the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp [flags] influx v1 dbrp [command] ``` ## Commands | Command | Description | |--------------------------------------------------------------|---------------------| |[create](/influxdb/cloud/reference/cli/influx/v1/dbrp/create/)|Create a DBRP mapping| |[delete](/influxdb/cloud/reference/cli/influx/v1/dbrp/delete/)|Delete a DBRP mapping| | [list](/influxdb/cloud/reference/cli/influx/v1/dbrp/list/) | List DBRP mappings | |[update](/influxdb/cloud/reference/cli/influx/v1/dbrp/update/)|Update a DBRP mapping| ## Flags |Flag| | Description | |----|--------|------------------------------| |`-h`|`--help`|Help for the `v1 dbrp `command| #### Related * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/cloud/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/cloud/reference/cli/influx/v1/dbrp/create/ * influx CLI 2.0.2+ The `influx v1 dbrp create` command creates a DBRP mapping with the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp create [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/cloud/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/cloud/reference/cli/influx/v1/dbrp/delete/ * influx CLI 2.0.2+ The `influx v1 dbrp delete` command deletes a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp delete [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/cloud/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/cloud/reference/cli/influx/v1/dbrp/list/ * influx CLI 2.0.2+ The `influx v1 dbrp list` command lists and searches DBRP mappings in the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp list [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [dbrp](/influxdb/cloud/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/cloud/reference/cli/influx/v1/dbrp/update/ * influx CLI 2.0.2+ The `influx v1 dbrp update` command updates a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/). ## Usage ``` influx v1 dbrp update [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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 * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [DBRP](/influxdb/cloud/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/cloud/reference/cli/influx/v1/shell/ * influx CLI 2.4.0+ * InfluxDB Cloud 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 Cloud, databases and retention policies have been > combined and replaced with [buckets](/influxdb/cloud/reference/glossary/#bucket). > To use the InfluxQL to query an InfluxDB Cloud bucket, first > map your DBRP combinations to an appropriate bucket. For more information, see[Query data with InfluxQL](/influxdb/cloud/query-data/influxql/). ## Usage ```sh influx v1 shell [flags] ``` ## Flags |Flag| | Description |Input type|Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) * [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) * [Use the InfluxQL shell](/influxdb/v2/tools/influxql-shell/) [InfluxQL](/influxdb/cloud/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/cloud/reference/cli/influx/version/ * influx CLI 2.0.0+ 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/cloud/tags/influx/)[cli](/influxdb/cloud/tags/cli/) | Flag | | Description | | --- | --- | --- | | Flag | | Description | | -h | --help | Help for the version command | --- # influx write Source: https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/write/ * influx CLI 2.0.0+ * Updated in CLI v2.0.5 The `influx write` command writes data to InfluxDB via stdin or from a specified file. Write data using [line protocol](/influxdb/cloud/reference/syntax/line-protocol),[annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv), or[extended annotated CSV](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/annotated-csv/extended/#csv-annotations). ## Subcommands | Subcommand | Description | |-----------------------------------------------------------|-----------------------------------| |[dryrun](/influxdb/cloud/reference/cli/influx/write/dryrun)|Write to stdout instead of InfluxDB| ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/write-data/) * [Write CSV data to InfluxDB](/influxdb/cloud/write-data/developer-tools/csv/) * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) * [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/) * [influx CLI—Provide required authentication credentials](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials) * [influx CLI—Flag patterns and conventions](/influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions) [write](/influxdb/cloud/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/cloud/reference/cli/influx/write/dryrun/ * influx CLI 2.0.0+ 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/cloud/reference/syntax/line-protocol),[annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv), and[extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended). Output is always **line protocol**. ## Usage ``` influx write dryrun [flags] ``` ## Flags |Flag| | Description |Input type |Maps to [?](/influxdb/cloud/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/cloud/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/cloud/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/cloud/write-data/) * [Write CSV data to InfluxDB](/influxdb/cloud/write-data/developer-tools/csv/) * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) * [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/) [write](/influxdb/cloud/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 | | --- # Frequently asked questions Source: https://docs.influxdata.com/influxdb/cloud/reference/faq/ ##### Account management * [How do I reset my password?](#how-do-i-reset-my-password) * [How do I switch between InfluxDB Cloud accounts?](#how-do-i-switch-between-influxdb-cloud-accounts) ##### Billing and usage * [How do I manage payment methods?](#how-do-i-manage-payment-methods) * [Who do I contact for billing issues?](#who-do-i-contact-for-billing-issues) * [How do I view data my data usage?](#how-do-i-view-data-my-data-usage) * [How do I increase my organization’s rate limits and quotas?](#how-do-i-increase-my-organizations-rate-limits-and-quotas) ##### InfluxDB Cloud service health * [Where can I see the current status of InfluxDB Cloud?](#where-can-i-see-the-current-status-of-influxdb-cloud) ##### 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) * [Can you change the permission level of members in your organization?](#can-you-change-the-permission-level-of-members-in-your-organization) ##### Administration * [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) * [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) ##### 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) ##### 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 Cloud?](#how-do-i-use-influxql-with-influxdb-cloud) * [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) * [Why am I getting the error, “total duration of queries in the last 30s exceeds limit of 25m0s”?](#why-am-i-getting-the-error-total-duration-of-queries-in-the-last-30s-exceeds-limit-of-25m0s) ##### 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) ## Account management #### How do I reset my password? Use the **Forgot Password** link on the InfluxDB Cloud login page to update your password. For more information, see[Change your password](/influxdb/cloud/account-management/change-password/). #### How do I switch between InfluxDB Cloud accounts? Use the **Switch Accounts** functionality in your InfluxDB Cloud account settings to switch between InfluxDB Cloud accounts. For more information, see [Switch InfluxDB Cloud accounts](/influxdb/cloud/account-management/switch-account/). ## Billing and usage #### How do I manage payment methods? * If you subscribed to InfluxDB Cloud through InfluxData, you can manage payment methods in the [Billing section](https://cloud2.influxdata.com/me/billing) of your InfluxDB Cloud account. * If you subscribed to InfluxDB Cloud through a cloud provider marketplace (**AWS Marketplace**, **Azure Marketplace**, or **GCP Marketplace**), use your cloud provider’s billing administration to manage payment methods. For more information, see [Manage InfluxDB Cloud billing](/influxdb/cloud/account-management/billing/). #### Who do I contact for billing issues? For billing issues, please [contact InfluxData support](https://support.influxdata.com/s/contactsupport). #### How do I view data my data usage? To view your InfluxDB Cloud organization’s data usage, view the [Usage page](https://cloud2.influxdata.com/me/usage)in the InfluxDB Cloud user interface. For more information, see[View InfluxDB Cloud data usage](/influxdb/cloud/account-management/data-usage/). #### How do I increase my organization’s rate limits and quotas? * If using the InfluxDB Cloud [Free Plan](/influxdb/cloud/account-management/pricing-plans/#free-plan), for increased rate limits and quotas, upgrade to a[Usage-Based](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan)or [Annual Plan](/influxdb/cloud/account-management/pricing-plans/#annual-plan). * If using a **Usage-Based** or **Annual** Plan, [contact InfluxData support](https://support.influxdata.com/s/contactsupport)and request rate limit and quota adjustments. ## InfluxDB Cloud service health #### Where can I see the current status of InfluxDB Cloud? InfluxDB Cloud regions and underlying services are monitored at all times. To see the current status of InfluxDB Cloud, view the [InfluxDB Cloud status page](https://status.influxdata.com). To receive outage alerts and updates, subscribe to our status page. ## Security #### What different types of API tokens exist? InfluxDB Cloud supports the following token types: * All Access tokens * Custom tokens For more information about each token type, see [Manage API tokens](/influxdb/cloud/admin/tokens/). #### Can I use InfluxDB with authentication disabled? InfluxDB Cloud enforces security best practices by requiring API requests to be authenticated. Authentication cannot be disabled. #### Can you change the permission level of members in your organization? InfluxDB Cloud has only one permission level for users: Owner. With Owner permissions, a user can delete resources and other users from your organization. Take care when inviting a user. ## Administration #### 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/). #### 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 hourly \*\*. You may need to wait for the next retention enforcement cycle to run. For more information, see [Data retention](/influxdb/cloud/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/cloud/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/cloud/write-data/best-practices/duplicate-points/). ## 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 Cloud? Using InfluxQL with InfluxDB Cloud is made possible by the[v1 compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) which replicates the `/query` endpoint from InfluxDB 1.x. This allows all InfluxDB v1-compatible clients to work with InfluxDB Cloud. However, InfluxQL relies on a database and retention policy data model doesn’t exist in InfluxDBCloud, but has been replaced by [buckets](/influxdb/cloud/reference/glossary/#bucket). InfluxDB Cloud 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 Cloudand configuring DBRP mapping, see [Query with InfluxQL](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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='' ``` #### Why am I getting the error, “total duration of queries in the last 30s exceeds limit of 25m0s”? This error indicates you are exceeding the [Total query time global limit](/influxdb/cloud/account-management/limits/#global-limits)for your organization. Potential causes include: * A single long-running query. * Running too many queries at once. * A combination of both. If you are encountering this error due to a single long-running query, the query and potentially your schema should be analyzed for optimization. The following resources may help: * [Optimize Flux queries](/influxdb/cloud/query-data/optimize-queries/) * [Schema design best practices](/influxdb/cloud/write-data/best-practices/schema-design/) If you are encountering this error due to the number of concurrent queries, try delaying or staggering queries so they don’t all run at the same time. ## Deleting data #### Can I delete a field? Yes. InfluxDB Cloud supports deleting data by field. Use the `_field` label in your [delete predicate](/influxdb/cloud/reference/syntax/delete-predicate/)to identify the field to delete. ```js _field == "example-field" ``` #### Can I delete a measurement? Yes. InfluxDB Cloud supports deleting data by measurement. Use the `_measurement` label in your [delete predicate](/influxdb/cloud/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 Cloud does not support deleting multiple measurements in a single delete request. To delete multiple measurements, [issue a delete request](/influxdb/cloud/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. Because the delete queue executes asynchronously, there isn’t a way to accurately predict when the delete operation will be performed at the storage layer. 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/cloud/reference/glossary/#series-cardinality) is the total number of unique**measurement**, **tag set**, and **field key** combinations (series) stored on disk and indexed in memory. #### Why does series cardinality matter? InfluxDB maintains an in-memory index of every [series](/influxdb/cloud/reference/glossary/#series). As the number of unique series grows, it can negatively affect query performance. Each InfluxDB Cloud organization has a series cardinality limit to prevent runaway cardinality. For information about adjusting cardinality limits, see[How do I increase my organization’s rate limits and quotas?](#how-do-i-increase-my-organizations-rate-limits-and-quotas). 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/cloud/write-data/best-practices/resolve-high-cardinality/)for information about reducing series cardinality. | _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/cloud/reference/glossary/ [A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) | [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | X | Y | Z A ---------- ### abstract syntax tree (AST) Tree representation of source code that shows the structure, content, and rules of programming statements and discards additional syntax elements. The tree is hierarchical, with elements of program statements broken down into their parts. For more information about AST design, see [Abstract Syntax Tree on Wikipedia](https://en.wikipedia.org/wiki/Abstract_syntax_tree). ### agent A background process started by (or on behalf of) a user that typically requires user input. Telegraf 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/cloud/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/cloud/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 Cloud 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/cloud/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/cloud/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 Cloud. 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/cloud/reference/syntax/annotated-csv/) * [extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/#datatype) * [line protocol](/influxdb/cloud/reference/syntax/line-protocol/#data-types-and-format) * [InfluxQL](/influxdb/v1/query_language/spec/#literals) * [Flux](/influxdb/cloud/reference/flux/language/types/) * [InfluxDB](/influxdb/cloud/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/cloud/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/cloud/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 Cloud 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). ### 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/cloud/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 Cloud 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/cloud/reference/syntax/line-protocol/). M ---------- ### measurement The part of InfluxDB’s structure that describes the data stored in the associated fields. Measurements are strings. With **InfluxDB 3**, a time series measurement equates to a relational database table with fields, tags, and timestamp as columns. 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/cloud/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/cloud/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) ### primary key With the InfluxDB 3 storage engine, the primary key is the list of columns used to uniquely identify each row in a table. Rows are uniquely identified by their timestamp and tag set. ### 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/cloud/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/cloud/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/cloud/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, tag set, and field key ). 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/cloud/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/cloud/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/cloud/reference/internals/shards/) * [Manage buckets](/influxdb/cloud/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/cloud/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/cloud/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 With **InfluxDB 3**, a time series measurement equates to a relational database table with fields, tags, and timestamp as columns. 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/cloud/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/cloud/write-data/no-code/use-telegraf/auto-config/), [Manually configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config/), [Telegraf plugins](/telegraf/v1/plugins//), [Use Telegraf to collect data](/influxdb/cloud/write-data/no-code/use-telegraf/), [View a Telegraf configuration](/influxdb/cloud/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/cloud/reference/syntax/line-protocol/#elements-of-line-protocol). To specify time when querying data, see [Query InfluxDB with Flux](/influxdb/cloud/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: * **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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/query-data/flux/window-aggregate/). [glossary](/influxdb/cloud/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 Cloud internals Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/ ### [InfluxDB Cloud data durability](/influxdb/cloud/reference/internals/durability/) InfluxDB Cloud ensures the durability of all stored data by replicating data across multiple availability zones in a cloud region, automatically creating backups, and verifying that replicated data is consistent and readable. ### [InfluxDB Cloud security](/influxdb/cloud/reference/internals/security/) InfluxDB Cloud is built on industry-standard security practices and principles. ### [InfluxDB Cloud system buckets](/influxdb/cloud/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. ### [Time To Become Readable](/influxdb/cloud/reference/internals/ttbr/) **Time To Become Readable (TTBR)** is the delay between when you write data to InfluxDB Cloud and when that data becomes queryable. TTBR is variable and is affected by many factors. ### [Data retention in InfluxDB Cloud](/influxdb/cloud/reference/internals/data-retention/) The InfluxDB Cloud retention service checks for and removes data with timestamps beyond the defined retention period of the bucket the data is stored in. --- # Data retention in InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/data-retention/ The **InfluxDB Cloud retention enforcement service** checks for and removes data with timestamps beyond the defined retention period of the[bucket](/influxdb/cloud/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. * [Bucket retention period](#bucket-retention-period) * [When does data actually get deleted?](#when-does-data-actually-get-deleted) ## Bucket retention period A **bucket retention period** is the [duration](/influxdb/cloud/glossary/#duration) of time that a bucket retains data. Retention periods can be infinite or as short as an hour.[Points](/influxdb/cloud/reference/glossary/#point) in a bucket with timestamps beyond the defined retention period (relative to now) are flagged for deletion (also known as “tombstoned”). > [!Note] > #### View bucket retention periods > > Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list/)to view the retention period buckets in your organization. ## When does data actually get deleted? The InfluxDB Cloud retention enforcement service **runs hourly** and tombstones all points with timestamps beyond the bucket retention period. Tombstoned points persist on disk, but are filtered from all query results until the next [compaction](/influxdb/cloud/reference/glossary/#compaction) cycle, when they are removed from disk. Compaction cycle intervals vary. [internals](/influxdb/cloud/tags/internals/) --- # InfluxDB Cloud data durability Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/durability/ InfluxDB Cloud replicates all data in the storage tier across two availability zones in a cloud region, automatically creates backups, and verifies that replicated data is consistent and readable. ##### On this page * [Data replication](#data-replication) * [Backup processes](#backup-processes) * [Recovery](#recovery) * [Data verification](#data-verification) ## Data replication InfluxDB Cloud replicates data in both the write tier and the storage tier. * **Write tier:** all data written to InfluxDB is processed by a durable message queue. The message queue partitions each batch of points based off series keys and then replicates each partition across other physical nodes in the message queue. * **Storage tier:** all data in the underlying storage tier is replicated across two availability zones in a cloud region. ## Backup processes InfluxDB Cloud backs up all data in the following way: * [Backup on write](#backup-on-write) * [Backup after compaction](#backup-after-compaction) * [Periodic TSM snapshots](#periodic-tsm-snapshots) ### Backup on write All inbound write requests to InfluxDB Cloud are added to a durable message queue. The message queue does the following: 1. Caches the [line protocol](/influxdb/cloud/reference/glossary/#line-protocol)of each write request. 2. Writes data to the storage tier. 3. Routinely persists cached line protocol to object storage as an out-of-band backup. Message queue backups provide raw line protocol that can be used to recover from catastrophic failure in the storage tier or an accidental deletion. The durability of the message queue is 96 hours, meaning InfluxDB Cloud can sustain a failure of its underlying storage tier or object storage services for up to 96 hours without any data loss. To minimize potential data loss due to defects introduced in the InfluxDB Cloud service, we minimize the code used between the data ingest and backup processes. ### Backup after compaction The InfluxDB storage engine compresses data over time in a process known as[compaction](/influxdb/cloud/reference/glossary/#compaction). When each compaction cycle completes, InfluxDB Cloud stores compressed[TSM](/influxdb/cloud/reference/glossary/#tsm-time-structured-merge-tree) files in object storage. ### Periodic TSM snapshots To provide multiple data recovery points, InfluxDB Cloud takes weekly snapshots of TSM files uploaded to object storage. The TSM snapshot includes a copy of all (non-deleted) data when the snapshot is created. These snapshots are preserved for 100 days. ## Recovery InfluxDB Cloud uses the following out-of-band backups stored in object storage to recover data: * **Message queue backup:** line protocol from inbound write requests within the last 96 hours * **Compaction backup:** TSM files * **TSM snapshots:** Weekly snapshots of TSM files in objectstore The Recovery Point Objective (RPO) is any accepted write. The Recovery Time Objective (RTO) is harder to definitively predict as potential failure modes can vary. While most common failure modes can be resolved within minutes or hours, critical failure modes may take longer. For example, if we need to rebuild all data from the TSM snapshots and message queue backup, it could take 24 hours or longer. ## Data verification InfluxDB Cloud has two data verification services running at all times: * **Entropy detection:** ensures that replicated data is consistent * **Data verification:** verifies that data written to InfluxDB is readable ## InfluxDB Cloud status InfluxDB Cloud regions and underlying services are monitored at all times. For information about the current status of InfluxDB Cloud, see the[InfluxDB Cloud status page](https://status.influxdata.com). [backups](/influxdb/cloud/tags/backups/)[internals](/influxdb/cloud/tags/internals/) --- # InfluxDB Cloud security Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/security/ InfluxData’s information security program is based on industry-recognized standards and frameworks, including but not limited to ISO 27001, NIST 800-53, CIS20, and SOC2 Type II. Our security policy describes the secure development, deployment, and operation of InfluxDB Cloud. To protect data, InfluxDB Cloud includes the following: * Guaranteed [tenant isolation](#tenant-isolation) and [data integrity](#data-integrity). * Trusted cloud infrastructure including [Amazon Web Services (AWS)](#amazon-web-services-aws),[Microsoft Azure](#microsoft-azure), and [Google Cloud Platform (GCP)](#google-cloud-platform-gcp), building on security controls of these cloud providers, such as physical security, disk encryption, and key management services (KMS). * Comprehensive [application and service security](#application-and-service-security)covering both technical security measures and the people and processes that maintain the platform, including: * [Internal access controls](#internal-access-controls) * [Configuration management](#configuration-management) * [Secure software development life cycle (SDLC)](#secure-software-development-life-cycle-sdlc) * [Separation of environments and duties](#separation-of-environments-and-duties) * [Monitoring, logging, and alerting](#monitoring-logging-and-alerting) * [Third-party security assessments](#security-assessments) * [Business continuity and disaster recovery](#business-continuity-and-disaster-recovery) * [Data durability](#data-durability) * [Incident response](#incident-response) * [Configurable security controls](#configurable-security-controls): * [Authentication, authorization, and accounting](#access-authentication-and-authorization) * [Role-based access controls (RBAC)](#role-based-access-controls-rbac) * [Advanced controls](#advanced-controls) * [Compliance auditing](#compliance-and-auditing)to ensure continuous review and adoption of industry-recognized standards and best practices. ## Tenant isolation In the InfluxDB Cloud multi-tenant platform, access controls ensure that only valid authenticated and authorized requests access your account data. Access control includes: * A unique organization ID assigned to an account when the account is created. All internal Cloud services require this organization ID to authenticate entities before accessing or operating on data. * All external requests must be authorized with a valid token or session. Every InfluxDB Cloud service, from individual API calls to user interface (UI) interactions, enforce this policy. ## Data integrity A dedicated internal service ensures data integrity by periodically creating, recording, and writing test data into test buckets. The service periodically executes queries to ensure the data hasn’t been lost or corrupted. A separate instance of this service lives within each InfluxDB Cloud cluster. Additionally, the service creates out-of-band backups in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/), and ensures the backup data matches the data on disk. ## Cloud infrastructure InfluxDB Cloud cluster architecture InfluxDB Cloud is available on the following cloud providers: * [Amazon Web Services (AWS)](https://aws.amazon.com/) * [Microsoft Azure](https://azure.microsoft.com/en-us/) * [Google Cloud Platform (GCP)](https://cloud.google.com/) To ensure data security, availability, and durability, each instance is isolated and protected in its own virtual private cloud (VPC). ### Amazon Web Services (AWS) An instance of InfluxDB Cloud consists of microservices in Kubernetes. Each VPC within AWS is segmented into public and private subnets: * The public subnet contains resources exposed to the public internet, including load balancers and network address translation (NAT) gateways. * The private subnet contains supporting infrastructure (e.g., compute, storage) not exposed to the public internet. AWS data centers are compliant with many physical and information security standards. For detail about AWS’s physical security and data center protocols, see [AWS’s Compliance](https://aws.amazon.com/compliance/). ### Google Cloud Platform (GCP) In Google Cloud Platform (GCP), InfluxDB Cloud uses the Google Kubernetes Engine (GKE) and Google Compute Engine to deploy individual cluster components. Clusters are isolated at the project level to enhance access controls, data governance, and support auditing. Google Cloud Platform data centers are compliant with many physical and information security standards. For detail about physical security in GCP data centers, see [Google’s Compliance website](https://cloud.google.com/security/compliance/). ### Microsoft Azure In Microsoft Azure, InfluxDB Cloud uses Azure Kubernetes Service (AKS) and Azure Virtual Machines to deploy individual cluster components. To support auditing and authorization control within Azure, clusters are deployed into dedicated VNets within each region. Microsoft Azure data centers are compliant with many physical and information security standards. For detail about physical security within Microsoft Azure data centers, see [Microsoft’s Compliance website](https://www.microsoft.com/en-us/trust-center/compliance/compliance-overview). ### Data encryption InfluxDB Cloud enforces TLS encryption for data in transit from all clients, including Telegraf agents, browsers, and custom applications. Requests using TLS 1.1 or earlier are rejected. By default, data at rest is encrypted using strong encrypted methods (AES-256) within AWS, GCP, and Microsoft Azure. User managed encryption keys are not supported in InfluxDB Cloud at this time. ## Application and service security InfluxData maintains the following application and service security controls: ### Internal access controls * Administrative privileges are restricted to named groups of authorized users. * Shared accounts are prohibited. * Multi-factor authentication (MFA) is required for all infrastructure (AWS, GCP, and Azure) and for other production systems with access to user information (see [InfluxData Subprocessors](https://www.influxdata.com/legal/influxdata-subprocessors/)). * InfluxDB Cloud access is logged and audited regularly. ### Configuration management InfluxDB Cloud is programmatically managed and deployed using “infrastructure as code” which undergoes version control and testing as part of the automated deployment process. Permission to push code is tightly controlled, requiring peer review and approval by designated infrastructure engineers, and has automated safeguards to prevent production-impacting events. ### Secure software development life cycle (SDLC) InfluxData follows security best practices throughout the development cycle, including: * Security control points at multiple phases of development. * Manual security code review on critical assets. * Security considered in the design phase, starting with architecture review and threat modeling. * Source code management: * Version control * Mandatory peer code review * Automated functional testing and static code analysis * Automated vulnerability scans on third-party dependencies and libraries * Automated vulnerability scans on containers. * Regular dynamic application security testing and third-party penetration tests. * Regular engineering team training in secure application development practices. ### Separation of environments and duties Production and non-production environments are separate. Developers use non-production environments solely for development, testing, and staging, and do not use user data for non-production use cases. Production access is limited to authorized personnel based on the principles of least privilege and separation of duties. ### Monitoring, logging, and alerting InfluxData continuously monitors and analyzes metrics from InfluxDB Cloud environments. * Services are carefully monitored to ensure performance and availability, and to detect anomalies. * Application logging, performance, and observability data are gathered and used for event analysis, capacity planning, alerting, and instrumentation. Access to these logs and operator interfaces is controlled by group access permissions, and provided only to teams that require access to deliver InfluxDB Cloud services. ### Security assessments We use trusted third-party security firms to complete penetration testing to discover vulnerabilities post-development, and validate remediations from previous engagements. This includes white box and gray box testing against InfluxDB Cloud. ### Business continuity and disaster recovery InfluxData is a highly distributed organization with employees located across the globe. Our IT infrastructure is cloud-based and there is no on-premises infrastructure. This allows us to access services from anywhere around the globe and rely upon the disaster recovery capabilities of our service providers to ensure our own business continuity. As a cloud-native company, all of InfluxData’s business functions that are provided by cloud vendors rely on those vendors’ Service Level Agreements (SLA) to maintain the services provided to InfluxData. The Business Continuity Plan and Disaster Recovery Plan are updated annually. ### Data durability Data is replicated within multiple storage engines of InfluxDB Cloud. The replication mechanism executes a serializable upsert and delete stream against all replicas and runs background entropy detection processes to identify diverged replicas. Ingested data is also recorded out of band to provider-operated object storage. For more information, see [InfluxDB Cloud data durability](/influxdb/cloud/reference/internals/durability). ### Incident response Report security incidents to [security@influxdata.com](mailto:security@influxdata.com) or [support@influxdata.com](mailto:support@influxdata.com). We maintain procedures for incident alerting and response, performance or downtime events, security, and customer notification. We perform root cause analysis (RCA) as part of our incident response. ## Configurable security controls Users can configure the following security controls: ### Access, authentication, and authorization InfluxDB Cloud authentication and authorization We use [Auth0](https://auth0.com/) for InfluxDB Cloud authentication. User accounts can be created directly on the InfluxDB Cloud system via Auth0. Users also have the option to use “social sign-on” with their existing Google or Microsoft accounts for authentication. API access within custom applications requires an API token. Tokens belong to an organization and are mapped to InfluxDB permissions within the organization as defined when the token is created. For more information on the types of tokens and ways to create them, see [Manage API tokens](/influxdb/cloud/admin/tokens/). ### Role-based access controls (RBAC) InfluxDB Cloud accounts support multiple users in an organization. By default, each user with the *Owner* role has full permissions on resources in your organization. ### Advanced controls For users needing stricter security around data access and risk mitigation measures, we recommend the following: * **Single sign-on (SSO)**. Authentication requests from a particular email domain can be routed to an Enterprise SSO provider for authentication before they are provided with a valid session token to access InfluxDB Cloud UI. This is currently only available to users with annual commercial contracts. If you would like to set this up, please contact us at [sales@influxdata.com](mailto:sales@influxdata.com). * **Multi-factor authentication (MFA)**. Currently, we can enable MFA via an Enterprise SSO connection. MFA is then enabled on the user’s Enterprise SSO authentication provider. If you would like to set this up, please contact us at [sales@influxdata.com](mailto:sales@influxdata.com). * **Periodic API Token rotation**. We recommend that users periodically connect directly from their applications and automatically delete their current API tokens and create new tokens programmatically. Please refer to our [API documentation](/influxdb/cloud/api/authorizations-api-tokens/)for information on creating and deleting tokens programmatically. ## Compliance and auditing InfluxDB Cloud is **SOC2 Type II** certified. To request a copy of our SOC2 Type II report, or for information on the ISO 27001 Information Security Management System, please email [sales@influxdata.com](mailto:sales@influxdata.com). [security](/influxdb/cloud/tags/security/)[internals](/influxdb/cloud/tags/internals/) --- # InfluxDB Cloud system buckets Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/system-buckets/ #### Related * [Monitor data and send alerts](/influxdb/cloud/monitor-alert/) * [Process data with InfluxDB tasks](/influxdb/cloud/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/cloud/tags/buckets/) --- # Time To Become Readable Source: https://docs.influxdata.com/influxdb/cloud/reference/internals/ttbr/ **Time To Become Readable (TTBR)** is the delay between when you write data to InfluxDB Cloud and when that data becomes queryable. TTBR is variable and is affected by many factors. * [How write requests work in the InfluxDB Cloud API](#how-write-requests-work-in-the-influxdb-cloud-api) * [Flux vs InfluxQL](#flux-vs-influxql) * [InfluxDB Cloud TTBRs](#influxdb-cloud-ttbrs) ## How write requests work in the InfluxDB Cloud API Whenever you send a write request to the `/api/v2/write` endpoint, the following actions occur: 1. API validates the request and queues the write. 2. If the write is queued, API responds with an HTTP 204 status code. 3. API handles the write asynchronously and reaches eventual consistency. *For more information, see [`/api/v2/write` documentation](/influxdb/cloud/api/write-data/).* > [!Note] > The returned 204 status code does not mean that the point is queryable; > it means the write request has been added to the durable write queue*(for more information, see[Handle write and delete responses](/influxdb/cloud/write-data/troubleshoot/#handle-write-and-delete-responses))*. > TTBR represents the time it takes for the write request to be queued, > the write operation to be executed, **and** the data to become queryable. > > For more information about status codes returned from the `/api/v1/write` endpoint ## Flux vs InfluxQL One of the primary factors that affects TTBR is the query language you use to query the newly written data. InfluxQL queries use a metadata cache that stores information about fields and series. **If you write a point with a new field**, the new field will not be queryable by InfluxQL until InfluxDB Cloud refreshes the metadata cache, which can take up to 15 minutes. Flux does not rely on the metadata cache, so the newly written data should be queryable in approximately one second. **If you write a point with an existing field**, and the field already exists in the metadata cache, both InfluxQL and Flux should be able to query the new data in approximately one second. ## InfluxDB Cloud TTBRs |Write request to|Flux| InfluxQL | |----------------|----|-----------| | Existing field |≈1s | ≈1s | | New field |≈1s |≈10m to 15m| #### Related * [Write data to InfluxDB](/influxdb/cloud/write-data/) * [Query data in InfluxDB](/influxdb/cloud/query-data/) [write](/influxdb/cloud/tags/write/)[query](/influxdb/cloud/tags/query/) | Write request to | Flux | InfluxQL | | --- | --- | --- | | Write request to | Flux | InfluxQL | | Existing field | ≈1s | ≈1s | | New field | ≈1s | ≈10m to 15m | --- # InfluxDB key concepts Source: https://docs.influxdata.com/influxdb/cloud/reference/key-concepts/ Before working with InfluxDB Cloud, it’s helpful to learn a few key concepts. Browse the topics and videos below to learn more. ### [InfluxDB data elements](/influxdb/cloud/reference/key-concepts/data-elements/) InfluxDB structures data using elements such as timestamps, field keys, field values, tags, etc. ### [InfluxDB data schema](/influxdb/cloud/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/cloud/reference/key-concepts/design-principles/) Principles and tradeoffs related to InfluxDB design. [key concepts](/influxdb/cloud/tags/key-concepts/) --- # InfluxDB data elements Source: https://docs.influxdata.com/influxdb/cloud/reference/key-concepts/data-elements/ InfluxDB Cloud 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/write-data/best-practices/schema-design) can prevent [high series cardinality](/influxdb/cloud/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 Cloud (TSM) Cloud (TSM), a [series key](/influxdb/cloud/reference/glossary/#series-key) is a unique combination of measurement, tag set, and field key. For example, the [sample data](#sample-data) includes two unique series keys: |measurement| tag set |field key| |-----------|-----------------------------------|---------| | census |location=klamath,scientist=anderson| bees | | census |location=portland,scientist=mullen | ants | 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 bees * 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/cloud/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/cloud/admin/buckets/). ## Organization An InfluxDB **organization** is a workspace for a group of [users](/influxdb/cloud/admin/users/). All [dashboards](/influxdb/cloud/visualize-data/dashboards/), [tasks](/influxdb/cloud/process-data/), buckets, and users belong to an organization. For more information about organizations, see [Manage organizations](/influxdb/cloud/admin/organizations/). If you’re new to using InfluxDB, see how to [get started](/influxdb/cloud/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/) [key concepts](/influxdb/cloud/tags/key-concepts/)[schema](/influxdb/cloud/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 | field key | | --- | --- | --- | | measurement | tag set | field key | | census | location=klamath,scientist=anderson | bees | | census | location=portland,scientist=mullen | ants | --- # InfluxDB data schema Source: https://docs.influxdata.com/influxdb/cloud/reference/key-concepts/data-schema/ InfluxDB [data elements](/influxdb/cloud/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/cloud/query-data/execute-queries/data-explorer/#view-raw-data) when [exploring metrics with InfluxDB](/influxdb/cloud/visualize-data/explore-metrics) * To return query results in [annotated CSV syntax](/influxdb/cloud/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/cloud/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/cloud/query-data/flux/group-data/). [key concepts](/influxdb/cloud/tags/key-concepts/) --- # InfluxDB design principles Source: https://docs.influxdata.com/influxdb/cloud/reference/key-concepts/design-principles/ 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/cloud/write-data/best-practices/duplicate-points/). [key concepts](/influxdb/cloud/tags/key-concepts/)[design principles](/influxdb/cloud/tags/design-principles/) --- # Policies and procedures Source: https://docs.influxdata.com/influxdb/cloud/reference/policies/ ### [Product and feature end-of-life procedures](/influxdb/cloud/reference/policies/end-of-life/) InfluxData adheres to the following process for any End-of-Life (EOL) of products and features, including the shutdown of InfluxDB Cloud regions. --- # Product and feature end-of-life procedures Source: https://docs.influxdata.com/influxdb/cloud/reference/policies/end-of-life/ InfluxData adheres to the following process for any End-of-Life (EOL) of products and features, including the shutdown of InfluxDB Cloud regions. 1. **Email Notices**: Customers are given at least six months notice of the change in service via the following communication methods: * Email notifications are sent to all users and billing contacts associated with the account. * Emails are sent as “Service Notification” emails that customers and users cannot opt out of. Service Notifications are limited to critical service changes or updates and come from a support or formal alert alias. * Initial email notifications are followed by at least two additional reminders. For longer notice periods (one year or more), reminders are sent at least quarterly. As the date approaches, additional reminders are sent. Any new accounts established after the date of the first email notification that are impacted by the service shutdown are included in the subsequent reminders. 2. **Non-Email Notification**: Notifications and reminders are added to the following areas: * In-app notification for InfluxDB products that include a user interface (UI) that users must read or acknowledge in order to proceed in the app. * For annual accounts or accounts billing more than $500 USD per month, an additional personal outreach is attempted by a Sales Team Member or Technical Support Team member. -[docs.influxdata.com](https://docs.influxdata.com) notification informing visitors of the upcoming end-of-life. The notification remains from the date of the first email through the end-of-life date. * Reminders published in the InfluxDB Community Slack channel starting on the day of the initial email and the day before the event. * For any planned InfluxDB Cloud cluster removal, a banner notification is added to the InfluxData status page located at [status.influxdata.com](https://status.influxdata.com)at the same time the first notification is sent (at least six months in advance of the shutdown). 3. **Fail-Safe Controls**: Because the above communication methods may not be 100% effective, InfluxData implements the following fail-safe controls to allow for a “scream test” with the ability to notify customers via an outage and wait to see who responds before shutting down the service or feature and before deleting any data. At least 30 days before the scheduled service removal, InfluxData temporarily disables the service (in a fully reversible manner) for up to 24 hours so that all users relying on the service should be able to detect the service loss and can get assistance. After 24 hours, the service is returned to normal operation. Depending on the results of the first “scream test,” InfluxData may perform additional scream tests. * As soon as the first “scream test” is started, a banner is added to the top of the [status.influxdata.com](https://status.influxdata.com) page advising users about the service removal. This banner stays in place until the service is fully removed. * *Feature Flagging*: For reversible actions and other changes that can be feature flagged, InfluxData adds a feature flag, which enables flexibility to turn off the service for everyone, but still allow it for individual accounts in case of emergency. * *System Backup*: Back up the system at the point in time of execution of the end-of-life, including data and configuration when appropriate. * *Export Capability*: For any end-of-life event that would cause customer data to be deleted, an export capability exists to give the customer a reasonable method of exporting their data. * *Waiting Period*: There is at least a 30-day waiting period from disablement of service before the service is actually removed. This allows 30 days for customers and users to report a service outage and notify them if they were not aware of the end-of-life. 4. **Data Recovery**: If a customer contacts us within the 30-day waiting period, InfluxData restores the service when possible, or provides backups of data if a restore of the service is not possible. 5. **Data Retention**: Data retention in InfluxDB Cloud is described in InfluxData’s [Data retention documentation](/influxdb/cloud/reference/internals/data-retention/)and SOC-2 Statement. --- # Prometheus metric parsing formats Source: https://docs.influxdata.com/influxdb/cloud/reference/prometheus-metrics/ [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*| |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/cloud/write-data/developer-tools/scrape-prometheus-metrics/) * [Work with Prometheus in Flux](/flux/v0/prometheus/) * [Telegraf Prometheus input plugin](/telegraf/v1/input-prometheus) * [prometheus.scrape() function](/flux/v0/stdlib/experimental/prometheus/scrape/) [prometheus](/influxdb/cloud/tags/prometheus/) | Scraping tool | InfluxDB Metric version | | --- | --- | | Scraping tool | InfluxDB Metric version | | Telegraf Prometheus plugin | Determined by metric_version configuration option | | 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 | --- # InfluxDB Cloud regions Source: https://docs.influxdata.com/influxdb/cloud/reference/regions/ InfluxDB Cloud is available on multiple cloud providers and in multiple regions. Each region has a unique InfluxDB Cloud URL and API endpoint. Use the URLs below to interact with your InfluxDB Cloud instances with the[InfluxDB API](/influxdb/cloud/reference/api/), [InfluxDB client libraries](/influxdb/cloud/api-guide/client-libraries/),[`influx` CLI](/influxdb/cloud/reference/cli/influx/), or [Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/). [Request a cloud region](https://www.influxdata.com/influxdb-cloud-2-0-provider-region/) > [!Note] > #### Regions with multiple clusters > > Some InfluxDB Cloud regions have multiple Cloud clusters, each with a unique URL. > To find your cluster URL, [log in to your InfluxDB Cloud organization](https://cloud2.influxdata.\> com) > and review your organization URL. The first subdomain identifies your > InfluxDB Cloud cluster. For example: > > ``` > https://us-west-2-1.aws.cloud2.influxdata.com/orgs/03a2bbf46249a000/... > ``` ### Amazon Web Services (AWS) | Region | Location | URL(s) | |:-----------------|:-----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | US West (Oregon) | Oregon, USA |us-west-2-1: [https://us-west-2-1.aws.cloud2.influxdata.com](https://us-west-2-1.aws.cloud2.influxdata.com)

us-west-2-2: [https://us-west-2-2.aws.cloud2.influxdata.com](https://us-west-2-2.aws.cloud2.influxdata.com)| |US East (Virginia)| Virginia, USA | [https://us-east-1-1.aws.cloud2.influxdata.com](https://us-east-1-1.aws.cloud2.influxdata.com) | | EU Frankfurt |Frankfurt, Germany| [https://eu-central-1-1.aws.cloud2.influxdata.com](https://eu-central-1-1.aws.cloud2.influxdata.com) | ### Google Cloud Platform (GCP) | Region |Location | URL(s) | |:----------------|:--------|:-------------------------------------------------------------------------------------------------| |US Central (Iowa)|Iowa, USA|[https://us-central1-1.gcp.cloud2.influxdata.com](https://us-central1-1.gcp.cloud2.influxdata.com)| ### Microsoft Azure | Region | Location | URL(s) | |:----------------------|:---------------------|:---------------------------------------------------------------------------------------------------| |West Europe (Amsterdam)|Amsterdam, Netherlands|[https://westeurope-1.azure.cloud2.influxdata.com](https://westeurope-1.azure.cloud2.influxdata.com)| | East US (Virginia) | Virginia, USA | [https://eastus-1.azure.cloud2.influxdata.com](https://eastus-1.azure.cloud2.influxdata.com) | | Region | Location | URL(s) | | --- | --- | --- | | Region | Location | URL(s) | | US West (Oregon) | Oregon, USA | us-west-2-1: https://us-west-2-1.aws.cloud2.influxdata.com us-west-2-2: https://us-west-2-2.aws.cloud2.influxdata.com | | US East (Virginia) | Virginia, USA | https://us-east-1-1.aws.cloud2.influxdata.com | | EU Frankfurt | Frankfurt, Germany | https://eu-central-1-1.aws.cloud2.influxdata.com | | Region | Location | URL(s) | | --- | --- | --- | | Region | Location | URL(s) | | US Central (Iowa) | Iowa, USA | https://us-central1-1.gcp.cloud2.influxdata.com | | Region | Location | URL(s) | | --- | --- | --- | | Region | Location | URL(s) | | West Europe (Amsterdam) | Amsterdam, Netherlands | https://westeurope-1.azure.cloud2.influxdata.com | | East US (Virginia) | Virginia, USA | https://eastus-1.azure.cloud2.influxdata.com | --- # Release notes Source: https://docs.influxdata.com/influxdb/cloud/reference/release-notes/ Find important information about what’s included in new versions of our products: ### [InfluxDB Cloud updates](/influxdb/cloud/reference/release-notes/cloud-updates/) Important changes and what’s new in each InfluxDB Cloud update. ### [influx CLI release notes](/influxdb/cloud/reference/release-notes/influx-cli/) Important changes and what’s new in each version of the influx command line interface (CLI). --- # InfluxDB Cloud updates Source: https://docs.influxdata.com/influxdb/cloud/reference/release-notes/cloud-updates/ InfluxDB Cloud updates occur frequently. Find a compilation of recent updates below. To find information about the latest Flux updates in InfluxDB Cloud, see [Flux release notes](/influxdb/cloud/reference/release-notes/flux/). ## April 2025 ### Flux VS Code extension no longer maintained `vsflux` is no longer available in the Visual Studio Marketplace. The `vsflux` Visual Studio Code extension and the `flux-lsp` Flux Language Server Protocol plugin are no longer maintained. Their repositories have been archived and are no longer receiving updates. ## October 2022 ### Custom data retention periods Set a custom data retention period for a bucket. Note that free users can only retain data up to 30 days. ### MQTT connector Connect to your MQTT subscription from the InfluxDB Cloud UI. ## September 2022 ### Time zone selector Choose the time zone for individual dashboard cells. ### Adaptive zoom Get a more granular view of graph visualizations by zooming in and requerying the data. For details, see [Graph visualizations](/influxdb/cloud/visualize-data/visualization-types/graph/). ### Arduino onboarding Quickly get started with Arduino within minutes of logging in with the Arduino wizard. ## August 2022 ### CLI onboarding The command line interface (CLI) onboarding wizard minimizes the learning curve for using the CLI, making it easy to use within a few minutes of logging in. ### Switch organizations and accounts in the header Quickly access settings and navigate between multiple accounts or, if applicable, multiple organizations, in the header menu. ## July ### Request a proof of concept from the UI Request a proof of concept (POC) from the help options in the InfluxDB Cloud UI. A sales representative will contact you to customize a POC for your data and use case. ### Accessible graph color options To ensure graphing functionality is accessible to colorblind users, we added two additional colorblind-friendly color pallet graph customization options. ### Sample IoT application and code snippets for Python Quickly start writing and querying your data with **Python**. Now, when you complete the **Python** onboarding wizard, you’ll have the option to do either of the following: * View an IoT [Sample App](https://github.com/influxdata/iot-api-python) written in Python. * View [Boilerplate Snippets](https://github.com/InfluxCommunity/sample-flask/blob/main/app.py/) of code in Python. ## June 2022 ### Private InfluxDB Cloud offering New support for private InfluxDB Cloud offering on AWS, Azure, and Google Cloud Marketplaces for annual customers. Please contact sales@influxdata.com for more information. ### Sample IoT application and code snippets for Node.js Quickly start writing and querying your data with **JavaScript/Node.js**. Now, when you complete the **JavaScript/Node.js** onboarding wizard, you’ll have the option to do either of the following: * View an IoT [Sample App](https://github.com/influxdata/iot-api-js) written in Node.js. * View [Boilerplate Snippets](https://github.com/influxdata/nodejs-samples/) of code in Node.js. ### Help bar updates * If you have a [Usage-Based plan](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan), you can now submit **Support requests** and questions directly to our **Salesforce Support queue** (without needing a Salesforce account). Hover over the question mark in InfluxDB Cloud, and select **Contact Support**. You’ll receive a confirmation email with your ticket number for reference. * Add a [Status page](https://status.influxdata.com/) to display InfluxDB uptime, downtime, and incident management information for all Cloud regions. Hover over the question mark in InfluxDB Cloud, and select **Status Page**. * Add a link to quickly access InfluxDB University. Hover over the question mark in InfluxDB Cloud, and select [InfluxDB University](https://university.influxdata.com/). ### Bug fixes * Keep the time picker on the screen when the Script Editor is open. * Escape commas in strings that were breaking the rendering of table visualizations. * Add a Copy to Clipboard button to copy the organization name on the Organization Settings page. * Ensure the following: * The Copy button no longer hides graph error messages. * Nested objects no longer break tables. * Query Explorer displays results when data is returned. * Single Usage stats text is selectable. * Users get redirected to the Login page after a session expires. * Renamed “Token last used” to “Token last modified” to be more accurate and descriptive. ## May 2022 ### Bulk delete API tokens Efficiently delete multiple tokens at once. For details, see [Delete a token using the InfluxDB API](/influxdb/v2/admin/tokens/delete-token/#delete-a-token-using-the-influxdb-api). ### Help bar Find relevant content easily from the Cloud UI using the help tab in left side panel. ## April 2022 ### Query improvements in Data Explorer and notebooks It’s now easier to use the visual builder to create queries in the Data Explorer and notebooks: * The builder requires you to select a measurement before you can select associated tags. * All measurements, fields, tags, and tag values appear in the builder, not just the ones in the currently specified time range. This update ensures that measurements, fields, and tags, are visible even if you set a very short time range. ### Onboarding wizards for common programming languages During onboarding, choose the Python, JavaScript, or Go wizard to quickly get started writing data and executing simple queries. For details, see [Write and query data using the programming language of your choice](/influxdb/cloud/get-started/#write-and-query-data-using-the-programming-language-of-your-choice). ## March 2022 ### Deep linking Navigate to UI pages without having to enter your organization ID in the URL using deep links. For example, `cloud2.influxdata.com/me/billing` redirects to your organization’s billing page. ## February 2022 ### Remove yourself from an organization You can now remove yourself as a member of an organization in the Cloud UI. For details, see [Remove a user from your organization](/influxdb/cloud/admin/organizations/users/#remove-a-user-from-your-organization/). ### Add auto-refresh functionality to Notebooks Automatically refresh Notebooks data. For details, see [Create a notebook](/influxdb/cloud/tools/notebooks/create-notebook/). ## Performance improvements to dashboards and queries Previously, InfluxDB loaded all variables on the client side, even those not included in a dashboard or query. Now, InfluxDB only loads variables used by queries or dashboards. ## January 2022 ### Update Tokens UI To enhance security, the Tokens UI will only display an InfluxDB Cloud token when it’s [first created](/influxdb/cloud/admin/tokens/create-token/). If you return to the Token page later, you won’t be able to view or copy the token. To learn more about token access restrictions, see [Create an API token](/influxdb/cloud/admin/tokens/create-token/). ### Multi-account support You can now invite a user to join an organization using the same email they’ve used in another InfluxDB Cloud account. Users [can switch between accounts in the UI](/influxdb/cloud/account-management/switch-account/). ## December 2021 * **Paginated dashboards in UI**: Previously, the Dashboards page could take awhile to load with more than a few dashboards. Now, all dashboards are immediately paginated and accessible on the Dashboards page. * **$250 usage credit**: Available when you choose a usage-based plan during signup. * **Improved task reliability and reporting** * **Improved error handling** for InfluxQL queries. * When you select a bucket from **Data (Load Data) \> Buckets**, the bucket opens in Notebooks. ## November 2021 * [Remove Website demo data](#remove-website-demo-data) * [Add sample data buckets to Notebooks UI](#add-sample-data-buckets-to-notebooks-ui) * [Add ability to share notebooks](#add-ability-to-share-notebooks) ### Remove Website Demo Data To improve user experience and consolidate system-delivered data, we removed the Website Demo Data bucket in Data Explorer, and now provide new sample data buckets in notebooks (see [Add sample data buckets to Notebooks UI](#add-sample-data-buckets-to-notebooks-ui)). If you’ve used the Website Demo Data bucket in the past, your existing demo data isn’t affected, and you may continue to use the data as needed. ### Add sample data buckets to Notebooks UI To get started with sample data in InfluxDB Cloud, check out the new sample data buckets in the Notebooks UI, which support a variety of use cases. Sample data buckets provide a way to explore InfluxDB without ingesting your own data. Now, you can add the following buckets with sample data to your notebooks: * Air Sensor Data * Coinbase bitcoin price * NOAA National Buoy Data * USGS Earthquakes ### Add ability to share notebooks Add ability to [share a notebook](/influxdb/cloud/tools/notebooks/manage-notebooks/#share-a-notebook) in the InfluxDB Cloud notebook UI. ## October 2021 * [API invokable scripts](#api-invokable-scripts) * [New UI design](#new-ui-design) * [Flux update](#flux-update) * [Telegraf configuration UI](#telegraf-configuration-ui) ### API invokable scripts Use [API invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) to assign and execute a script through an API endpoint. ### New UI design Refresh the look and feel of InfluxDB Cloud UI. The updated icons, fonts, and layouts improve visibility, accessibility, and user experience. The updated icons, fonts, and layouts improve visibility, accessibility, and user experience. For those interested in the code, check out the [Clockface UI kit](https://github.com/influxdata/clockface). ### Flux update Upgrade to [Flux v0.139](/flux/v0/release-notes/). ### Telegraf configuration UI Update Telegraf configuration in the UI to make it easier to set up and configure Telegraf plugins. See how to [use the InfluxDB UI to generate and store new Telegraf plugins](/influxdb/cloud/tools/telegraf-configs/create/#use-the-influxdb-ui). ## September 2021 * **Paginated tasks in UI**: Previously, the Tasks page only listed the first 100 tasks. Now, all tasks are accessible and paginated on the Tasks page. * **Enhanced Flux VS Code extension to include tasks**: Add ability to create and edit [InfluxDB tasks](/influxdb/v2/process-data/get-started/) in Visual Studio Code using the Flux extension. See how to [use the Flux VS Code extension](/influxdb/v2/tools/flux-vscode/). ## August 2021 * Add support for [explicit bucket schemas](/influxdb/cloud/admin/buckets/bucket-schema/), which lets you enforce explicit schemas for each InfluxDB measurement, including column names, tags, fields, and data types. * Add ability to convert [notebook cells into raw Flux script](/influxdb/cloud/tools/notebooks/create-notebook/#view-and-edit-flux-script-in-a-cell). Now you can view and edit the code. * Add [delete request rate limits](/influxdb/cloud/account-management/data-usage/#exceeded-rate-limits) per organization. ## July 2021 * Add new [Asia Pacific (Australia) region](https://ap-southeast-2-1.aws.cloud2.influxdata.com). * Redesign the View Raw Data table in Data Explorer. Group keys and data types are now easily identifiable underneath column headings. * Dashboard improvements: * Add ability to add an [annotation to a specific time range](/influxdb/cloud/visualize-data/annotations/). * Add ability to [automatically refresh dashboard](/influxdb/cloud/visualize-data/dashboards/control-dashboard/#automatically-refresh-dashboard). * Add new static legend to Graph and Band Plot visualizations. ## May 2021 * Add new [Cloud 2 Usage Dashboard template](https://github.com/influxdata/community-templates/tree/master/usage_dashboard) to monitor your Cloud usage data, including rate limiting events. For more detail on Cloud data usage and rate limiting events, see how to [view InfluxDB Cloud data usage](/influxdb/cloud/account-management/data-usage/). For more detail on how to install and customize this template, see [InfluxDB templates in InfluxDB Cloud](/influxdb/cloud/tools/influxdb-templates/cloud/). * Add support for [using annotations](/influxdb/cloud/visualize-data/annotations/) in your dashboards. * Add new [map visualization](/influxdb/cloud/visualize-data/visualization-types/map/) to display geo-temporal data. ## April 2021 * Add new [GCP Europe West (Belgium) region](/influxdb/cloud/reference/regions/#google-cloud-platform-gcp). * Add [mosaic visualization](/influxdb/cloud/visualize-data/visualization-types/mosaic/). Use this visualization to display state changes in your time series data. * Add [notebooks](/influxdb/cloud/tools/notebooks/). Use notebooks to build and share ways to explore, visualize, and process your time series data. Learn how notebooks can help you [downsample](/influxdb/cloud/tools/notebooks/downsample/) and [normalize](/influxdb/cloud/tools/notebooks/clean-data/) your time series data. ## January 2021 * [New AWS and Microsoft regions](#aws-and-microsoft-regions) * [Microsoft social sign-on](#microsoft-social-sign-on) * [InfluxDB community templates](#influxdb-community-templates) * [Load Data updates](#load-data-updates) * [Visualization updates](#visualization-updates) * [CLI updates](#cli-updates) * [API updates](#api-updates) * [Task updates](#task-updates) * [Telegraf plugins in UI](#telegraf-plugins-in-ui) * [Performance improvements](#performance-improvements) ### AWS and Microsoft regions * Add support for Microsoft Azure and new AWS regions: * [Microsoft Azure](/influxdb/cloud/reference/regions/#microsoft-azure): * West Europe (Amsterdam) region * East US (Virginia) region * [AWS](/influxdb/cloud/reference/regions/#amazon-web-services-aws): * US East (Virginia) region ### Microsoft social sign-on * Add [Microsoft (Windows Live) social sign-on](https://cloud2.influxdata.com/signup). Use your Windows Live credentials to easily sign in to your InfluxDB Cloud account. ### InfluxDB community templates * Access any [InfluxDB community template](https://github.com/influxdata/community-templates#templates) directly in the Cloud user interface (UI). For more details, see how to [install and customize a template in the UI](/influxdb/cloud/tools/influxdb-templates/cloud/). * Use the new [InfluxDB 2 Operational Monitoring community template](https://github.com/influxdata/community-templates/tree/master/influxdb2_operational_monitoring) to monitor InfluxDB OSS 2.0. ### Load Data updates * Redesign the Load Data page to increase discovery and ease of use. Now, you can [load data from sources directly in the InfluxDB user interface](/influxdb/cloud/write-data/no-code/load-data/). * Add support for new data sources: * InfluxDB v2 Listener * NSD * OPC-UA * Windows Event Log ### Visualization updates * Add new [Band Plot visualization](/influxdb/v2/visualize-data/visualization-types/band/). * Add the `legendColorizeRows` property to toggle the color on and off in the legend. ### CLI updates * Usability improvements to `influx` CLI: * Add option to print raw query results in [`influx query`](/influxdb/cloud/reference/cli/influx/query/). * Add ability to export resources by name using [`influx export`](/influxdb/cloud/reference/cli/influx/export/). * Add new processing options and enhancements to [`influx write`](/influxdb/cloud/reference/cli/influx/write/). * Add `--active-config` flag to [`influx`](/influxdb/cloud/reference/cli/influx/) commands to set the configuration for a single command. * Add `max-line-length` flag to the [`influx write`](/influxdb/cloud/reference/cli/influx/write/) command to address “token too long” errors for large inputs. * Add `--force` flag to the [`influx stacks rm`](/influxdb/cloud/reference/cli/influx/stacks/remove/) command, which lets you remove a stack without the confirmation prompt. * Allow password to be specified as a CLI option in [`influx v1 auth create`](/influxdb/cloud/reference/cli/influx/v1/auth/create/#flags). * Allow password to be specified as a CLI option in [`influx v1 auth set-password`](/influxdb/cloud/reference/cli/influx/v1/auth/set-password/). * Improve ID-related error messages for [`influx v1 dbrp`] commands. ### API updates * [List all buckets](/influxdb/cloud/api/buckets/) in the API now supports the `after` parameter as an alternative to `offset`. * Add the `v1/authorization` package to support authorizing requests to the InfluxDB 1.x API. ### Task updates * Record the last success and failure run times in tasks. * Inject the task option `latestSuccessTime` in Flux Extern. ### 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. ## 2020-9-25 ### Install and customize InfluxDB community templates in the Cloud UI Install and customize any [InfluxDB community template](https://github.com/influxdata/community-templates#templates) directly in the Cloud user interface (UI). For more details, see how to [install and customize a template in the UI](/influxdb/cloud/tools/influxdb-templates/cloud/). ## 2020-09-02 ### Pricing updates and Azure region * Update [pricing vectors](/influxdb/cloud/account-management/pricing-plans/#pricing-vectors) to determine pricing by the total data out and query count. * Add [Microsoft Azure support](/influxdb/cloud/reference/regions/#microsoft-azure) for the `eastus` and `westeurope` regions. Each region has a unique InfluxDB Cloud URL and API endpoint. ### Bug fixes * Resolve issues in checks and notifications. ## 2019-09-10 *Monitoring & Alerts* ## Features * **InfluxDB OSS 2.0 alpha-17** –*See the [alpha-17 release notes](/influxdb/v2/reference/release-notes/influxdb/#v200-alpha17) for details.* * Alerts and Notifications to Slack (Free Plan), PagerDuty and HTTP (Usage-based Plan). * Rate limiting on cardinality for Free Plan. * Billing notifications. * Pricing calculator. * Improved Signup flow. ## 2019-07-23 *General Availability* ### Features * **InfluxDB OSS 2.0 alpha-15** –*See the [alpha-9 release notes](/influxdb/v2/reference/release-notes/influxdb/#v200-alpha15) for details.* * Usage-based Plan. * Adjusted Free Plan rate limits. * Timezone selection in the user interface. ## 2019-05-06 *Public Beta* ### Features * Add rate limiting for Free Plan users. * Add client libraries for Go and JS. ### Bug fixes * Users cannot delete themselves from their Cloud account. * The bucket retention period for Free Plan users is set to 72 hours. * Free Plan users cannot change a bucket’s retention period. ## 2019-05-02 ### Features * **InfluxDB OSS 2.0 alpha-9** –*See the [alpha-9 release notes](/influxdb/v2/reference/release-notes/influxdb/#v200-alpha9) for details.* ### Bug fixes * Usage statistics on the Usage page show correct values. * Existing tasks with duration specified in nanoseconds no longer need to be resubmitted. * Removed the additional user that showed up as an owner under the Cloud organization. * Cloud users can use CLI tools to interact with their Cloud tenant. ## 2019-04-05 ### Features * **InfluxDB OSS 2.0 alpha-7** –*See the [alpha-7 release notes](/influxdb/v2/reference/release-notes/influxdb/#v200-alpha7) for details.* ### Bug fixes * Logout works in InfluxDB Cloud UI. * Single sign-on works between https://cloud2.influxdata.com and https://us-west-2-1.aws.cloud2.influxdata.com. * Able to copy error message from UI. * Able to change a task from every to cron. * Able to create a new bucket when switching between periodically and never (retention options). --- # influx CLI release notes Source: https://docs.influxdata.com/influxdb/cloud/reference/release-notes/influx-cli/ ## 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/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/org/members/add/). * Add the [InfluxQL Shell (REPL)](/influxdb/cloud/reference/cli/influx/v1/shell/). * **(InfluxDB Cloud only)** Manage [InfluxDB Cloud Invokable Scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)with [`influx scripts`](/influxdb/cloud/reference/cli/influx/scripts/). ### 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/cloud/reference/cli/influx/remote/) command. * Add [`influx replication`](/influxdb/cloud/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 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/cloud/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. --- # Sample data Source: https://docs.influxdata.com/influxdb/cloud/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. 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/cloud/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/cloud/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/cloud/query-data/flux/sql/#join-sql-data-with-data-in-influxdb)in the [Query SQL data sources](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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) > [!Note] > #### Static sample data and bucket retention periods > > If writing a static sample dataset to a bucket with a limited retention period, > use [sample.alignToNow()](/flux/v0/stdlib/influxdata/influxdb/sample/aligntonow/)to shift timestamps to align the last point in the set to now. > This will prevent writing points with timestamps beyond the bucket’s retention period. > For example: > > ``` > import "influxdata/influxdb/sample" > > sample.data(set: "birdMigration") > |> sample.alignToNow() > |> to("example-bucket") > ``` ### 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/cloud/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/cloud/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/cloud/query-data/common-queries/) and[Common tasks](/influxdb/cloud/process-data/common-tasks/) guides. --- # InfluxDB Cloud (TSM) service notices Source: https://docs.influxdata.com/influxdb/cloud/reference/service-notices/ Important service notices related to the InfluxDB Cloud (TSM) platform. ### [End-of-Life of Native Collector - MQTT](/influxdb/cloud/reference/service-notices/native-collector-mqtt-eol/) InfluxData has made a strategic decision to end-of-life (EOL) the Native Collector - MQTT feature that is currently available in InfluxDB Cloud (TSM) on **April 30th, 2024**. --- # End-of-Life of Native Collector - MQTT Source: https://docs.influxdata.com/influxdb/cloud/reference/service-notices/native-collector-mqtt-eol/ InfluxData has made a strategic decision to end-of-life (EOL) the Native Collector - MQTT feature that is currently available in InfluxDB Cloud (TSM). This EOL will take effect **April 30th, 2024**, after which this feature will be completely removed from InfluxDB Cloud (TSM) and will no longer be supported. Please refer to the FAQ below for more details and guidance on alternate solutions currently available. * [What is the Native Collector - MQTT Feature?](#what-is-the-native-collector---mqtt-feature) * [Why is this feature being EOL’d?](#why-is-this-feature-being-eold) * [What alternatives are available in light of this EOL announcement?](#what-alternatives-are-available-in-light-of-this-eol-announcement) * [What are the expected next steps?](#what-are-the-expected-next-steps) * [Will I lose any data already ingested?](#will-i-lose-any-data-already-ingested) * [Where can I get more information on using Telegraf as a replacement for Native Collector - MQTT?](#where-can-i-get-more-information-on-using-telegraf-as-a-replacement-for-native-collector---mqtt) ### What is the Native Collector - MQTT Feature? The Native Collector - MQTT feature was introduced in InfluxDB Cloud in 2022 as a way to ingest data directly from MQTT sources into InfluxDB Cloud. This feature has been removed and is no longer available to new customers or existing customers who have not been using it. It was only available to a limited number of existing customers who were actively using it. ### Why is this feature being EOL’d? The adoption of this feature was lower than anticipated given most customers continued to use [Telegraf](/telegraf/v1/), InfluxData’s data collection agent, which provides more features for MQTT ingestion than this feature did. After a thorough assessment, we determined that our customers can have a similar (and even superior) experience using the[MQTT Consumer Telegraf input plugin](https://www.influxdata.com/integration/mqtt-telegraf-consumer/). ### What alternatives are available in light of this EOL announcement? We recommend using [Telegraf](/telegraf/v1/) with the [MQTT Consumer Telegraf input plugin](https://www.influxdata.com/integration/mqtt-telegraf-consumer/)as an alternative to the Native Collector - MQTT feature. Telegraf is InfluxData’s popular open source data collection agent that comes with 300+ plugins for data input and output, including MQTT. ### What are the expected next steps? The Native Collector - MQTT feature will continue to work and function until**April 30th, 2024**. In the meantime, we won’t release any new enhancements to the feature. After the EOL date, we will decommission the feature, and any MQTT subscriptions that you have will no longer receive and ingest data into InfluxDB. ### Will I lose any data already ingested? No, data already written to InfluxDB will not be affected by this change. ### Where can I get more information on using Telegraf as a replacement for Native Collector - MQTT? See [MQTT Consumer Telegraf input plugin](https://www.influxdata.com/integration/mqtt-telegraf-consumer/). --- # InfluxDB syntaxes Source: https://docs.influxdata.com/influxdb/cloud/reference/syntax/ 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/cloud/reference/syntax/flux/) Flux is a functional data scripting language designed for querying, analyzing, and acting on data. ### [InfluxQL](/influxdb/cloud/reference/syntax/influxql/) InfluxQL is an SQL-like query language for interacting with data in InfluxDB. ### [Line protocol](/influxdb/cloud/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/cloud/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 or write data to InfluxDB using annotated CSV and the `influx write` command. ### [Delete predicate](/influxdb/cloud/reference/syntax/delete-predicate/) The InfluxDB `/delete` endpoint uses an InfluxQL-like predicate syntax to determine what data points to delete. [syntax](/influxdb/cloud/tags/syntax/) --- # Annotated CSV Source: https://docs.influxdata.com/influxdb/cloud/reference/syntax/annotated-csv/ 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/cloud/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/cloud/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/cloud/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/cloud/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 * [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/) [csv](/influxdb/cloud/tags/csv/)[syntax](/influxdb/cloud/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/cloud/reference/syntax/annotated-csv/extended/ **Extended annotated CSV** provides additional annotations and options that specify how CSV data should be converted to [line protocol](/influxdb/cloud/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/cloud/reference/syntax/annotated-csv/)annotations. The Flux [`csv.from` function](/flux/v0/stdlib/csv/from/) only supports[annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/), not extended annotated CSV. To write data to InfluxDB, line protocol must include the following: * [measurement](/influxdb/cloud/reference/syntax/line-protocol/#measurement) * [field set](/influxdb/cloud/reference/syntax/line-protocol/#field-set) * [timestamp](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) *(Optional but recommended)* * [tag set](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/cli/influx/write/#flags)to specify the [timestamp precision](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#string) field**. ##### double Column is a **[float](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/glossary/#boolean) field**. If column values are not [supported boolean values](/influxdb/cloud/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/cloud/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/cloud/write-data/developer-tools/csv/) * [influx write](/influxdb/cloud/reference/cli/influx/write/) * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) [csv](/influxdb/cloud/tags/csv/)[syntax](/influxdb/cloud/tags/syntax/)[write](/influxdb/cloud/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/cloud/reference/syntax/delete-predicate/ InfluxDB uses an InfluxQL-like predicate syntax to determine what data[points](/influxdb/cloud/reference/glossary/#point) to delete. InfluxDB uses the delete predicate to evaluate the [series keys](/influxdb/cloud/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/cloud/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/cloud/reference/syntax/influxql) syntax, [any InfluxQL keyword](/influxdb/cloud/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 Cloud** supports deleting data by any column or tag***except*** the following: * `_time` * `_value` ## 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 field](#delete-points-by-field) * [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 field The following will delete points with the `temperature` field: ```sql _field="temperature" ``` ### 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` or `_value`. #### Related * [Delete data](/influxdb/cloud/write-data/delete-data/) * [influx delete](/influxdb/cloud/reference/cli/influx/delete/) [syntax](/influxdb/cloud/tags/syntax/)[delete](/influxdb/cloud/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/cloud/reference/syntax/flux/ 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/cloud/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/cloud/tags/syntax/)[flux](/influxdb/cloud/tags/flux/) --- # Flux vs InfluxQL Source: https://docs.influxdata.com/influxdb/cloud/reference/syntax/flux/flux-vs-influxql/ Flux is an alternative to [InfluxQL](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/influxql/ ### [Influx Query Language (InfluxQL) 2.x specification](/influxdb/cloud/reference/syntax/influxql/spec/) Reference (spec) for Influx Query Language (InfluxQL) 2.x. ### [InfluxQL internals reference](/influxdb/cloud/reference/syntax/influxql/internals/) Read about the implementation of InfluxQL. --- # InfluxQL internals reference Source: https://docs.influxdata.com/influxdb/cloud/reference/syntax/influxql/internals/ Learn about the implementation of InfluxQL to understand how results are processed and how to create efficient queries: * [Query life cycle](#query-life-cycle) * [Understanding iterators](#understanding-iterators) * [Cursors](#cursors) * [Auxiliary fields](#auxiliary-fields) * [Built-in iterators](#built-in-iterators) * [Call iterators](#call-iterators) ## Query life cycle 1. InfluxQL query string is tokenized and then parsed into an abstract syntax tree (AST). This is the code representation of the query itself. 2. The AST is passed to the `QueryExecutor` which directs queries to the appropriate handlers. For example, queries related to meta data are executed by the meta service and `SELECT` statements are executed by the shards themselves. 3. The query engine then determines the shards that match the `SELECT`statement’s time range. From these shards, iterators are created for each field in the statement. 4. Iterators are passed to the emitter which drains them and joins the resulting points. The emitter’s job is to convert simple time/value points into the more complex result objects that are returned to the client. ### Understanding iterators Iterators provide a simple interface for looping over a set of points. For example, this is an iterator over Float points: ``` type FloatIterator interface { Next() *FloatPoint } ``` These iterators are created through the `IteratorCreator` interface: ``` type IteratorCreator interface { CreateIterator(opt *IteratorOptions) (Iterator, error) } ``` The `IteratorOptions` provide arguments about field selection, time ranges, and dimensions that the iterator creator can use when planning an iterator. The `IteratorCreator` interface is used at many levels such as the `Shards`,`Shard`, and `Engine`. This allows optimizations to be performed when applicable such as returning a precomputed `COUNT()`. Iterators aren’t just for reading raw data from storage though. Iterators can be composed so that they 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/cloud/reference/syntax/influxql/spec/ 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/cloud/query-data/influxql/explore-data/) * [Explore your schema with InfluxQL](/influxdb/cloud/query-data/influxql/explore-schema/) * [Query engine internals](/influxdb/cloud/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/cloud/reference/glossary/#database) names, [retention policy](/influxdb/cloud/reference/glossary/#retention-policy-rp) names, [user](/influxdb/cloud/reference/glossary/#user) names, [measurement](/influxdb/cloud/reference/glossary/#measurement) names, [tag keys](/influxdb/cloud/reference/glossary/#tag-key), and [field keys](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#measurement) name,[retention policy](/influxdb/cloud/reference/glossary/#retention-policy-rp) name,[subscription](/influxdb/cloud/reference/glossary/#subscription) name, and[user](/influxdb/cloud/reference/glossary/#user) name. In those cases, `time` does not require double quotes in queries.`time` cannot be a [field key](/influxdb/cloud/reference/glossary/#field-key) or[tag key](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#field-key) and [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/cloud/query-data/influxql/explore-data/select/) > * [measurements](/influxdb/cloud/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/cloud/query-data/influxql/explore-data/select/#from-clause) > * [tag values](/influxdb/cloud/reference/glossary/#tag-value) and string [field values](/influxdb/cloud/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/cloud/query-data/influxql/explore-data/where/) > * [tag keys](/influxdb/cloud/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/cloud/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/cloud/reference/glossary/#database), and [retention polices](/influxdb/cloud/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/cloud/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/cloud/reference/glossary/#series-cardinality) is the major factor that affects RAM requirements. For more information, see: * [Don’t have too many series](/influxdb/cloud/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/cloud/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. * [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/cloud/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/cloud/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/cloud/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/cloud/write-data/) [write](/influxdb/cloud/tags/write/)[line protocol](/influxdb/cloud/tags/line-protocol/)[syntax](/influxdb/cloud/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 | | \ | \ | | \\ | \ | | \\\ | \\ | | \\\\ | \\ | | \\\\\ | \\\ | | \\\\\\ | \\\ | --- # Sign up for InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/sign-up/ InfluxDB Cloud (TSM) is a fully managed and hosted version of InfluxDB 2.x, designed to collect, store, process, and visualize metrics and events. > [!Note] > #### New InfluxDB Cloud signups use InfluxDB 3 > > New InfluxDB Cloud signups are for [InfluxDB Cloud Serverless, powered by the InfluxDB 3 storage engine](/influxdata/cloud-serverless/). > > If you are looking to use InfluxDB v2 (TSM), consider self-hosting [InfluxDB OSS v2](/influxdata/v2/). InfluxDB Cloud (TSM) is API-compatible and functionally compatible with InfluxDB OSS v2. The primary differences between InfluxDB OSS v2 and InfluxDB Cloud are: * [InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) that collect data from specified targets are not available in InfluxDB Cloud. * InfluxDB Cloud instances are currently limited to a single organization. * [Start for free](#start-for-free) * [Sign up](#sign-up) * [(Optional) Download, install, and use the influx CLI](#optional-download-install-and-use-the-influx-cli) * [Sign in](#sign-in) * [Get started working with data](#get-started-working-with-data) ### Other deployment options * **InfluxDB OSS v2 (single-node, self-hosted)**: Available for on-premises setups. * **InfluxDB Cloud Serverless**: Managed, multi-tenant InfluxDB Cloud 3 instance. * **InfluxDB Cloud Dedicated**: Managed, single-tenant InfluxDB Cloud 3 cluster. ## Sign up > [!Note] > #### New InfluxDB Cloud signups use InfluxDB 3 > > New InfluxDB Cloud signups are for [InfluxDB Cloud Serverless, powered by the InfluxDB 3 storage engine](/influxdata/cloud-serverless/). > > If you are looking to use InfluxDB v2 (TSM), consider self-hosting [InfluxDB OSS v2](/influxdata/v2/). ## (Optional) Download, install, and use the influx CLI To use the `influx` CLI to manage and interact with your InfluxDB Cloud instance, complete the following steps: [macOS](#macos)[Linux](#linux)[Windows](#windows) #### Step 1: Download influx CLI for macOS Click the following button to download and install `influx` CLI for macOS. [influx CLI (macOS)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-darwin-amd64.tar.gz) #### Step 2: Unpackage the influx binary **Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. To unpackage the downloaded archive, **double click the archive file in Finder**or run the following command in a macOS command prompt application such**Terminal** or **[iTerm2](https://www.iterm2.com/)**: ```sh # Unpackage contents to the current working directory tar zxvf ~/Downloads/influxdb2-client-2.9.1-darwin-amd64.tar.gz ``` #### Step 3: (Optional) Place the binary in your $PATH If you choose, you can place `influx` in your `$PATH` or you can prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). **Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. ```sh # Copy the influx binary to your $PATH sudo cp influxdb2-client-2.9.1-darwin-amd64/influx /usr/local/bin/ ``` > [!Note] > > [!Note] > If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. #### Step 4: (macOS Catalina only) Authorize InfluxDB binaries If running `influx` on macOS Catalina, you must manually authorize the`influx` binary in the **Security & Privacy** section of **System Preferences**. #### Step 5: Set up a configuration profile To avoid having to pass your InfluxDB [API token](/influxdb/cloud/admin/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. In a terminal, run the following command: ```sh # Set up a configuration profile influx config create -n default \ -u https://cloud2.influxdata.com \ -o example-org \ -t mySuP3rS3cr3tT0keN \ -a ``` This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. For more detail, see [influx config](/influxdb/cloud/reference/cli/influx/config/). #### Step 6: Learn `influx` CLI commands To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/). #### Step 1: Download influx CLI for Linux Click one of the following buttons to download and install the `influx` CLI appropriate for your chipset. [influx CLI (amd64)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-amd64.tar.gz)[influx CLI (arm)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-linux-arm64.tar.gz) #### Step 2: Unpackage the influx binary **Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. ```sh # Unpackage contents to the current working directory tar xvfz influxdb2-client-2.9.1-linux-amd64.tar.gz ``` #### Step 3: (Optional) Place the binary in your $PATH If you choose, you can place `influx` in your `$PATH` or you can prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). **Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. ```sh # Copy the influx and influxd binary to your $PATH sudo cp influxdb2-client-2.9.1-linux-amd64/influx /usr/local/bin/ ``` If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. #### Step 4: Set up a configuration profile To avoid having to pass your InfluxDB [API token](/influxdb/cloud/admin/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. In a terminal, run the following command: ```sh # Set up a configuration profile influx config create -n default \ -u https://cloud2.influxdata.com \ -o example-org \ -t mySuP3rS3cr3tT0keN \ -a ``` This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. For more detail, see [influx config](/influxdb/cloud/reference/cli/influx/config/). #### Step 5: Learn `influx` CLI commands To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/). #### Step 1: Download influx CLI for Windows Click the following button to download and install `influx` CLI for Windows. [influx CLI (Windows)](https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.9.1-windows-amd64.zip) #### Step 2: Expand the downloaded archive Expand the downloaded archive into `C:\Program Files\InfluxData\influxdb`. #### Step 3: Grant network access When using the `influx` CLI for the first time, Windows Defender will appear 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**. #### Step 4: Learn `influx` CLI commands To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/). ## Sign in Sign in to [InfluxDB Cloud](https://cloud2.influxdata.com) using your email address and password. [Sign in to InfluxDB Cloud now](https://cloud2.influxdata.com) ## Get started working with data To learn how to get started working with time series data, see [Get Started](/influxdb/cloud/get-started). [get-started](/influxdb/cloud/tags/get-started/)[install](/influxdb/cloud/tags/install/)[cli](/influxdb/cloud/tags/cli/) --- # InfluxDB tools and integrations Source: https://docs.influxdata.com/influxdb/cloud/tools/ > [!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/cloud/tools/telegraf-configs/) InfluxDB Cloud lets you automatically generate Telegraf configurations or upload customized Telegraf configurations that collect metrics and write them to InfluxDB Cloud. ### [Notebooks](/influxdb/cloud/tools/notebooks/) Use notebooks to build and annotate processes and data flows for time series data. ### [InfluxDB templates](/influxdb/cloud/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/cloud/tools/influx-cli/) Use the `influx` command line interface to interact with and manage InfluxDB Cloud. ### [Use the Interactive Flux REPL](/influxdb/cloud/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/cloud/tools/influxql-shell/) Use the InfluxQL interactive shell to execute InfluxQL queries and interact with InfluxDB. ### [Use the Flux LSP with Vim](/influxdb/cloud/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 Cloud](/influxdb/cloud/tools/grafana/) Use [Grafana](https://grafana.com/) to visualize data from your **InfluxDB Cloud** instance. ### [Use Chronograf with InfluxDB Cloud](/influxdb/cloud/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.0** and the [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). ### [Use Kapacitor with InfluxDB Cloud](/influxdb/cloud/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 Cloud**. ### [Use Postman with the InfluxDB API](/influxdb/cloud/tools/postman/) Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, to interact with the [InfluxDB API](/influxdb/cloud/api-guide/). ### [Use ThingWorx with InfluxDB Cloud](/influxdb/cloud/tools/thingworx/) Connect [ThingWorx](https://www.ptc.com/en/products/thingworx) with your **InfluxDB Cloud** instance. ### [Use the InfluxDB documentation MCP server](/influxdb/cloud/tools/mcp-server/) Query InfluxDB Cloud (TSM) documentation from your IDE using the InfluxDB documentation Model Context Protocol (MCP) server. --- # Use Chronograf with InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/tools/chronograf/ [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 Cloud** and the[1.x compatibility API](/influxdb/cloud/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/cloud/reference/urls/))* ``` http://localhost:8086 ``` * **Connection Name:** Name to uniquely identify this connection configuration * **Organization:** InfluxDB [organization](/influxdb/cloud/admin/organizations/) * **Token:** InfluxDB [API token](/influxdb/cloud/admin/tokens/) * **Telegraf Database Name:** InfluxDB [bucket](/influxdb/cloud/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 Cloud, database/retention-policy (DBRP) combinations are mapped to buckets using the `database-name/retention-policy` naming convention.**DBRP mappings are required to query InfluxDB Cloud using InfluxQL.** For information, see [DBRP mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) and [Create DBRP mappings](/influxdb/cloud/query-data/influxql/dbrp/#create-dbrp-mappings). 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 Cloud, see [Use Kapacitor with InfluxDB](/influxdb/cloud/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 Cloud. For example, you **cannot** do the following: * Define databases * Modify retention policies * Add users * Kill queries When connected to an InfluxDB Cloud or InfluxDB Cloud 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/cloud/reference/cli/influx/) * [InfluxDB v2 API](/influxdb/cloud/reference/api/) ### Limited InfluxQL support InfluxDB Cloud and InfluxDB OSS Cloud support InfluxQL **read-only** queries. For more information, see [InfluxQL support](/influxdb/cloud/query-data/influxql/#influxql-support). #### Related * [Chronograf documentation](/chronograf/v1/) --- # Use the Interactive Flux REPL Source: https://docs.influxdata.com/influxdb/cloud/tools/flux-repl/ 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/cloud/tags/flux/) --- # Use the Flux LSP with Vim Source: https://docs.influxdata.com/influxdb/cloud/tools/flux-vim-lsp/ > [!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 Cloud Source: https://docs.influxdata.com/influxdb/cloud/tools/grafana/ Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/)to visualize data from your **InfluxDB Cloud** 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] > SQL is only supported in InfluxDB 3. For more information, see how to upgrade to [InfluxDB Cloud Serverless](/influxdb/cloud/upgrade/v2-to-cloud/). ## Quick reference | Configuration | Value | |-------------------------------------------------------------------------------------------------------------|----------------------------------------------| | **Product selection** | | | **InfluxDB Cloud (TSM)** | | | | | | **URL** | | |[Region URL](/influxdb/cloud/reference/regions/)–for example, `https://us-east-2-1.aws.cloud2.influxdata.com`| | | | | | **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[region URL](/influxdb/cloud/reference/regions/)–for example, `https://us-east-2-1.aws.cloud2.influxdata.com` * **Product**: From the dropdown, select**InfluxDB Cloud (TSM)** * **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 Cloud (TSM) Click **Save & Test**. Grafana attempts to connect to InfluxDB Cloud 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 Cloud (TSM) with v1 auth Click **Save & Test**. Grafana attempts to connect to InfluxDB Cloud 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](/influxdb/cloud/query-data/get-started/) * [Query data with InfluxQL](/influxdb/cloud/query-data/influxql/) * [Get started with Flux](/flux/v0/get-started/) [grafana](/influxdb/cloud/tags/grafana/) | Configuration | Value | | --- | --- | | Configuration | Value | | Product selection | | | InfluxDB Cloud (TSM) | | | | | | URL | | | Region URL –for example, https://us-east-2-1.aws.cloud2.influxdata.com | | | | | | 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) | --- # Install and use the influx CLI Source: https://docs.influxdata.com/influxdb/cloud/tools/influx-cli/ Use the `influx` CLI to interact with and manage your InfluxDB Cloud instance. Write and query data, generate InfluxDB templates, export data, and more. * [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 ``` ### 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/cloud/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/cloud/admin/organizations/). * `API_TOKEN`: your [API token](/influxdb/cloud/admin/tokens/). For more information about managing CLI configurations, see the[`influx config` documentation](/influxdb/cloud/reference/cli/influx/config/). For instructions on how to create API tokens, see [Create a token](/influxdb/cloud/admin/tokens/create-token/). ### Enable shell completion (Optional) To install `influx` shell completion scripts, see[`influx completion`](/influxdb/cloud/reference/cli/influx/completion/#install-completion-scripts). ## Use influx CLI commands *For information about `influx` CLI commands, see the[`influx` CLI reference documentation](/influxdb/cloud/reference/cli/influx/).* #### Related * [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/) [cli](/influxdb/cloud/tags/cli/) --- # InfluxDB templates Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/ InfluxDB templates are prepackaged InfluxDB configurations that contain everything from dashboards and Telegraf configurations to notifications and alerts. Use InfluxDB templates to quickly set up a fresh instance of InfluxDB, back up your dashboard configuration, or share your configuration with the InfluxData community. **InfluxDB templates do the following:** * Reduce setup time * Facilitate secure, portable, source-controlled InfluxDB platform states. * Simplify sharing and using pre-built InfluxDB solutions. ## Template manifests A template consists of a single file known as a **manifest** that defines the InfluxDB state and associated [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. If resources in the template depend on other InfluxDB resources, all dependencies must be included in the template. *See [Create an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/create/) for information about generating template manifests.* ### Template resources Include the following **resources** in a template: * buckets * checks * dashboards * dashboard variables * labels * notification endpoints * notification rules * tasks * Telegraf configurations ## Stacks **InfluxDB stacks** are stateful InfluxDB templates. When you apply a template, InfluxDB associates resources in the template with a stack. Use stacks to add, update, or remove templated resources over time. For more information, see [InfluxDB Stacks](#influxdb-stacks) below. ### [InfluxDB templates in Cloud](/influxdb/cloud/tools/influxdb-templates/cloud/) Install templates directly in the UI or download the `influx` CLI to apply and manage InfluxDB templates in your InfluxDB Cloud account. ### [Monitor InfluxDB Enterprise using a template](/influxdb/cloud/tools/influxdb-templates/monitor-enterprise/) Monitor your InfluxDB Enterprise instance using InfluxDB Cloud and a pre-built InfluxDB template. ### [Use InfluxDB templates](/influxdb/cloud/tools/influxdb-templates/use/) Use the `influx` command line interface (CLI) and the InfluxDB `/api/v2/templates` API to summarize, validate, and apply templates from file systems and URLs. ### [Create an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/create/) Use the InfluxDB UI and the `influx export` command to create InfluxDB templates. ### [InfluxDB stacks](/influxdb/cloud/tools/influxdb-templates/stacks/) InfluxDB stacks are stateful InfluxDB templates that let you add, update, and remove templated resources over time, avoid duplicating resources when applying the same or similar templates more than once, and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. [templates](/influxdb/cloud/tags/templates/) --- # InfluxDB templates in InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/cloud/ To use templates in InfluxDB Cloud, you have a couple options: * [Install and customize templates directly in the Cloud UI](#install-and-customize-a-template-in-the-cloud-ui) * [Apply and manage templates using the `influx` CLI](#apply-and-manage-templates-using-the-influx-cli) ## Install and customize a template in the Cloud UI > [!Note] > To ensure the template works, complete the **ReadMe** instructions after installing a template. For example, you may need to configure telegraf to write specific data to your Cloud instance before the template can be used. 1. Under **Settings** icon in the navigation bar. Settings 2. Click **Templates**. 3. (Optional) If you already have a template URL, you can skip this step. Click **Browse Community Templates** to explore templates and obtain a template URL (YAML or JSON file). 4. Enter the URL to the template’s YAML or JSON file (from the [InfluxData Community Templates](https://github.com/influxdata/community-templates) repository), and then click **Lookup Template**. The Template Installer displays the template name and the number of resources included in the template (for example, dashboards, Telegraf configurations, buckets, and more). 5. Click **Install Template**. A message confirms the template has been successfully installed. 6. Under **Installed Templates**, find the template, and do the following: * Click **View Readme**. Complete the instructions to finalize your template. * (Optional) To customize a template, under **Installed Resources**, expand the template resources, and then click a resource to update it. Update any of the following resources included in the template: * Buckets. [Update buckets](/influxdb/cloud/admin/buckets/update-bucket/) * Dashboards. [Control dashboards](/influxdb/cloud/visualize-data/dashboards/control-dashboard/) * Labels. [Edit labels](/influxdb/cloud/visualize-data/labels/#edit-a-label) * Checks. [Update checks](/influxdb/cloud/monitor-alert/checks/update/) * Notification endpoints. [Update notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/update/) * Notification rules. [Update notification rules](/influxdb/cloud/monitor-alert/notification-rules/update/) * Telegraf configurations. [Update a Telegraf configurations](/influxdb/cloud/tools/telegraf-configs/update/) 7. (Optional) Add or delete resources from the template, and then use the `influx` CLI to [export resources to a new template (JSON or YAML file)](/influxdb/cloud/tools/influxdb-templates/create/#export-all-resources). > [!Note] > To install and configure the `influx` CLI, complete steps 1-2 in the procedure below. ## Apply and manage templates using the influx CLI Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/)to apply and manage templates in your InfluxDB Cloud account. If you haven’t already, do the following: 1. [Download and install `influx` CLI](/influxdb/cloud/get-started/#optional-download-install-and-use-the-influx-cli). 2. [Configure the `influx` CLI](/influxdb/cloud/get-started/#set-up-influxdb) to use your InfluxDB Cloud instance URL, organization, and tokens. 3. [Use the `influx` CLI](/influxdb/cloud/reference/cli/influx/) to use, manage, and create InfluxDB templates: * [Use templates](/influxdb/cloud/tools/influxdb-templates/use/) * [Create templates](/influxdb/cloud/tools/influxdb-templates/create/) [templates](/influxdb/cloud/tags/templates/) --- # Create an InfluxDB template Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/create/ Use the InfluxDB user interface (UI) and the `influx export` command to create InfluxDB templates. Add resources (buckets, Telegraf configurations, tasks, and more) in the InfluxDB UI and export the resources as a template. > [!Note] > #### InfluxDB OSS v2 for creating templates > > Templatable resources are scoped to a single organization, so the simplest way to create a > template is to create a new organization, build the template within the organization, > and then [export all resources](#export-all-resources) as a template. > > **[InfluxDB OSS](/influxdb/v2/)** supports multiple organizations so you > can create new organizations for the sole purpose of building and maintaining a template. > In **InfluxDB Cloud**, your user account is an organization.**We recommend [using InfluxDB OSS to create InfluxDB templates](/influxdb/v2/tools/influxdb-templates/create/).** ## Export a template Do one of the following to export a template: * [Export all resources in an organization](#export-all-resources) * [Export specific resources in an organization](#export-specific-resources) * [Export a stack and its associated resources](#export-a-stack) ### Export all resources To export all templatable resources within an organization to a template manifest, use the `influx export all` 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 template format—both **YAML** (`.yml`) and**JSON** (`.json`) are supported. ###### Export all resources to a template ```bash # Syntax influx export all --org --file --token ``` ```bash # Example influx export all \ --org $INFLUX_ORG \ --file /path/to/templates/TEMPLATE_FILE.yml \ --token $INFLUX_TOKEN ``` #### Export resources filtered by labelName or resourceKind The `influx export all` command has an optional `--filter` flag that exports only resources that match specified label names or resource kinds. Provide multiple filters for both `labelName` and `resourceKind` ###### 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") ``` ```bash influx export all \ --org $INFLUX_ORG \ --file /path/to/templates/TEMPLATE_FILE.yml \ --token $INFLUX_TOKEN \ --filter=resourceKind=Bucket \ --filter=resourceKind=Dashboard \ --filter=labelName=Example1 \ --filter=labelName=Example2 ``` For information about flags, see the[`influx export all` documentation](/influxdb/cloud/reference/cli/influx/export/all/). ### Export specific resources To export specific resources within an organization to a template manifest, use the `influx export` with resource flags for each resource to include. The command uses the API token to filter resources for the organization. Provide the following: * **API token** with read access to the organization. * **Destination path and filename** for the template manifest. The filename extension determines the template format—both **YAML** (`.yml`) and**JSON** (`.json`) are supported. * **Resource flags** with corresponding lists of resource IDs to include in the template. For information about what resource flags are available, see the[`influx export` documentation](/influxdb/cloud/reference/cli/influx/export/). ###### Export specific resources to a template ```bash # Syntax influx export --file --token [resource-flags] ``` ```bash # Example influx export \ --file /path/to/templates/TEMPLATE_FILE.yml \ --token $INFLUX_TOKEN \ --buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \ --dashboards=00000xX0x0X00x000 \ --telegraf-configs=00000x0x000X0x0X0 ``` ### Export a stack To export a stack and all its associated resources as a template, use the`influx export stack` command. The command uses the API token to filter resources for the organization. Provide the following: * **API token** with read access to the organization * **Destination path and filename** for the template manifest. The filename extension determines the template format—both **YAML** (`.yml`) and**JSON** (`.json`) are supported. * **Stack ID** ###### Export a stack as a template ```bash # Syntax influx export stack \ --token \ --file \ ``` ```bash # Example influx export stack \ -t $INFLUX_TOKEN \ -f /path/to/templates/TEMPLATE_FILE.yml \ 05dbb791a4324000 ``` ## Include user-definable resource names > [!Warning] > #### Environment reference substitution not supported > > This feature is not supported by InfluxDB Cloud. ## 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/cloud/reference/cli/influx/export/) * [influx export all](/influxdb/cloud/reference/cli/influx/export/all/) [templates](/influxdb/cloud/tags/templates/) --- # Monitor InfluxDB Enterprise using a template Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/monitor-enterprise/ Use [InfluxDB Cloud](/influxdb/cloud/), the [InfluxDB Enterprise 1.x Template](https://github.com/influxdata/community-templates/tree/master/influxdb-enterprise-1x), and Telegraf to monitor one or more InfluxDB Enterprise instances. Do the following: 1. [Review requirements](#review-requirements) 2. [Install the InfluxDB Enterprise Monitoring template](#install-the-influxdb-enterprise-monitoring-template) 3. [Set up InfluxDB Enterprise for monitoring](#set-up-influxdb-enterprise-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) 8. (Optional) [Monitor with InfluxDB Insights](#monitor-with-influxdb-insights) ## 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 Enterprise 1.x](/enterprise_influxdb/v1/introduction/install-and-deploy/) and permissions to install Telegraf on this machine * Internet connectivity from the machine running InfluxDB Enterprise 1.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/limits/#free-plan-limits) ## Install the InfluxDB Enterprise Monitoring template The InfluxDB Enterprise Monitoring template includes a Telegraf configuration that sends InfluxDB Enterprise metrics to an InfluxDB endpoint and a dashboard that visualizes the metrics. 1. [Log into your InfluxDB Cloud account](https://cloud2.influxdata.com/), go to **Settings \> Templates**, and enter the following template URL: ``` https://raw.githubusercontent.com/influxdata/community-templates/master/influxdb-enterprise-1x/enterprise.yml ``` 2. Click **Lookup Template**, and then click **Install Template**. InfluxDB Cloud imports the template, which includes the following resources: * Telegraf Configuration `monitoring-enterprise-1x` * Dashboard `InfluxDB 1.x Enterprise` * Label `enterprise` * Variables `influxdb_host` and `bucket` ## Set up InfluxDB Enterprise for monitoring By default, InfluxDB Enterprise 1.x has a `/metrics` endpoint available, which exports Prometheus-style system metrics. 1. Make sure 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 Enterprise instance to view the InfluxDB Enterprise system metrics in your browser: ``` http://localhost:8086/metrics ``` Or use `curl` to fetch metrics: ``` curl http://localhost:8086/metrics # HELP boltdb_reads_total Total number of boltdb reads # TYPE boltdb_reads_total counter boltdb_reads_total 41 # HELP boltdb_writes_total Total number of boltdb writes # TYPE boltdb_writes_total counter boltdb_writes_total 28 # HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles. ... ``` 3. Add your **InfluxDB Cloud** account information (URL and organization) to your Telegraf configuration by doing the following: 1. Go to **Load Data \> Telegraf** [in your InfluxDB Cloud account](https://cloud2.influxdata.com/), and click **InfluxDB Output Plugin** at the top-right corner. 2. Copy the `urls`, `token`, `organization`, and `bucket` and close the window. 3. Click **monitoring-enterprise-1.x**. 4. Replace `urls`, `token`, `organization`, and `bucket` under `outputs.influxdb_v2` with your InfluxDB Cloud account information. Alternatively, store this information in your environment variables and include the environment variables in your configuration. > [!Note] > To ensure the InfluxDB Enterprise monitoring dashboard can display the recorded metrics, set the destination bucket name to `enterprise_metrics` in your `telegraf.conf`. 5. Add the [Prometheus input plugin](https://github.com/influxdata/telegraf/blob/release-1.19/plugins/inputs/prometheus/README.md) to your `telegraf.conf`. Specify your your InfluxDB Enterprise URL(s) in the `urls` parameter. For example: ``` [[inputs.prometheus]] urls = ["http://localhost:8086/metrics"] username = "$INFLUX_USER" password = "$INFLUX_PASSWORD" ``` If you’re using unique URLs or have security set up for your `/metrics` endpoint, configure those options here and save the updated configuration. For more information about customizing Telegraf, see [Configure Telegraf](/telegraf/v1/administration/configuration/#global-tags). 4. Click **Save Changes**. ## Set up Telegraf Set up Telegraf to scrape metrics from InfluxDB Enterprise to send to your InfluxDB Cloud account. On each InfluxDB Enterprise instance you want to monitor, do the following: 1. Go to **Load Data \> Telegraf** [in your InfluxDB Cloud account](https://cloud2.influxdata.com/). 2. Click **Setup Instructions** under **monitoring-enterprise-1.x**. 3. Complete the Telegraf Setup instructions. If you are using environment variables, set them up now. > [!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 Telegraf begins pushing metrics to your InfluxDB Cloud account. ## View the Monitoring dashboard To see your data in real time, view the Monitoring dashboard. 1. Select **Boards** (**Dashboards**) in your **InfluxDB Cloud** account. Dashboards 2. Click **InfluxDB Enterprise 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 dropown 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. Save the Check and click on **View History** of the Check under the gear icon to verify it is running. ## 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 \> Notification Endpoint** and click **Create**, and enter a name and description for your Slack endpoint. 3. 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 \> Notification Rules** and click **Create**. 2. Fill out the **About** and **Conditions** section then click **Create Notification Rule**. ## Monitor with InfluxDB Insights For InfluxDB Enterprise customers, Insights is a free service that monitors your cluster and sends metrics to a private Cloud account. This allows InfluxDB Support to monitor your cluster health and access usage statistics when assisting with support tickets that you raise. To apply for this service, contact [InfluxData Support](https://support.influxdata.com/). [templates](/influxdb/cloud/tags/templates/)[monitor](/influxdb/cloud/tags/monitor/) --- # InfluxDB stacks Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/stacks/ **InfluxDB stacks** are **stateful [InfluxDB templates](/influxdb/cloud/influxdb-templates)**that let you add, update, and remove templated resources over time, avoid duplicating resources when applying the same or similar templates more than once, and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. ## Ideal use cases for InfluxDB stacks Stacks help save time and effort in the following use cases: * [Actively develop and extend templates](#actively-develop-and-extend-templates) * [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) ### Actively develop and extend 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. ### 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 allow template users to gracefully apply updates without creating duplicate resources. ### Apply template updates across multiple InfluxDB instances In many cases, users have more than one instance of InfluxDB running and apply the same template to each separate instance. By using stacks, you can make changes to a stack on one instance,[export the stack as a template](/influxdb/cloud/tools/influxdb-templates/create/#export-a-stack)and then apply the changes to your other InfluxDB instances. ## Manage InfluxDB Stacks * [Initialize a stack](#initialize-a-stack) * [Update a stack](#update-a-stack) * [View stacks](#view-stacks) * [Remove a stack](#remove-a-stack) ### [Initialize a stack](/influxdb/cloud/tools/influxdb-templates/stacks/init/) InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/use/) **without providing a stack ID**. To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/cloud/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/cloud/tools/influxdb-templates/stacks/init/) ### [Update a stack](/influxdb/cloud/tools/influxdb-templates/stacks/update/) Use the [`influx apply` command](/influxdb/cloud/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/cloud/tools/influxdb-templates/stacks/update/) ### [View stacks](/influxdb/cloud/tools/influxdb-templates/stacks/view/) Use the [`influx stacks` command](/influxdb/cloud/reference/cli/influx/stacks/) to view installed InfluxDB stacks and their associated resources. ```sh influx stacks -o example-org ``` [Read more ](/influxdb/cloud/tools/influxdb-templates/stacks/view/) ### [Remove a stack](/influxdb/cloud/tools/influxdb-templates/stacks/remove/) Use the [`influx stacks remove` command](/influxdb/cloud/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/cloud/tools/influxdb-templates/stacks/remove/) #### Related --- # Initialize an InfluxDB stack Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/stacks/init/ InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/cloud/tools/influxdb-templates/use/)**without providing a stack ID**. To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/cloud/reference/cli/influx/stacks/init/). ## Initialize a stack when applying a template To automatically create a new stack when [applying an InfluxDB template](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/stacks/init/) --- # Remove an InfluxDB stack Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/stacks/remove/ Use the [`influx stacks remove` command](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/remove/) --- # Update an InfluxDB stack Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/stacks/update/ Use the [`influx apply` command](/influxdb/cloud/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/cloud/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/cloud/reference/cli/influx/apply/) * [influx stacks update](/influxdb/cloud/reference/cli/influx/stacks/update/) --- # View InfluxDB stacks Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/stacks/view/ Use the [`influx stacks` command](/influxdb/cloud/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/cloud/reference/cli/influx/stacks/) --- # Use InfluxDB templates Source: https://docs.influxdata.com/influxdb/cloud/tools/influxdb-templates/use/ 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/cloud/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/cloud/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/cloud/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/cloud/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 > [!Warning] > #### Environment reference substitution not supported > > This feature is not supported by InfluxDB Cloud. ### Include a secret when installing a template Some templates use [secrets](/influxdb/cloud/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/cloud/admin/secrets/add/).* #### Related * [influx apply](/influxdb/cloud/reference/cli/influx/apply/) * [influx template](/influxdb/cloud/reference/cli/influx/template/) * [influx template validate](/influxdb/cloud/reference/cli/influx/template/validate/) * [InfluxDB HTTP API](/influxdb/cloud/api/) [templates](/influxdb/cloud/tags/templates/) --- # Use the InfluxQL shell Source: https://docs.influxdata.com/influxdb/cloud/tools/influxql-shell/ 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 Cloud, databases and retention policies have been combined and replaced with [buckets](/influxdb/cloud/reference/glossary/#bucket). To use the InfluxQL to query an InfluxDB Cloud bucket, first map your DBRP combinations to an appropriate bucket. For information about creating DBRP mappings, see[Query data with InfluxQL](/influxdb/cloud/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/cloud/tools/influx-cli/#install-the-influx-cli). ## Start the InfluxQL shell Use the [`influx v1 shell` command](/influxdb/cloud/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 Cloud region URL](/influxdb/cloud/reference/regions/) * [Organization name or ID](/influxdb/cloud/admin/organizations/view-orgs/) * [API token](/influxdb/cloud/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/cloud/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 Cloud. For information about what queries are supported see[InfluxQL support in InfluxDB Cloud](/influxdb/cloud/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/cloud/reference/cli/influx/v1/shell/) [InfluxQL](/influxdb/cloud/tags/influxql/) --- # Use Kapacitor with InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/tools/kapacitor/ [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 Cloud** using the[InfluxDB 1.x compatibility API](/influxdb/cloud/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 Cloud 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 Cloud, 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/cloud/reference/urls/). ```toml [[influxdb]] # ... urls = ["http://localhost:8086"] ``` ### Provide InfluxDB authentication credentials InfluxDB Cloud and InfluxDB OSS Cloud require authentication. Provide the following credentials in your `[[influxdb]].username` and `[[influxdb]].password`configuration options: * **username:** InfluxDB username * **password:** InfluxDB [API token](/influxdb/cloud/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/cloud/admin/tokens/create-token/). ### Disable InfluxDB subscriptions InfluxDB Cloud and InfluxDB OSS Cloud 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 Cloud 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/cloud/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 Cloud, 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/cloud/reference/api/influxdb-1x/dbrp/) and [Create DBRP mappings](/influxdb/cloud/query-data/influxql/dbrp/#create-dbrp-mappings). The following example TICKscript writes to the `my-db/my-rp` bucket in InfluxDB Cloud or InfluxDB OSS Cloud. ```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/cloud/tools/mcp-server/ 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/cloud/tags/mcp/)[LLM](/influxdb/cloud/tags/llm/)[AI](/influxdb/cloud/tags/ai/) --- # Notebooks Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/ 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/cloud/tools/notebooks/overview/) Learn about the building blocks of a notebook. ### [Create a notebook](/influxdb/cloud/tools/notebooks/create-notebook/) Create a notebook to explore, visualize, and process your data. ### [Manage notebooks](/influxdb/cloud/tools/notebooks/manage-notebooks/) View, update, share, and delete notebooks. ### [Downsample data with notebooks](/influxdb/cloud/tools/notebooks/downsample/) Downsample data to summarize data at specified time intervals and reduce the overall disk usage as data collects over time. Learn how to create a notebook that downsamples data. ### [Normalize data with notebooks](/influxdb/cloud/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/cloud/tools/notebooks/troubleshoot-notebooks/) Common issues with the notebooks feature. --- # Normalize data with notebooks Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/clean-data/ 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/cloud/reference/sample-data/#noaa-ndbc-data), normalizes degree-based wind directions to cardinal directions, and then writes the normalized data to a bucket. \> [!Important] \> \*\*Note\*\*: Using sample data counts towards your total InfluxDB Cloud usage. 1. [Create a new notebook](/influxdb/cloud/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/cloud/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. *(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.” 6. 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/cloud/tags/notebooks/) --- # Create a notebook Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/create-notebook/ 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/cloud/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/cloud/query-data/flux/). 7. (Optional) Change your visualization settings with the drop-down menu and the **Configure** button at the top of the **Visualize the Result** cell. 8. (Optional) Toggle the **Presentation** switch to display visualization cells and hide all other cells. 9. (Optional) Configure notebook actions (**Alert** or **Task**) . 10. (Optional) To run your notebook actions, select and click **Run** under the notebook title. 11. (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) 12. (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/cloud/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/cloud/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**Run** in the upper left drop-down list. ## Add a validation cell A validation cell uses the **Table** [visualization type](/influxdb/cloud/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/cloud/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/cloud/visualize-data/visualization-types/). ## Add an action cell Add an [action cell](/influxdb/cloud/tools/notebooks/overview/#action) to create an [alert](/influxdb/cloud/monitor-alert/)or process data with a [task](/influxdb/cloud/process-data/manage-tasks/) . * [Add an Alert cell](#add-an-alert-cell) * * [Add a Task cell](#add-a-task-cell) ### Add an Alert cell To add an [alert](/influxdb/cloud/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 a Task cell To add a [task](/influxdb/cloud/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. --- # Downsample data with notebooks Source: https://docs.influxdata.com/influxdb/cloud/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. 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/cloud/admin/buckets/create-bucket/). 2. [Create a new notebook](/influxdb/cloud/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`. 3. Use [`to()`](/flux/v0/stdlib/influxdata/influxdb/to/)to write the downsampled data back to an InfluxDB bucket. ``` __PREVIOUS_RESULT__ |> aggregateWindow(every: 10m, fn: mean) |> to(bucket: "example-bucket") ``` 7. *(Optional)* Click and select **Note** to add a note to describe your notebook, for example, “Downsample Coinbase bitcoin prices into hourly averages.” 8. 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/cloud/tags/notebooks/) --- # Manage notebooks Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/manage-notebooks/ Manage your notebooks in the UI: * [View or update a notebook](#view-or-update-notebooks) * [Share a notebook](#share-a-notebook) * [Unshare a notebook](#unshare-a-notebook) * [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. ## Share a notebook 1. In the navigation menu on the left, click **Notebooks**. Notebooks 1. Click the notebook to open it, and then click the icon. 2. Select an API token with read-access to all resources in the notebook, and then click the **✓** icon. 3. Share the generated notebook URL as needed. ## Unshare a notebook To stop sharing a notebook, select next to the shared notebook URL. ## 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**. --- # Overview of notebooks Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/overview/ Learn how notebooks can help to streamline and simplify your day-to-day business processes. See an overview of [notebook concepts](/influxdb/cloud/tools/notebooks/overview/#notebook-concepts), [notebook controls](/influxdb/cloud/tools/notebooks/overview/#notebook-controls), and [notebook cell types](/influxdb/cloud/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. ### Run Select Run (or press **Control+Enter**) to display results of each cell and write data to the selected bucket. ### 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**. ### Share notebook To generate a URL for the notebook, click the icon. For more detail, see how to [share a notebook](/influxdb/cloud/tools/notebooks/manage-notebooks/#share-a-notebook). ## 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/cloud/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/cloud/monitor-alert/). * **Tasks**: Use the notebook to set up and export a task. See how to [manage tasks in InfluxDB](/influxdb/cloud/process-data/manage-tasks/). [notebooks](/influxdb/cloud/tags/notebooks/) --- # Troubleshoot notebooks Source: https://docs.influxdata.com/influxdb/cloud/tools/notebooks/troubleshoot-notebooks/ ### 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. --- # Use Postman with the InfluxDB API Source: https://docs.influxdata.com/influxdb/cloud/tools/postman/ [api](/influxdb/cloud/tags/api/)[authentication](/influxdb/cloud/tags/authentication/) --- # Telegraf configurations Source: https://docs.influxdata.com/influxdb/cloud/tools/telegraf-configs/ 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/cloud/tools/telegraf-configs/view/#view-setup-instructions) for > each Telegraf configuration are provided in the InfluxDB UI.* ## Manage Telegraf configurations ### [Create a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/create/) Use the InfluxDB UI or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to create an Telegraf configuration. ### [Clone a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/clone/) Use the InfluxDB UI to clone an Telegraf configuration. ### [View Telegraf configurations](/influxdb/cloud/tools/telegraf-configs/view/) Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to view and download InfluxDB Telegraf configurations. ### [Update a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/update/) Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to update InfluxDB Telegraf configurations. ### [Remove a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/remove/) Use the InfluxDB UI or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to remove Telegraf configurations from InfluxDB. #### Related * [Manually configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config/) * [Automatically configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/) [telegraf](/influxdb/cloud/tags/telegraf/) --- # Clone a Telegraf configuration Source: https://docs.influxdata.com/influxdb/cloud/tools/telegraf-configs/clone/ 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/cloud/tools/telegraf-configs/create/ 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/cloud/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/cloud/write-data/no-code/use-telegraf/auto-config/). ## Use the influx CLI Use the [`influx telegrafs create` command](/influxdb/cloud/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/cloud/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/cloud/write-data/no-code/use-telegraf/manual-config/) * [Automatically configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/) * [Update a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/update/) --- # Remove a Telegraf configuration Source: https://docs.influxdata.com/influxdb/cloud/tools/telegraf-configs/remove/ Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/tools/telegraf-configs/update/ Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/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/cloud/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/cloud/tools/telegraf-configs/view/ Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/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/cloud/reference/cli/influx/telegrafs/) to list Telegraf configurations stored in InfluxDB. ```sh influx telegrafs ``` --- # Use ThingWorx with InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/tools/thingworx/ > [!Note] > InfluxDB Cloud is a built-in component of ThingWorx on PTC Cloud in Azure. Therefore, PTC recommends using ThingWorx on [PTC Cloud](https://www.ptc.com/en/customer-success/cloud). Alternatively, use this guide to configure self-managed ThingWorx to use InfluxDB Cloud as a persistence provider. **To use InfluxDB Cloud as a persistence provider in ThingWorx** 1. Set up an [InfluxDB Cloud account compatible with ThingWorx](#set-up-an-influxdb-cloud-account-compatible-with-thingworx) 2. [Set up PTC ThingWorx](#set-up-ptc-thingworx) 3. [Use the InfluxDB 1.x compatibility API on InfluxDB Cloud](#use-the-influxdb-1x-compatibility-api-on-influxdb-cloud) ## Set up an InfluxDB Cloud account compatible with ThingWorx 1. [Sign up for a Cloud account](/influxdb/cloud/sign-up/), and do the following when signing up: * Select an AWS or Google region to store your data. To deploy on Azure region, see [use PTC Cloud](https://www.ptc.com/en/customer-success/cloud). * Select a Usage-based plan by entering credit card information. 2. [Create a bucket](/influxdb/cloud/admin/buckets/create-bucket/) with an infinite retention period (select **Never** for when to **Delete Data**), and then copy the new bucket ID and save for step 4. > [!Note] > **Tip:** We recommend naming your bucket “thingworx”. In ThingWorx, this bucket name becomes the database name selected for the InfluxDB persistence provider configuration. 3. [Create an All-Access token](/influxdb/cloud/admin/tokens/create-token/) in InfluxDB Cloud, and save the token string for step 4. To access this string in the UI, double-clicking the new token name, and copy the string at the top of the dialog. 4. Create a DBRP mapping for your bucket by sending an HTTP `POST` request to the `/api/v2/dbrps/` InfluxDB API endpoint. ``` curl --request POST "${influxdb-cloud-url}/api/v2/dbrps" \ --header 'Content-Type: application/json' \ --header "Authorization: Token ${INFLUX_API_TOKEN}" \ --data-raw "{ \"bucketID\": \"${INFLUX_BUCKET_ID}\", \"orgID\": \"${INFLUX_ORG_ID}\", \"database\": \"${INFLUX_BUCKET}\", \"retention_policy\": \"${INFLUX_RETENTION_PERIOD}\", \"default\": true }" ``` Replace the following: * *`INFLUX_BUCKET_ID`*: your [InfluxDB bucket](/influxdb/cloud/reference/glossary/#bucket) ID, created in step 2 * *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token), created in step 3 * *`INFLUX_ORG_ID`*: your [InfluxDB organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id) * *`INFLUX_BUCKET`*: your [InfluxDB bucket](/influxdb/cloud/reference/glossary/#bucket) name (`thingworx`), created in step 2 * *`INFLUX_RETENTION_PERIOD`*: your [InfluxDB retention period](/influxdb/cloud/reference/glossary/#retention-period), typically `autogen` 5. (Optional) We recommend [creating a new Read/Write token](/influxdb/cloud/admin/tokens/create-token/) with read/write access to the bucket that you set up in step 2. A read/write token is useful for non-admin users to access configuration settings in ThingWorx. Copy and save the new token string to [set up PTC ThingWorx](#set-up-ptc-thingworx). (To do this, double-click the token in the UI, and copy the string at the top of the dialog.) ## Set up PTC ThingWorx 1. If you haven’t already, [start at step 4 in Using InfluxDB as the Persistence Provider](https://support.ptc.com/help/thingworx_hc/thingworx_8_hc/en/index.html#page/ThingWorx%2FHelp%2FComposer%2FDataStorage%2FPersistenceProviders%2Fusing_influxdb_as_the_persistence_provider.html). (Steps 1-3 are covered in [Set up an InfluxDB Cloud account compatible with ThingWorx](#set-up-an-influxdb-cloud-account-compatible-with-thingworx).) 2. For the persistence provider configuration settings, enter the following values: * **Connection URL**: Your [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions) * **Database Schema**: Database name in the DBRP mapping set up in step 4 above. * **Username**: Login email address for your InfluxDB Cloud account. * **Password**: Token string–either All-Access created in step 3 or Read/Write created in step 5. ## ThingWorx API requests ThingWorx uses the [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) to access the InfluxDB v2 API on InfluxDB Cloud. ThingWorx includes the InfluxDB persistence provider configuration settings that you set up for PTC ThingWorx in your API requests. > [!Note] > **Deleting data:** The InfluxDB v1 API in InfluxDB Cloud supports a subset of delete operations, namely DROP MEASUREMENT and DELETE statements. In some edge cases, deletes take longer to appear in query results from InfluxDB Cloud (than InfluxDB open source). To delete specific fields, delete data from ThingWorx directly in InfluxDB Cloud using the InfluxDB v2 API. [thingworx](/influxdb/cloud/tags/thingworx/)[ptc](/influxdb/cloud/tags/ptc/)[iiot](/influxdb/cloud/tags/iiot/)[persistence provider](/influxdb/cloud/tags/persistence-provider/) --- # Upgrade to InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/upgrade/ Upgrade to InfluxDB Cloud from InfluxDB 1.x and 2.x: ### [Upgrade from InfluxDB 1.x to InfluxDB Cloud](/influxdb/cloud/upgrade/v1-to-cloud/) To upgrade from InfluxDB 1.x to InfluxDB Cloud, migrate data, and then create database and retention policy (DBRP) mappings. ### [Upgrade from InfluxDB OSS 2.x to InfluxDB Cloud](/influxdb/cloud/upgrade/v2-to-cloud/) To upgrade from Influx 2.x to InfluxDB Cloud, create a new InfluxDB Cloud account, migrate resources, time series data, and more. --- # Upgrade from InfluxDB 1.x to InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/upgrade/v1-to-cloud/ To upgrade from **InfluxDB OSS 1.x** to **InfluxDB Cloud**: 1. [Create an InfluxDB Cloud account](#create-an-influxdb-cloud-account) 2. [Create an All-Access API token](#create-an-all-access-authentication-token) 3. [Download and install the `influx` CLI](#download-and-install-the-influx-cli) 4. [Create DBRP mappings](#create-dbrp-mappings) 5. [Dual write to InfluxDB 1.x and InfluxDB Cloud](#dual-write-to-influxdb-1x-and-influxdb-cloud) 6. [Migrate time series data](#migrate-time-series-data) 7. [Migrate continuous queries](#migrate-continuous-queries) 8. [Collaborate with other users](#collaborate-with-other-users) ## Create an InfluxDB Cloud account Do one of the following to create an InfluxDB Cloud account: * [Subscribe through InfluxData](/influxdb/cloud/sign-up/#subscribe-through-influxdata) and start for free. * [Subscribe through your cloud provider](/influxdb/cloud/sign-up/#subscribe-through-a-cloud-provider). ## Create an All-Access API token InfluxDB Cloud uses [authentication tokens](/influxdb/cloud/security/tokens/) to authorize API requests. Create an **All-Access** token in your InfluxDB Cloud user interface (UI) to use for the upgrade process. 1. Click **Data (Load Data) \> Tokens** in the left navigation bar. Load Data 2. Click **Generate**, and then select **All-Access Token**. 3. Enter a description for the token, and then click **✓ Save**. *For more information about managing tokens and token types, see [Manage tokens](/influxdb/cloud/admin/tokens/).* ## Download and install the influx CLI 1. Visit the [InfluxDB downloads page](https://www.influxdata.com/downloads/)and download the **InfluxDB Cloud CLI** (`influx`). 2. Place the `influx` binary in your system `PATH` or execute the CLI commands from the directory where the `influx` CLI exists. 3. [Create a CLI connection configuration](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials)for your InfluxDB Cloud account. Include the following flags: * **--config-name**: Unique name for the connection configuration. * **--host-url**:[InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/). * **--org**: InfluxDB Cloud organization name. The default organization name is the email address associated with your account. * **--token**: InfluxDB Cloud **All-Access** token. ``` influx config create \ --config-name cloud \ --host-url https://cloud2.influxdata.com \ --org your.email@example.com \ --token mY5uP3rS3cRe7Cl0uDt0K3n \ --active ``` > [!Note] > #### Required InfluxDB Cloud credentials > > All `influx` CLI examples below assume the required InfluxDB Cloud **host**,**organization**, and **API token** credentials are provided by your[`influx` CLI configuration](/influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials). ## Create DBRP mappings InfluxDB database and retention policy (DBRP) mappings associate database and retention policy combinations with InfluxDB cloud [buckets](/influxdb/cloud/reference/glossary/#bucket). These mappings allow InfluxDB 1.x clients to query and write to InfluxDB Cloud buckets while using the 1.x DBRP convention. *For more information about DBRP mapping, see[Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/).* **To map a DBRP combination to an InfluxDB Cloud bucket** 1. **Create a bucket** [Create an InfluxDB Cloud bucket](/influxdb/cloud/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/cloud/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/cloud/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 ``` See [Required InfluxDB Cloud credentials](#required-influxdb-cloud-credentials) ## Dual write to InfluxDB 1.x and InfluxDB Cloud Update external clients to write to your InfluxDB Cloud instance.**We recommend writing data to both InfluxDB 1.x and InfluxDB Cloud until you finish [migrating your existing time series data](#migrate-time-series-data)**. Configure external clients with your InfluxDB Cloud **host**, **organization**, and **API token**. ### Update Telegraf configurations If using Telegraf to collect and write metrics to InfluxDB 1.x, update your Telegraf configuration to write to both InfluxDB 1.x and InfluxDB Cloud: 1. Update your Telegraf configuration with a `influxdb_v2` output to write to your InfluxDB Cloud instance. ##### Example dual-write Telegraf configuration ##### ``` # Write metrics to InfluxDB 1.x [[outputs.influxdb]] urls = ["https://localhost:8086"] database = "example-db" retention_policy = "example-rp" # Write metrics to InfluxDB Cloud [[outputs.influxdb_v2]] urls = ["https://cloud2.influxdata.com"] token = "$INFLUX_TOKEN" organization = "your.email@example.com" bucket = "example-db/example-rp" ``` 2. Add the `INFLUX_TOKEN` environment variable to your Telegraf environment(s) and set the value to your InfluxDB Cloud API token. 3. Restart Telegraf with the updated configuration and begin writing to both InfluxDB 1.x and InfluxDB Cloud. ## Migrate time series data To migrate time series data from your InfluxDB 1.x instance to InfluxDB Cloud: 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 Cloud 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 Cloud** [`influx write` command](/influxdb/cloud/reference/cli/influx/write/)to write the exported line protocol to InfluxDB Cloud. ``` # Syntax influx write \ --bucket \ --file # Example influx write \ --bucket example-db/example-rp \ --file /path/to/example-db_example-rp.lp ``` See [Required InfluxDB Cloud credentials](#required-influxdb-cloud-credentials) 3. Repeat steps 1-2 for each bucket. > [!Note] > #### InfluxDB Cloud write rate limits > > Read and write requests are subject to [rate limits](/influxdb/cloud/account-management/limits/#rate-limits) associated with your > InfluxDB Cloud plan. > If your exported line protocol size potentially exceeds your rate limits, > include the `--rate-limit` flag with `influx write` to rate limit written data. > > ``` > influx write \ > --bucket example-bucket \ > --file /path/to/example-db_example-rp.lp \ > --rate-limit "5MB/5min" > ``` > > See [Required InfluxDB Cloud credentials](#required-influxdb-cloud-credentials) > > To minimize network bandwidth usage, we recommend using gzip to compress exported line protocol. > However, when writing to InfluxDB Cloud, **Data In** and **Ingest batch size**rate limits track the payload size of the **uncompressed** line protocol. ## Migrate continuous queries For information about migrating InfluxDB 1.x continuous queries to InfluxDB Cloud tasks, see [Migrate continuous queries to tasks](/influxdb/cloud/upgrade/v1-to-cloud/migrate-cqs/). ## Collaborate with other users To collaborate with other users in your InfluxDB Cloud organization,[invite users to join your organization](/influxdb/cloud/admin/organizations/users/#invite-a-user-to-your-organization/). #### Related * [Migrate continuous queries to tasks](/influxdb/cloud/upgrade/v1-to-cloud/migrate-cqs/) --- # Migrate continuous queries to tasks Source: https://docs.influxdata.com/influxdb/cloud/upgrade/v1-to-cloud/migrate-cqs/ InfluxDB Cloud replaces 1.x continuous queries (CQs) with **InfluxDB tasks**. To migrate continuous queries to InfluxDB Cloud 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 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 Cloud 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 Cloud, database and retention policy combinations are mapped to specific buckets (for more information, see [Database and retention policy mapping](/influxdb/cloud/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/cloud/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 Cloud, database and retention policy combinations are mapped to specific buckets (for more information, see [Database and retention policy mapping](/influxdb/cloud/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 Cloud 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 Cloud, 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/cloud/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/cloud/query-data/flux/) * [Common tasks](/influxdb/cloud/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](/influxdb/cloud/query-data/get-started/) * [Query data with Flux](/influxdb/cloud/query-data/flux/) * [Process data with InfluxDB tasks](/influxdb/cloud/process-data/) * [Common data processing tasks](/influxdb/cloud/process-data/common-tasks/) --- # Upgrade from InfluxDB OSS 2.x to InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/upgrade/v2-to-cloud/ > [!Note] > #### Migrate to InfluxDB Cloud Serverless > > To unlock the benefits of the InfluxDB 3 storage engine, including unlimited > cardinality and SQL, [migrate your data to an InfluxDB Cloud Serverless organization](/influxdb3/cloud-serverless/write-data/migrate-data/migrate-tsm-to-serverless/). > > All InfluxDB Cloud [accounts](/influxdb3/cloud-serverless/admin/accounts/) and[organizations](/influxdb3/cloud-serverless/admin/organizations/) created through[cloud2.influxdata.com](https://cloud2.influxdata.com) on or after **January 31, 2023**are on InfluxDB Cloud Serverless and are powered by the InfluxDB 3 storage engine. > > To see which storage engine your organization uses, find the **InfluxDB Cloud powered by**link in your [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com)version information. If your organization is using TSM, you’ll see **TSM**followed by the version number. If Serverless, you’ll see **InfluxDB Cloud Serverless**followed by the version number. To upgrade from **InfluxDB OSS 2.x** to **InfluxDB Cloud**: 1. [Create an InfluxDB Cloud account](#create-an-influxdb-cloud-account) 2. [Create an All-Access API token](#create-an-all-access-authentication-token) 3. [Set up influx CLI connection configurations](#set-up-influx-cli-connection-configurations) 4. [Use templates to migrate InfluxDB resources](#use-templates-to-migrate-influxdb-resources) 5. [Migrate DBRP mappings](#migrate-dbrp-mappings) 6. [Dual write to InfluxDB 2.x and InfluxDB Cloud](#dual-write-to-influxdb-2x-and-influxdb-cloud) 7. [Migrate time series data](#migrate-time-series-data) 8. [Collaborate with other users](#collaborate-with-other-users) > [!Note] > #### Consider when upgrading > > * InfluxDB Cloud requires token authentication, and you must create all new API tokens. > * InfluxDB Cloud does not support: > * Multiple [organizations](/influxdb/cloud/reference/glossary/#organization) per account. > Upgrade a single InfluxDB OSS 2.x organization to an InfluxDB Cloud organization. > To upgrade multiple organizations, create a separate InfluxDB Cloud account for each organization. > * [InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/). > To scrape Prometheus-formatted metrics, use the [Telegraf Prometheus input plugin](/telegraf/v1/plugins/#prometheus). > * [1.x compatible authorizations](/influxdb/v2/reference/api/influxdb-1x/#authentication). ## Create an InfluxDB Cloud account Do one of the following to create an InfluxDB Cloud account: * [Subscribe through InfluxData](/influxdb/cloud/sign-up/#subscribe-through-influxdata) and start for free. * [Subscribe through your cloud provider](/influxdb/cloud/sign-up/#subscribe-through-a-cloud-provider). ## Create an All-Access API token InfluxDB API tokens are unique to each organization. Create an **All-Access** token in your InfluxDB Cloud user interface (UI) to use for the upgrade process. 1. Click **Data (Load Data) \> Tokens** in the left navigation bar. Load Data 2. Click **Generate**, and then select **All-Access Token**. 3. Enter a description for the token, and then click **✓ Save**. > [!Note] > If you’ve created other tokens in your InfluxDB 2.x instance for external libraries or > integrations, create corresponding tokens for each in your InfluxDB Cloud instance. > You cannot migrate tokens from InfluxDB 2.x to InfluxDB Cloud. *For more information about managing tokens and token types, see [Manage tokens](/influxdb/cloud/admin/tokens/).* ## Set up influx CLI connection configurations The `influx` command line interface (CLI) lets you create connection configurations that automatically provides **host**, **organization**, and **API token**credentials to CLI commands. Use the `influx` CLI packaged with InfluxDB 2.x and the[`influx config create` command](/influxdb/cloud/reference/cli/influx/config/create/)to set up the connection configurations for both your InfluxDB Cloud instance and your InfluxDB 2.x instance. Include the following flags for each configuration: * **--config-name**: Unique name for the connection configuration. The examples below use `cloud` and `oss` respectively. * **--host-url**:[InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) or[InfluxDB 2.x URL](/influxdb/v2/reference/urls/). * **--org**: InfluxDB organization name. The default organization name in InfluxDB Cloud is the email address associated with your account. * **--token**: API token to use to connect to InfluxDB. * **InfluxDB Cloud**: Provide an **All-Access** token. * **InfluxDB OSS 2.x**: Provide an [Operator token](/influxdb/v2/admin/tokens/#operator-token). ##### Create an InfluxDB Cloud connection configuration ```sh # Example cloud connection configuration influx config create \ --config-name cloud \ --host-url https://cloud2.influxdata.com \ --org your.email@example.com \ --token mY5uP3rS3cRe7Cl0uDt0K3n ``` ##### Create an InfluxDB 2.x connection configuration ```sh # Example 2.x connection configuration influx config create \ --config-name oss \ --host-url http://localhost:8086 \ --org example-org \ --token mY5uP3rS3cRe70S5t0K3n ``` ## Use templates to migrate InfluxDB resources [InfluxDB templates](/influxdb/cloud/tools/influxdb-templates/) let you export InfluxDB[resources](/influxdb/cloud/tools/influxdb-templates/#template-resources) such as buckets, dashboards, labels, tasks, and more and import them into another InfluxDB instance. Export resources from your **InfluxDB 2.x** instance and migrate them to your **InfluxDB Cloud** instance. > [!Note] > #### InfluxDB Cloud Free Plan resource limits > > If upgrading to an InfluxDB Cloud Free Plan, you are only able to create a [limited number of resources](/influxdb/cloud/account-management/limits/#free-plan-limits). > If your exported template exceeds these limits, the resource migration will fail. * **To migrate *all resources* from an InfluxDB 2.x organization to an InfluxDB Cloud organization**: Use the [`influx export all` command](/influxdb/cloud/reference/cli/influx/export/all)and pipe the output into the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/). Use the `--active-config` flag with each command to specify which connection configuration to use: ``` influx export all --active-config oss | influx apply --active-config cloud ``` * **To migrate *specific resources* from an InfluxDB 2.x organization to an InfluxDB Cloud organization**: Use the [`influx export` command](/influxdb/cloud/reference/cli/influx/export/)with lists of specific resources to export or the [`influx export all` command](/influxdb/cloud/reference/cli/influx/export/all)**with filters**. Pipe the output into the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/). Use the `--active-config` flag with each command to specify which connection configuration to use: [Migrate specific resources](#migrate-specific-resources)[Migrate all with filters](#migrate-all-with-filters) ``` influx export \ --active-config oss \ --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 \ --labels o0x0oox0Xxoxx001,o0x0oox0Xxoxx002 \ --dashboards 0XxXooXoo0xooXo0X1,0XxXooXoo0xooXo0X2 | \ influx apply --active-config cloud ``` ``` influx export all \ --active-config oss \ --filter=resourceKind=Bucket \ --filter=resourceKind=Dashboard \ --filter=labelName=Foo | \ influx apply --active-config cloud ``` For more export command examples, see the [`influx export`](/influxdb/cloud/reference/cli/influx/export/#examples)and [`influx export all`](/influxdb/cloud/reference/cli/influx/export/all#examples) documentation. #### Update hardcoded InfluxDB URLs #### If any of your migrated resources contain hardcoded InfluxDB URLs (`http://localhost:8086`), do one of the following to update these URLs to your [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/): * Migrate your resources to InfluxDB Cloud, and then update URLs in the InfluxDB Cloud UI. * Save your template to a file, update URLs in the file, and then apply the template to your InfluxDB Cloud instance. ## Migrate DBRP mappings InfluxDB database and retention policy (DBRP) mappings let you query InfluxDB Cloud buckets with InfluxQL and the InfluxDB 1.x DBRP convention.**If you have DBRP mappings in your InfluxDB 2.x instance**, migrate them to your InfluxDB Cloud instance. [](#migrate-dbrp-mappings-to-influxdb-cloud) Migrate DBRP mappings to InfluxDB Cloud 1. Use the [`influx v1 dbrp list` command](/influxdb/cloud/reference/cli/influx/v1/dbrp/list/)to view the list of DBRP mappings in your **InfluxDB 2.x** instance. ``` influx v1 dbrp list --active-config oss ``` 2. Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list/)to view a list of your **InfluxDB Cloud** buckets and their IDs. ``` influx bucket list --active-config cloud ``` 3. Use the [`influx v1 dbrp create` command](/influxdb/cloud/reference/cli/influx/v1/dbrp/create/)to create DBRP mappings in your **InfluxDB Cloud** instance that map DBRP combinations to the appropriate bucket ID. ``` influx v1 dbrp create \ --active-config cloud \ --bucket-id 12ab34cd56ef \ --database example-db \ --rp example-rp ``` ## Dual write to InfluxDB 2.x and InfluxDB Cloud Update external clients to write to your InfluxDB Cloud instance.**We recommend writing data to both InfluxDB 2.x and InfluxDB Cloud until you finish [migrating your existing time series data](#migrate-time-series-data)**. For step-by-step instructions, see [Dual write](/influxdb/cloud/write-data/no-code/use-telegraf/dual-write/). ## Migrate time series data To migrate your time series data from your InfluxDB 2.x instance to your InfluxDB Cloud instance, do the following: 1. Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list/)to view a list of your **InfluxDB 2.x** buckets and their IDs. ``` influx bucket list --active-config oss ``` 2. Use the [`influxd inspect export-lp` command](/influxdb/v2/reference/cli/influxd/inspect/export-lp/)to export data from a bucket in your **InfluxDB 2.x** instance as line protocol. Include the following flags: * **--bucket-id**: Bucket ID to export * **--engine-path**: InfluxDB [engine path](/influxdb/v2/reference/internals/file-system-layout/#engine-path) * **--output-path**: Output file path * **--compress**: *(Optional)* Gzip the exported line protocol * **--start**: *(Optional)* Earliest timestamp to export * **--end**: *(Optional)* Latest timestamp to export ``` influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --compress \ --output-path path/to/bucket-export.lp ``` 3. Use the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/)to write your exported line protocol to your **InfluxDB Cloud** instance. Provide the following. * **--bucket**: Target bucket name *OR* **\--bucket-id**: Target bucket ID * **--compression**: *(Optional)* `gzip` if the exported line protocol is compressed * **--file**: Import file path ``` influx write \ --active-config cloud \ --bucket example-bucket \ --compression gzip \ --file path/to/bucket-export.lp ``` 4. Repeat steps 2-3 for each bucket. > [!Note] > #### InfluxDB Cloud write rate limits > > Write requests are subject to rate limits associated with your[InfluxDB Cloud pricing plan](/influxdb/cloud/account-management/pricing-plans/). > If your exported line protocol size potentially exceeds your rate limits, > consider doing one of the following: > > * Include the `--rate-limit` flag with `influx write` to rate limit written data. > > ``` > influx write \ > --active-config cloud \ > --bucket example-bucket \ > --file path/to/bucket-export.lp \ > --rate-limit "5MB/5min" > ``` > > * Include `--start` and `--end` flags with `influxd inspect export-lp` to limit > exported data by time and then sequentially write the consecutive time ranges. > > ``` > influxd inspect export-lp \ > --bucket-id 12ab34cd56ef \ > --engine-path ~/.influxdbv2/engine \ > --start 2021-01-01T00:00:00Z \ > --end 2021-02-01T00:00:00Z \ > --compress \ > --output-path path/to/example-bucket-jan-2021.lp > ``` > > To minimize network bandwidth usage, we recommend using gzip to compress exported line protocol. > However, when writing to InfluxDB Cloud, **Data In** and **Ingest batch size**rate limits track the payload size of the **uncompressed** line protocol. #### Migrate system buckets InfluxDB [system buckets](/influxdb/cloud/reference/internals/system-buckets/)contain data related to the InfluxDB monitoring and alerting system. Although the retention period for system buckets in both InfluxDB Cloud and InfluxDB 2.x is only seven days, if you want to migrate this data, use the same method described above [to migrate time series data](#migrate-time-series-data). #### Export and write data in a single command If your data and rate limits allow, you can export and write data in a single command without writing a line protocol export file to disk. The `influxd inspect export-lp` command can output to **stdout** and the `influx write`command accepts line protocol from **stdin**. [](#export-and-write-data) Export and write data ```sh influxd inspect export-lp \ --bucket-id 12ab34cd56ef \ --engine-path ~/.influxdbv2/engine \ --compress \ --output-path - | \ influx write \ --active-config cloud \ --bucket example-bucket \ --compression gzip \ --rate-limit "5MB/5min" ``` ## Collaborate with other users To collaborate with other users in your InfluxDB Cloud organization,[invite users to join your organization](/influxdb/cloud/admin/organizations/users/#invite-a-user-to-your-organization/). --- # Visualize data with the InfluxDB UI Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/ 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. ### [Explore metrics with InfluxDB](/influxdb/cloud/visualize-data/explore-metrics/) Explore and visualize your data in InfluxDB’s Data Explorer. The InfluxDB user interface (UI) allows you to move seamlessly between using the Flux builder and manually editing the query. ### [Manage InfluxDB dashboards](/influxdb/cloud/visualize-data/dashboards/) Create, edit, and manage custom dashboards in the InfluxDB user interface (UI). ### [Use and manage variables](/influxdb/cloud/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/cloud/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/cloud/visualize-data/annotations/) Add annotations to your InfluxDB dashboards to provide useful, contextual information about single points in time. ### [Visualization types](/influxdb/cloud/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/cloud/tags/visualize/) --- # Use annotations in dashboards Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/annotations/ 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/cloud/tags/labels/)[annotations](/influxdb/cloud/tags/annotations/) --- # Manage InfluxDB dashboards Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/ Create, edit, and manage dashboards from the **Dashboards** tab in the left navigation. ### [Create a dashboard](/influxdb/cloud/visualize-data/dashboards/create-dashboard/) Create a new dashboard or import an existing dashboard in the InfluxDB user interface (UI). ### [Control a dashboard](/influxdb/cloud/visualize-data/dashboards/control-dashboard/) Control an InfluxDB dashboard in the InfluxDB user interface (UI). ### [Export a dashboard](/influxdb/cloud/visualize-data/dashboards/export-dashboard/) Export a dashboard using the InfluxDB user interface (UI). ### [Delete a dashboard](/influxdb/cloud/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 https://cloud2.influxdata.com/orgs/03a2bbf46249a000/dashboards/04b6b15034cc000/... ``` ### Dashboard ID in the CLI Use [`influx dashboards`](/influxdb/cloud/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/cloud/tags/dashboards/) --- # Control a dashboard Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/control-dashboard/ 1. In the navigation menu on the left, select **Boards** (**Dashboards**). Dashboards 2. Double-click a dashboard name to open it, and then do any of the following: * [Add a cell](#add-a-cell) * [Add a note](#add-a-note) * [Select a timezone](#select-a-timezone) * [Manually refresh a dashboard](#manually-refresh-a-dashboard) * [Automatically refresh a dashboard](#automatically-refresh-a-dashboard) * [Select the time range](#select-the-time-range) * [Add variables](#add-variables) * [View in presentation mode](#view-in-presentation-mode) * [Toggle dark mode and light mode](#toggle-dark-mode-and-light-mode) ### Add a cell 1. Click **Add Cell** in the upper left hand corner to open the Data Explorer and configure a new cell for your dashboard. 2. Click **Name this cell** , and enter a cell name. 3. Create and submit your query. 4. Click the **✓ check mark** in the upper right hand corner to add the cell to the dashboard. For details on using the Data Explorer, see [Explore metrics](/influxdb/cloud/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. Click **Save**. ### Select a timezone * From the timezone drop-down list, select the timezone to use for the dashboard–**Local** (default) or **UTC**. Select timezone ### Manually refresh a dashboard * Click the refresh button () to manually refresh the dashboard’s data. ### Automatically refresh a dashboard 1. Click **Set Auto Refresh**, and then configure the following options: * Select **Indefinite** to automatically refresh continuously, or select **Custom** to set a time to stop automatically refreshing. * **Refresh Interval**: Enter how frequently the dashboard should refresh. * **Inactivity Timeout**: Set how long the user should be inactive for the dashboard to time out and stop automatically refreshing. 2. Click **Confirm** to save your changes. ### Select the time range 1. Select from the time range options from the list. 2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. The default time range is 5 minutes. > [!Note] > The custom time range uses the selected timezone (local time or UTC). ### Add variables * Click **Show Variables** to display variables available for your dashboard. For details, see [Use and manage variables](/influxdb/cloud/visualize-data/variables/). ### View in presentation mode * Click the ellipsis button, and then select **Presentation Mode** to enter presentation mode. Presentation mode lets you 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 ellipsis button, and then select the moon or sun icons to toggle your dashboard between **dark mode** and **light mode.** Dark & light mode [dashboards](/influxdb/cloud/tags/dashboards/) --- # Create a dashboard Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/create-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/cloud/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/cloud/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/cloud/tags/dashboards/) --- # Delete a dashboard Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/delete-dashboard/ 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/cloud/tags/dashboards/) --- # Export a dashboard Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/export-dashboard/ 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/cloud/tags/dashboards/) --- # Explore metrics with InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/explore-metrics/ Explore and visualize your data in the **Data Explorer**. The InfluxDB user interface (UI) allows you to move seamlessly between using the Flux builder or templates and manually editing the query. Choose between [visualization types](/influxdb/cloud/visualize-data/visualization-types/) for your query. To open the **Data Explorer**, click the **Explore** (**Data Explorer**) icon in the left navigation menu: Data Explorer ## Explore data with Flux and the Data Explorer Flux is InfluxData’s functional data scripting language designed for querying, analyzing, and acting on time series data. See [Get started with Flux](/influxdb/cloud/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/cloud/query-data/flux/group-data/). 1. 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. 2. Use the **Functions** list to review the available Flux functions. Click a function from the list to add it to your query. 3. 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**. 4. 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/cloud/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 **To save your query**: Click **Save as** in the upper right, 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**. | Key | Description | | --- | --- | | Key | Description | | Control + / ( ⌘ + / on Mac) | Comment/uncomment current or selected lines | | Control + Enter | Submit query | --- # Manage labels in the InfluxDB UI Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/labels/ 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/cloud/tags/labels/) --- # Use and manage variables Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/ 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/cloud/visualize-data/variables/create-variable/) Create dashboard variables in the Data Explorer, from the Organization page, or import a variable. ### [Update a variable](/influxdb/cloud/visualize-data/variables/update-variable/) Update a dashboard variable in the InfluxDB user interface. ### [View variables](/influxdb/cloud/visualize-data/variables/view-variables/) View dashboard variables in the InfluxDB user interface. ### [Export a variable](/influxdb/cloud/visualize-data/variables/export-variable/) Export a dashboard variable in the InfluxDB user interface. ### [Delete a variable](/influxdb/cloud/visualize-data/variables/delete-variable/) Delete a dashboard variable in the InfluxDB user interface. ### [Variable types](/influxdb/cloud/visualize-data/variables/variable-types/) Overview of the types of dashboard variables available in InfluxDB ### [Common variable queries](/influxdb/cloud/visualize-data/variables/common-variables/) Useful queries to use to populate values in common dashboard variable use cases. [variables](/influxdb/cloud/tags/variables/) --- # Common variable queries Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/common-variables/ ## List buckets List all buckets in the current organization. ***Flux functions:**[buckets()](/flux/v0/stdlib/influxdata/influxdb/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 v1](/flux/v0/stdlib/influxdata/influxdb/v1/) **Flux functions:** [v1.measurements()](/flux/v0/stdlib/influxdata/influxdb/v1/measurements/)* ```js import "influxdata/influxdb/v1" v1.measurements(bucket: "bucket-name") ``` ## List fields in a measurement List all fields in a specified bucket and measurement. ***Flux package:** [InfluxDB v1](/flux/v0/stdlib/influxdata/influxdb/v1/) **Flux functions:** [v1.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/v1/measurementtagvalues/)* ```js import "influxdata/influxdb/v1" v1.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 v1](/flux/v0/stdlib/influxdata/influxdb/v1/)* ***Flux functions:** [v1.tagValues()](/flux/v0/stdlib/influxdata/influxdb/v1/tagvalues/)* ```js import "influxdata/influxdb/v1" v1.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 v1](/flux/v0/stdlib/influxdata/influxdb/v1/)* ***Flux functions:** [v1.tagValues()](/flux/v0/stdlib/influxdata/influxdb/v1/tagvalues/)* ```js import "influxdata/influxdb/v1" v1.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 v1](/flux/v0/stdlib/influxdata/influxdb/v1/)* ***Flux functions:** [v1.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/v1/measurementtagvalues/)* ```js import "influxdata/influxdb/v1" v1.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 v1](/flux/v0/stdlib/influxdata/influxdb/v1/)* ***Flux functions:** [v1.measurementTagValues()](/flux/v0/stdlib/influxdata/influxdb/v1/measurementtagvalues/)* ```js import "influxdata/influxdb/v1" v1.measurementTagValues( bucket: "bucket-name", measurement: "kubernetes_node", tag: "node_name", ) ``` [variables](/influxdb/cloud/tags/variables/) --- # Create a variable Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/create-variable/ 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/cloud/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/cloud/visualize-data/variables/variable-types/#query). > The [Table visualization type](/influxdb/cloud/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/cloud/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/cloud/visualize-data/variables/common-variables/).* 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 **New Variable**. 4. In the window that appears: * Enter a name for your variable. * Select your variable type. For details on each type, see [Variable types](/influxdb/v2/visualize-data/variables/variable-types/). * Enter the appropriate variable information based on the variable type. 5. Click **Create Variable**. ## 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. 5. Click **Import JSON as Variable**. [variables](/influxdb/cloud/tags/variables/) --- # Delete a variable Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/delete-variable/ 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/cloud/tags/variables/) --- # Export a variable Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/export-variable/ 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/cloud/tags/variables/) --- # Update a variable Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/update-variable/ 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/cloud/tags/variables/) --- # Variable types Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/variable-types/ 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 CSV 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/cloud/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/cloud/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 ``` [variables](/influxdb/cloud/tags/variables/) --- # View variables Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/variables/view-variables/ 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/cloud/tags/variables/) --- # Visualization types Source: https://docs.influxdata.com/influxdb/cloud/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. ### [Band](/influxdb/cloud/visualize-data/visualization-types/band/) ### [Gauge](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/visualize-data/visualization-types/scatter/) The Scatter view uses a scatter plot to display time series data. ### [Single stat](/influxdb/cloud/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/cloud/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. ### [Map](/influxdb/cloud/visualize-data/visualization-types/map/) The Map visualization displays geo-temporal data on a geographic map. --- # Band visualization Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/visualization-types/band/ 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/cloud/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/cloud/visualize-data/visualization-types/gauge/ 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/cloud/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. 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/cloud/visualize-data/visualization-types/graph/ 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. * **Adaptive Zoom**: Enable this option to zoom in on graphs for a more granular view. Zooming in dynamically updates the window period to re-query the data. If you’ve hard-coded the window period, we don’t recommend enabling this option. ###### 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/cloud/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. 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/cloud/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/cloud/visualize-data/visualization-types/scatter/) --- # Histogram visualization Source: https://docs.influxdata.com/influxdb/cloud/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. 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 --- # Map visualization Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/visualization-types/map/ The **Map** visualization displays geo-temporal data on a geographic map. Map data visualization ## Set up the Map visualization To view geo-temporal data on a geographic map, set up a Map visualization. ### Set up the Map visualization 1. Do one of the following: * Click **Data Explorer** in the navigation bar. Data Explorer * Click **Dashboards** in the navigation bar: Dashboards Click the name of the dashboard to update and then do one of the following: * **To edit an existing cell**, click the icon on the cell and then **Configure**. * **To create a new cell**, click **Add Cell**. 2. Use the **Query Builder** or the **Script Editor** to enter your query. To determine the location of points on a geographic map, query results must include the following **fields**: * **lat**: latitude in decimal degrees (WGS 84) * **lon**: longitude in decimal degrees (WGS 84) ***Or*** the `s2_cell_id` **tag** ([S2 Cell ID](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering) as a token) If query results include `lat` and `lon` fields *and* an `s2_cell_id` tag, the map uses the `lat` and `lon` fields to determine point locations. If results only include the `s2_cell_id`, the map uses the center of the S2 cell as the point location. *See [Example queries](#example-queries).* ## Example queries * [View a bird’s migration path](#view-a-birds-migration-path) * [View earthquakes reported by USGS](#view-earthquakes-reported-by-usgs) ### View a bird’s migration path The following query uses the [Bird migration sample data](/influxdb/cloud/reference/sample-data/#bird-migration-sample-data)to display the migration path of a specific bird. ```js from(bucket: "migration") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "migration") |> filter(fn: (r) => r._field == "lat" or r._field == "lon") |> filter(fn: (r) => r.id == "91864A") |> aggregateWindow(every: v.windowPeriod, fn: last) ``` ### View earthquakes reported by USGS The following query uses the [United States Geological Survey (USGS) earthquake data](/influxdb/cloud/reference/sample-data/#usgs-earthquake-data) to display the locations of earthquakes. ```js from(bucket: "usgs") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) |> filter(fn: (r) => r._measurement == "earthquakes") |> filter(fn: (r) => r._field == "lat" or r._field == "lon") ``` --- # Mosaic visualization Source: https://docs.influxdata.com/influxdb/cloud/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. 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/cloud/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/cloud/visualize-data/visualization-types/scatter/ 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/cloud/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/cloud/visualize-data/visualization-types/heatmap/) --- # Single Stat visualization Source: https://docs.influxdata.com/influxdb/cloud/visualize-data/visualization-types/single-stat/ 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/cloud/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. 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/cloud/write-data/ > [!Note] > To explore InfluxDB using existing data (*without writing your own data*), see how to [add sample data](/influxdb/cloud/query-data/execute-queries/query-sample-data/#add-sample). 1. Learn the [best practices](/influxdb/cloud/write-data/best-practices/) for writing data. 2. (Optional) Migrate a large amount of historical data, by [writing data in bulk](/influxdb/cloud/write-data/bulk-ingest-cloud/). 3. Discover how to write data [without coding](/influxdb/cloud/write-data/no-code), by [loading data source in the UI](/influxdb/cloud/write-data/no-code/load-data/), or using [developer tools](/influxdb/cloud/write-data/developer-tools). 4. Do any of the following: * [Troubleshoot the most common issues writing data](/influxdb/cloud/write-data/troubleshoot/) * [Delete data you no longer need](/influxdb/cloud/write-data/delete-data/) * [Query and explore data](/influxdb/cloud/query-data/) * [Process data](/influxdb/cloud/process-data/) * [Visualize data](/influxdb/cloud/visualize-data/) * [Monitor and alert](/influxdb/cloud/monitor-alert/) The following video discusses different ways to write data to InfluxDB: #### Related * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) * [influx write](/influxdb/cloud/reference/cli/influx/write/) * [How to Ingest Data in InfluxDB (Video)](/resources/videos/ingest-data/) [write](/influxdb/cloud/tags/write/)[line protocol](/influxdb/cloud/tags/line-protocol/) --- # Best practices for writing data Source: https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/ The following articles walk through recommendations and best practices for writing data to InfluxDB. ### [Optimize writes to InfluxDB](/influxdb/cloud/write-data/best-practices/optimize-writes/) Simple tips to optimize performance and system overhead when writing data to InfluxDB. ### [Handle duplicate data points](/influxdb/cloud/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/cloud/write-data/best-practices/schema-design/) Design your schema for simpler and more performant queries. ### [Resolve high series cardinality](/influxdb/cloud/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 series 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/cloud/write-data/best-practices/duplicate-points/ InfluxDB identifies unique data points by their measurement, tag set, and timestamp (each a part of [Line protocol](/influxdb/cloud/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/cloud/tags/best-practices/)[write](/influxdb/cloud/tags/write/) --- # Optimize writes to InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/optimize-writes/ 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/cloud/write-data/no-code/use-telegraf/) > * [InfluxDB client libraries](/influxdb/cloud/api-guide/client-libraries/) ## 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/cloud/write-data/#timestamp-precision).* ## Use gzip compression Use gzip compression to speed up writes to InfluxDB. 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 = ["https://cloud2.influxdata.com"] # ... content_encoding = "gzip" ``` ### Enable gzip compression in InfluxDB client libraries Each [InfluxDB client library](/influxdb/cloud/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/cloud/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`). #### Related * [How to Ingest Data in InfluxDB (Video)](/resources/videos/ingest-data/) [best practices](/influxdb/cloud/tags/best-practices/)[write](/influxdb/cloud/tags/write/) --- # Resolve high series cardinality Source: https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/ If reads and writes to InfluxDB have started to slow down, high [series cardinality](/influxdb/cloud/reference/glossary/#series-cardinality) (too many series) may be causing memory issues. Cardinality can also cause writes to fail if it exceeds your [plan’s adjustable service quota](/influxdb/cloud/account-management/limits/). 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/cloud/reference/glossary/#measurement) * [tags](/influxdb/cloud/reference/glossary/#tag) * [field keys](/influxdb/cloud/reference/glossary/#field-key) Each unique set of indexed data elements forms a [series key](/influxdb/cloud/reference/glossary/#series-key).[Tags](/influxdb/cloud/reference/glossary/#tag) containing highly variable information like unique IDs, hashes, and random strings lead to a large number of [series](/influxdb/cloud/reference/glossary/#series), also known as high [series cardinality](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/admin/buckets/delete-bucket/) or [delete a range of data](/influxdb/cloud/write-data/delete-data/). --- # InfluxDB schema design Source: https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/schema-design/ Design your [schema](/influxdb/cloud/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/cloud/write-data/best-practices/resolve-high-cardinality/). ## Design to query The schemas below demonstrate [measurements](/influxdb/cloud/reference/glossary/#measurement), [tag keys](/influxdb/cloud/reference/glossary/#tag-key), and [field keys](/influxdb/cloud/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/cloud/reference/glossary/#tag-value) or [field values](/influxdb/cloud/reference/glossary/#field-value), not in [tag keys](/influxdb/cloud/reference/glossary/#tag-key), [field keys](/influxdb/cloud/reference/glossary/#field-key), or [measurements](/influxdb/cloud/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. #### 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/cloud/reference/glossary/#tag-key) and a [field key](/influxdb/cloud/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. > [!Note] > Use [explicit bucket schemas]() to enforce unique tag and field keys within a schema. ## Use tags and fields [Tag values](/influxdb/cloud/reference/glossary/#tag-value) are indexed and [field values](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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 * [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 | --- # Bulk ingest historical data Source: https://docs.influxdata.com/influxdb/cloud/write-data/bulk-ingest-cloud/ To upload a large amount **(10 GB or greater)** of previously existing *historical*data into InfluxDB Cloud, contact [InfluxData Support](https://support.influxdata.com/) for assistance. We’ll review your ingest rate limits, volume, and existing[data schema](/influxdb/cloud/reference/key-concepts/data-schema) to ensure the most efficient migration. This data migration assistance is a **one-time** offer. --- # Delete data Source: https://docs.influxdata.com/influxdb/cloud/write-data/delete-data/ Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) or the InfluxDB API[`/api/v2/delete`](/influxdb/cloud/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 Cloud supports deleting data by the following: * time range * measurement (`_measurement`) * tag * field (`_field`) In InfluxDB Cloud, writes and deletes are asynchronous and eventually consistent. Once InfluxDB validates your request and queues the delete, it sends a *success* response (HTTP `204` status code) as an acknowledgement. To ensure that InfluxDB handles writes and deletes in the order you request them, wait for the acknowledgement before you send the next request. Once InfluxDB executes a queued delete, 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/cloud/reference/cli/influx/config/)to provide your **InfluxDB host, organization, and API token**. 1. Use the [`influx delete` command](/influxdb/cloud/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/cloud/reference/glossary/#rfc3339-timestamp). 4. *(Optional)* Use the `-p`, `--predicate` flag to include a [delete predicate](/influxdb/cloud/reference/syntax/delete-predicate)that identifies which points to delete. Deleting data without a [delete predicate](/influxdb/cloud/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 for a specific field in a specified time range](#delete-points-for-a-specific-field-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 points for a specific field in a specified time range ```sh influx delete --bucket example-bucket \ --start 2022-01-01T00:00:00Z \ --stop 2022-02-01T00:00:00Z \ --predicate '_field="example-field"' ``` ## Delete data using the API Use the InfluxDB API [`/api/v2/delete` endpoint](/influxdb/cloud/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/cloud/admin/organizations/view-orgs/#view-your-organization-id) * **bucket** or **bucketID:** bucket name or [bucket ID](/influxdb/cloud/admin/buckets/view-buckets/) * **Request body:** JSON object with the following fields: \* Required * \* **start:** earliest time to delete data from ([RFC3339](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) * \* **stop:** latest time to delete data from ([RFC3339](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) * **predicate:** [delete predicate](/influxdb/cloud/reference/syntax/delete-predicate) statement Deleting data without a [delete predicate](/influxdb/cloud/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 for a specific field in a specified time range](#delete-points-for-a-specific-field-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" }' ``` ##### Delete points for a specific field 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": "2022-01-01T00:00:00Z", "stop": "2022-02-01T00:00:00Z", "predicate": "_field=\"example-field\"" }' ``` *For more information, see the [`/api/v2/delete` endpoint documentation](/influxdb/cloud/api/delete/).* To delete a bucket see [Delete a bucket](/influxdb/cloud/admin/buckets/delete-bucket/). #### Related * [Delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/) * [influx delete](/influxdb/v2/reference/cli/influx/delete/) [delete](/influxdb/cloud/tags/delete/) --- # Write data with developer tools Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/ Write data to InfluxDB with developer tools. ### [Write data with third-party technologies](/influxdb/cloud/write-data/developer-tools/third-party-solutions/) Write data to InfluxDB using third-party developer tools. ### [Write CSV data to InfluxDB](/influxdb/cloud/write-data/developer-tools/csv/) Use the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/) to write CSV data to InfluxDB. Include annotations with the CSV data to determine how the data translates into [line protocol](/influxdb/cloud/reference/syntax/line-protocol/). ### [Write data with client libraries](/influxdb/cloud/write-data/developer-tools/client-libraries/) Use client libraries to write data to InfluxDB. ### [Write data with line protocol](/influxdb/cloud/write-data/developer-tools/line-protocol/) Use line protocol to write data to InfluxDB. ### [Scrape Prometheus metrics](/influxdb/cloud/write-data/developer-tools/scrape-prometheus-metrics/) Use Telegraf or Flux to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and store them in InfluxDB. ### [Write data with the influx CLI](/influxdb/cloud/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/cloud/write-data/developer-tools/api/) Use the `/api/v2/write` endpoint of the InfluxDB API to write data to InfluxDB. --- # Write data with the InfluxDB API Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/api/ 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. | | Precision |Use the [`precision`](/influxdb/cloud/reference/glossary/#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 your [InfluxDB Cloud region](/influxdb/cloud/reference/regions/). [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/cloud/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. | | 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/cloud/write-data/developer-tools/client-libraries/ Use language-specific client libraries to integrate with the InfluxDB v2 API. See [Client libraries reference](/influxdb/cloud/api-guide/client-libraries/) for more information. --- # Write CSV data to InfluxDB Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/csv/ 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/cloud/reference/cli/influx/write/) to write CSV data to InfluxDB. Include [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/)annotations to specify how the data translates into [line protocol](/influxdb/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/line-protocol/#measurement) * [field set](/influxdb/cloud/reference/syntax/line-protocol/#field-set) * [timestamp](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) *(Optional but recommended)* * [tag set](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/line-protocol/#boolean). If your CSV data contains boolean values that line protocol does not support,[define your boolean format](/influxdb/cloud/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/cloud/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/cloud/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/cloud/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/cloud/reference/syntax/annotated-csv/#annotated-csv-in-flux). > > Required columns: > > * `_time` > * `_measurement` > * `_field` > * `_value` #### Related * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) * [influx write](/influxdb/cloud/reference/cli/influx/write/) --- # Write data with the influx CLI Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/influx-cli/ To write data from the command line, use the [`influx write` command](/influxdb/cloud/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/cloud/reference/syntax/line-protocol/) and [Annotated CSV](/influxdb/cloud/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/cloud/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. | --- # Write data with line protocol Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/line-protocol/ Use line protocol to write data to InfluxDB Cloud. Line protocol is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point. Learn more about [line protocol](/influxdb/v2/reference/syntax/line-protocol/). Write data using line protocol with the following methods: * [Upload a file or manually paste data in the UI](/influxdb/cloud/write-data/no-code/load-data/#load-csv-or-line-protocol-in-ui) * [Use influx write command](#influx-write-command) ## Write line protocol using the influx write command Use the [`influx write` command](/influxdb/v2/reference/cli/influx/write/) to write data using line protocol to InfluxDB. Set the path to the line protocol file using the `-f` flag. Verify that your line protocol follows the correct [line protocol format](#line-protocol-format) conventions. #### Example write command ```sh influx write -b example-bucket -f path/to/example.txt ``` #### line protocol format ``` 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 ``` Line protocol data looks like this: ```sh mem,host=host1 used_percent=23.43234543 1556892576842902000 cpu,host=host1 usage_user=3.8234,usage_system=4.23874 1556892726597397000 mem,host=host1 used_percent=21.83599203 1556892777007291000 ``` #### Write line protocol * [via stdin](#write-line-protocol-via-stdin) * [from a file](#write-line-protocol-from-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 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 " ``` ##### Write line protocol from a file ```sh influx write \ --bucket example-bucket \ --file path/to/line-protocol.txt ``` ##### 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 ``` InfluxDB Cloud limits data in an uncompressed write request payload to 250 MB. After 250 MB is uncompressed and written, the remaining lines are not written, and the caller receives a 413 response. We recommend the caller retry the request with a smaller uncompressed payload. #### Timestamp precision When writing data to InfluxDB, we [recommend including a timestamp](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) with each point. If a data point does not include a timestamp when it is received by the database, InfluxDB uses the current system time (UTC) of its host machine. The default precision for timestamps is in nanoseconds. If the precision of the timestamps is anything other than nanoseconds (`ns`), you must **specify the precision in your write request**. InfluxDB accepts the following precisions: * `ns` - Nanoseconds * `us` - Microseconds * `ms` - Milliseconds * `s` - Seconds *For more details about line protocol, see the [Line protocol reference](/influxdb/cloud/reference/syntax/line-protocol) and [Best practices for writing data](/influxdb/cloud/write-data/best-practices/).* #### Related * [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) * [influx write](/influxdb/cloud/reference/cli/influx/write/) --- # Scrape Prometheus metrics Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/scrape-prometheus-metrics/ Use [Telegraf](/telegraf/v1/) 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 prometheus.scrape()](#use-prometheusscrape) ## Use Telegraf To use Telegraf to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and write them to InfluxDB Cloud , 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/cloud/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 Cloud . ##### 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 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 Cloud , 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 Cloud 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/cloud/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](/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](/influxdb/cloud/tags/prometheus/) --- # Write data with third-party technologies Source: https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/third-party-solutions/ 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` 5. Click **Next**. 6. Enter a name in the **Stack name** field. 7. 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 8. Do not alter or add to any other fields. Click **Next**. 9. Select the **I acknowledge that AWS CloudFormation might create IAM resources** check box. 10. 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/cloud/write-data/migrate-data/ Migrate data to InfluxDB from other InfluxDB instances including by InfluxDB OSS and InfluxDB Cloud. ### [Migrate data from InfluxDB OSS to InfluxDB Cloud](/influxdb/cloud/write-data/migrate-data/migrate-oss/) To migrate data from an InfluxDB OSS bucket to an InfluxDB Cloud bucket, export your data as line protocol and then write it to your InfluxDB Cloud bucket. ### [Migrate data between InfluxDB Cloud organizations](/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud/) To migrate data from one InfluxDB Cloud organization to another, query the data from time-based batches and write the queried data to a bucket in another InfluxDB Cloud organization. ### [Migrate data from InfluxDB Cloud to InfluxDB OSS](/influxdb/cloud/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 between InfluxDB Cloud organizations Source: https://docs.influxdata.com/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud/ To migrate data from one InfluxDB Cloud organization to another, query the data from time-based batches and write the queried data to a bucket in another InfluxDB Cloud organization. Because full data migrations will likely exceed your organizations’ limits and adjustable quotas, migrate your data in batches. The following guide provides instructions for setting up an InfluxDB task that queries data from an InfluxDB Cloud bucket in time-based batches and writes each batch to another InfluxDB Cloud bucket in another organization. > [!Important] > All query and write requests are subject to your InfluxDB Cloud 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) * [Migrate to InfluxDB Cloud Serverless](#migrate-to-influxdb-cloud-serverless) ## Set up the migration > [!Note] > The migration process requires two buckets in your destination InfluxDB > organization—one bucket to store the migrated data and another bucket to store migration metadata. > If the destination organization uses the [InfluxDB Cloud Free Plan](/influxdb/cloud/account-management/limits/#free-plan), > any buckets in addition to these two will exceed the your plan’s bucket limit. 1. **In the InfluxDB Cloud organization you’re migrating data *from***,[create an API token](/influxdb/cloud/admin/tokens/create-token/)with **read access** to the bucket you want to migrate. 2. **In the InfluxDB Cloud organization you’re migrating data *to***: 1. Add the **InfluxDB Cloud API token from the source organization** as a secret using the key, `INFLUXDB_CLOUD_TOKEN`.*See [Add secrets](/influxdb/cloud/admin/secrets/add/) for more information.* 2. [Create a bucket](/influxdb/cloud/admin/buckets/create-bucket/)**to migrate data to**. 3. [Create a bucket](/influxdb/cloud/admin/buckets/create-bucket/)**to store temporary migration metadata**. 4. [Create a new task](/influxdb/cloud/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 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/cloud/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 = (write-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 1 MB and you’re using the InfluxDB Cloud Free Plan with a write limit of 5 MB per five minutes: ``` batchInterval = (5 / 1) * 1d // batchInterval = 5d ``` You *could* query 5 days of data before hitting your write 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 `4d`**. ##### Important things to note * This assumes no other queries are running in your source InfluxDB Cloud organization. * This assumes no other writes are happening in your destination InfluxDB Cloud organization. ## 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/cloud/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 to InfluxDB Cloud Serverless To unlock the benefits of the InfluxDB 3 storage engine, including unlimited cardinality and SQL, [migrate your data to an InfluxDB Cloud Serverless organization](/influxdb3/cloud-serverless/write-data/migrate-data/migrate-tsm-to-serverless/). All InfluxDB Cloud [accounts](/influxdb3/cloud-serverless/admin/accounts/) and[organizations](/influxdb3/cloud-serverless/admin/organizations/) created through[cloud2.influxdata.com](https://cloud2.influxdata.com) on or after **January 31, 2023**are on InfluxDB Cloud Serverless and are powered by the InfluxDB 3 storage engine. To see which storage engine your organization uses, find the **InfluxDB Cloud powered by**link in your [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com)version information. If your organization is using TSM, you’ll see **TSM**followed by the version number. If Serverless, you’ll see **InfluxDB Cloud Serverless**followed by the version number. --- # Migrate data from InfluxDB Cloud to InfluxDB OSS Source: https://docs.influxdata.com/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-oss/ 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/cloud/security/secrets/add/) for more information.* 2. [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/)**to migrate data to**. 3. [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/)**to store temporary migration metadata**. 4. [Create a new task](/influxdb/cloud/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/cloud/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/cloud/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 InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/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. > [!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/cloud/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/cloud/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/cloud/reference/internals/file-system-layout/#file-system-layout), If using a [custom engine-path](/influxdb/cloud/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 Cloud UI](/influxdb/cloud/write-data/no-code/load-data/#load-csv-or-line-protocol-in-ui) * [Write line protocol using the `influx write` command](/influxdb/cloud/reference/cli/influx/write/) * [Write line protocol using the InfluxDB API](/influxdb/cloud/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/cloud/write-data/no-code/ 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/cloud/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/cloud/write-data/no-code/use-telegraf/) Use Telegraf to collect and write data to InfluxDB v2.0. Create Telegraf configurations in the InfluxDB UI or manually configure Telegraf. ### [Write data with no-code third-party technologies](/influxdb/cloud/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/cloud/write-data/no-code/load-data/ 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/cloud/reference/glossary/#token) and [buckets](/influxdb/cloud/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**. --- # Write data with no-code third-party technologies Source: https://docs.influxdata.com/influxdb/cloud/write-data/no-code/third-party/ 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/cloud/admin/organizations/),[bucket](/influxdb/cloud/admin/buckets/), and an [API token](/influxdb/cloud/admin/tokens/)with write permission on the bucket. To setup InfluxDB and create credentials, follow the[Get started](/influxdb/cloud/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)* ``` https://cloud2.influxdata.com/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/cloud/write-data/no-code/use-telegraf/ [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 v2.0. 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/cloud/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/cloud/write-data/no-code/use-telegraf/dual-write/) Write data to both OSS and Cloud simultaneously. ### [Manually configure Telegraf](/influxdb/cloud/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 v2.0. Start Telegraf using the custom configuration. ### [Use Telegraf plugins](/influxdb/cloud/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/cloud/write-data/no-code/use-telegraf/auto-config/ 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] > Only a subset of plugins are configurable using the InfluxDB UI. > To use plugins other than those listed, you must [manually configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config). > [!Note] > *View the [requirements](/influxdb/cloud/write-data/no-code/use-telegraf#requirements)for using Telegraf with InfluxDB v2.0.* ## Create a Telegraf configuration 1. Open the InfluxDB Cloud UI. 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. > [!Note] > Not all available plugins are listed on this screen. For more information on manually configuring additional plugins, see [Manually add Telegraf plugins](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config/). 7. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. 8. Click **Create and Verify**. 9. 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.* 10. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. Once confirmed, a **Connection Found!** message appears. 11. 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) 1. Save the file and place it in a directory that **telegraf.exe** can access. ## Start Telegraf Requests to the [InfluxDB v2 API](/influxdb/cloud/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/cloud/admin/tokens/view-tokens/).* 2. To configure your 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 https://cloud2.influxdata.com/api/v2/telegrafs/0xoX00oOx0xoX00o ``` ## Manage Telegraf configurations For more information about managing Telegraf configurations in InfluxDB, see[Telegraf configurations](/influxdb/cloud/tools/telegraf-configs/). #### Related * [Create a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/create/) --- # Dual write to InfluxDB OSS and InfluxDB Cloud Source: https://docs.influxdata.com/influxdb/cloud/write-data/no-code/use-telegraf/dual-write/ 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/cloud/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/cloud/write-data/no-code/use-telegraf/manual-config/ Use the Telegraf `influxdb_v2` output plugin to collect and write metrics into an InfluxDB v2.0 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/cloud/write-data/no-code/use-telegraf#requirements)for using Telegraf with InfluxDB v2.0.* ## 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 v2.0 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 **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 v2.0 instances. See [InfluxDB URLs](/influxdb/cloud/reference/urls/) for information about which URLs to use.**InfluxDB Cloud requires HTTPS**. ##### token Your InfluxDB v2.0 authorization token. For information about viewing tokens, see [View tokens](/influxdb/cloud/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 = ["https://cloud2.influxdata.com"] token = "$INFLUX_TOKEN" organization = "example-org" bucket = "example-bucket" # ... ``` > [!Note] > ##### Write to InfluxDB v1.x and InfluxDB Cloud > > 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 v2.0 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/cloud/reference/cli/influx/telegrafs/create/)or [`influx telegrafs update`](/influxdb/cloud/reference/cli/influx/telegrafs/update/) commands. For more information, see: * [Create a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/create/#use-the-influx-cli) * [Update a Telegraf configuration](/influxdb/cloud/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/cloud/tools/telegraf-configs/create/) * [Update a Telegraf configuration](/influxdb/cloud/tools/telegraf-configs/update/) [manually](/influxdb/cloud/tags/manually/)[plugin](/influxdb/cloud/tags/plugin/)[mqtt](/influxdb/cloud/tags/mqtt/) --- # Use Telegraf plugins Source: https://docs.influxdata.com/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/ The following articles guide you through step-by-step Telegraf configuration examples: ### [HTTP input plugin](/influxdb/cloud/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/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin/ 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 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/cloud/write-data/oss-to-cloud/ 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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/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/cloud/write-data/replication/ 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/cloud/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/cloud/write-data/replication/replicate-data/ 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) ## Configure a replication stream Use the [`influx` CLI](/influxdb/cloud/tools/influx-cli/) or the[InfluxDB Cloud API](/influxdb/cloud/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 InfluxDB OSS instance, use the `influx remote create` command and provide the following arguments for the remote instance: * Remote connection name * [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) * InfluxDB Cloud API token *(API token must have write access to the target bucket)* * InfluxDB Cloud 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 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) * InfluxDB OSS bucket ID to replicate writes from * InfluxDB Cloud bucket ID to replicate writes to ```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 replicates all writes to the specified local bucket to the InfluxDB Cloud 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 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 InfluxDB OSS [API token](/influxdb/cloud/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:**InfluxDB OSS organization ID * \* **remoteAPIToken:** InfluxDB Cloud API token *(API token must have write access to the target bucket)* * \* **remoteOrgID:** InfluxDB Cloud organization ID * \* **remoteURL:** [InfluxDB Cloud region URL](/influxdb/cloud/reference/regions/) ```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 InfluxDB OSS [API token](/influxdb/cloud/admin/tokens/) * **Query parameters:** * **orgID:**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 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 InfluxDB OSS [API token](/influxdb/cloud/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:** 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:** InfluxDB OSS organization ID * \* **remoteBucketID:** InfluxDB Cloud bucket ID to replicate writes to (mutually exclusive with `remoteBucketName`) * \* **remoteBucketName:** InfluxDB Cloud bucket name to replicate writes to (mutually exclusive with `remoteBucketID`) * \* **remoteID:** Remote connection ID > [!Note] > `remoteBucketID` and `remoteBucketName` are mutually exclusive. ```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 replicates all writes from the specified local bucket to the InfluxDB Cloud 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 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 InfluxDB OSS [API token](/influxdb/cloud/admin/tokens/) * **Query parameters:** * **orgID:**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 Cloud 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 Cloud 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/cloud/reference/internals/metrics/). #### Related * [influx remote](/influxdb/cloud/reference/cli/influx/remote/) * [influx replication](/influxdb/cloud/reference/cli/influx/replication/) [write](/influxdb/cloud/tags/write/)[replication](/influxdb/cloud/tags/replication/) --- # Troubleshoot issues writing data Source: https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/ 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 In InfluxDB Cloud, writes and deletes are asynchronous and eventually consistent. Once InfluxDB validates your request and [queues](/influxdb/cloud/reference/internals/durability/#backup-on-write) the write or delete, it sends a *success* response (HTTP `204` status code) as an acknowledgement. To ensure that InfluxDB handles writes and deletes in the order you request them, wait for the acknowledgement before you send the next request. Because writes are asynchronous, keep the following in mind: * Data might not yet be queryable when you receive *success* (HTTP `204` status code). * InfluxDB may still reject points after you receive *success* (HTTP `204` status code). ### 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: | HTTP response code | Message | Description | |-----------------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `204 "Success"` | | If InfluxDB validated the request data format and queued the data for writing to the bucket | | `400 "Bad request"` | `message` contains the first malformed line | If data is malformed | | `401 "Unauthorized"` | | If the [`Authorization: Token` header](/influxdb/cloud/api-guide/api_intro/#authentication) is missing or malformed or if the [API token](/influxdb/cloud/api-guide/api_intro/#authentication) doesn’t have [permission](/influxdb/cloud/admin/tokens/) to write to the bucket | | `404 "Not found"` |requested **resource type** (for example, “organization”) and **resource name**| If a requested resource, such as an organization or bucket, wasn’t found | | `413 "Request too large"` | cannot read data: points in batch is too large | If a **write** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits) | | `429 “Too many requests”` | `Retry-After` header: xxx (seconds to wait before retrying the request) |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)| |`500 "Internal server error"`| | Default status for an error | | `503 “Service unavailable“` | Series cardinality exceeds your plan’s service quota | If **series cardinality** exceeds your plan’s [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) | 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 partial writes For example, a partial write may occur when InfluxDB writes all points that conform to the bucket schema, but rejects points that have the wrong data type in a field. To check for writes that fail asynchronously, create a [task](/influxdb/cloud/process-data/manage-tasks/) to [check the \_monitoring bucket for rejected points](#review-rejected-points). To resolve partial writes and rejected points, see [troubleshoot failures](#troubleshoot-failures). ## Troubleshoot failures If you notice data is missing in your bucket, do the following: * Check the `message` property in the response body for details about the error–for example, `partial write error` indicates [rejected points](#troubleshoot-rejected-points). * Check for [rejected points](#troubleshoot-rejected-points) in your organization’s `_monitoring` bucket. * Verify all lines contain valid syntax ([line protocol](/influxdb/cloud/reference/syntax/line-protocol/) or [CSV](/influxdb/cloud/reference/syntax/annotated-csv/)). See how to [find parsing errors](#find-parsing-errors). * Verify the data types match the [series](/influxdb/cloud/reference/key-concepts/data-elements/#series) or [bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). See how to resolve [explicit schema rejections](#resolve-explicit-schema-rejections). * Verify the timestamps match the [precision parameter](/influxdb/cloud/write-data/#timestamp-precision). * Minimize payload size and network errors by [optimizing writes](/influxdb/cloud/write-data/best-practices/optimize-writes/). ## Troubleshoot rejected points When you receive an HTTP `204` (Success) status code, InfluxDB has validated your request format and queued your data for writing. However, InfluxDB Cloud (TSM) processes data asynchronously, which means points may still be rejected after you receive a success response. InfluxDB may reject points for several reasons: * Line protocol parsing errors * Invalid timestamps * Data type conflicts with existing schema * Retention policy violations * Series cardinality exceeding your plan’s limits To verify if your data was successfully written, query your data or check the `_monitoring` bucket for rejected points. * [Review rejected points](#review-rejected-points) * [Find parsing errors](#find-parsing-errors) * [Find data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) * [Resolve data type conflicts](#resolve-data-type-conflicts) * [Resolve explicit schema rejections](#resolve-explicit-schema-rejections) ### Review rejected points To get a log of rejected points, query the [`rejected_points` measurement](/influxdb/cloud/reference/internals/system-buckets/#_monitoring-bucket-schema) in your organization’s `_monitoring` bucket. To more quickly locate `rejected_points`, keep the following in mind: * If your line protocol batch contains single lines with multiple [fields](/influxdb/cloud/reference/syntax/line-protocol/#field-set), InfluxDB logs an entry for each point (each unique field) that is rejected. * Each entry contains a `reason` tag that describes why the point was rejected. * Entries for [data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) have a `count` field value of `1`. * Entries for [parsing errors](#find-parsing-errors) contain an `error` field (and don’t contain a `count` field). #### rejected\_points schema | Name | Value | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| |`_measurement`| `rejected_points` | | `_field` | [`count`](#find-data-type-conflicts-and-schema-rejections) or [`error`](#find-parsing-errors) | | `_value` | [`1`](#find-data-type-conflicts-and-schema-rejections) or [error details](#find-parsing-errors) | | `bucket` | ID of the bucket that rejected the point | |`measurement` | Measurement name of the point | | `field` | Name of the field that caused the rejection | | `reason` |Brief description of the problem. See specific reasons in [data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) | | `gotType` |Received [field](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) type: `Boolean`, `Float`, `Integer`, `String`, or `UnsignedInteger`| | `wantType` |Expected [field](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) type: `Boolean`, `Float`, `Integer`, `String`, or `UnsignedInteger`| |`` | Time the rejected point was logged | #### Find parsing errors If InfluxDB can’t parse a line (for example, due to syntax problems), the response `message` might not provide details. To find parsing error details, query `rejected_points` entries that contain the `error` field. ```js from(bucket: "_monitoring") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "rejected_points") |> filter(fn: (r) => r._field == "error") ``` #### Find data type conflicts and schema rejections To find `rejected_points` caused by [data type conflicts](#resolve-data-type-conflicts) or [schema rejections](#resolve-explicit-schema-rejections), query for the `count` field. ```js from(bucket: "_monitoring") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "rejected_points") |> filter(fn: (r) => r._field == "count") ``` ### Resolve data type conflicts When you write to a bucket that has the `implicit` schema type, InfluxDB compares new points to points that have the same [series](/influxdb/cloud/reference/key-concepts/data-elements/#series). If a point has a field with a different data type than the series, InfluxDB rejects the point and logs a `rejected_points` entry. The `rejected_points` entry contains one of the following reasons: | Reason | Meaning | |----------------------------------|-------------------------------------------------------------------------------------------------------------| | `type conflict in batch write` |The **batch** contains another point with the same series, but one of the fields has a different value type. | |`type conflict with existing data`|The **bucket** contains another point with the same series, but one of the fields has a different value type.| ### Resolve explicit schema rejections If you write to a bucket with an[explicit schema](/influxdb/cloud/admin/buckets/bucket-schema/), the data must conform to the schema. Otherwise, InfluxDB rejects the data. Do the following to interpret explicit schema rejections: * [Detect a measurement mismatch](#detect-a-measurement-mismatch) * [Detect a field type mismatch](#detect-a-field-type-mismatch) #### Detect a measurement mismatch InfluxDB rejects a point if the [measurement](/influxdb/cloud/reference/key-concepts/data-elements/#measurement) doesn’t match the **name** of a [bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). The `rejected_points` entry contains the following `reason` tag value: | Reason | Meaning | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------| |`measurement not allowed by schema`|The **bucket** is configured to use explicit schemas and none of the schemas matches the **measurement** of the point.| Consider the following [line protocol](/influxdb/cloud/reference/syntax/line-protocol) data. ``` airSensors,sensorId=TLM0201 temperature=73.97,humidity=35.23,co=0.48 1637014074 ``` The line has an `airSensors` measurement and three fields (`temperature`, `humidity`, and `co`). If you try to write this data to a bucket that has the [`explicit` schema type](/influxdb/cloud/admin/buckets/bucket-schema/) and doesn’t have an `airSensors` schema, the `/api/v2/write` InfluxDB API returns an error and the following data: ```json { "code": "invalid", "message": "3 out of 3 points rejected (check rejected_points in your _monitoring bucket for further information)" } ``` InfluxDB logs three `rejected_points` entries, one for each field. | \_measurement |\_field|\_value| field |measurement| reason | |----------------|-------|-------|-----------|-----------|---------------------------------| |rejected\_points| count | 1 | humidity |airSensors |measurement not allowed by schema| |rejected\_points| count | 1 | co |airSensors |measurement not allowed by schema| |rejected\_points| count | 1 |temperature|airSensors |measurement not allowed by schema| #### Detect a field type mismatch InfluxDB rejects a point if the [measurement](/influxdb/cloud/reference/key-concepts/data-elements/#measurement) matches the **name** of a bucket schema and the field data types don’t match. The `rejected_points` entry contains the following reason: | Reason | Meaning | |---------------------------------|----------------------------------------------------------------------------------------------------| |`field type mismatch with schema`|The point has the same measurement as a configured schema and they have different field value types.| Consider a bucket that has the following `airSensors` [`explicit bucket schema`](/influxdb/cloud/admin/buckets/bucket-schema/): ```json { "name": "airSensors", "columns": [ { "name": "time", "type": "timestamp" }, { "name": "sensorId", "type": "tag" }, { "name": "temperature", "type": "field", "dataType": "float" }, { "name": "humidity", "type": "field", "dataType": "float" }, { "name": "co", "type": "field", "dataType": "float" } ] } ``` The following [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) data has an `airSensors` measurement, a `sensorId` tag, and three fields (`temperature`, `humidity`, and `co`). ``` airSensors,sensorId=L1 temperature=90.5,humidity=70.0,co=0.2 1637014074 airSensors,sensorId=L1 temperature="90.5",humidity=70.0,co=0.2 1637014074 ``` In the example data above, the second point has a `temperature` field value with the *string* data type. Because the `airSensors` schema requires `temperature` to have the *float* data type, InfluxDB returns a `400` error and a message that describes the result: ```json { "code": "invalid", "message": "partial write error (5 accepted): 1 out of 6 points rejected (check rejected_points in your _monitoring bucket for further information)" } ``` InfluxDB logs the following `rejected_points` entry to the `_monitoring` bucket: | \_measurement |\_field|\_value| bucket | field |gotType|measurement| reason |wantType| |----------------|-------|-------|----------------|-----------|-------|-----------|-------------------------------|--------| |rejected\_points| count | 1 |a7d5558b880a93da|temperature|String |airSensors |field type mismatch with schema| Float | #### Related * [InfluxDB Cloud internals](/influxdb/cloud/reference/internals/) * [influx write](/influxdb/cloud/reference/cli/influx/write/) * [InfluxDB Cloud limits and adjustable quotas](/influxdb/cloud/account-management/limits/) [write](/influxdb/cloud/tags/write/)[line protocol](/influxdb/cloud/tags/line-protocol/)[errors](/influxdb/cloud/tags/errors/) | HTTP response code | Message | Description | | --- | --- | --- | | HTTP response code | Message | Description | | 204 "Success" | | If InfluxDB validated the request data format and queued the data for writing to the bucket | | 400 "Bad request" | message contains the first malformed line | If data is malformed | | 401 "Unauthorized" | | If the Authorization: Token header is missing or malformed or if the API token doesn’t have permission to write to the bucket | | 404 "Not found" | requested resource type (for example, “organization”) and resource name | If a requested resource, such as an organization or bucket, wasn’t found | | 413 "Request too large" | cannot read data: points in batch is too large | If a write request exceeds the maximum global limit | | 429 “Too many requests” | Retry-After header: xxx (seconds to wait before retrying the request) | If a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit | | 500 "Internal server error" | | Default status for an error | | 503 “Service unavailable“ | Series cardinality exceeds your plan’s service quota | If series cardinality exceeds your plan’s adjustable service quotas | | Name | Value | | --- | --- | | Name | Value | | _measurement | rejected_points | | _field | count or error | | _value | 1 or error details | | bucket | ID of the bucket that rejected the point | | measurement | Measurement name of the point | | field | Name of the field that caused the rejection | | reason | Brief description of the problem. See specific reasons in data type conflicts and schema rejections | | gotType | Received field type: Boolean , Float , Integer , String , or UnsignedInteger | | wantType | Expected field type: Boolean , Float , Integer , String , or UnsignedInteger | | | Time the rejected point was logged | | Reason | Meaning | | --- | --- | | Reason | Meaning | | type conflict in batch write | The batch contains another point with the same series, but one of the fields has a different value type. | | type conflict with existing data | The bucket contains another point with the same series, but one of the fields has a different value type. | | Reason | Meaning | | --- | --- | | Reason | Meaning | | measurement not allowed by schema | The bucket is configured to use explicit schemas and none of the schemas matches the measurement of the point. | | _measurement | _field | _value | field | measurement | reason | | --- | --- | --- | --- | --- | --- | | _measurement | _field | _value | field | measurement | reason | | rejected_points | count | 1 | humidity | airSensors | measurement not allowed by schema | | rejected_points | count | 1 | co | airSensors | measurement not allowed by schema | | rejected_points | count | 1 | temperature | airSensors | measurement not allowed by schema | | Reason | Meaning | | --- | --- | | Reason | Meaning | | field type mismatch with schema | The point has the same measurement as a configured schema and they have different field value types. | | _measurement | _field | _value | bucket | field | gotType | measurement | reason | wantType | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | _measurement | _field | _value | bucket | field | gotType | measurement | reason | wantType | | rejected_points | count | 1 | a7d5558b880a93da | temperature | String | airSensors | field type mismatch with schema | Float |