Documentation

Define custom partitions

Use the influxctl CLI to define custom partition strategies when creating a database or table. By default, InfluxDB Clustered partitions data by day.

The partitioning strategy of a database or table is determined by a partition template which defines the naming pattern for partition keys. Partition keys uniquely identify each partition. When a partition template is applied to a database, it becomes the default template for all tables in that database, but can be overridden when creating a table.

Partition templates can only be applied on create

You can only apply a partition template when creating a database or table. You can’t update a partition template on an existing resource.

Use the following command flags to identify partition template parts:

  • --template-tag: An InfluxDB tag to use in the partition template.
  • --template-tag-bucket: An InfluxDB tag and number of “buckets” to group tag values into. Provide the tag key and the number of buckets to bucket tag values into separated by a comma: tagKey,N.
  • --template-timeformat: A Rust strftime date and time string that specifies the time format in the partition template and determines the time interval to partition by.

A partition template can include up to 7 total tag and tag bucket parts and only 1 time part.

View partition template part restrictions.

Always provide a time format when using custom partitioning

When defining a custom partition template for your database or table using any of the influxctl --template-* flags, always include the --template-timeformat flag with a time format to use in your partition template. Otherwise, InfluxDB omits time from the partition template and won’t compact partitions.

Create a database with a custom partition template

The following example creates a new example-db database and applies a partition template that partitions by distinct values of two tags (room and sensor-type), bucketed values of the customerID tag, and by day using the time format %Y-%m-%d:

influxctl database create \
  --template-tag room \
  --template-tag sensor-type \
  --template-tag-bucket customerID,500 \
  --template-timeformat '%Y-%m-%d' \
  example-db

Create a table with a custom partition template

The following example creates a new example-table table in the specified database and applies a partition template that partitions by distinct values of two tags (room and sensor-type), bucketed values of the customerID tag, and by month using the time format %Y-%m:

influxctl table create \
  --template-tag room \
  --template-tag sensor-type \
  --template-tag-bucket customerID,500 \
  --template-timeformat '%Y-%m' \
  
DATABASE_NAME
\
example-table

Replace the following in your command:

  • DATABASE_NAME: your InfluxDB Clustered database

Example partition templates

Given the following line protocol with a 2024-01-01T00:00:00Z timestamp:

prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000
Partitioning by distinct tag values
Description Tag parts Time part Resulting partition key
By day (default) %Y-%m-%d 2024-01-01
By month %Y-%m 2024-01
By year %Y 2024
Single tag, by day line %Y-%m-%d A | 2024-01-01
Single tag, by month line %Y-%m A | 2024-01
Single tag, by year line %Y A | 2024
Multiple tags, by day line, station %Y-%m-%d A | weld1 | 2024-01-01
Multiple tags, by month line, station %Y-%m A | weld1 | 2024-01
Multiple tags, by year line, station %Y A | weld1 | 2024
Partition by tag buckets
Description Tag part Tag bucket part Time part Resulting partition key
Distinct tag, tag buckets, by day line station,100 %Y-%m-%d A | 3 | 2024-01-01
Distinct tag, tag buckets, by month line station,500 %Y-%m A | 303 | 2024-01

Was this page helpful?

Thank you for your feedback!


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.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered