6.3 KiB
Use the influxctl CLI
to define custom partition strategies when creating a database or table.
By default, {{< product-name >}} 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
[!Warning]
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.
[!Note] A partition template can include up to 7 total tag and tag bucket parts and only 1 time part.
[!Important]
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-timeformatflag 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:
{{% code-placeholders "DATABASE_NAME" %}}
influxctl table create \
--template-tag room \
--template-tag sensor-type \
--template-tag-bucket customerID,500 \
--template-timeformat '%Y-%m' \
DATABASE_NAME \
example-table
{{% /code-placeholders %}}
Replace the following in your command:
- {{% code-placeholder-key %}}
DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} 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 |