Manage explicit bucket schemas

[!Warning]

Don't use explicit schemas with InfluxDB 3

Don't use explicit bucket schemas with InfluxDB 3. The sections on this page provide help for managing and troubleshooting explicit buckets you may already have.

In InfluxDB 2.x, 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.

• View bucket schema type and schemas
  • 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 InfluxDB HTTP API
• Update a bucket schema
  • Update a bucket schema using the influx CLI
  • Update a bucket schema using the InfluxDB HTTP API
• Troubleshoot bucket schema errors
  • Bucket not found
    • Failed to create measurement
• Troubleshoot write errors

Test your explicit schema

When testing an explicit schema, start by trying to write data that doesn't conform to the schema and that the bucket should reject.

Write valid schemas

To ensure your schema is valid, review schema design best practices. 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 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 type.
3. Include at least one column with the field type (without a field, there is no time-series data), as in the following example:

Valid: a schema with timestamp and field columns.

[
  {"name":"time","type":"timestamp"},
  {"name":"fsWrite","type":"field"}
]

Not valid: a schema without a field column.

[
  {"name":"time","type":"timestamp"},
  {"name":"host","type":"tag"}
]

The default field data type is string. To set the data type of a field column, provide the dataType property and a valid field data type (string, float, integer, or boolean), as in the following example:

[
  {"name":"time","type":"timestamp"},
  {"name":"fsWrite","type":"field","dataType":"float"}
]

View bucket schema type and schemas

Use the InfluxDB UI, influx CLI, or InfluxDB HTTP API to view schema type and schemas for buckets.

View schema type and schemas in the InfluxDB UI

1. 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. 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:

{{% api-endpoint method="get" endpoint="https://{{< influxdb/host >}}/api/v2/buckets/{BUCKET_ID}/schema/measurements" api-ref="/influxdb3/cloud-serverless/api/#operation/getMeasurementSchemas" %}}

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 InfluxDB HTTP API

Update a bucket schema using the influx CLI

1. View the existing measurement schema 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:

   shCopy

   # sensor.ndjson
   {{< get-shared-text "bucket-schema/sensor.ndjson" >}}
   

   shCopy

   echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson
   

3. To update the bucket schema, use the influx bucket-schema update command and specify the columns file with the --columns-file flag.

   shCopy

   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 and copy the columns list.

2. Send a request to the HTTP API /api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID} endpoint.

   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://{{< influxdb/host >}}/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}" api-ref="/influxdb3/cloud-serverless/api/#operation/updateMeasurementSchema" >}}

   jsCopy

   {
     "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 doesn't have WRITE permission for the bucket, InfluxDB returns the following error:

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:

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.