Define custom partitions
Use the influxctl CLI
to define custom partition strategies when creating a database or table.
By default, InfluxDB Cloud Dedicated 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.
- Create a database with a custom partition template
- Create a table with a custom partition template
- Example partition templates
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 Cloud Dedicated 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!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.