Manage bucket schemas

Use explicit bucket schemas to enforce column names, tags, fields, and data types for your data.

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.

After you create a bucket schema, you’re ready to write data to your bucket.

Before you begin

The bucket-schema examples below reference InfluxDB data elements. We recommend reviewing data elements and InfluxDB key concepts if you aren’t familiar with these concepts.

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.

    influx bucket create \
      --name my_schema_bucket \
      --schema-type explicit
  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), as in the following examples:


    {"name": "time", "type": "timestamp"},
    {"name": "service", "type": "tag"},
    {"name": "host", "type": "tag"},
    {"name": "usage_user", "type": "field", "dataType": "float"},
    {"name": "usage_system", "type": "field", "dataType": "float"}

    {"name": "time", "type": "timestamp"}
    {"name": "service", "type": "tag"}
    {"name": "sensor", "type": "tag"}
    {"name": "temperature", "type": "field", "dataType": "float"}
    {"name": "humidity", "type": "field", "dataType": "float"}

  3. Use the influx bucket-schema create command 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 in your data.
    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 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 with the influx bucket list command to view column details.

    influx bucket-schema list \
      --bucket my_explicit_bucket \

    InfluxDB returns column details:

    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 or edit the schema columns file and append new columns. The following example appends column CO2 to the original sensor.ndjson schema file:

    # sensor.ndjson
    {"name": "time", "type": "timestamp"}
    {"name": "service", "type": "tag"}
    {"name": "sensor", "type": "tag"}
    {"name": "temperature", "type": "field", "dataType": "float"}
    {"name": "humidity", "type": "field", "dataType": "float"}
    echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson
  3. Use the influx bucket-schema update command to add the new columns to the bucket schema.

    influx bucket-schema update \
      --bucket my_explicit_bucket \
      --name sensor \
      --columns-file sensor.ndjson

Troubleshoot errors

Troubleshoot and resolve the following bucket schema 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:

influx write -b my_explicit_bucket 'cpu,host=myHost usage_user="1001" 1556896326'

The following error occurs:

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:

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:

Error: failed to create measurement: 422 Unprocessable Entity

Select your region

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.