Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Feature/2470 bucket schema (#2765) 

feature: document new CLI support for managing explicit bucket schemas (#2470)
  * "explicit" schema-type for buckets
  * `bucket-schema` to manage measurement schemas for buckets
  * task-based overview of new bucket-schema feature in CLI for cloud.
  * reference docs for bucket-schema and bucket schema-type.
  * columns file examples.

other technical updates
* added shortcodes `get-leaf-text` and `get-assets-text`. Documented in CONTRIBUTING.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>
Co-authored-by: Kelly <kelly@influxdata.com>
Co-authored-by: null <kelseiv@users.noreply.github.com>
pull/2819/head
Jason Stirnaman 2021-07-07 11:53:54 -05:00 committed by GitHub
parent 01a25524c4
commit e7858c75d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 653 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
CONTRIBUTING.md
View File

@ -260,7 +260,7 @@ Find more info [here][{{< enterprise-link >}}]
```
### InfluxDB Cloud Content
For sections content that relate specifically to InfluxDB Cloud, use the `{{% cloud %}}` shortcode.
For sections of content that relate specifically to InfluxDB Cloud, use the `{{% cloud %}}` shortcode.
```md
{{% cloud %}}
@ -520,7 +520,7 @@ flowchart TB
Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system
diagram using a Markdown unordered list.
##### Example filestsytem diagram shortcode
##### Example filesystem diagram shortcode
```md
{{< filesystem-diagram >}}
- Dir1/
@ -668,6 +668,80 @@ list_code_example: |
```
~~~
#### Organize and include native code examples
To include text from a file in `/assets/text/`, use the
`{{< get-assets-text >}}` shortcode and provide the relative path and filename.
This is useful for maintaining and referencing sample code variants in their
native file formats.
1. Store code examples in their native formats at `/assets/text/`.
```md
/assets/text/example1/example.js
/assets/text/example1/example.py
```
2. Include the files, e.g. in code tabs
````md
{{% code-tabs-wrapper %}}
{{% code-tabs %}}
[Javascript](#js)
[Python](#py)
{{% /code-tabs %}}
{{% code-tab-content %}}
```js
{{< get-assets-text "example1/example.js" >}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```py
{{< get-assets-text "example1/example.py" >}}
```
{{% /code-tab-content %}}
{{% /code-tabs-wrapper %}}
````
#### Include specific files from the same directory
To include the text from one file in another file in the same
directory, use the `{{< get-leaf-text >}}` shortcode.
The directory that contains both files must be a
Hugo [*Leaf Bundle*](https://gohugo.io/content-management/page-bundles/#leaf-bundles),
a directory that doesn't have any child directories.
In the following example, `api` is a leaf bundle. `content` isn't.
```md
content
|
|--- api
| query.pdmc
| query.sh
| _index.md
```
##### query.pdmc
```md
# Query examples
```
##### query.sh
```md
curl https://localhost:8086/query
```
To include `query.sh` and `query.pdmc` in `api/_index.md`, use the following code:
````md
{{< get-leaf-text "query.pdmc" >}}
# Curl example
```sh
{{< get-leaf-text "query.sh" >}}
```
````
Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages:
`.ad`, `.adoc`, `.asciidoc`, `.htm`, `.html`, `.markdown`, `.md`, `.mdown`, `.mmark`, `.pandoc`, `.pdc`, `.org`, or `.rst`.
#### Reference a query example in children
To include a query example with the children in your list, update `data/query_examples.yml`
with the example code, input, and output, and use the `list_query_example`

6
assets/text/bucket-schema/bucket-schema-columns.sh Normal file
View File

@ -0,0 +1,6 @@
[
{"name": "time", "type": "timestamp"},
{"name": "host", "type": "tag"},
{"name": "usage_user", "type": "field", "dataType": "float"},
{"name": "usage_system", "type": "field", "dataType": "float"}
]

3
assets/text/bucket-schema/bucket-schema-type.sh Normal file
View File

@ -0,0 +1,3 @@
influx bucket create \
--name my_schema_bucket \
--schema-type explicit

5
assets/text/bucket-schema/sensor.ndjson Normal file
View File

@ -0,0 +1,5 @@
{"name": "time", "type": "timestamp"}
{"name": "service", "type": "tag"}
{"name": "sensor", "type": "tag"}
{"name": "temperature", "type": "field", "dataType": "float"}
{"name": "humidity", "type": "field", "dataType": "float"}

7
assets/text/bucket-schema/usage-cpu.json Normal file
View File

@ -0,0 +1,7 @@
[
{"name": "time", "type": "timestamp"},
{"name": "service", "type": "tag"},
{"name": "host", "type": "tag"},
{"name": "usage_user", "type": "field", "dataType": "float"},
{"name": "usage_system", "type": "field", "dataType": "float"}
]

6
assets/text/bucket-schema/usage-resources.csv Normal file
View File

@ -0,0 +1,6 @@
name,type,data_type
time,timestamp,
host,tag,
service,tag,
fsRead,field,float
fsWrite,field,float
1 name type data_type
2 time timestamp
3 host tag
4 service tag
5 fsRead field float
6 fsWrite field float

2
content/influxdb/cloud/organizations/buckets/_index.md
View File

@ -17,4 +17,4 @@ A bucket belongs to an organization.
The following articles provide information about managing buckets:
{{< children >}}
{{< children sort="weight">}}

170
content/influxdb/cloud/organizations/buckets/bucket-schema/_index.md Normal file
View File

@ -0,0 +1,170 @@
---
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.
menu:
influxdb_cloud:
name: Manage explicit bucket schemas
parent: Manage buckets
weight: 250
influxdb/cloud/tags: [buckets, bucket-schema, bucket schemas, explicit bucket schemas, schema]
related:
- /influxdb/cloud/reference/key-concepts/
- /influxdb/cloud/reference/key-concepts/data-schema/
- /influxdb/cloud/reference/key-concepts/data-elements/
---
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/#field), [fields](/influxdb/cloud/reference/glossary/#field), and
[data types](/influxdb/cloud/reference/glossary/#data-type) for your data.
{{% bucket-schema/type %}}
After you create a bucket schema, you're ready to [write data](/influxdb/cloud/write-data/) to your bucket.
{{% note %}}
#### Before you begin
The `bucket-schema` examples below reference [**InfluxDB data elements**](/influxdb/cloud/reference/key-concepts/data-elements/). We recommend reviewing data elements and [**InfluxDB key concepts**](/influxdb/cloud/reference/key-concepts/) if you aren't familiar with these concepts.
{{% /note %}}
- [Create a bucket schema](#create-a-bucket-schema)
- [Update a bucket schema](#update-a-bucket-schema)
- [Errors](#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`.
```sh
{{< get-assets-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.
The file defines the column names, tags, fields, and data types to require for a measurement.
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-assets-text "bucket-schema/usage-resources.csv" >}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```json
{{< get-assets-text "bucket-schema/usage-cpu.json" >}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```json
{{< get-assets-text "bucket-schema/sensor.ndjson" >}}
```
{{% /code-tab-content %}}
{{% /code-tabs-wrapper %}}
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.
Provide the following:
- location of your file with the `columns-file` flag
- measurement name with the `name` flag. This will match the [measurement column](/influxdb/cloud/reference/key-concepts/data-elements/#measurement) in your data.
```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
```
### 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.
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.
```sh
influx bucket-schema list \
--bucket my_explicit_bucket \
--extended-output
```
InfluxDB returns column details:
```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:
```sh
# sensor.ndjson
{{< get-assets-text "bucket-schema/sensor.ndjson" >}}
```
```sh
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.
```sh
influx bucket-schema update \
--bucket my_explicit_bucket \
--name sensor \
--columns-file sensor.ndjson
```
### Errors
#### Not permitted by schema
If data in the write request doesn't conform to the defined schema, InfluxDB returns an error.
In the following example, the *cpu* measurement has an incorrect `usage_user` [data type](/influxdb/cloud/reference/glossary/#data-type):
```sh
influx write -b my_explicit_bucket 'cpu,host=myHost usage_user="1001" 1556896326'
```
The following error occurs:
```sh
Error: failed to write data:
unable to parse 'cpu,host=myHost usage_user="1001" 1556896326':
schema: field type for field "usage_user" not permitted by schema; got String but expected Float
```
#### No measurement schemas
If you attempt to write to a bucket that has schema-type `explicit` and doesn't have a defined schema, the
bucket rejects write attempts and returns the following error:
```sh
Error: failed to write data: schema: bucket "my_explicit_bucket" contains
no measurement schemas
```
#### 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:
```sh
Error: failed to create measurement: 422 Unprocessable Entity
```

17
content/influxdb/cloud/organizations/buckets/create-bucket.md
View File

@ -66,3 +66,20 @@ influx bucket create -n <bucket-name> -o <org-name> -r <retention-period-duratio
# Example
influx bucket create -n my-bucket -o my-org -r 72h
```
### Create a bucket with an explicit schema
{{% bucket-schema/type %}}
1.
```sh
{{< get-assets-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/).
```sh
influx bucket-schema create \
--bucket my_schema_bucket \
--name temperature \
--columns-file schema.json
```

40
content/influxdb/cloud/reference/cli/influx/bucket-schema/_index.md Normal file
View File

@ -0,0 +1,40 @@
---
title: influx bucket-schema
description: The `influx bucket-schema` command and its subcommands manage schemas of buckets in InfluxDB.
menu:
influxdb_cloud_ref:
name: influx bucket-schema
parent: influx
weight: 101
influxdb/cloud/tags: [buckets, bucket-schema]
cascade:
related:
- /influxdb/cloud/organizations/buckets/bucket-schema
- /influxdb/cloud/organizations/buckets/
- /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials
- /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions
---
The `influx bucket-schema` command and its subcommands manage
schemas for InfluxDB buckets.
## Usage
```
influx bucket-schema [flags]
influx bucket-schema [command]
```
## Subcommands
| Subcommand | Description |
|:---------- |:----------- |
| [create](/influxdb/cloud/reference/cli/influx/bucket-schema/create) | Create a bucket schema |
| [list](/influxdb/cloud/reference/cli/influx/bucket-schema/list) | List bucket schemas |
| [update](/influxdb/cloud/reference/cli/influx/bucket-schema/update) | Update a bucket schema |
## Flags
| Flag | | Description | Input type | {{< cli/mapped >}} |
|:---- |:--- |:----------- |:---------- |:------------------ |
| `-h` | `--help` | Help for the `bucket-schema` command | | |

90
content/influxdb/cloud/reference/cli/influx/bucket-schema/create.md Normal file
View File

@ -0,0 +1,90 @@
---
title: influx bucket-schema create
description: The `influx bucket-schema create` command sets the schema for a measurement in an InfluxDB bucket that has the `explicit` schema-type.
menu:
influxdb_cloud_ref:
name: influx bucket-schema create
parent: influx bucket-schema
weight: 201
related:
- /influxdb/cloud/organizations/buckets/bucket-schema
---
The `influx bucket-schema create` command sets the schema for a measurement in an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema).
## Usage
```sh
influx bucket-schema create [flags]
```
## Flags
| Flag | | Description | Input type | {{< cli/mapped >}} |
| :--- | :------------------ | :-------------------------------------------------------------------- | :--------: | :-------------------- |
| `-c` | `--active-config` | CLI configuration to use for command | string | |
| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | |
| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | |
| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | |
| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Create a schema with columns format](#create-a-schema-with-columns-format) | string | |
| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` |
| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | |
| `-h` | `--help` | Help for the `create` command | | |
| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` |
| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` |
| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` |
| `-n` | `--name` | ({{< req >}}) Measurement name | string | |
| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` |
| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` |
| | `--skip-verify` | Skip TLS certificate verification | | |
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
## Examples
{{< cli/influx-creds-note >}}
- [Create a columns file](#create-a-columns-file)
- [Create a schema using the influx CLI](#create-a-schema-using-the-influx-cli)
- [Create a schema and print column information](#create-a-schema-and-print-column-information)
- [Create a schema with columns format](#create-a-schema-with-columns-format)
## Create a schema using the influx CLI
```sh
influx bucket-schema create \
--bucket example-bucket \
--name temperature \
--columns-file columns.csv
```
## Create a schema and print column information
```sh
influx bucket-schema create \
--bucket example-bucket \
--name cpu \
--columns-file columns.csv \
--extended-output
```
## Create a schema with columns format
By default, InfluxDB attempts to detect the **columns file** format.
If your file's extension doesn't match the format, set the format with the [`columns-format` flag](/influxdb/cloud/reference/cli/influx/bucket-schema/create).
```sh
influx bucket-schema create \
--bucket example-bucket \
--name cpu \
--columns-file columns.json \
--columns-format ndjson
```
```sh
influx bucket-schema create \
--bucket example-bucket \
--name cpu \
--columns-file columns.txt \
--columns-format csv
```

59
content/influxdb/cloud/reference/cli/influx/bucket-schema/list.md Normal file
View File

@ -0,0 +1,59 @@
---
title: influx bucket-schema list
description: The `influx bucket-schema list` command lists the schemas of an InfluxDB bucket that has the `explicit` schema-type.
menu:
influxdb_cloud_ref:
name: influx bucket-schema list
parent: influx bucket-schema
weight: 201
related:
- /influxdb/cloud/organizations/buckets/bucket-schema
---
The `influx bucket-schema list` command lists the schemas of an
InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema).
## Usage
```sh
influx bucket-schema list [flags]
```
## Flags
| Flag | | Description | Input type | {{< cli/mapped >}} |
| :--- | :------------------ | :-------------------------------------------------------------------- | :--------: | :-------------------- |
| `-c` | `--active-config` | CLI configuration to use for command | string | |
| `-n` | `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | |
| `-i` | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | |
| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` |
| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | |
| `-h` | `--help` | Help for the `create` command | | |
| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` |
| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` |
| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` |
| `-n` | `--name` | Measurement name | string | |
| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` |
| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` |
| | `--skip-verify` | Skip TLS certificate verification | | |
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
## Examples
{{< cli/influx-creds-note >}}
## List all schemas of a bucket and print column information
```sh
influx bucket-schema list \
--bucket example-bucket
--extended-output
```
## Print column details for a single measurement
```sh
influx bucket-schema list \
--bucket example-bucket \
--name cpu \
--extended-output
```

96
content/influxdb/cloud/reference/cli/influx/bucket-schema/update.md Normal file
View File

@ -0,0 +1,96 @@
---
title: influx bucket-schema update
description: The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the `explicit` schema-type.
menu:
influxdb_cloud_ref:
name: influx bucket-schema update
parent: influx bucket-schema
weight: 201
related:
- /influxdb/cloud/organizations/buckets/bucket-schema
---
The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema).
`bucket-schema update` requires a bucket with at least one defined schema.
## Usage
```sh
influx bucket-schema update [flags]
```
##### Supported operations
- Adding new columns to a schema
##### Unsupported operations
- Modify existing columns in a schema
- Delete columns from a schema
## Flags
| Flag | | Description | Input type | {{< cli/mapped >}} |
| :--- | :------------------ | :-------------------------------------------------------------------- | :--------: | :-------------------- |
| `-c` | `--active-config` | CLI configuration to use for command | string | |
| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | |
| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | |
| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | |
| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Update a schema with columns format](#update-a-schema-with-columns-format) | string | |
| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` |
| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | |
| `-h` | `--help` | Help for the `create` command | | |
| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` |
| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` |
| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` |
| `-n` | `--name` | ({{< req >}}) Measurement name | string | |
| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` |
| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` |
| | `--skip-verify` | Skip TLS certificate verification | | |
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
## Examples
{{< cli/influx-creds-note >}}
- [Update a schema using the influx CLI](#update-a-schema-using-the-influx-cli)
- [Update a schema and print column information](#update-a-schema-and-print-column-information)
- [Update a schema with columns format](#update-a-schema-specifying-the-columns-format)
## Update a schema using the influx CLI
```sh
influx bucket-schema update \
--bucket example-bucket \
--name temperature \
--columns-file columns.csv
```
## Update a schema and print column information
```sh
influx bucket-schema update \
--bucket example-bucket \
--name cpu \
--columns-file columns.csv \
-extended-output
```
## Update a schema with columns format
By default, InfluxDB attempts to detect the **columns file** format.
If your file's extension doesn't match the format, set the format with the `columns-format` flag.
```sh
influx bucket-schema update \
--bucket example-bucket \
--name cpu \
--columns-file columns.json \
--columns-format ndjson
```
```sh
influx bucket-schema update \
--bucket example-bucket \
--name cpu \
--columns-file columns.txt \
--columns-format csv
```

52
content/influxdb/v2.0/reference/cli/influx/bucket/create.md
View File

@ -18,27 +18,30 @@ related:
The `influx bucket create` command creates a bucket in InfluxDB.
## Usage
```sh
influx bucket create [flags]
```
## Flags
| Flag | | Description | Input type | {{< cli/mapped >}} |
|:---- |:--- |:----------- |:----------: |:------------------ |
| `-c` | `--active-config` | CLI configuration to use for command | string | |
| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string |`INFLUX_CONFIGS_PATH` |
| `-d` | `--description` | Bucket description | string | |
| `-h` | `--help` | Help for the `create` command | | |
| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` |
| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` |
| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` |
| `-n` | `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` |
| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` |
| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` |
| `-r` | `--retention` | Duration bucket retains data (0 is infinite, default is 0) | duration | |
| | `--shard-group-duration` | Bucket shard group duration (OSS only) | string | |
| | `--skip-verify` | Skip TLS certificate verification | | |
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
| Flag | | Description | Input type | {{< cli/mapped >}} |
| :--- | :----------------------- | :-------------------------------------------------------------------- | :--------: | :-------------------- |
| `-c` | `--active-config` | CLI configuration to use for command | string | |
| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` |
| `-d` | `--description` | Bucket description | string | |
| `-h` | `--help` | Help for the `create` command | | |
| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` |
| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` |
| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` |
| `-n` | `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` |
| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` |
| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` |
| `-r` | `--retention` | Duration bucket retains data (0 is infinite, default is 0) | duration | |
| | `--schema-type` | Bucket schema type (`explicit`, default `implicit`) _(Cloud only)_. For more information, see [Manage bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/). | string | |
| | `--shard-group-duration` | Bucket shard group duration (OSS only) | string | |
| | `--skip-verify` | Skip TLS certificate verification | | |
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
{{% note %}}
Valid `--retention` units are nanoseconds (`ns`), microseconds (`us` or `µs`),
@ -53,13 +56,16 @@ milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and
- [Create a bucket that retains data for 30 days](#create-a-bucket-that-retains-data-for-30-days)
- [Create a bucket with a description](#create-a-bucket-with-a-description)
- [Create a bucket with a custom shard group duration](#create-a-bucket-with-a-custom-shard-group-duration)
- [Create a bucket with an explicit schema](#create-a-bucket-with-an-explicit-schema)
##### Create a bucket with infinite data retention
```sh
influx bucket create --name example-bucket
```
##### Create a bucket that retains data for 30 days
```sh
influx bucket create \
--name example-bucket \
@ -67,6 +73,7 @@ influx bucket create \
```
##### Create a bucket with a description
```sh
influx bucket create \
--name example-bucket \
@ -74,6 +81,7 @@ influx bucket create \
```
##### Create a bucket with a custom shard group duration
Custom shard group durations are only supported in **InfluxDB OSS**.
The shard group duration must be shorter than the bucket's retention period. For more information, see [InfluxDB shards and shard groups](/influxdb/v2.0/reference/internals/shards/).
@ -83,3 +91,15 @@ influx bucket create \
--retention 30d \
--shard-group-duration 2d
```
##### Create a bucket with an explicit schema
{{% cloud %}}
[Explicit bucket schemas](/influxdb/cloud/reference/cli/influx/bucket-schema) are only
supported in **InfluxDB Cloud**.
For more information, see [Manage bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/).
{{% /cloud %}}
```sh
{{< get-assets-text "bucket-schema/bucket-schema-type.sh" >}}
```

9
content/influxdb/v2.0/reference/glossary.md
View File

@ -99,6 +99,15 @@ A bucket is a named location where time series data is stored.
All buckets have a [retention period](#retention-period).
A bucket belongs to an organization.
### bucket schema
In InfluxDB Cloud, an explicit bucket schema lets you strictly enforce the data that can be written into one or more measurements in a bucket by defining the column names, tags, fields, and data types allowed for each measurement. By default, buckets in InfluxDB 2.0 have an `implicit` schema that lets you write data without restrictions on columns, fields, or data types.
Learn how to [manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/) in InfluxDB Cloud.
Related entries: [data type](#data-type), [field](#field), [measurement](#measurement)
## C
### check

18
content/influxdb/v2.0/reference/key-concepts/data-elements.md
View File

@ -23,6 +23,7 @@ InfluxDB 2.0 includes the following data elements:
- [series](#series)
- [point](#point)
- [bucket](#bucket)
- [bucket schema](#bucket-schema)
- [organization](#organization)
The sample data below is used to illustrate data elements concepts.
@ -140,6 +141,23 @@ InfluxDB scans every field value in the dataset for `bees` before the query retu
Now that `bees` and `ants` are tags, InfluxDB doesn't have to scan all `_field` and `_value` columns. This makes your queries faster.
## Bucket schema
In InfluxDB Cloud, a bucket with the `explicit` schema-type requires an explicit
schema for each measurement.
Measurements contain tags, fields, and timestamps.
An explicit schema constrains the shape of data that can be written to that measurement.
The following schema constrains `census` data:
name | type | data_type
|:------- |:---------------|:--------------------
time | timestamp |
location | tag | string
scientist | tag | string
ants | field | integer
bees | field | integer
## Series
Now that you're familiar with measurements, field sets, and tag sets, it's time to discuss series keys and series. A **series key** is a collection of points that share a measurement, tag set, and field key. For example, the [sample data](#sample-data) includes two unique series keys:

5
layouts/shortcodes/bucket-schema-requires.html Normal file
View File

@ -0,0 +1,5 @@
#### Bucket schema-type
Before you can use `influx bucket-schema create`, you must use the
[`influx bucket create`](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-for-an-explicit-measurement-schema)
command to set the bucket schema-type to `explicit`.

4
layouts/shortcodes/bucket-schema/type.html Normal file
View File

@ -0,0 +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).

2
layouts/shortcodes/get-assets-text.html Normal file
View File

@ -0,0 +1,2 @@
{{- $file := resources.Get (printf "text/%s" ($.Get 0)) -}}
{{- $file.Content | safeHTML -}}

3
layouts/shortcodes/get-leaf-text.html Normal file
View File

@ -0,0 +1,3 @@
{{- $filename := .Get 0 -}}
{{- $file := .Page.Resources.GetMatch $filename -}}
{{- $file.Content -}}