From e4e4878a3db301f8dd990b25a95938f9357155d5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 22 Mar 2023 11:20:39 -0500 Subject: [PATCH] 4806 document different ways to execute queries against iox (#4822) * hotfix(cloud-iox): update buckets docs URLs * fix(ui): update menu item name * fix: buckets: update cloud-iox URL, add Update using API --- api-docs/cloud-iox/ref.yml | 20 +-- .../cloud-iox/admin/accounts/limits.md | 2 +- .../cloud-iox/admin/buckets/create-bucket.md | 2 +- .../cloud-iox/admin/buckets/update-bucket.md | 134 ++++++++++++++++++ .../cloud-iox/admin/buckets/view-buckets.md | 2 +- .../use-telegraf/configure/manual-config.md | 2 +- .../organizations/buckets/create-bucket.md | 2 +- .../organizations/buckets/update-bucket.md | 69 +++++++-- .../organizations/buckets/view-buckets.md | 2 +- .../execute-queries/query-demo-data.md | 2 +- .../execute-queries/query-sample-data.md | 2 +- .../no-code/use-telegraf/manual-config.md | 2 +- 12 files changed, 207 insertions(+), 34 deletions(-) create mode 100644 content/influxdb/cloud-iox/admin/buckets/update-bucket.md diff --git a/api-docs/cloud-iox/ref.yml b/api-docs/cloud-iox/ref.yml index 182c440cc..b787fa14d 100644 --- a/api-docs/cloud-iox/ref.yml +++ b/api-docs/cloud-iox/ref.yml @@ -7136,7 +7136,7 @@ paths: #### Related Guides - - [Manage buckets](/influxdb/cloud-iox/organizations/buckets/) + - [Manage buckets](/influxdb/cloud-iox/admin/buckets/) operationId: GetBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7267,7 +7267,7 @@ paths: #### Related Guides - - [Create a bucket](/influxdb/cloud-iox/organizations/buckets/create-bucket/) + - [Create a bucket](/influxdb/cloud-iox/admin/buckets/create-bucket/) - [Create bucket CLI reference](/influxdb/cloud-iox/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: @@ -7405,7 +7405,7 @@ paths: #### Related Guides - - [Delete a bucket](/influxdb/cloud-iox/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](/influxdb/cloud-iox/admin/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7568,7 +7568,7 @@ paths: #### Related Guides - - [Update a bucket](/influxdb/cloud-iox/organizations/buckets/update-bucket/) + - [Update a bucket](/influxdb/cloud-iox/admin/buckets/update-bucket/) operationId: PatchBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8449,8 +8449,8 @@ paths: #### Related guides - - [Manage bucket schemas](/influxdb/cloud-iox/organizations/buckets/bucket-schema/). - - [Create a bucket with an explicit schema](/influxdb/cloud-iox/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) + - [Manage bucket schemas](/influxdb/cloud-iox/admin/buckets/bucket-schema/). + - [Create a bucket with an explicit schema](/influxdb/cloud-iox/admin/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) operationId: createMeasurementSchema parameters: - description: | @@ -8637,7 +8637,7 @@ paths: #### Related guides - - [Manage bucket schemas](/influxdb/cloud-iox/organizations/buckets/bucket-schema/). + - [Manage bucket schemas](/influxdb/cloud-iox/admin/buckets/bucket-schema/). - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). operationId: updateMeasurementSchema parameters: @@ -15907,7 +15907,7 @@ tags: ### Related guides - - [Manage buckets](/influxdb/cloud-iox/organizations/buckets/) + - [Manage buckets](/influxdb/cloud-iox/admin/buckets/) name: Buckets - name: Cells - name: Checks @@ -15920,8 +15920,8 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/cloud-iox/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/cloud-iox/organizations/buckets/view-buckets/). | + | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/cloud-iox/admin/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/cloud-iox/admin/buckets/view-buckets/). | | `org` | string | The organization name or ID ([find your organization](/influxdb/cloud-iox/organizations/view-orgs/). | | `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/cloud-iox/organizations/view-orgs/). | name: Common parameters diff --git a/content/influxdb/cloud-iox/admin/accounts/limits.md b/content/influxdb/cloud-iox/admin/accounts/limits.md index 251ba761a..a94c00ee5 100644 --- a/content/influxdb/cloud-iox/admin/accounts/limits.md +++ b/content/influxdb/cloud-iox/admin/accounts/limits.md @@ -68,7 +68,7 @@ To write historical data older than 30 days, retain data for more than 30 days, - Unlimited checks - Unlimited notification rules - Unlimited notification endpoints for [all endpoints](/flux/v0.x/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-iox/organizations/buckets/update-bucket/#update-a-buckets-retention-period-in-the-influxdb-ui), or set a custom retention period using the [`influx bucket update command`](/influxdb/cloud-iox/reference/cli/influx/bucket/update/) with the [`influx` CLI](influxdb/cloud/reference/cli/influx/). +- **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-iox/admin/buckets/update-bucket/#update-a-buckets-retention-period-in-the-influxdb-ui), or set a custom retention period using the [`influx bucket update command`](/influxdb/cloud-iox/reference/cli/influx/bucket/update/) with the [`influx` CLI](influxdb/cloud/reference/cli/influx/). ## Global limits diff --git a/content/influxdb/cloud-iox/admin/buckets/create-bucket.md b/content/influxdb/cloud-iox/admin/buckets/create-bucket.md index 27073d291..63ce32323 100644 --- a/content/influxdb/cloud-iox/admin/buckets/create-bucket.md +++ b/content/influxdb/cloud-iox/admin/buckets/create-bucket.md @@ -29,7 +29,7 @@ There are two places you can create a bucket in the UI. ### Create a bucket from the Load Data menu -1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud-iox/admin/buckets/update-bucket.md b/content/influxdb/cloud-iox/admin/buckets/update-bucket.md new file mode 100644 index 000000000..22abaddd8 --- /dev/null +++ b/content/influxdb/cloud-iox/admin/buckets/update-bucket.md @@ -0,0 +1,134 @@ +--- +title: Update a bucket +seotitle: Update a bucket in InfluxDB +description: Update a bucket's name or retention period in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud_iox: + name: Update a bucket + parent: Manage buckets +weight: 202 +--- + +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**. + + {{< nav-icon "data" >}} + +2. Click **{{< caps >}}Settings{{< /caps >}}** to the right of the bucket you want to rename. +3. Click **{{< caps >}}Rename{{< /caps >}}**. +3. Review the information in the window that appears and click **{{< caps >}}I understand, let's rename my bucket{{< /caps >}}**. +4. Update the bucket's name and click **Change Bucket Name**. + +## Update a bucket's retention period in the InfluxDB UI + +1. In the navigation menu on the left, select **Load Data** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **{{< caps >}}Settings{{< /caps >}}** next to the bucket you want to update. +3. In the window that appears, under **Delete data**, select a retention period: + + - **{{< caps >}}Never{{< /caps >}}**: data in the bucket is retained indefinitely. + - **{{< caps >}}Older Than{{< /caps >}}**: 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-iox/api/#operation/PatchBucketsID) to set a custom retention period. + {{% /note %}} +5. Click **{{< caps >}}Save Changes{{< /caps >}}**. + +## Update a bucket using the influx CLI + +Use the [`influx bucket update` command](/influxdb/cloud-iox/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`)_ + +{{< cli/influx-creds-note >}} + +##### 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**. +{{% /note %}} + +```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-iox/api/#operation/PatchBucketsID) +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 +- description +- retention rules + +1. To find the bucket ID, send a request to the HTTP API [`GET /api/v2/buckets/` endpoint](/influxdb/cloud-iox/api/#operation/GetBuckets) to retrieve the list of buckets. + + {{< api-endpoint method="get" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}} + +2. Send a request to the HTTP API [PATCH `/api/v2/buckets/{BUCKET_ID}` endpoint](/influxdb/cloud-iox/api/#operation/PatchBucketsID). + + 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: + + {{< api-endpoint method="patch" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}" >}} + + ```js + { + "name": "air_sensor", + "description": "bucket holding air sensor data", + "retentionRules": [ + { + "type": "expire", + "everySeconds": 2592000 + } + ] + } + ``` diff --git a/content/influxdb/cloud-iox/admin/buckets/view-buckets.md b/content/influxdb/cloud-iox/admin/buckets/view-buckets.md index 9a542a4ff..cf1850fd4 100644 --- a/content/influxdb/cloud-iox/admin/buckets/view-buckets.md +++ b/content/influxdb/cloud-iox/admin/buckets/view-buckets.md @@ -11,7 +11,7 @@ weight: 202 ## View buckets in the InfluxDB UI -1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud-iox/write-data/use-telegraf/configure/manual-config.md b/content/influxdb/cloud-iox/write-data/use-telegraf/configure/manual-config.md index 9b7af66a7..3a5ad9062 100644 --- a/content/influxdb/cloud-iox/write-data/use-telegraf/configure/manual-config.md +++ b/content/influxdb/cloud-iox/write-data/use-telegraf/configure/manual-config.md @@ -57,7 +57,7 @@ in the `telegraf.conf`. To find an example InfluxDB v2 output plugin configuration in the UI: -1. In the navigation menu on the left, select **Data (Load Data)** > **Telegraf**. +1. In the navigation menu on the left, select **Load Data** > **Telegraf**. {{< nav-icon "load data" >}} diff --git a/content/influxdb/cloud/organizations/buckets/create-bucket.md b/content/influxdb/cloud/organizations/buckets/create-bucket.md index 02be7a134..4711a84da 100644 --- a/content/influxdb/cloud/organizations/buckets/create-bucket.md +++ b/content/influxdb/cloud/organizations/buckets/create-bucket.md @@ -27,7 +27,7 @@ There are two places you can create a bucket in the UI. ### Create a bucket from the Load Data menu -1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud/organizations/buckets/update-bucket.md b/content/influxdb/cloud/organizations/buckets/update-bucket.md index 676fa2ec8..96c4f53b9 100644 --- a/content/influxdb/cloud/organizations/buckets/update-bucket.md +++ b/content/influxdb/cloud/organizations/buckets/update-bucket.md @@ -9,9 +9,9 @@ menu: weight: 202 --- -Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update a 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 an bucket's name will affect any assets that reference the bucket by name, including the following: +Note that updating a bucket's name will affect any resources that reference the bucket by name, including the following: - Queries - Dashboards @@ -19,43 +19,44 @@ Note that updating an bucket's name will affect any assets that reference the bu - Telegraf configurations - Templates -If you change a bucket name, be sure to update the bucket in the above places as well. +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 **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} -2. Click **Settings** to the right of the bucket you want to rename. -3. Click **Rename**. -3. Review the information in the window that appears and click **I understand, let's rename my bucket**. +2. Click **{{< caps >}}Settings{{< /caps >}}** to the right of the bucket you want to rename. +3. Click **{{< caps >}}Rename{{< /caps >}}**. +3. Review the information in the window that appears and click **{{< caps >}}I understand, let's rename my bucket{{< /caps >}}**. 4. Update the bucket's name and click **Change Bucket Name**. ## Update a bucket's retention period in the InfluxDB UI -1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} -2. Click **Settings** next to the bucket you want to update. +2. Click **{{< caps >}}Settings{{< /caps >}}** 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. + - **{{< caps >}}Never{{< /caps >}}**: data in the bucket is retained indefinitely. + - **{{< caps >}}Older Than{{< /caps >}}**: select a predefined retention period from the dropdown menu. {{% note %}} -Use the [`influx bucket update` command](#update-a-buckets-retention-period) to set a custom retention period. +Use the [`influx bucket update` command](#update-a-buckets-retention-period) +or the [InfluxDB HTTP API `PATCH /api/v2/buckets` endpoint](/influxdb/cloud/api/#operation/PatchBucketsID) to set a custom retention period. {{% /note %}} -5. Click **Save Changes**. +5. Click **{{< caps >}}Save Changes{{< /caps >}}**. ## 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: +to update a bucket. +Updating a bucket requires the following: - The bucket ID _(provided in the output of `influx bucket list`)_ -- The name or ID of the organization the bucket belongs to. {{< cli/influx-creds-note >}} @@ -93,3 +94,41 @@ 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/#operation/PatchBucketsID) +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 +- description +- retention rules + +1. To find the bucket ID, send a request to the HTTP API [`GET /api/v2/buckets/` endpoint](/influxdb/cloud/api/#operation/GetBuckets) to retrieve the list of buckets. + + {{< api-endpoint method="get" endpoint="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/#operation/PatchBucketsID). + + 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: + + {{< api-endpoint method="patch" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}" >}} + + ```js + { + "name": "air_sensor", + "description": "bucket holding air sensor data", + "retentionRules": [ + { + "type": "expire", + "everySeconds": 2592000 + } + ] + } + ``` diff --git a/content/influxdb/cloud/organizations/buckets/view-buckets.md b/content/influxdb/cloud/organizations/buckets/view-buckets.md index c2e2159a9..bbbfb59ae 100644 --- a/content/influxdb/cloud/organizations/buckets/view-buckets.md +++ b/content/influxdb/cloud/organizations/buckets/view-buckets.md @@ -11,7 +11,7 @@ weight: 202 ## View buckets in the InfluxDB UI -1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, select **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud/query-data/execute-queries/query-demo-data.md b/content/influxdb/cloud/query-data/execute-queries/query-demo-data.md index 87186a701..c932e2f0b 100644 --- a/content/influxdb/cloud/query-data/execute-queries/query-demo-data.md +++ b/content/influxdb/cloud/query-data/execute-queries/query-demo-data.md @@ -37,7 +37,7 @@ Choose from the following demo data sets: ## Add a demo data bucket -1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, click **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud/query-data/execute-queries/query-sample-data.md b/content/influxdb/cloud/query-data/execute-queries/query-sample-data.md index ebb3ea8e8..a81132441 100644 --- a/content/influxdb/cloud/query-data/execute-queries/query-sample-data.md +++ b/content/influxdb/cloud/query-data/execute-queries/query-sample-data.md @@ -63,7 +63,7 @@ In the navigation menu on the left, click **Data Explorer**. ### Add sample data -1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. +1. In the navigation menu on the left, click **Load Data** > **Buckets**. {{< nav-icon "data" >}} diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md index 29dc579d7..30cedaef0 100644 --- a/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md @@ -53,7 +53,7 @@ in the `telegraf.conf`. To find an example InfluxDB v2 output plugin configuration in the UI: -1. In the navigation menu on the left, select **Data (Load Data)** > **Telegraf**. +1. In the navigation menu on the left, select **Load Data** > **Telegraf**. {{< nav-icon "load data" >}}