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.

InfluxDB UI influx CLI InfluxDB API

There are two places you can create a bucket in the UI.

• Create a bucket from the Load Data menu
• Create a bucket in the Data Explorer

Create a bucket from the Load Data menu

1. In the navigation menu on the left, select Data (Load Data) > Buckets.

   Load Data

2. Click Create Bucket in the upper right.

3. Enter a Name for the bucket (see Bucket naming restrictions).

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).

   Data Explorer

2. In the From panel in the Flux Builder, select + Create Bucket.

3. Enter a Name for the bucket (see Bucket naming restrictions).

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.

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 (")

Related

• Data retention in InfluxDB