Documentation

Create a bucket

Use the InfluxDB user interface (UI) the influx command line interface (CLI), or the InfluxDB API to create a bucket.

Bucket limits

A single InfluxDB 2.7 OSS instance supports approximately 20 buckets actively being written to or queried across all organizations depending on the use case. Any more than that can adversely affect performance.

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.
  1. Click Create Bucket in the upper right.
  2. Enter a Name for the bucket (see Bucket naming restrictions).
  3. Select when to Delete Data:
    • Never to retain data forever.
    • Older than to choose a specific retention period.
  4. 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).
  1. In the From panel in the Flux Builder, select + Create Bucket.
  2. Enter a Name for the bucket (see Bucket naming restrictions).
  3. Select when to Delete Data:
    • Never to retain data forever.
    • Older than to choose a specific retention period.
  4. Click Create to create the bucket.

Use the influx bucket create command to create a new bucket.

Include the following flags with the command:

  • -n, --name: Bucket name (see Bucket naming restrictions)
  • -o, --org or --org-id: Organization name or ID
  • -r, --retention: Bucket 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)

The minimum retention period is one hour.

# Syntax
influx bucket create \
  --name <bucket-name> \
  --org <org-name> \
  --retention <retention-period-duration>

# Example
influx bucket create \
  --name my-bucket \
  --org my-org \
  --retention 72h

To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:

POST https://localhost:8086/api/v2/buckets

Include the following in your request:

  • Headers:
    • Authorization: Token scheme with your InfluxDB API token
    • Content-type: application/json
  • Request body: JSON object with the following fields:
    * Required
    • * name: Bucket name (see Bucket naming restrictions)
    • * orgID: InfluxDB organization ID
    • description: Bucket description
    • retentionRules: JSON array containing a single object with the following fields:
      • type: expire
      • everySecond: Number of seconds to retain data (0 means forever)
      • shardGroupDuration: Number of seconds to retain shard groups (0 means forever)

Example

The URL depends on the version and location of your InfluxDB 2.7 instance (see InfluxDB URLs).

INFLUX_TOKEN=YOUR_API_TOKEN
INFLUX_ORG_ID=YOUR_ORG_ID

curl --request POST \
  "http://localhost:8086/api/v2/buckets" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header "Content-type: application/json" \
  --data '{
    "orgID": "'"${INFLUX_ORG_ID}"'",
    "name": "iot-center",
    "retentionRules": [
      {
        "type": "expire",
        "everySeconds": 86400,
        "shardGroupDurationSeconds": 0
      }
    ]
  }'

For information about InfluxDB API options and response codes, see InfluxDB API Buckets documentation.

Bucket naming restrictions

Bucket names must adhere to the following naming restrictions:

  • Must contain two or more characters
  • Cannot start with an underscore (_)
  • Cannot contain a double quote (")

Was this page helpful?

Thank you for your feedback!


Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following: