Documentation

Create a bucket

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

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

Names must be unique within the organization. When you send a request such as writing or querying, InfluxDB Cloud Serverless uses the bucket name and token in your request to find the bucket within the organization.

Table and column limits

In InfluxDB Cloud Serverless, table (measurement) and column are limited per bucket. Each measurement is represented by a table. Time, fields, and tags are each represented by a column.

Maximum number of tables: 500 Maximum number of columns: 200

Auto-generate buckets on write

InfluxDB can automatically create DBRP mappings and associated buckets for you during the following operations:

Create a bucket

Create a bucket using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.

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 Load Data > Buckets.
  1. Click Create Bucket in the upper right.
  2. Enter a Name for the bucket.
  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 header bar, toggle the “Switch to old Data Explorer” button to the “on” position to display the Flux Builder.
  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.

To create a bucket with the influx CLI, use the influx bucket create command and specify values for the following flags:

The following example creates a bucket with a retention period of 72 hours:

influx bucket create \
  --name 
BUCKET_NAME
\
--retention
72h

Retention period syntax

Retention rules specify the bucket retention period, the duration that data is stored before it expires. The retention period also defines the minimum timestamp that you can write to the bucket; the bucket rejects data older than the retention period.

Use the --retention flag to specify a retention period for the bucket. The retention period value is a time duration value made up of a numeric value plus a duration unit. For example, 30d means 30 days. A zero duration (0d) retention period is infinite and data won’t expire. The retention period value cannot be negative or contain whitespace.

Valid durations units include
  • m: minute
  • h: hour
  • d: day
  • w: week
  • mo: month
  • y: year
Example retention period values
  • 0d: infinite/none
  • 3d: 3 days
  • 6w: 6 weeks
  • 1mo: 1 month (30 days)
  • 1y: 1 year
  • 30d30d: 60 days
  • 2.5d: 60 hours

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

POST https://cloud2.influxdata.com/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
    • orgID: InfluxDB organization ID
    • description: Bucket description
    • * retentionRules: JSON array containing a single object with the following fields:
      • type: expire
      • everySecond: Retention period as a number of seconds (0 means forever)
      • shardGroupDuration: Number of seconds to retain shard groups (0 means forever)

The following example creates a bucket with a retention period of 86,400 seconds, or 24 hours:

curl --silent -w "%{response_code}: %{errormsg}\n" \
  -XPOST "https://cloud2.influxdata.com/api/v2/buckets" \
  --header "Authorization: Token 
API_TOKEN
"
\
--header "Content-type: application/json" \ --data @- << EOF { "orgID": "
ORG_ID
",
"name": "BUCKET_NAME", "retentionRules": [ { "type": "expire", "everySeconds":
86400
} ] } EOF

Replace the following:

  • BUCKET_NAME: the name of the bucket
  • 86400: the number of seconds data is stored before it expires. Default is infinite–data won’t expire.
  • API_TOKEN: a token with sufficient permissions to the specified bucket

If successful, the output is an HTTP 201: Created status code and the bucket; otherwise, an error status and message.

/api/v2 retentionRules syntax

Retention rules specify the bucket retention period. The retention period also defines the minimum timestamp that you can write to the bucket; the bucket rejects data older than the retention period. The default retention period is infinite–data won’t expire.

To specify the retention period, set the retentionRules.everySeconds property to the number of seconds. A zero seconds (0) retention period is infinite. The retention period value can’t be negative or contain whitespace.

retentionRules example

{
  "orgID": "ORG_ID",
  "name": "BUCKET_NAME",
  "retentionRules": [
    {
      "type": "expire",
      "everySeconds": "RETENTION_PERIOD_SECONDS"
    }
  ]
}

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


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:

InfluxDB Cloud Serverless