4758 link to explicit bucket schemas leads to 404 (#4783)
* fix: using the CLI and API to create a bucket with schema-type explicit - Provide API request and response example. - In current cloud, separate bucket creation from schema creation for simplicity. - Give flags and properties similar formats. * fix: explicit bucket-schema and create-bucket for cloud and iox - Adds explicit bucket-schema page for cloud-iox - Adds administer/buckets/create-bucket for cloud-iox - Adds API examples for Cloud. * fix(cloud): view buckets with API. * fix(cloud-iox): view buckets. * fix(all): fix reference. * fix(cloud-iox): bucket-schema link (#4758) * fix(cloud-iox): replace links with existing iox links. * fix(cloud-iox): frontmatter. * fix(cloud-iox): move bucket-schema page and add link to schema-design. * Update content/influxdb/cloud-iox/administer/buckets/_index.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/create-bucket.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/create-bucket.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/manage-explicit-bucket-schemas.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/manage-explicit-bucket-schemas.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/manage-explicit-bucket-schemas.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud-iox/administer/buckets/manage-explicit-bucket-schemas.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud/organizations/buckets/create-bucket.md * Update content/influxdb/cloud/organizations/buckets/create-bucket.md * Apply suggestions from code review Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud/organizations/buckets/bucket-schema/_index.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * Update content/influxdb/cloud/organizations/buckets/bucket-schema/_index.md Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com> * fix(cloud-iox): rename /administer to /admin (#4758) --------- Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>pull/4780/head^2
Jason Stirnaman
GitHub
parent
7c3696f674
commit
c27d2f0367
|
|
@ -0,0 +1,15 @@
|
||||||
|
---
|
||||||
|
title: Administer InfluxDB Cloud
|
||||||
|
seotitle: Administer InfluxDB Cloud
|
||||||
|
description: View and manage InfluxDB resources related to your InfluxDB Cloud account such as
|
||||||
|
accounts, organizations, buckets, API tokens, and secrets.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Administer InfluxDB Cloud
|
||||||
|
weight: 10
|
||||||
|
influxdb/cloud-iox/tags: [admin, administer]
|
||||||
|
---
|
||||||
|
|
||||||
|
The following articles provide information about managing your InfluxDB Cloud resources:
|
||||||
|
|
||||||
|
{{< children >}}
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
---
|
||||||
|
title: Manage buckets
|
||||||
|
seotitle: Manage buckets in InfluxDB
|
||||||
|
description: Manage buckets in InfluxDB using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Manage buckets
|
||||||
|
parent: Administer InfluxDB Cloud
|
||||||
|
weight: 105
|
||||||
|
influxdb/cloud-iox/tags: [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:
|
||||||
|
|
||||||
|
{{< children sort="weight">}}
|
||||||
|
|
@ -0,0 +1,146 @@
|
||||||
|
---
|
||||||
|
title: Create a bucket
|
||||||
|
seotitle: Create a bucket in InfluxDB
|
||||||
|
description: Create buckets to store time series data in InfluxDB using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Create a bucket
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 201
|
||||||
|
related:
|
||||||
|
- /influxdb/cloud-iox/admin/buckets/manage-explicit-bucket-schemas/
|
||||||
|
---
|
||||||
|
|
||||||
|
Use the InfluxDB user interface (UI), `influx` command line interface (CLI), or 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 in the InfluxDB UI](#create-a-bucket-in-the-influxdb-ui)
|
||||||
|
- [Create a bucket using the influx CLI](#create-a-bucket-using-the-influx-cli)
|
||||||
|
- [Create a bucket using the InfluxDB HTTP API](#create-a-bucket-using-the-influxdb-api)
|
||||||
|
- [Create a bucket that enforces explicit schemas](#create-a-bucket-that-enforces-explicit-schemas)
|
||||||
|
|
||||||
|
## Create a bucket in the InfluxDB UI
|
||||||
|
|
||||||
|
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**.
|
||||||
|
|
||||||
|
{{< nav-icon "data" >}}
|
||||||
|
|
||||||
|
2. Click **{{< icon "plus" >}} Create Bucket** in the upper right.
|
||||||
|
3. Enter a **Name** for the bucket.
|
||||||
|
4. Select when to **Delete Data**:
|
||||||
|
- **Never** to retain data forever.
|
||||||
|
- **Older than** to choose a specific retention period.
|
||||||
|
5. Click **Create** to create the bucket.
|
||||||
|
|
||||||
|
### Create a bucket in the Data Explorer
|
||||||
|
|
||||||
|
1. In the navigation menu on the left, select **Explore* (**Data Explorer**).
|
||||||
|
|
||||||
|
{{< nav-icon "data-explorer" >}}
|
||||||
|
|
||||||
|
2. In the **From** panel in the Flux Builder, select `+ Create Bucket`.
|
||||||
|
3. Enter a **Name** for the bucket.
|
||||||
|
4. Select when to **Delete Data**:
|
||||||
|
- **Never** to retain data forever.
|
||||||
|
- **Older than** to choose a specific retention period.
|
||||||
|
5. Click **Create** to create the bucket.
|
||||||
|
|
||||||
|
## Create a bucket 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:
|
||||||
|
|
||||||
|
| Requirement | Include by |
|
||||||
|
|:-------------------------------|:-----------|
|
||||||
|
| Organization | `-o` |
|
||||||
|
| Bucket | `-n` |
|
||||||
|
| Retention Period Duration | `-r` |
|
||||||
|
|
||||||
|
The following example creates a bucket with a retention period of seventy-two hours:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
influx bucket create -n my-bucket -o {INFLUX_ORG} -r 72h
|
||||||
|
```
|
||||||
|
|
||||||
|
## Create a bucket using the InfluxDB API
|
||||||
|
|
||||||
|
To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:
|
||||||
|
|
||||||
|
[{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
|
||||||
|
In your request body, specify values for the following properties:
|
||||||
|
|
||||||
|
| Requirement | Include by |
|
||||||
|
|:---------------------|:-----------------|
|
||||||
|
| Organization | `orgID` |
|
||||||
|
| Bucket | `name` |
|
||||||
|
| Retention Rules | `retentionRules` |
|
||||||
|
|
||||||
|
The following example creates a bucket with a retention period of `86,400` seconds, or twenty-four hours:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
|
||||||
|
```
|
||||||
|
|
||||||
|
_For information about **InfluxDB API options and response codes**, see
|
||||||
|
[InfluxDB API Buckets reference documentation](/influxdb/cloud/api/#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-iox/admin/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.
|
||||||
|
|
||||||
|
{{< tabs-wrapper >}}
|
||||||
|
{{% tabs %}}
|
||||||
|
[influx CLI](#)
|
||||||
|
[InfluxDB API](#)
|
||||||
|
{{% /tabs %}}
|
||||||
|
|
||||||
|
{{% tab-content %}}
|
||||||
|
<!------------------------------ BEGIN CLI CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the `influx bucket create` command and specify the `--schema-type=explicit` flag:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{% tab-content %}}
|
||||||
|
|
||||||
|
<!----------------------------- BEGIN API CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the HTTP API [`/api/v2/buckets`](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
endpoint and set the `schemaType` property value to `explicit` in the request body--for example:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"orgID": "{INFLUX_ORG_ID}",
|
||||||
|
"name": "my-explicit-bucket",
|
||||||
|
"description": "My Explicit Bucket",
|
||||||
|
"rp": "string",
|
||||||
|
"retentionRules": [
|
||||||
|
{
|
||||||
|
"type": "expire",
|
||||||
|
"everySeconds": 86400,
|
||||||
|
"shardGroupDurationSeconds": 0
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"schemaType": "explicit"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{< /tabs-wrapper >}}
|
||||||
|
|
||||||
|
Next, see how to [create an explicit bucket schema](/influxdb/cloud-iox/admin/buckets/bucket-schema/) for a measurement.
|
||||||
|
|
@ -0,0 +1,300 @@
|
||||||
|
---
|
||||||
|
title: Manage explicit bucket schemas
|
||||||
|
seotitle: Manage explicit bucket schemas in InfluxDB
|
||||||
|
description: Manage explicit bucket schemas using the influx CLI or InfluxDB HTTP API. Optionally, ensure data you write follows a specific schema.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Manage explicit bucket schemas
|
||||||
|
weight: 201
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 250
|
||||||
|
influxdb/cloud/tags: [buckets, bucket-schema, bucket schemas, explicit bucket schemas, explicit measurement schema, schema]
|
||||||
|
related:
|
||||||
|
- /influxdb/cloud/reference/key-concepts/
|
||||||
|
- /influxdb/cloud/reference/key-concepts/data-schema/
|
||||||
|
- /influxdb/cloud/reference/key-concepts/data-elements/
|
||||||
|
- /influxdb/cloud-iox/admin/buckets/create-bucket/
|
||||||
|
- /influxdb/cloud/reference/cli/influx/
|
||||||
|
---
|
||||||
|
|
||||||
|
Use [**explicit bucket schemas**](/influxdb/cloud/reference/glossary/#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.
|
||||||
|
Buckets with the `explicit` schema-type, use
|
||||||
|
explicit bucket schemas to ensure measurements have specific columns and data types and to prevent non-conforming writes.
|
||||||
|
|
||||||
|
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**. We recommend reviewing [schema design best practices](/influxdb/cloud-iox/write-data/best-practices/schema-design/) and [**elements of line protocol**](/influxdb/cloud/reference/syntax/line-protocol/#elements-of-line-protocol) if you aren't familiar with these concepts.
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
- [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-iox/admin/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-iox/reference/glossary/#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)](http://ndjson.org/),
|
||||||
|
as in the following examples:
|
||||||
|
{{< code-tabs-wrapper >}}
|
||||||
|
{{% code-tabs %}}
|
||||||
|
[usage-resources.csv](#)
|
||||||
|
[usage-cpu.json](#)
|
||||||
|
[sensor.ndjson](#)
|
||||||
|
{{% /code-tabs %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/usage-resources.csv" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/usage-cpu.json" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{< /code-tabs-wrapper >}}
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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/#operation/createMeasurementSchema)
|
||||||
|
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:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"name": "airSensors",
|
||||||
|
"columns": [
|
||||||
|
{"name": "time", "type": "timestamp"},
|
||||||
|
{"name": "sensorId", "type": "tag"},
|
||||||
|
{"name": "temperature", "type": "field"},
|
||||||
|
{"name": "humidity", "type": "field", "dataType": "float"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
#### Test your explicit 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.
|
||||||
|
<!-- Pending IOx troubleshoot page --
|
||||||
|
For more information about errors to expect in your tests, see [explicit schema rejections](/influxdb/cloud-iox/write-data/troubleshoot/#troubleshoot-rejected-points).
|
||||||
|
-->
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
### Write valid schemas
|
||||||
|
|
||||||
|
To ensure your schema is valid, review [schema design best practices](/influxdb/cloud-iox/write-data/best-practices/schema-design/).
|
||||||
|
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-iox/reference/glossary/#timestamp) type.
|
||||||
|
3. Include at least one column with the [`field`](/influxdb/cloud-iox/reference/glossary/#field) 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-iox/reference/glossary/#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-iox/reference/glossary/#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-iox/admin/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 {{< caps >}}Show Schema{{< /caps>}} button. Click {{< caps >}}Show Schema{{< /caps>}} 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/#operation/getMeasurementSchemas):
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# sensor.ndjson
|
||||||
|
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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/#operation/updateMeasurementSchema).
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
{{< api-endpoint method="patch" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"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-iox/reference/glossary/#token) 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.
|
||||||
|
|
||||||
|
<!-- Pending IOx troubleshoot page --
|
||||||
|
To resolve failures and partial writes, see how to [troubleshoot writes](/influxdb/cloud/write-data/troubleshoot/).
|
||||||
|
-->
|
||||||
|
|
@ -0,0 +1,42 @@
|
||||||
|
---
|
||||||
|
title: View buckets
|
||||||
|
seotitle: View buckets in InfluxDB
|
||||||
|
description: View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud:
|
||||||
|
name: View buckets
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 202
|
||||||
|
---
|
||||||
|
|
||||||
|
## View buckets in the InfluxDB UI
|
||||||
|
|
||||||
|
1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**.
|
||||||
|
|
||||||
|
{{< nav-icon "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/#operation/GetBuckets) to view buckets in an organization.
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="https://cloud2.influxdata.com/api/v2/buckets" %}}
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
---
|
||||||
|
title: Manage buckets
|
||||||
|
seotitle: Manage buckets in InfluxDB Cloud
|
||||||
|
description: Manage buckets in InfluxDB Cloud using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Manage buckets
|
||||||
|
parent: Administer InfluxDB Cloud
|
||||||
|
weight: 105
|
||||||
|
influxdb/cloud-iox/tags: [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:
|
||||||
|
|
||||||
|
{{< children sort="weight">}}
|
||||||
|
|
@ -0,0 +1,146 @@
|
||||||
|
---
|
||||||
|
title: Create a bucket
|
||||||
|
seotitle: Create a bucket in InfluxDB Cloud
|
||||||
|
description: Create buckets to store time series data in InfluxDB Cloud using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Create a bucket
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 201
|
||||||
|
related:
|
||||||
|
- /influxdb/cloud-iox/admin/buckets/manage-explicit-bucket-schemas/
|
||||||
|
---
|
||||||
|
|
||||||
|
Use the InfluxDB user interface (UI), `influx` command line interface (CLI), or 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 in the InfluxDB UI](#create-a-bucket-in-the-influxdb-ui)
|
||||||
|
- [Create a bucket using the influx CLI](#create-a-bucket-using-the-influx-cli)
|
||||||
|
- [Create a bucket using the InfluxDB HTTP API](#create-a-bucket-using-the-influxdb-api)
|
||||||
|
- [Create a bucket that enforces explicit schemas](#create-a-bucket-that-enforces-explicit-schemas)
|
||||||
|
|
||||||
|
## Create a bucket in the InfluxDB UI
|
||||||
|
|
||||||
|
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**.
|
||||||
|
|
||||||
|
{{< nav-icon "data" >}}
|
||||||
|
|
||||||
|
2. Click **{{< icon "plus" >}} Create Bucket** in the upper right.
|
||||||
|
3. Enter a **Name** for the bucket.
|
||||||
|
4. Select when to **Delete Data**:
|
||||||
|
- **Never** to retain data forever.
|
||||||
|
- **Older than** to choose a specific retention period.
|
||||||
|
5. Click **Create** to create the bucket.
|
||||||
|
|
||||||
|
### Create a bucket in the Data Explorer
|
||||||
|
|
||||||
|
1. In the navigation menu on the left, select **Explore* (**Data Explorer**).
|
||||||
|
|
||||||
|
{{< nav-icon "data-explorer" >}}
|
||||||
|
|
||||||
|
2. In the **From** panel in the Flux Builder, select `+ Create Bucket`.
|
||||||
|
3. Enter a **Name** for the bucket.
|
||||||
|
4. Select when to **Delete Data**:
|
||||||
|
- **Never** to retain data forever.
|
||||||
|
- **Older than** to choose a specific retention period.
|
||||||
|
5. Click **Create** to create the bucket.
|
||||||
|
|
||||||
|
## Create a bucket 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:
|
||||||
|
|
||||||
|
| Requirement | Include by |
|
||||||
|
|:-------------------------------|:-----------|
|
||||||
|
| Organization | `-o` |
|
||||||
|
| Bucket | `-n` |
|
||||||
|
| Retention Period Duration | `-r` |
|
||||||
|
|
||||||
|
The following example creates a bucket with a retention period of 72 hours:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
influx bucket create -n my-bucket -o {INFLUX_ORG} -r 72h
|
||||||
|
```
|
||||||
|
|
||||||
|
## Create a bucket using the InfluxDB API
|
||||||
|
|
||||||
|
To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:
|
||||||
|
|
||||||
|
[{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
|
||||||
|
In your request body, specify values for the following properties:
|
||||||
|
|
||||||
|
| Requirement | Include by |
|
||||||
|
|:---------------------|:-----------------|
|
||||||
|
| Organization | `orgID` |
|
||||||
|
| Bucket | `name` |
|
||||||
|
| Retention Rules | `retentionRules` |
|
||||||
|
|
||||||
|
The following example creates a bucket with a retention period of `86,400` seconds, or twenty-four hours:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
|
||||||
|
```
|
||||||
|
|
||||||
|
_For information about **InfluxDB API options and response codes**, see
|
||||||
|
[InfluxDB API Buckets reference documentation](/influxdb/cloud/api/#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-iox/admin/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.
|
||||||
|
|
||||||
|
{{< tabs-wrapper >}}
|
||||||
|
{{% tabs %}}
|
||||||
|
[influx CLI](#)
|
||||||
|
[InfluxDB API](#)
|
||||||
|
{{% /tabs %}}
|
||||||
|
|
||||||
|
{{% tab-content %}}
|
||||||
|
<!------------------------------ BEGIN CLI CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the `influx bucket create` command and specify the `--schema-type=explicit` flag:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{% tab-content %}}
|
||||||
|
|
||||||
|
<!----------------------------- BEGIN API CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the HTTP API [`/api/v2/buckets`](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
endpoint and set the `schemaType` property value to `explicit` in the request body--for example:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"orgID": "{INFLUX_ORG_ID}",
|
||||||
|
"name": "my-explicit-bucket",
|
||||||
|
"description": "My Explicit Bucket",
|
||||||
|
"rp": "string",
|
||||||
|
"retentionRules": [
|
||||||
|
{
|
||||||
|
"type": "expire",
|
||||||
|
"everySeconds": 86400,
|
||||||
|
"shardGroupDurationSeconds": 0
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"schemaType": "explicit"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{< /tabs-wrapper >}}
|
||||||
|
|
||||||
|
Next, see how to [create an explicit bucket schema](/influxdb/cloud-iox/admin/buckets/bucket-schema/) for a measurement.
|
||||||
|
|
@ -0,0 +1,303 @@
|
||||||
|
---
|
||||||
|
title: Manage explicit bucket schemas
|
||||||
|
seotitle: Manage explicit bucket schemas in InfluxDB
|
||||||
|
description: Manage explicit bucket schemas using the influx CLI or InfluxDB HTTP API. Optionally, ensure data you write follows a specific schema.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud_iox:
|
||||||
|
name: Manage explicit bucket schemas
|
||||||
|
weight: 201
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 250
|
||||||
|
influxdb/cloud/tags: [buckets, bucket-schema, bucket schemas, explicit bucket schemas, explicit measurement schema, schema]
|
||||||
|
related:
|
||||||
|
- /influxdb/cloud/reference/key-concepts/
|
||||||
|
- /influxdb/cloud/reference/key-concepts/data-schema/
|
||||||
|
- /influxdb/cloud/reference/key-concepts/data-elements/
|
||||||
|
- /influxdb/cloud-iox/admin/buckets/create-bucket/
|
||||||
|
- /influxdb/cloud/reference/cli/influx/
|
||||||
|
---
|
||||||
|
|
||||||
|
Use [**explicit bucket schemas**](/influxdb/cloud-iox/reference/glossary/#bucket-schema) to enforce [column names](/influxdb/cloud-iox/reference/glossary/#column), [tags](/influxdb/cloud-iox/reference/glossary/#tag), [fields](/influxdb/cloud-iox/reference/glossary/#field), and
|
||||||
|
[data types](/influxdb/cloud-iox/reference/glossary/#data-type) for your data.
|
||||||
|
Buckets with the `explicit` schema-type, use
|
||||||
|
explicit bucket schemas to ensure measurements have specific columns and data types and to prevent non-conforming writes.
|
||||||
|
|
||||||
|
After you create a bucket schema, you're ready to [write data](/influxdb/cloud-iox/write-data/) to your bucket.
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
#### Before you begin
|
||||||
|
|
||||||
|
The examples below reference **InfluxDB data elements**. We recommend reviewing [schema design best practices](/influxdb/cloud-iox/write-data/best-practices/schema-design/) and [**elements of line protocol**](/influxdb/cloud-iox/reference/syntax/line-protocol/#elements-of-line-protocol) if you aren't familiar with these concepts.
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
- [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-iox/admin/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-iox/reference/glossary/#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)](http://ndjson.org/),
|
||||||
|
as in the following examples:
|
||||||
|
|
||||||
|
{{< code-tabs-wrapper >}}
|
||||||
|
{{% code-tabs %}}
|
||||||
|
[usage-resources.csv](#)
|
||||||
|
[usage-cpu.json](#)
|
||||||
|
[sensor.ndjson](#)
|
||||||
|
{{% /code-tabs %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/usage-resources.csv" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/usage-cpu.json" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{< /code-tabs-wrapper >}}
|
||||||
|
|
||||||
|
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`: Measurement name.
|
||||||
|
- `--columns-file`: 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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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/#operation/createMeasurementSchema)
|
||||||
|
and set the following properties in the request body:
|
||||||
|
|
||||||
|
- `name`: Measurement name.
|
||||||
|
- `columns`: Array of *column definitions* for your measurement.
|
||||||
|
|
||||||
|
For example, the following request defines the _explicit_ bucket measurement schema for `airSensors` measurements:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"name": "airSensors",
|
||||||
|
"columns": [
|
||||||
|
{"name": "time", "type": "timestamp"},
|
||||||
|
{"name": "sensorId", "type": "tag"},
|
||||||
|
{"name": "temperature", "type": "field"},
|
||||||
|
{"name": "humidity", "type": "field", "dataType": "float"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
#### Test your explicit 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.
|
||||||
|
<!-- Pending IOx troubleshoot page --
|
||||||
|
For more information about errors to expect in your tests, see [explicit schema rejections](/influxdb/cloud-iox/write-data/troubleshoot/#troubleshoot-rejected-points).
|
||||||
|
-->
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
### Write valid schemas
|
||||||
|
|
||||||
|
To ensure your schema is valid, review [schema design best practices](/influxdb/cloud-iox/write-data/best-practices/schema-design/).
|
||||||
|
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-iox/reference/glossary/#timestamp) type.
|
||||||
|
3. Include at least one column with the [`field`](/influxdb/cloud-iox/reference/glossary/#field) 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-iox/reference/glossary/#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-iox/reference/glossary/#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-iox/admin/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 {{< caps >}}Show Schema{{< /caps>}} button. Click {{< caps >}}Show Schema{{< /caps>}} 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/#operation/getMeasurementSchemas):
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# sensor.ndjson
|
||||||
|
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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/#operation/updateMeasurementSchema).
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
{{< api-endpoint method="patch" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"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-iox/reference/glossary/#token) 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.
|
||||||
|
|
||||||
|
<!-- Pending IOx troubleshoot page --
|
||||||
|
To resolve failures and partial writes, see how to [troubleshoot writes](/influxdb/cloud/write-data/troubleshoot/).
|
||||||
|
-->
|
||||||
|
|
@ -0,0 +1,42 @@
|
||||||
|
---
|
||||||
|
title: View buckets
|
||||||
|
seotitle: View buckets in InfluxDB Cloud
|
||||||
|
description: View a list of all the buckets for an organization in InfluxDB Cloud using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
|
menu:
|
||||||
|
influxdb_cloud:
|
||||||
|
name: View buckets
|
||||||
|
parent: Manage buckets
|
||||||
|
weight: 202
|
||||||
|
---
|
||||||
|
|
||||||
|
## View buckets in the InfluxDB UI
|
||||||
|
|
||||||
|
1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**.
|
||||||
|
|
||||||
|
{{< nav-icon "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/#operation/GetBuckets) to view buckets in an organization.
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="https://cloud2.influxdata.com/api/v2/buckets" %}}
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -25,7 +25,7 @@ for simpler and more performant queries.
|
||||||
- [Design for query simplicity](#design-for-query-simplicity)
|
- [Design for query simplicity](#design-for-query-simplicity)
|
||||||
- [Keep measurement names, tag keys, and field keys simple](#keep-measurement-names-tag-keys-and-field-keys-simple)
|
- [Keep measurement names, tag keys, and field keys simple](#keep-measurement-names-tag-keys-and-field-keys-simple)
|
||||||
- [Avoid keywords and special characters](#avoid-keywords-and-special-characters)
|
- [Avoid keywords and special characters](#avoid-keywords-and-special-characters)
|
||||||
|
- [Use explicit bucket schemas to enforce schema](#use-explicit-bucket-schemas-to-enforce-schema)
|
||||||
---
|
---
|
||||||
|
|
||||||
## InfluxDB data structure
|
## InfluxDB data structure
|
||||||
|
|
@ -75,12 +75,14 @@ The InfluxDB IOx engine supports nearly infinite tag value and series cardinalit
|
||||||
|
|
||||||
### Do not use duplicate names for tags and fields
|
### Do not use duplicate names for tags and fields
|
||||||
|
|
||||||
Tags and fields within the same measurement can not be named the same.
|
Tags and fields within the same measurement can't be named the same.
|
||||||
All tags an fields are stored as unique columns in a table representing the
|
All tags and fields are stored as unique columns in a table representing the
|
||||||
measurement on disk. Tags and fields named the same cause a column conflict.
|
measurement on disk.
|
||||||
|
If you attempt to write a measurement that contains tags or fields with the same name,
|
||||||
|
the write fails due to a column conflict.
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
Use [explicit bucket schemas](/influxdb/cloud-iox/...) to enforce unique tag and
|
Use [explicit bucket schemas](/influxdb/cloud-iox/admin/buckets/manage-explicit-bucket-schemas/) to enforce unique tag and
|
||||||
field keys within a schema.
|
field keys within a schema.
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
|
|
@ -366,3 +368,9 @@ iox.from(bucket: "example-bucket")
|
||||||
|
|
||||||
{{% /code-tab-content %}}
|
{{% /code-tab-content %}}
|
||||||
{{< /code-tabs-wrapper >}}
|
{{< /code-tabs-wrapper >}}
|
||||||
|
|
||||||
|
## Use explicit bucket schemas to enforce schema
|
||||||
|
|
||||||
|
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,
|
||||||
|
use [`explicit` buckets and explicit bucket schemas](/influxdb/cloud-iox/admin/buckets/manage-explicit-bucket-schemas/).
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
title: Manage bucket schemas
|
title: Manage bucket schemas
|
||||||
seotitle: Manage bucket schemas in InfluxDB
|
seotitle: Manage bucket schemas in InfluxDB
|
||||||
description: Manage bucket schemas in InfluxDB. Optionally, ensure data written to InfluxDB follows a specific schema.
|
description: Manage explicit bucket schemas using the influx CLI or InfluxDB HTTP API. Optionally, ensure data you write follows a specific schema.
|
||||||
menu:
|
menu:
|
||||||
influxdb_cloud:
|
influxdb_cloud:
|
||||||
name: Manage explicit bucket schemas
|
name: Manage explicit bucket schemas
|
||||||
|
|
@ -12,12 +12,13 @@ related:
|
||||||
- /influxdb/cloud/reference/key-concepts/
|
- /influxdb/cloud/reference/key-concepts/
|
||||||
- /influxdb/cloud/reference/key-concepts/data-schema/
|
- /influxdb/cloud/reference/key-concepts/data-schema/
|
||||||
- /influxdb/cloud/reference/key-concepts/data-elements/
|
- /influxdb/cloud/reference/key-concepts/data-elements/
|
||||||
|
- /influxdb/cloud/organizations/buckets/create-bucket/
|
||||||
|
- /influxdb/cloud/reference/cli/influx/
|
||||||
---
|
---
|
||||||
|
|
||||||
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
|
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.
|
[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.
|
||||||
{{% bucket-schema/type %}}
|
|
||||||
|
|
||||||
After you create a bucket schema, you're ready to [write data](/influxdb/cloud/write-data/) to your bucket.
|
After you create a bucket schema, you're ready to [write data](/influxdb/cloud/write-data/) to your bucket.
|
||||||
|
|
||||||
|
|
@ -25,148 +26,209 @@ After you create a bucket schema, you're ready to [write data](/influxdb/cloud/w
|
||||||
|
|
||||||
#### Before you begin
|
#### Before you begin
|
||||||
|
|
||||||
The `bucket-schema` 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.
|
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.
|
||||||
|
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
- [Create a bucket schema](#create-a-bucket-schema)
|
- [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](#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)
|
- [Troubleshoot write errors](#troubleshoot-write-errors)
|
||||||
|
|
||||||
## Create a bucket schema
|
## Create an explicit bucket and schema
|
||||||
Use the `influx` CLI to set the schema-type and measurement schemas for your bucket:
|
|
||||||
1. Create a bucket with the `schema-type` flag set to `explicit`.
|
|
||||||
|
|
||||||
```sh
|
To create an explicit bucket and schemas for your data, do the following:
|
||||||
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Use your text editor to create a schema columns file for each measurement you want to add.
|
1. If you haven't already, [create a bucket that enforces explicit schemas](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-that-enforces-explicit-schemas).
|
||||||
The file defines the column names, tags, fields, and data types to require for a measurement.
|
2. [Create a bucket schema](#create-a-bucket-schema).
|
||||||
|
|
||||||
Format the file as CSV, JSON, or [Newline delimited JSON (NDJSON)](http://ndjson.org/),
|
### Create a bucket schema
|
||||||
as in the following examples:
|
|
||||||
|
|
||||||
{{% code-tabs-wrapper %}}
|
|
||||||
{{% code-tabs %}}
|
|
||||||
[usage-resources.csv](#)
|
|
||||||
[usage-cpu.json](#)
|
|
||||||
[sensor.ndjson](#)
|
|
||||||
{{% /code-tabs %}}
|
|
||||||
{{% code-tab-content %}}
|
|
||||||
```sh
|
|
||||||
{{< get-shared-text "bucket-schema/usage-resources.csv" >}}
|
|
||||||
```
|
|
||||||
{{% /code-tab-content %}}
|
|
||||||
{{% code-tab-content %}}
|
|
||||||
```json
|
|
||||||
{{< get-shared-text "bucket-schema/usage-cpu.json" >}}
|
|
||||||
```
|
|
||||||
{{% /code-tab-content %}}
|
|
||||||
{{% code-tab-content %}}
|
|
||||||
```json
|
|
||||||
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
|
||||||
```
|
|
||||||
{{% /code-tab-content %}}
|
|
||||||
{{% /code-tabs-wrapper %}}
|
|
||||||
|
|
||||||
#### Write valid schemas
|
With an `explicit` bucket, you predefine *measurement schemas* with column names, tags, fields, and data types for measurements.
|
||||||
To ensure your schema is valid, review [InfluxDB data elements](/influxdb/cloud/reference/key-concepts/data-elements/).
|
A measurement schema has the following properties:
|
||||||
Follow these rules when creating your schema columns file:
|
|
||||||
1. Use valid measurement and column names that:
|
- `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)](http://ndjson.org/),
|
||||||
|
as in the following examples:
|
||||||
|
{{< code-tabs-wrapper >}}
|
||||||
|
{{% code-tabs %}}
|
||||||
|
[usage-resources.csv](#)
|
||||||
|
[usage-cpu.json](#)
|
||||||
|
[sensor.ndjson](#)
|
||||||
|
{{% /code-tabs %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/usage-resources.csv" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/usage-cpu.json" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{% code-tab-content %}}
|
||||||
|
```json
|
||||||
|
{{< get-shared-text "bucket-schema/sensor.ndjson" >}}
|
||||||
|
```
|
||||||
|
{{% /code-tab-content %}}
|
||||||
|
{{< /code-tabs-wrapper >}}
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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/#operation/createMeasurementSchema)
|
||||||
|
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:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"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).
|
||||||
|
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
### 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 unique within the schema
|
||||||
- Are 1 to 128 characters long
|
- Are 1 to 128 characters long
|
||||||
- Contain only [Unicode](https://www.unicode.org/charts/) characters
|
- Contain only [Unicode](https://www.unicode.org/charts/) characters
|
||||||
- Don't start with underscore `_`
|
- Don't start with underscore `_`
|
||||||
- Don't start with a number `0-9`
|
- Don't start with a number `0-9`
|
||||||
- Don't contain single quote `'` or double quote `"`
|
- Don't contain single quote `'` or double quote `"`
|
||||||
2. Include a column with the [`timestamp`](/influxdb/cloud/reference/key-concepts/data-elements/#timestamp) type.
|
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:
|
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.
|
**Valid**: a schema with [`timestamp`]() and [`field`]() columns.
|
||||||
```json
|
```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":"time","type":"timestamp"},
|
||||||
{"name":"fsWrite","type":"field","dataType":"float"}
|
{"name":"fsWrite","type":"field"}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Use the [`influx bucket-schema create` command](/influxdb/cloud/reference/cli/influx/bucket-schema/create) to add the schema for each measurement to your bucket.
|
**Not valid**: a schema without a `field` column.
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{"name":"time","type":"timestamp"},
|
||||||
|
{"name":"host","type":"tag"}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
Provide the following:
|
The default [field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) is `string`.
|
||||||
- location of your file with the `columns-file` flag
|
To set the data type of a field column, provide the `dataType` property and a valid
|
||||||
- measurement name with the `name` flag. 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.
|
[field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) (`string`, `float`, `integer`, or `boolean`),
|
||||||
|
as in the following example:
|
||||||
|
|
||||||
```sh
|
```json
|
||||||
influx bucket-schema create \
|
[
|
||||||
--bucket my_explicit_bucket \
|
{"name":"time","type":"timestamp"},
|
||||||
--name usage_resources \
|
{"name":"fsWrite","type":"field","dataType":"float"}
|
||||||
--columns-file usage-resources.csv
|
]
|
||||||
|
```
|
||||||
|
|
||||||
influx bucket-schema create \
|
## View bucket schema type and schemas
|
||||||
--bucket my_explicit_bucket \
|
|
||||||
--name usage_cpu \
|
|
||||||
--columns-file usage-cpu.json
|
|
||||||
|
|
||||||
influx bucket-schema create \
|
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.
|
||||||
--bucket my_explicit_bucket \
|
|
||||||
--name sensor \
|
|
||||||
--columns-file sensor.ndjson
|
|
||||||
```
|
|
||||||
|
|
||||||
### Troubleshoot create errors
|
### View schema type and schemas in the InfluxDB UI
|
||||||
|
|
||||||
#### Failed to create measurement
|
1. [View buckets](/influxdb/cloud/organizations/buckets/view-buckets/).
|
||||||
If you attempt to `create` a schema for an existing measurement name, InfluxDB rejects the new schema and returns the following error:
|
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 {{< caps >}}Show Schema{{< /caps>}} button. Click {{< caps >}}Show Schema{{< /caps>}} to view measurement schemas for the bucket.
|
||||||
|
|
||||||
```sh
|
### View schema type and schemas using the influx CLI
|
||||||
Error: failed to create measurement: 422 Unprocessable Entity
|
|
||||||
```
|
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/#operation/getMeasurementSchemas):
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements" %}}
|
||||||
|
|
||||||
## Update a bucket schema
|
## Update a bucket schema
|
||||||
|
|
||||||
Use the [`influx bucket-schema update` command](/influxdb/cloud/reference/cli/influx/bucket-schema/update) to add new columns to a schema. You cannot modify or delete columns in bucket schemas.
|
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.
|
||||||
|
|
||||||
1. View explicit bucket schemas.
|
- [Update a bucket schema using the influx CLI](#update-a-bucket-schema-using-the-influx-cli)
|
||||||
Use the [`extended-output` flag](/influxdb/cloud/reference/cli/influx/bucket-schema/list#list-all-schema-of-a-bucket-and-print-column-information) with the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket-schema/list) to view column details.
|
- [Update a bucket schema using the InfluxDB HTTP API](#update-a-bucket-schema-using-the-influxdb-http-api)
|
||||||
|
|
||||||
```sh
|
### Update a bucket schema using the influx CLI
|
||||||
influx bucket-schema list \
|
|
||||||
--bucket my_explicit_bucket \
|
|
||||||
--extended-output
|
|
||||||
```
|
|
||||||
|
|
||||||
InfluxDB returns column details:
|
1. [View the existing measurement schema](#view-schema-type-and-schemas-using-the-influx-cli) and save the `columns` list to a file.
|
||||||
|
|
||||||
```sh
|
2. In your text editor or terminal, append new columns to the list from the previous step.
|
||||||
ID Measurement Name Column Name Column Type Column Data Type Bucket ID
|
The following example appends column `CO2` to the original *sensor.ndjson* schema file:
|
||||||
07c62z721z2ca000 sensor time timestamp a7d5558b880a95da
|
|
||||||
07c62z721z2ca000 sensor service tag a7d5558b880a95da
|
|
||||||
07c62z721z2ca000 sensor sensor tag a7d5558b880a95da
|
|
||||||
07c62z721z2ca000 sensor temperature field float a7d5558b880a95da
|
|
||||||
07c62z721z2ca000 sensor humidity field float a7d5558b880a95da
|
|
||||||
```
|
|
||||||
|
|
||||||
2. In your text editor or terminal, [create](#create-a-bucket-schema) or edit the schema columns file and append new columns. The following example appends column `CO2` to the original *sensor.ndjson* schema file:
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
# sensor.ndjson
|
# sensor.ndjson
|
||||||
|
|
@ -177,7 +239,7 @@ Use the [`extended-output` flag](/influxdb/cloud/reference/cli/influx/bucket-sch
|
||||||
echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson
|
echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Use the [`influx bucket-schema update` command](/influxdb/cloud/reference/cli/influx/bucket-schema/update) to add the new columns to the bucket schema.
|
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.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
influx bucket-schema update \
|
influx bucket-schema update \
|
||||||
|
|
@ -186,6 +248,47 @@ Use the [`extended-output` flag](/influxdb/cloud/reference/cli/influx/bucket-sch
|
||||||
--columns-file sensor.ndjson
|
--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/#operation/updateMeasurementSchema).
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
{{< api-endpoint method="patch" endpoint="https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"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/security/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
|
## Troubleshoot write errors
|
||||||
|
|
||||||
InfluxDB returns an error for the following reasons:
|
InfluxDB returns an error for the following reasons:
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
title: Create a bucket
|
title: Create a bucket
|
||||||
seotitle: Create a bucket in InfluxDB
|
seotitle: Create a bucket in InfluxDB Cloud
|
||||||
description: Create buckets to store time series data in InfluxDB using the InfluxDB UI or the influx CLI.
|
description: Create buckets to store time series data in InfluxDB Cloud using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
menu:
|
menu:
|
||||||
influxdb_cloud:
|
influxdb_cloud:
|
||||||
name: Create a bucket
|
name: Create a bucket
|
||||||
|
|
@ -9,9 +9,18 @@ menu:
|
||||||
weight: 201
|
weight: 201
|
||||||
---
|
---
|
||||||
|
|
||||||
Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI)
|
Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB HTTP API
|
||||||
to create a bucket.
|
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 in the InfluxDB UI](#create-a-bucket-in-the-influxdb-ui)
|
||||||
|
- [Create a bucket using the influx CLI](#create-a-bucket-using-the-influx-cli)
|
||||||
|
- [Create a bucket using the InfluxDB HTTP API](#create-a-bucket-using-the-influxdb-api)
|
||||||
|
- [Create a bucket that enforces explicit schemas](#create-a-bucket-that-enforces-explicit-schemas)
|
||||||
|
|
||||||
## Create a bucket in the InfluxDB UI
|
## Create a bucket in the InfluxDB UI
|
||||||
|
|
||||||
There are two places you can create a bucket in the UI.
|
There are two places you can create a bucket in the UI.
|
||||||
|
|
@ -44,72 +53,90 @@ There are two places you can create a bucket in the UI.
|
||||||
|
|
||||||
## Create a bucket using the influx CLI
|
## Create a bucket using the influx CLI
|
||||||
|
|
||||||
Use the [`influx bucket create` command](/influxdb/cloud/reference/cli/influx/bucket/create)
|
To create a bucket with the `influx` CLI, use the [`influx bucket create` command](/influxdb/cloud/reference/cli/influx/bucket/create)
|
||||||
to create a new bucket. A bucket requires the following:
|
and specify values for the following flags:
|
||||||
|
|
||||||
- bucket name
|
- `-o`, `--org`: Organization name
|
||||||
- organization name or ID
|
- `-n`, `--name`: Bucket name
|
||||||
- retention period (duration to keep data) in one of the following units:
|
- `-r`, `--retention`: Retention period duration
|
||||||
- nanoseconds (`ns`)
|
|
||||||
- microseconds (`us` or `µs`)
|
|
||||||
- milliseconds (`ms`)
|
|
||||||
- seconds (`s`)
|
|
||||||
- minutes (`m`)
|
|
||||||
- hours (`h`)
|
|
||||||
- days (`d`)
|
|
||||||
- weeks (`w`)
|
|
||||||
|
|
||||||
{{% note %}}
|
The following example creates a bucket with a retention period of `72` hours:
|
||||||
The minimum retention period is **one hour**.
|
|
||||||
{{% /note %}}
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
# Syntax
|
influx bucket create -n my-bucket -o {INFLUX_ORG} -r 72h
|
||||||
influx bucket create -n <BUCKET_NAME> -o <INFLUX_ORG> -r <RETENTION_PERIOD_DURATION>
|
|
||||||
|
|
||||||
# Example
|
|
||||||
influx bucket create -n my-bucket -o my-org -r 72h
|
|
||||||
```
|
```
|
||||||
### Create a bucket with an explicit schema
|
|
||||||
|
|
||||||
{{% bucket-schema/type %}}
|
## Create a bucket using the InfluxDB API
|
||||||
|
|
||||||
1.
|
To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:
|
||||||
```sh
|
|
||||||
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Create a bucket schema. For more information, see [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/).
|
[{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
|
||||||
```sh
|
In your request body, specify values for the following properties:
|
||||||
influx bucket-schema create \
|
|
||||||
--bucket my_schema_bucket \
|
|
||||||
--name temperature \
|
|
||||||
--columns-file schema.json
|
|
||||||
```
|
|
||||||
|
|
||||||
### Create a bucket using the InfluxDB API
|
| Requirement | Include by |
|
||||||
|
|:---------------------|:-----------------|
|
||||||
|
| Organization | `orgID` |
|
||||||
|
| Bucket | `name` |
|
||||||
|
| Retention Rules | `retentionRules` |
|
||||||
|
|
||||||
Use the InfluxDB API to create a bucket.
|
The following example creates a bucket with a retention period of `86,400` seconds, or 24 hours:
|
||||||
|
|
||||||
|
|
||||||
Create a bucket in InfluxDB using an HTTP request to the InfluxDB API `/buckets` endpoint.
|
|
||||||
Use the `POST` request method and include the following in your request:
|
|
||||||
|
|
||||||
| Requirement | Include by |
|
|
||||||
|:----------- |:---------- |
|
|
||||||
| Organization | Use `orgID` in the JSON payload. |
|
|
||||||
| Bucket | Use `name` in the JSON payload. |
|
|
||||||
| Retention Rules | Use `retentionRules` in the JSON payload. |
|
|
||||||
| API token | Use the `Authorization: Token` header. |
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
The URL depends on your InfluxDB Cloud region _(see [InfluxDB URLs](/influxdb/cloud/reference/regions/))_.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
|
{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
|
||||||
```
|
```
|
||||||
|
|
||||||
_For information about **InfluxDB API options and response codes**, see
|
_For information about **InfluxDB API options and response codes**, see
|
||||||
[InfluxDB API Buckets documentation](/influxdb/cloud/api/#operation/PostBuckets)._
|
[InfluxDB API Buckets reference documentation](/influxdb/cloud/api/#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/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.
|
||||||
|
|
||||||
|
{{< tabs-wrapper >}}
|
||||||
|
{{% tabs %}}
|
||||||
|
[influx CLI](#)
|
||||||
|
[InfluxDB API](#)
|
||||||
|
{{% /tabs %}}
|
||||||
|
|
||||||
|
{{% tab-content %}}
|
||||||
|
<!------------------------------ BEGIN CLI CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the `influx bucket create` command and specify the `--schema-type=explicit` flag:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{% tab-content %}}
|
||||||
|
|
||||||
|
<!----------------------------- BEGIN API CONTENT ----------------------------->
|
||||||
|
|
||||||
|
Use the HTTP API [`/api/v2/buckets`](/influxdb/cloud/api/#operation/PostBuckets)
|
||||||
|
endpoint and set the `schemaType` property value to `explicit` in the request body--for example:
|
||||||
|
|
||||||
|
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/api/v2/buckets" >}}
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"orgID": "{INFLUX_ORG_ID}",
|
||||||
|
"name": "my-explicit-bucket",
|
||||||
|
"description": "My Explicit Bucket",
|
||||||
|
"rp": "string",
|
||||||
|
"retentionRules": [
|
||||||
|
{
|
||||||
|
"type": "expire",
|
||||||
|
"everySeconds": 86400,
|
||||||
|
"shardGroupDurationSeconds": 0
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"schemaType": "explicit"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
{{% /tab-content %}}
|
||||||
|
{{< /tabs-wrapper >}}
|
||||||
|
|
||||||
|
Next, see how to [create an explicit bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/) for a measurement.
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
title: View buckets
|
title: View buckets
|
||||||
seotitle: View buckets in InfluxDB
|
seotitle: View buckets in InfluxDB
|
||||||
description: View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI or the influx CLI.
|
description: View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
|
||||||
menu:
|
menu:
|
||||||
influxdb_cloud:
|
influxdb_cloud:
|
||||||
name: View buckets
|
name: View buckets
|
||||||
|
|
@ -23,7 +23,7 @@ weight: 202
|
||||||
## View buckets using the influx CLI
|
## View buckets using the influx CLI
|
||||||
|
|
||||||
Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list)
|
Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list)
|
||||||
to view a buckets in an organization.
|
to view buckets in an organization.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
influx bucket list
|
influx bucket list
|
||||||
|
|
@ -32,3 +32,9 @@ influx bucket list
|
||||||
Other filtering options such as filtering by a name or ID are available.
|
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)
|
See the [`influx bucket list` documentation](/influxdb/cloud/reference/cli/influx/bucket/list)
|
||||||
for information about other available flags.
|
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/#operation/GetBuckets) to view buckets in an organization.
|
||||||
|
|
||||||
|
{{% api-endpoint method="get" endpoint="https://cloud2.influxdata.com/api/v2/buckets" %}}
|
||||||
|
|
@ -776,7 +776,7 @@ For example, if the precision is set to `ms`, the nanosecond epoch timestamp `14
|
||||||
Telegraf output plugins do not alter the timestamp further.
|
Telegraf output plugins do not alter the timestamp further.
|
||||||
The precision setting is ignored for service input plugins.
|
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)
|
Related entries: [aggregator plugin](#aggregator-plugin), [input plugin](#input-plugin), [output plugin](#output-plugin), [processor plugin](#processor-plugin), [service input plugin](#service-input-plugin)
|
||||||
|
|
||||||
### predicate expression
|
### predicate expression
|
||||||
|
|
||||||
|
|
@ -865,7 +865,7 @@ The InfluxDB 2.x equivalent is [retention period](#retention-period).
|
||||||
For more information about retention policies, see the
|
For more information about retention policies, see the
|
||||||
[latest 1.x documentation](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
|
[latest 1.x documentation](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
|
||||||
|
|
||||||
Related entries: [retention period](#retention-period),
|
Related entries: [retention period](#retention-period),
|
||||||
|
|
||||||
### RFC3339 timestamp
|
### RFC3339 timestamp
|
||||||
A timestamp that uses the human-readable DateTime format proposed in
|
A timestamp that uses the human-readable DateTime format proposed in
|
||||||
|
|
@ -1165,7 +1165,7 @@ There are different types of API tokens:
|
||||||
|
|
||||||
{{% /cloud-only %}}
|
{{% /cloud-only %}}
|
||||||
|
|
||||||
Related entries: [Create a token](/influxdb/v2.6/security/tokens/create-token/).
|
Learn how to [create a token](/influxdb/v2.6/security/tokens/create-token/).
|
||||||
|
|
||||||
### tracing
|
### tracing
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
By default, buckets have an `implicit` **schema-type** and a schema that
|
By default, buckets have an `implicit` **schema-type** and a schema that
|
||||||
conforms to your data.
|
conforms to your data.
|
||||||
To require data to have specific columns and data types and prevent non-conforming write requests,
|
To require measurements to have specific columns and data types and prevent non-conforming write requests,
|
||||||
[create a bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/#create-a-bucket-schema).
|
[use `explicit` buckets and measurement schema](/influxdb/cloud/organizations/buckets/bucket-schema).
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue