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)
|
||||
- [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)
|
||||
|
||||
- [Use explicit bucket schemas to enforce schema](#use-explicit-bucket-schemas-to-enforce-schema)
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Tags and fields within the same measurement can not be named the same.
|
||||
All tags an fields are stored as unique columns in a table representing the
|
||||
measurement on disk. Tags and fields named the same cause a column conflict.
|
||||
Tags and fields within the same measurement can't be named the same.
|
||||
All tags and fields are stored as unique columns in a table representing the
|
||||
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 %}}
|
||||
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.
|
||||
{{% /note %}}
|
||||
|
||||
|
|
@ -366,3 +368,9 @@ iox.from(bucket: "example-bucket")
|
|||
|
||||
{{% /code-tab-content %}}
|
||||
{{< /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
|
||||
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:
|
||||
influxdb_cloud:
|
||||
name: Manage explicit bucket schemas
|
||||
|
|
@ -12,12 +12,13 @@ related:
|
|||
- /influxdb/cloud/reference/key-concepts/
|
||||
- /influxdb/cloud/reference/key-concepts/data-schema/
|
||||
- /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
|
||||
[data types](/influxdb/cloud/reference/glossary/#data-type) for your data.
|
||||
|
||||
{{% bucket-schema/type %}}
|
||||
Explicit bucket schemas ensure that measurements have specific columns and data types and prevent non-conforming write requests.
|
||||
|
||||
After you create a bucket schema, you're ready to [write data](/influxdb/cloud/write-data/) to your bucket.
|
||||
|
||||
|
|
@ -25,148 +26,209 @@ After you create a bucket schema, you're ready to [write data](/influxdb/cloud/w
|
|||
|
||||
#### 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 %}}
|
||||
|
||||
- [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 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 a bucket 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`.
|
||||
## Create an explicit bucket and schema
|
||||
|
||||
```sh
|
||||
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
||||
```
|
||||
To create an explicit bucket and schemas for your data, do the following:
|
||||
|
||||
2. Use your text editor to create a schema columns file for each measurement you want to add.
|
||||
The file defines the column names, tags, fields, and data types to require for a measurement.
|
||||
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).
|
||||
2. [Create a bucket schema](#create-a-bucket-schema).
|
||||
|
||||
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 %}}
|
||||
### Create a bucket schema
|
||||
|
||||
#### 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:
|
||||
With an `explicit` bucket, you predefine *measurement schemas* with column names, tags, fields, and data types for measurements.
|
||||
A measurement schema has the following properties:
|
||||
|
||||
- `name`: the measurement name. The name must match the [measurement column](/influxdb/cloud/reference/key-concepts/data-elements/#measurement) in your data, obey [naming rules](#write-valid-schemas), and be unique within the bucket.
|
||||
- `columns`: a list of *column definitions* for the measurement.
|
||||
|
||||
To learn more about rules for measurement _names_ and _columns_, see how to [write valid schemas](#write-valid-schemas).
|
||||
|
||||
Use the [**`influx` CLI**](/influxdb/cloud/reference/cli/influx/) or [**InfluxDB HTTP API**](/influxdb/cloud/api) to create an explicit bucket schema for a measurement.
|
||||
|
||||
- [Create a bucket schema using the influx CLI](#create-a-bucket-schema-using-the-influx-cli)
|
||||
- [Create a bucket schema using the InfluxDB HTTP API](#create-a-bucket-schema-using-the-influxdb-http-api)
|
||||
|
||||
#### Create a bucket schema using the influx CLI
|
||||
|
||||
1. Use your text editor to create a schema columns file for each measurement you want to add. Format the file as CSV, JSON, or [Newline delimited JSON (NDJSON)](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 1 to 128 characters long
|
||||
- Contain only [Unicode](https://www.unicode.org/charts/) characters
|
||||
- Don't start with underscore `_`
|
||||
- Don't start with a number `0-9`
|
||||
- Don't contain single quote `'` or double quote `"`
|
||||
2. Include a column with the [`timestamp`](/influxdb/cloud/reference/key-concepts/data-elements/#timestamp) type.
|
||||
3. Include at least one column with the [`field`](/influxdb/cloud/reference/key-concepts/data-elements/#fields) type (without a field, there is no time-series data), as in the following example:
|
||||
2. Include a column with the [`timestamp`](/influxdb/cloud/reference/key-concepts/data-elements/#timestamp) type.
|
||||
3. Include at least one column with the [`field`](/influxdb/cloud/reference/key-concepts/data-elements/#fields) type (without a field, there is no time-series data), as in the following example:
|
||||
|
||||
**Valid**: a schema with [`timestamp`]() and [`field`]() columns.
|
||||
```json
|
||||
[
|
||||
{"name":"time","type":"timestamp"},
|
||||
{"name":"fsWrite","type":"field"}
|
||||
]
|
||||
```
|
||||
|
||||
**Not valid**: a schema without a `field` column.
|
||||
```json
|
||||
[
|
||||
{"name":"time","type":"timestamp"},
|
||||
{"name":"host","type":"tag"}
|
||||
]
|
||||
```
|
||||
|
||||
The default [field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) is `string`.
|
||||
To set the data type of a field column, provide the `dataType` property and a valid
|
||||
[field data type](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) (`string`, `float`, `integer`, or `boolean`),
|
||||
as in the following example:
|
||||
|
||||
```json
|
||||
[
|
||||
**Valid**: a schema with [`timestamp`]() and [`field`]() columns.
|
||||
```json
|
||||
[
|
||||
{"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:
|
||||
- location of your file with the `columns-file` flag
|
||||
- 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.
|
||||
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:
|
||||
|
||||
```sh
|
||||
influx bucket-schema create \
|
||||
--bucket my_explicit_bucket \
|
||||
--name usage_resources \
|
||||
--columns-file usage-resources.csv
|
||||
```json
|
||||
[
|
||||
{"name":"time","type":"timestamp"},
|
||||
{"name":"fsWrite","type":"field","dataType":"float"}
|
||||
]
|
||||
```
|
||||
|
||||
influx bucket-schema create \
|
||||
--bucket my_explicit_bucket \
|
||||
--name usage_cpu \
|
||||
--columns-file usage-cpu.json
|
||||
## View bucket schema type and schemas
|
||||
|
||||
influx bucket-schema create \
|
||||
--bucket my_explicit_bucket \
|
||||
--name sensor \
|
||||
--columns-file sensor.ndjson
|
||||
```
|
||||
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.
|
||||
|
||||
### Troubleshoot create errors
|
||||
### View schema type and schemas in the InfluxDB UI
|
||||
|
||||
#### Failed to create measurement
|
||||
If you attempt to `create` a schema for an existing measurement name, InfluxDB rejects the new schema and returns the following error:
|
||||
1. [View buckets](/influxdb/cloud/organizations/buckets/view-buckets/).
|
||||
2. In the list of buckets, see the **Schema Type** in the metadata that follows each bucket name.
|
||||
3. Buckets with **Schema Type: Explicit** display the {{< caps >}}Show Schema{{< /caps>}} button. Click {{< caps >}}Show Schema{{< /caps>}} to view measurement schemas for the bucket.
|
||||
|
||||
```sh
|
||||
Error: failed to create measurement: 422 Unprocessable Entity
|
||||
```
|
||||
### 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 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.
|
||||
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 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)
|
||||
|
||||
```sh
|
||||
influx bucket-schema list \
|
||||
--bucket my_explicit_bucket \
|
||||
--extended-output
|
||||
```
|
||||
### Update a bucket schema using the influx CLI
|
||||
|
||||
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
|
||||
ID Measurement Name Column Name Column Type Column Data Type Bucket ID
|
||||
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:
|
||||
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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
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
|
||||
influx bucket-schema update \
|
||||
|
|
@ -186,6 +248,47 @@ Use the [`extended-output` flag](/influxdb/cloud/reference/cli/influx/bucket-sch
|
|||
--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
|
||||
|
||||
InfluxDB returns an error for the following reasons:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Create a bucket
|
||||
seotitle: Create a bucket in InfluxDB
|
||||
description: Create buckets to store time series data in InfluxDB using the InfluxDB UI or the influx CLI.
|
||||
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:
|
||||
name: Create a bucket
|
||||
|
|
@ -9,9 +9,18 @@ menu:
|
|||
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.
|
||||
|
||||
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.
|
||||
|
|
@ -44,72 +53,90 @@ There are two places you can create a bucket in the UI.
|
|||
|
||||
## Create a bucket using 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:
|
||||
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:
|
||||
|
||||
- bucket name
|
||||
- organization name or ID
|
||||
- retention period (duration to keep data) in one of the following units:
|
||||
- nanoseconds (`ns`)
|
||||
- microseconds (`us` or `µs`)
|
||||
- milliseconds (`ms`)
|
||||
- seconds (`s`)
|
||||
- minutes (`m`)
|
||||
- hours (`h`)
|
||||
- days (`d`)
|
||||
- weeks (`w`)
|
||||
- `-o`, `--org`: Organization name
|
||||
- `-n`, `--name`: Bucket name
|
||||
- `-r`, `--retention`: Retention period duration
|
||||
|
||||
{{% note %}}
|
||||
The minimum retention period is **one hour**.
|
||||
{{% /note %}}
|
||||
The following example creates a bucket with a retention period of `72` hours:
|
||||
|
||||
```sh
|
||||
# Syntax
|
||||
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
|
||||
influx bucket create -n my-bucket -o {INFLUX_ORG} -r 72h
|
||||
```
|
||||
### Create a bucket with an explicit schema
|
||||
|
||||
{{% bucket-schema/type %}}
|
||||
## Create a bucket using the InfluxDB API
|
||||
|
||||
1.
|
||||
```sh
|
||||
{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}}
|
||||
```
|
||||
To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:
|
||||
|
||||
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
|
||||
influx bucket-schema create \
|
||||
--bucket my_schema_bucket \
|
||||
--name temperature \
|
||||
--columns-file schema.json
|
||||
```
|
||||
In your request body, specify values for the following properties:
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
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/))_.
|
||||
The following example creates a bucket with a retention period of `86,400` seconds, or 24 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 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
|
||||
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:
|
||||
influxdb_cloud:
|
||||
name: View buckets
|
||||
|
|
@ -23,7 +23,7 @@ weight: 202
|
|||
## View buckets using the influx CLI
|
||||
|
||||
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
|
||||
influx bucket list
|
||||
|
|
@ -32,3 +32,9 @@ 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" %}}
|
||||
|
|
@ -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.
|
||||
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
|
||||
|
||||
|
|
@ -865,7 +865,7 @@ The InfluxDB 2.x equivalent is [retention period](#retention-period).
|
|||
For more information about retention policies, see the
|
||||
[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
|
||||
A timestamp that uses the human-readable DateTime format proposed in
|
||||
|
|
@ -1165,7 +1165,7 @@ There are different types of API tokens:
|
|||
|
||||
{{% /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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
By default, buckets have an `implicit` **schema-type** and a schema that
|
||||
conforms to your data.
|
||||
To require data 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).
|
||||
To require measurements to have specific columns and data types and prevent non-conforming write requests,
|
||||
[use `explicit` buckets and measurement schema](/influxdb/cloud/organizations/buckets/bucket-schema).
|
||||
|
|
|
|||
Loading…
Reference in New Issue