diff --git a/assets/styles/layouts/_article.scss b/assets/styles/layouts/_article.scss
index 4180b42a8..543caccc5 100644
--- a/assets/styles/layouts/_article.scss
+++ b/assets/styles/layouts/_article.scss
@@ -179,6 +179,7 @@
"article/captions",
"article/children",
"article/code",
+ "article/columns",
"article/cloud",
"article/diagrams",
"article/enterprise",
@@ -193,6 +194,7 @@
"article/list-filters",
"article/lists",
"article/note",
+ "article/opacity",
"article/pagination-btns",
"article/product-tags",
"article/related",
diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md
index 85a19e95a..5743ee95a 100644
--- a/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md
+++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md
@@ -91,7 +91,7 @@ _For more detailed information, see [Partition templates](/influxdb/cloud-dedica
A partition key uniquely identifies a partition. The structure of partition keys
is defined by a _[partition template](#partition-templates)_. Partition keys are
-composed of up to eight parts or dimensions (tags and time).
+composed of up to eight parts or dimensions (tags, tag buckets, and time).
Each part is delimited by the partition key separator (`|`).
{{< expand-wrapper >}}
@@ -104,18 +104,18 @@ Given the following line protocol with the following timestamps:
- 2024-01-01T01:00:00Z
```text
-production,line=A,station=1 temp=81.2,qty=35i 1704063600000000000
-production,line=A,station=2 temp=92.8,qty=35i 1704063600000000000
-production,line=B,station=1 temp=101.1,qty=43i 1704063600000000000
-production,line=B,station=2 temp=102.4,qty=43i 1704063600000000000
-production,line=A,station=1 temp=81.9,qty=36i 1704067200000000000
-production,line=A,station=2 temp=110.0,qty=22i 1704067200000000000
-production,line=B,station=1 temp=101.8,qty=44i 1704067200000000000
-production,line=B,station=2 temp=105.7,qty=44i 1704067200000000000
-production,line=A,station=1 temp=82.2,qty=35i 1704070800000000000
-production,line=A,station=2 temp=92.1,qty=30i 1704070800000000000
-production,line=B,station=1 temp=102.4,qty=43i 1704070800000000000
-production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
+production,line=A,station=cnc temp=81.2,qty=35i 1704063600000000000
+production,line=A,station=wld temp=92.8,qty=35i 1704063600000000000
+production,line=B,station=cnc temp=101.1,qty=43i 1704063600000000000
+production,line=B,station=wld temp=102.4,qty=43i 1704063600000000000
+production,line=A,station=cnc temp=81.9,qty=36i 1704067200000000000
+production,line=A,station=wld temp=110.0,qty=22i 1704067200000000000
+production,line=B,station=cnc temp=101.8,qty=44i 1704067200000000000
+production,line=B,station=wld temp=105.7,qty=44i 1704067200000000000
+production,line=A,station=cnc temp=82.2,qty=35i 1704070800000000000
+production,line=A,station=wld temp=92.1,qty=30i 1704070800000000000
+production,line=B,station=cnc temp=102.4,qty=43i 1704070800000000000
+production,line=B,station=wld temp=106.5,qty=43i 1704070800000000000
```
---
@@ -128,7 +128,7 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `%Y-%m-%d` (by day, default format)
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
@@ -154,8 +154,8 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `%d %b %Y` (by day, non-default format)
+- `line` tag
+- `%d %b %Y` time (by day, non-default format)
{{% /flex-content %}}
{{% flex-content %}}
@@ -183,23 +183,23 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `station`
-- `%Y-%m-%d` (by day, default format)
+- `line` tag
+- `station` tag
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
##### Partition keys
-- `A | 1 | 2023-12-31`
-- `A | 2 | 2023-12-31`
-- `B | 1 | 2023-12-31`
-- `B | 2 | 2023-12-31`
-- `A | 1 | 2024-01-01`
-- `A | 2 | 2024-01-01`
-- `B | 1 | 2024-01-01`
-- `B | 2 | 2024-01-01`
+- `A | cnc | 2023-12-31`
+- `A | wld | 2023-12-31`
+- `B | cnc | 2023-12-31`
+- `B | wld | 2023-12-31`
+- `A | cnc | 2024-01-01`
+- `A | wld | 2024-01-01`
+- `B | cnc | 2024-01-01`
+- `B | wld | 2024-01-01`
{{% /flex-content %}}
@@ -217,27 +217,19 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `station`
-- `%Y-%m-%d %H:00` (by hour)
+- `line` tag
+- `station,3` tag bucket
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
##### Partition keys
-- `A | 1 | 2023-12-31 23:00`
-- `A | 2 | 2023-12-31 23:00`
-- `B | 1 | 2023-12-31 23:00`
-- `B | 2 | 2023-12-31 23:00`
-- `A | 1 | 2024-01-01 00:00`
-- `A | 2 | 2024-01-01 00:00`
-- `B | 1 | 2024-01-01 00:00`
-- `B | 2 | 2024-01-01 00:00`
-- `A | 1 | 2024-01-01 01:00`
-- `A | 2 | 2024-01-01 01:00`
-- `B | 1 | 2024-01-01 01:00`
-- `B | 2 | 2024-01-01 01:00`
+- `A | 0 | 2023-12-31`
+- `B | 0 | 2023-12-31`
+- `A | 0 | 2024-01-01`
+- `B | 0 | 2024-01-01`
{{% /flex-content %}}
@@ -245,6 +237,82 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
{{% /flex %}}
+---
+
+{{% flex %}}
+
+
+
+{{% flex-content "half" %}}
+
+##### Partition template parts
+
+- `line` tag
+- `station` tag
+- `%Y-%m-%d %H:00` time (by hour)
+
+{{% /flex-content %}}
+{{% flex-content %}}
+
+##### Partition keys
+
+- `A | cnc | 2023-12-31 23:00`
+- `A | wld | 2023-12-31 23:00`
+- `B | cnc | 2023-12-31 23:00`
+- `B | wld | 2023-12-31 23:00`
+- `A | cnc | 2024-01-01 00:00`
+- `A | wld | 2024-01-01 00:00`
+- `B | cnc | 2024-01-01 00:00`
+- `B | wld | 2024-01-01 00:00`
+- `A | cnc | 2024-01-01 01:00`
+- `A | wld | 2024-01-01 01:00`
+- `B | cnc | 2024-01-01 01:00`
+- `B | wld | 2024-01-01 01:00`
+
+{{% /flex-content %}}
+
+
+
+{{% /flex %}}
+
+---
+
+{{% flex %}}
+
+
+
+{{% flex-content "half" %}}
+
+##### Partition template parts
+
+- `line` tag
+- `station,50` tag bucket
+- `%Y-%m-%d %H:00` time (by hour)
+
+{{% /flex-content %}}
+{{% flex-content %}}
+
+##### Partition keys
+
+- `A | 47 | 2023-12-31 23:00`
+- `A | 9 | 2023-12-31 23:00`
+- `B | 47 | 2023-12-31 23:00`
+- `B | 9 | 2023-12-31 23:00`
+- `A | 47 | 2024-01-01 00:00`
+- `A | 9 | 2024-01-01 00:00`
+- `B | 47 | 2024-01-01 00:00`
+- `B | 9 | 2024-01-01 00:00`
+- `A | 47 | 2024-01-01 01:00`
+- `A | 9 | 2024-01-01 01:00`
+- `B | 47 | 2024-01-01 01:00`
+- `B | 9 | 2024-01-01 01:00`
+
+{{% /flex-content %}}
+
+
+
+{{% /flex %}}
+
{{% /expand %}}
{{< /expand-wrapper >}}
@@ -275,7 +343,7 @@ FROM production
WHERE
time >= now() - INTERVAL '1 week'
AND line = 'A'
- AND station = '1'
+ AND station = 'cnc'
```
Using the default partitioning strategy (by day), the query engine
@@ -292,7 +360,7 @@ last seven days):
- {{< datetime/current-date offset=-7 trimTime=true >}}
The query engine must scan _all_ rows in the partitions to identify rows
-where `line` is `A` and `station` is `1`. This process takes valuable time
+where `line` is `A` and `station` is `cnc`. This process takes valuable time
and results in less performant queries.
However, if you partition by other tags, InfluxDB can identify partitions that
@@ -305,39 +373,40 @@ only those with data relevant to the query:
{{% columns 4 %}}
-- A | 1 | {{< datetime/current-date trimTime=true >}}
-- A | 2 | {{< datetime/current-date trimTime=true >}}
-- B | 1 | {{< datetime/current-date trimTime=true >}}
-- B | 2 | {{< datetime/current-date trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-7 trimTime=true >}}
- {{% /columns %}}
+- A | cnc | {{< datetime/current-date trimTime=true >}}
+- A | wld | {{< datetime/current-date trimTime=true >}}
+- B | cnc | {{< datetime/current-date trimTime=true >}}
+- B | wld | {{< datetime/current-date trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-1 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-1 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-1 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-1 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-2 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-2 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-2 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-2 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-3 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-3 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-3 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-3 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-4 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-4 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-4 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-4 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-5 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-5 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-5 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-5 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-6 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-6 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-6 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-6 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-7 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-7 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-7 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-7 trimTime=true >}}
+
+{{% /columns %}}
---
diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md
index a5b38c207..c558808d3 100644
--- a/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md
+++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md
@@ -26,10 +26,13 @@ query engine to more quickly identify what partitions contain the relevant data.
{{% note %}}
-#### Be careful partitioning on high-cardinality tags
+#### Use tag buckets for high-cardinality tags
-Partitioning using tags with many (10K+) unique values can actually hurt
-query performance as partitions are created for each unique tag value.
+Partitioning using distinct values of tags with many (10K+) unique values can
+actually hurt query performance as partitions are created for each unique tag value.
+Instead, use [tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+to partition by high-cardinality tags.
+This method of partitioning groups tag values into "buckets" and partitions by bucket.
{{% /note %}}
## Only partition by tags that _always_ have a value
@@ -51,4 +54,6 @@ hurts query performance.
it is better to partition by larger time intervals.
- Don't partition by tags that you typically don't use in your query workload.
-- [Be careful partitioning on high-cardinality tags](#be-careful-partitioning-on-high-cardinality-tags).
+- Don't partition by distinct values of high-cardinality tags.
+ Instead, [use tag buckets](#use-tag-buckets-for-high-cardinality-tags) to
+ partition by these tags.
diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
index 04a22fcef..2a5dd3ffd 100644
--- a/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
+++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
@@ -41,23 +41,32 @@ Use the following command flags to identify
- `--template-tag`: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag)
to use in the partition template.
- _Supports up to seven of these flags._
+- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#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](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
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.
+{{% /note %}}
+
_View [partition template part restrictions](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#restrictions)._
## 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 two tags (`room` and `sensor-type`) and by week using
-the time format `%Y wk:%W`:
+template that partitions by distinct values of two tags (`room` and `sensor-type`),
+bucketed values of the `customerID` tag, and by week using the time format `%Y wk:%W`:
```sh
influxctl database create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,500 \
--template-timeformat '%Y wk:%W' \
example-db
```
@@ -65,13 +74,15 @@ influxctl database create \
## Create a table with a custom partition template
The following example creates a new `example-table` table in the `example-db`
-database and applies a partition template that partitions by two tags
-(`room` and `sensor-type`) and by month using the time format `%Y-%m`:
+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`:
```sh
influxctl table create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,500 \
--template-timeformat '%Y-%m' \
example-db \
example-table
@@ -86,6 +97,8 @@ 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 part(s) | Time part | Resulting partition key |
| :---------------------- | :---------------- | :--------- | :----------------------- |
| By day (default) | | `%Y-%m-%d` | 2024-01-01 |
@@ -98,3 +111,10 @@ prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000
| Multiple tags, by day | `line`, `station` | `%F` | A \| weld1 \| 2024-01-01 |
| Multiple tags, by week | `line`, `station` | `%Y wk:%W` | A \| weld1 \| 2024 wk:01 |
| Multiple tags, by month | `line`, `station` | `%Y-%m` | A \| weld1 \| 2024-01 |
+
+##### Partition by tag buckets
+
+| Description | Tag part | Tag bucket part | Time part | Resulting partition key |
+| :--------------------------------- | :------- | :-------------- | :--------- | :---------------------- |
+| Distinct tag, tag buckets, by day | `line` | `station,100` | `%F` | A \| 3 \| 2024-01-01 |
+| Distinct tag, tag buckets, by week | `line` | `station,500` | `%Y wk:%W` | A \| 303 \| 2024 wk:01 |
diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md
index 087a39845..d024539bc 100644
--- a/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md
+++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md
@@ -15,15 +15,21 @@ A partition key uniquely identifies a partition and is used to name the partitio
Parquet file in the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-store).
A partition template consists of 1-8 _template parts_---dimensions to partition data by.
-There are two types of parts:
+There are three types of template parts:
-- **tag**: [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag) to
- partition by.
- _A partition template can include up to seven tag parts._
+- **tag**: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag)
+ to partition by.
+- **tag bucket**: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag)
+ and number of "buckets" to group tag values into. Data is partitioned by the
+ tag bucket rather than each distinct tag value.
- **time**: A Rust strftime date and time string that specifies the time interval
to partition data by. The smallest unit of time included in the time part
template is the interval used to partition data.
- _A partition template includes only 1 time part._
+
+{{% note %}}
+A partition template can include up to 7 total tag and tag bucket parts
+and only 1 time part.
+{{% /note %}}
- [Restrictions](#restrictions)
@@ -31,6 +37,7 @@ There are two types of parts:
- [Reserved keywords](#reserved-keywords)
- [Reserved Characters](#reserved-characters)
- [Tag part templates](#tag-part-templates)
+- [Tag bucket part templates](#tag-bucket-part-templates)
- [Time part templates](#time-part-templates)
- [Date specifiers](#date-specifiers)
- [Time specifiers](#time-specifiers)
@@ -46,6 +53,11 @@ There are two types of parts:
Each template part is limited to 200 bytes in length.
Anything longer will be truncated at 200 bytes and appended with `#`.
+### Partition key size limit
+
+With the truncation of template parts, the maximum length of a partition key is
+1,607 bytes (1.57 KiB).
+
### Reserved keywords
The following reserved keywords cannot be used in partition templates:
@@ -68,6 +80,33 @@ characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Gl
Tag part templates consist of a _tag key_ to partition by.
Generated partition keys include the unique _tag value_ specific to each partition.
+## Tag bucket part templates
+
+Tag bucket part templates consist of a _tag key_ to partition by and the
+_number of "buckets" to partition tag values into_--for example:
+
+```
+customerID,500
+```
+
+Values of the `customerID` tag are bucketed into 500 distinct "buckets."
+Each bucket is identified by the remainder of the tag value hashed into a 32bit
+integer divided by the specified number of buckets:
+
+```rust
+hash(tagValue) % N
+```
+
+Generated partition keys include the unique _tag bucket identifier_ specific to
+each partition.
+
+**Supported number of tag buckets**: 1-1,000
+
+{{% note %}}
+Tag buckets should be used to partition by high cardinality tags or tags with an
+unknown number of distinct values.
+{{% /note %}}
+
## Time part templates
Time part templates use [Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
diff --git a/content/influxdb/cloud-dedicated/admin/databases/create.md b/content/influxdb/cloud-dedicated/admin/databases/create.md
index 7a3be3509..c7d61d0f7 100644
--- a/content/influxdb/cloud-dedicated/admin/databases/create.md
+++ b/content/influxdb/cloud-dedicated/admin/databases/create.md
@@ -32,12 +32,18 @@ to create a database in your {{< product-name omit=" Clustered" >}} cluster.
- _Optional_: Database table (measurement) limit _(default is 500)_
- _Optional_: Database column limit _(default is 250)_
- _Optional_: [InfluxDB tags](/influxdb/cloud-dedicated/reference/glossary/#tag)
- to use in the partition template _(supports up to 7 different tags)_
+ to use in the partition template
+ - _Optional_: [InfluxDB tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+ to use in the partition template
- _Optional_: A [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
that specifies the time format in the partition template and determines
the time interval to partition by _(default is `%Y-%m-%d`)_
- Database name _(see [Database naming restrictions](#database-naming-restrictions))_
+ {{% note %}}
+_{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
+ {{% /note %}}
+
{{% code-placeholders "DATABASE_NAME|30d|500|200" %}}
```sh
influxctl database create \
@@ -46,6 +52,8 @@ influxctl database create \
--max-columns 250 \
--template-tag tag1 \
--template-tag tag2 \
+ --template-tag-bucket tag3,100 \
+ --template-tag-bucket tag4,300 \
--template-timeformat '%Y-%m-%d' \
DATABASE_NAME
```
@@ -209,8 +217,8 @@ format in the InfluxDB v3 storage engine. By default, data is partitioned by day
but, depending on your schema and workload, customizing the partitioning
strategy can improve query performance.
-Use the `--template-tag` and `--template-timeformat` flags to define partition template
-parts used to generate partition keys for the database.
+Use the `--template-tag`, `--template-tag-bucket, and `--template-timeformat`
+flags to define partition template parts used to generate partition keys for the database.
For more information, see [Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/).
{{% note %}}
diff --git a/content/influxdb/cloud-dedicated/admin/tables/create.md b/content/influxdb/cloud-dedicated/admin/tables/create.md
index da0ca3e92..5c89acd02 100644
--- a/content/influxdb/cloud-dedicated/admin/tables/create.md
+++ b/content/influxdb/cloud-dedicated/admin/tables/create.md
@@ -31,18 +31,26 @@ to a table, you must manually create the table before you write any data to it.
2. Run the `influxctl table create` command and provide the following:
- _Optional_: [InfluxDB tags](/influxdb/cloud-dedicated/reference/glossary/#tag)
- to use in the partition template _(supports up to 7 different tags)_
+ to use in the partition template
+ - _Optional_: [InfluxDB tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+ to use in the partition template
- _Optional_: A [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
that specifies the time format in the partition template and determines
the time interval to partition by _(default is `%Y-%m-%d`)_
- The name of the database to create the table in
- The name of the table to create
+ {{% note %}}
+_{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
+ {{% /note %}}
+
{{% code-placeholders "(DATABASE|TABLE)_NAME" %}}
```sh
influxctl table create \
--template-tag tag1 \
--template-tag tag2 \
+ --template-tag-bucket tag3,100 \
+ --template-tag-bucket tag4,300 \
--template-timeformat '%Y-%m-%d' \
DATABASE_NAME \
TABLE_NAME
@@ -57,8 +65,8 @@ format in the InfluxDB v3 storage engine. By default, data is partitioned by day
but, depending on your schema and workload, customizing the partitioning
strategy can improve query performance.
-Use the `--template-tag` and `--template-timeformat` flags to define partition
-template parts used to generate partition keys for the table.
+Use the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags to define partition template parts used to generate partition keys for the table.
If no template flags are provided, the table uses the partition template of the
target database.
For more information, see [Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/).
diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md
index 161bab73d..dd8ff7513 100644
--- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md
+++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md
@@ -53,9 +53,11 @@ The retention period value cannot be negative or contain whitespace.
#### Custom partitioning
You can override the default partition template (`%Y-%m-%d`) of the database
-with the `--template-tag` and `--template-timeformat` flags when you create the database.
-Provide a time format using [Rust strftime](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
-and include specific tags to use in the partition template.
+with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags when you create the database.
+Provide a time format using [Rust strftime](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values
+into a specified number of "buckets."
+Each of these can be used as part of the partition template.
Be sure to follow [partitioning best practices](/influxdb/cloud-dedicated/admin/custom-partitions/best-practices/).
## Usage
@@ -72,14 +74,15 @@ influxctl database create [flags]
## Flags
-| Flag | | Description |
-| :--- | :---------------------- | :------------------------------------------------------------------- |
-| | `--retention-period` | Database retention period (default is 0s or infinite) |
-| | `--max-tables` | Maximum tables per database (default is 500, 0 uses default) |
-| | `--max-columns` | Maximum columns per table (default is 250, 0 uses default) |
-| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
-| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
-| `-h` | `--help` | Output command help |
+| Flag | | Description |
+| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| | `--retention-period` | Database retention period (default is 0s or infinite) |
+| | `--max-tables` | Maximum tables per database (default is 500, 0 uses default) |
+| | `--max-columns` | Maximum columns per table (default is 250, 0 uses default) |
+| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
+| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) |
+| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
+| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb/cloud-dedicated/reference/cli/influxctl/#global-flags)._
@@ -90,7 +93,7 @@ _Also see [`influxctl` global flags](/influxdb/cloud-dedicated/reference/cli/inf
- [Create a database with an infinite retention period](#create-a-database-with-an-infinite-retention-period)
- [Create a database with a 30-day retention period](#create-a-database-with-a-30-day-retention-period)
- [Create a database with non-default table and column limits](#create-a-database-with-non-default-table-and-column-limits)
-- [Create a database with with a custom partition template](#create-a-database-with-with-a-custom-partition-template)
+- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template)
### Create a database with an infinite retention period
@@ -115,7 +118,7 @@ influxctl database create \
mydb
```
-### Create a database with with a custom partition template
+### Create a database with a custom partition template
The following example creates a new `mydb` database and applies a partition
template that partitions by two tags (`room` and `sensor-type`) and by week using
@@ -125,9 +128,24 @@ the time format `%Y wk:%W`:
influxctl database create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,1000 \
--template-timeformat '%Y wk:%W' \
mydb
```
_For more information about custom partitioning, see
[Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/)._
+
+{{% expand "View command updates" %}}
+
+#### v2.7.0 {date="2024-03-26"}
+
+- Introduce the `--template-tag-bucket` flag to group tag values into buckets
+ and partition by each tag bucket.
+
+#### v2.5.0 {date="2024-03-04"}
+
+- Introduce the `--template-tag` and `--template-timeformat` flags that define
+ a custom partition template for a database.
+
+{{% /expand %}}
diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md
index 3ec261a2c..7b846f426 100644
--- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md
+++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md
@@ -17,9 +17,11 @@ database in an {{< product-name omit=" Clustered" >}} cluster.
#### Custom partitioning
You can override the default partition template (the partition template of the target database)
-with the `--template-tag` and `--template-timeformat` flags when you create the table.
-Provide a time format using [Rust strftime](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
-and include specific tags to use in the partition template.
+with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags when you create the table.
+Provide a time format using [Rust strftime](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values
+into a specified number of "buckets."
+Each of these can be used as part of the partition template.
Be sure to follow [partitioning best practices](/influxdb/cloud-dedicated/admin/custom-partitions/best-practices/).
## Usage
@@ -37,11 +39,12 @@ influxctl table create [flags]
## Flags
-| Flag | | Description |
-| :--- | :---------------------- | :------------------------------------------------------------------- |
-| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
-| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
-| `-h` | `--help` | Output command help |
+| Flag | | Description |
+| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
+| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) |
+| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
+| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb/cloud-dedicated/reference/cli/influxctl/#global-flags)._
@@ -50,7 +53,7 @@ _Also see [`influxctl` global flags](/influxdb/cloud-dedicated/reference/cli/inf
## Examples
- [Create a table](#create-a-table)
-- [Create a table with with a custom partition template](#create-a-table-with-with-a-custom-partition-template)
+- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template)
In the following examples, replace:
@@ -67,7 +70,7 @@ influxctl table create DATABASE_NAME TABLE_NAME
```
{{% /code-placeholders %}}
-### Create a table with with a custom partition template
+### Create a table with a custom partition template
The following example creates a new table and applies a partition
template that partitions by two tags (`room` and `sensor-type`) and by week using
@@ -78,6 +81,7 @@ the time format `%Y wk:%W`:
influxctl table create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,1000 \
--template-timeformat '%Y wk:%W' \
DATABASE_NAME \
TABLE_NAME
@@ -86,3 +90,12 @@ influxctl table create \
_For more information about custom partitioning, see
[Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/)._
+
+{{% expand "View command updates" %}}
+
+#### v2.7.0 {date="2024-03-26"}
+
+- Introduce the `--template-tag-bucket` flag to group tag values into buckets
+ and partition by each tag bucket.
+
+{{% /expand %}}
diff --git a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md
index efc2e6c74..aea15e8ce 100644
--- a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md
+++ b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md
@@ -11,6 +11,30 @@ menu:
weight: 202
---
+## v2.7.0 {date="2024-03-26"}
+
+This minor release adds the `--template-tag-bucket` partition template option to
+the already existing `--template-time-format` and `--template-tag` options used
+to define custom partition templates for databases and tables.
+This also fixes a nil pointer issue when listing management tokens.
+
+### Features
+
+- Introduce the bucket template method for grouping tag values into buckets and
+ partitioning by each tag bucket.
+
+### Bug Fixes
+
+- Ensure strings are not nil pointers.
+
+### Dependency Updates
+
+- Update `github.com/jedib0t/go-pretty/v6` from 6.5.5 to 6.5.6.
+- Update `github.com/pelletier/go-toml/v2` from 2.1.1 to 2.2.0.
+- Update granite proto.
+
+---
+
## v2.6.0 {date="2024-03-18"}
`influxctl` 2.6.0 introduces the ability to create, list, and revoke
diff --git a/content/influxdb/clustered/admin/custom-partitions/_index.md b/content/influxdb/clustered/admin/custom-partitions/_index.md
index b431457d2..70c4e14fb 100644
--- a/content/influxdb/clustered/admin/custom-partitions/_index.md
+++ b/content/influxdb/clustered/admin/custom-partitions/_index.md
@@ -91,7 +91,7 @@ _For more detailed information, see [Partition templates](/influxdb/clustered/ad
A partition key uniquely identifies a partition. The structure of partition keys
is defined by a _[partition template](#partition-templates)_. Partition keys are
-composed of up to eight parts or dimensions (tags and time).
+composed of up to eight parts or dimensions (tags, tag buckets, and time).
Each part is delimited by the partition key separator (`|`).
{{< expand-wrapper >}}
@@ -104,18 +104,18 @@ Given the following line protocol with the following timestamps:
- 2024-01-01T01:00:00Z
```text
-production,line=A,station=1 temp=81.2,qty=35i 1704063600000000000
-production,line=A,station=2 temp=92.8,qty=35i 1704063600000000000
-production,line=B,station=1 temp=101.1,qty=43i 1704063600000000000
-production,line=B,station=2 temp=102.4,qty=43i 1704063600000000000
-production,line=A,station=1 temp=81.9,qty=36i 1704067200000000000
-production,line=A,station=2 temp=110.0,qty=22i 1704067200000000000
-production,line=B,station=1 temp=101.8,qty=44i 1704067200000000000
-production,line=B,station=2 temp=105.7,qty=44i 1704067200000000000
-production,line=A,station=1 temp=82.2,qty=35i 1704070800000000000
-production,line=A,station=2 temp=92.1,qty=30i 1704070800000000000
-production,line=B,station=1 temp=102.4,qty=43i 1704070800000000000
-production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
+production,line=A,station=cnc temp=81.2,qty=35i 1704063600000000000
+production,line=A,station=wld temp=92.8,qty=35i 1704063600000000000
+production,line=B,station=cnc temp=101.1,qty=43i 1704063600000000000
+production,line=B,station=wld temp=102.4,qty=43i 1704063600000000000
+production,line=A,station=cnc temp=81.9,qty=36i 1704067200000000000
+production,line=A,station=wld temp=110.0,qty=22i 1704067200000000000
+production,line=B,station=cnc temp=101.8,qty=44i 1704067200000000000
+production,line=B,station=wld temp=105.7,qty=44i 1704067200000000000
+production,line=A,station=cnc temp=82.2,qty=35i 1704070800000000000
+production,line=A,station=wld temp=92.1,qty=30i 1704070800000000000
+production,line=B,station=cnc temp=102.4,qty=43i 1704070800000000000
+production,line=B,station=wld temp=106.5,qty=43i 1704070800000000000
```
---
@@ -128,7 +128,7 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `%Y-%m-%d` (by day, default format)
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
@@ -154,8 +154,8 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `%d %b %Y` (by day, non-default format)
+- `line` tag
+- `%d %b %Y` time (by day, non-default format)
{{% /flex-content %}}
{{% flex-content %}}
@@ -183,23 +183,23 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `station`
-- `%Y-%m-%d` (by day, default format)
+- `line` tag
+- `station` tag
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
##### Partition keys
-- `A | 1 | 2023-12-31`
-- `A | 2 | 2023-12-31`
-- `B | 1 | 2023-12-31`
-- `B | 2 | 2023-12-31`
-- `A | 1 | 2024-01-01`
-- `A | 2 | 2024-01-01`
-- `B | 1 | 2024-01-01`
-- `B | 2 | 2024-01-01`
+- `A | cnc | 2023-12-31`
+- `A | wld | 2023-12-31`
+- `B | cnc | 2023-12-31`
+- `B | wld | 2023-12-31`
+- `A | cnc | 2024-01-01`
+- `A | wld | 2024-01-01`
+- `B | cnc | 2024-01-01`
+- `B | wld | 2024-01-01`
{{% /flex-content %}}
@@ -217,27 +217,19 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
##### Partition template parts
-- `line`
-- `station`
-- `%Y-%m-%d %H:00` (by hour)
+- `line` tag
+- `station,3` tag bucket
+- `%Y-%m-%d` time (by day, default format)
{{% /flex-content %}}
{{% flex-content %}}
##### Partition keys
-- `A | 1 | 2023-12-31 23:00`
-- `A | 2 | 2023-12-31 23:00`
-- `B | 1 | 2023-12-31 23:00`
-- `B | 2 | 2023-12-31 23:00`
-- `A | 1 | 2024-01-01 00:00`
-- `A | 2 | 2024-01-01 00:00`
-- `B | 1 | 2024-01-01 00:00`
-- `B | 2 | 2024-01-01 00:00`
-- `A | 1 | 2024-01-01 01:00`
-- `A | 2 | 2024-01-01 01:00`
-- `B | 1 | 2024-01-01 01:00`
-- `B | 2 | 2024-01-01 01:00`
+- `A | 0 | 2023-12-31`
+- `B | 0 | 2023-12-31`
+- `A | 0 | 2024-01-01`
+- `B | 0 | 2024-01-01`
{{% /flex-content %}}
@@ -245,6 +237,82 @@ production,line=B,station=2 temp=106.5,qty=43i 1704070800000000000
{{% /flex %}}
+---
+
+{{% flex %}}
+
+
+
+{{% flex-content "half" %}}
+
+##### Partition template parts
+
+- `line` tag
+- `station` tag
+- `%Y-%m-%d %H:00` time (by hour)
+
+{{% /flex-content %}}
+{{% flex-content %}}
+
+##### Partition keys
+
+- `A | cnc | 2023-12-31 23:00`
+- `A | wld | 2023-12-31 23:00`
+- `B | cnc | 2023-12-31 23:00`
+- `B | wld | 2023-12-31 23:00`
+- `A | cnc | 2024-01-01 00:00`
+- `A | wld | 2024-01-01 00:00`
+- `B | cnc | 2024-01-01 00:00`
+- `B | wld | 2024-01-01 00:00`
+- `A | cnc | 2024-01-01 01:00`
+- `A | wld | 2024-01-01 01:00`
+- `B | cnc | 2024-01-01 01:00`
+- `B | wld | 2024-01-01 01:00`
+
+{{% /flex-content %}}
+
+
+
+{{% /flex %}}
+
+---
+
+{{% flex %}}
+
+
+
+{{% flex-content "half" %}}
+
+##### Partition template parts
+
+- `line` tag
+- `station,50` tag bucket
+- `%Y-%m-%d %H:00` time (by hour)
+
+{{% /flex-content %}}
+{{% flex-content %}}
+
+##### Partition keys
+
+- `A | 47 | 2023-12-31 23:00`
+- `A | 9 | 2023-12-31 23:00`
+- `B | 47 | 2023-12-31 23:00`
+- `B | 9 | 2023-12-31 23:00`
+- `A | 47 | 2024-01-01 00:00`
+- `A | 9 | 2024-01-01 00:00`
+- `B | 47 | 2024-01-01 00:00`
+- `B | 9 | 2024-01-01 00:00`
+- `A | 47 | 2024-01-01 01:00`
+- `A | 9 | 2024-01-01 01:00`
+- `B | 47 | 2024-01-01 01:00`
+- `B | 9 | 2024-01-01 01:00`
+
+{{% /flex-content %}}
+
+
+
+{{% /flex %}}
+
{{% /expand %}}
{{< /expand-wrapper >}}
@@ -275,7 +343,7 @@ FROM production
WHERE
time >= now() - INTERVAL '1 week'
AND line = 'A'
- AND station = '1'
+ AND station = 'cnc'
```
Using the default partitioning strategy (by day), the query engine
@@ -292,7 +360,7 @@ last seven days):
- {{< datetime/current-date offset=-7 trimTime=true >}}
The query engine must scan _all_ rows in the partitions to identify rows
-where `line` is `A` and `station` is `1`. This process takes valuable time
+where `line` is `A` and `station` is `cnc`. This process takes valuable time
and results in less performant queries.
However, if you partition by other tags, InfluxDB can identify partitions that
@@ -305,39 +373,40 @@ only those with data relevant to the query:
{{% columns 4 %}}
-- A | 1 | {{< datetime/current-date trimTime=true >}}
-- A | 2 | {{< datetime/current-date trimTime=true >}}
-- B | 1 | {{< datetime/current-date trimTime=true >}}
-- B | 2 | {{< datetime/current-date trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-1 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-2 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-3 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-4 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-5 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-6 trimTime=true >}}
-- A | 1 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- A | 2 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- B | 1 | {{< datetime/current-date offset=-7 trimTime=true >}}
-- B | 2 | {{< datetime/current-date offset=-7 trimTime=true >}}
- {{% /columns %}}
+- A | cnc | {{< datetime/current-date trimTime=true >}}
+- A | wld | {{< datetime/current-date trimTime=true >}}
+- B | cnc | {{< datetime/current-date trimTime=true >}}
+- B | wld | {{< datetime/current-date trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-1 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-1 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-1 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-1 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-2 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-2 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-2 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-2 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-3 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-3 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-3 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-3 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-4 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-4 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-4 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-4 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-5 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-5 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-5 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-5 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-6 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-6 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-6 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-6 trimTime=true >}}
+- A | cnc | {{< datetime/current-date offset=-7 trimTime=true >}}
+- A | wld | {{< datetime/current-date offset=-7 trimTime=true >}}
+- B | cnc | {{< datetime/current-date offset=-7 trimTime=true >}}
+- B | wld | {{< datetime/current-date offset=-7 trimTime=true >}}
+
+{{% /columns %}}
---
diff --git a/content/influxdb/clustered/admin/custom-partitions/best-practices.md b/content/influxdb/clustered/admin/custom-partitions/best-practices.md
index 501764bf7..8429eaaa5 100644
--- a/content/influxdb/clustered/admin/custom-partitions/best-practices.md
+++ b/content/influxdb/clustered/admin/custom-partitions/best-practices.md
@@ -26,11 +26,13 @@ query engine to more quickly identify what partitions contain the relevant data.
{{% note %}}
-#### Be careful partitioning on high-cardinality tags
-
-Partitioning using tags with many (10K+) unique values can actually hurt
-query performance as partitions are created for each unique tag value.
+#### Use tag buckets for high-cardinality tags
+Partitioning using distinct values of tags with many (10K+) unique values can
+actually hurt query performance as partitions are created for each unique tag value.
+Instead, use [tag buckets](/influxdb/clustered/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+to partition by high-cardinality tags.
+This method of partitioning groups tag values into "buckets" and partitions by bucket.
{{% /note %}}
## Only partition by tags that _always_ have a value
@@ -52,4 +54,6 @@ hurts query performance.
it is better to partition by larger time intervals.
- Don't partition by tags that you typically don't use in your query workload.
-- [Be careful partitioning on high-cardinality tags](#be-careful-partitioning-on-high-cardinality-tags).
+- Don't partition by distinct values of high-cardinality tags.
+ Instead, [use tag buckets](#use-tag-buckets-for-high-cardinality-tags) to
+ partition by these tags.
diff --git a/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md b/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md
index 1ccb58b5a..586e94935 100644
--- a/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md
+++ b/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md
@@ -41,23 +41,32 @@ Use the following command flags to identify
- `--template-tag`: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag)
to use in the partition template.
- _Supports up to seven of these flags._
+- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#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](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates)
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.
+{{% /note %}}
+
_View [partition template part restrictions](/influxdb/clustered/admin/custom-partitions/partition-templates/#restrictions)._
## 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 two tags (`room` and `sensor-type`) and by week using
-the time format `%Y wk:%W`:
+template that partitions by distinct values of two tags (`room` and `sensor-type`),
+bucketed values of the `customerID` tag, and by week using the time format `%Y wk:%W`:
```sh
influxctl database create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,500 \
--template-timeformat '%Y wk:%W' \
example-db
```
@@ -65,13 +74,15 @@ influxctl database create \
## Create a table with a custom partition template
The following example creates a new `example-table` table in the `example-db`
-database and applies a partition template that partitions by two tags
-(`room` and `sensor-type`) and by month using the time format `%Y-%m`:
+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`:
```sh
influxctl table create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,500 \
--template-timeformat '%Y-%m' \
example-db \
example-table
@@ -86,6 +97,8 @@ 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 part(s) | Time part | Resulting partition key |
| :---------------------- | :---------------- | :--------- | :----------------------- |
| By day (default) | | `%Y-%m-%d` | 2024-01-01 |
@@ -98,3 +111,10 @@ prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000
| Multiple tags, by day | `line`, `station` | `%F` | A \| weld1 \| 2024-01-01 |
| Multiple tags, by week | `line`, `station` | `%Y wk:%W` | A \| weld1 \| 2024 wk:01 |
| Multiple tags, by month | `line`, `station` | `%Y-%m` | A \| weld1 \| 2024-01 |
+
+##### Partition by tag buckets
+
+| Description | Tag part | Tag bucket part | Time part | Resulting partition key |
+| :--------------------------------- | :------- | :-------------- | :--------- | :---------------------- |
+| Distinct tag, tag buckets, by day | `line` | `station,100` | `%F` | A \| 3 \| 2024-01-01 |
+| Distinct tag, tag buckets, by week | `line` | `station,500` | `%Y wk:%W` | A \| 303 \| 2024 wk:01 |
diff --git a/content/influxdb/clustered/admin/custom-partitions/partition-templates.md b/content/influxdb/clustered/admin/custom-partitions/partition-templates.md
index 6eda4c0b4..8d0b6daae 100644
--- a/content/influxdb/clustered/admin/custom-partitions/partition-templates.md
+++ b/content/influxdb/clustered/admin/custom-partitions/partition-templates.md
@@ -15,32 +15,36 @@ A partition key uniquely identifies a partition and is used to name the partitio
Parquet file in the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store).
A partition template consists of 1-8 _template parts_---dimensions to partition data by.
-There are two types of parts:
+There are three types of template parts:
-- **tag**: [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag) to
- partition by.
- _A partition template can include up to seven tag parts._
+- **tag**: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag)
+ to partition by.
+- **tag bucket**: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag)
+ and number of "buckets" to group tag values into. Data is partitioned by the
+ tag bucket rather than each distinct tag value.
- **time**: A Rust strftime date and time string that specifies the time interval
to partition data by. The smallest unit of time included in the time part
template is the interval used to partition data.
- _A partition template includes only 1 time part._
+
+{{% note %}}
+A partition template can include up to 7 total tag and tag bucket parts
+and only 1 time part.
+{{% /note %}}
-
- [Restrictions](#restrictions)
- [Template part size limit](#template-part-size-limit)
- [Reserved keywords](#reserved-keywords)
- [Reserved Characters](#reserved-characters)
- [Tag part templates](#tag-part-templates)
+- [Tag bucket part templates](#tag-bucket-part-templates)
- [Time part templates](#time-part-templates)
-
- [Date specifiers](#date-specifiers)
- [Time specifiers](#time-specifiers)
- [Time zone specifiers](#time-zone-specifiers)
- [Date and time specifiers](#date-and-time-specifiers)
- [Special specifiers](#special-specifiers)
-
-
+
## Restrictions
@@ -49,6 +53,11 @@ There are two types of parts:
Each template part is limited to 200 bytes in length.
Anything longer will be truncated at 200 bytes and appended with `#`.
+### Partition key size limit
+
+With the truncation of template parts, the maximum length of a partition key is
+1,607 bytes (1.57 KiB).
+
### Reserved keywords
The following reserved keywords cannot be used in partition templates:
@@ -71,6 +80,33 @@ characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Gl
Tag part templates consist of a _tag key_ to partition by.
Generated partition keys include the unique _tag value_ specific to each partition.
+## Tag bucket part templates
+
+Tag bucket part templates consist of a _tag key_ to partition by and the
+_number of "buckets" to partition tag values into_--for example:
+
+```
+customerID,500
+```
+
+Values of the `customerID` tag are bucketed into 500 distinct "buckets."
+Each bucket is identified by the remainder of the tag value hashed into a 32bit
+integer divided by the specified number of buckets:
+
+```rust
+hash(tagValue) % N
+```
+
+Generated partition keys include the unique _tag bucket identifier_ specific to
+each partition.
+
+**Supported number of tag buckets**: 1-1,000
+
+{{% note %}}
+Tag buckets should be used to partition by high cardinality tags or tags with an
+unknown number of distinct values.
+{{% /note %}}
+
## Time part templates
Time part templates use [Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
@@ -79,7 +115,6 @@ The smallest unit of time included in the time part template is the interval
used to partition data.
{{% warn %}}
-
#### Avoid partitioning by less than one day
We do not recommend using time intervals less than one day to partition data.
@@ -100,73 +135,73 @@ The following is adapted from the
### Date specifiers
-| Variable | Example | Description |
-| :------: | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `%Y` | `2001` | The full proleptic Gregorian year, zero-padded to 4 digits. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-). |
-| `%C` | `20` | The proleptic Gregorian year divided by 100, zero-padded to 2 digits. [^1] |
-| `%y` | `01` | The proleptic Gregorian year modulo 100, zero-padded to 2 digits. [^1] |
-| `%m` | `07` | Month number (01--12), zero-padded to 2 digits. |
-| `%b` | `Jul` | Abbreviated month name. Always 3 letters. |
-| `%B` | `July` | Full month name. Also accepts corresponding abbreviation in parsing. |
-| `%h` | `Jul` | Same as `%b`. |
-| `%d` | `08` | Day number (01--31), zero-padded to 2 digits. |
-| `%e` | ` 8` | Same as `%d` but space-padded. Same as `%_d`. |
-| `%a` | `Sun` | Abbreviated weekday name. Always 3 letters. |
-| `%A` | `Sunday` | Full weekday name. Also accepts corresponding abbreviation in parsing. |
-| `%w` | `0` | Sunday = 0, Monday = 1, ..., Saturday = 6. |
-| `%u` | `7` | Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601) |
-| `%U` | `28` | Week number starting with Sunday (00--53), zero-padded to 2 digits. [^2] |
-| `%W` | `27` | Same as `%U`, but week 1 starts with the first Monday in that year instead. |
-| `%G` | `2001` | Same as `%Y` but uses the year number in ISO 8601 week date. [^3] |
-| `%g` | `01` | Same as `%y` but uses the year number in ISO 8601 week date. [^3] |
-| `%V` | `27` | Same as `%U` but uses the week number in ISO 8601 week date (01--53). [^3] |
-| `%j` | `189` | Day of the year (001--366), zero-padded to 3 digits. |
-| `%D` | `07/08/01` | Month-day-year format. Same as `%m/%d/%y`. |
-| `%x` | `07/08/01` | Locale's date representation (e.g., 12/31/99). |
-| `%F` | `2001-07-08` | Year-month-day format (ISO 8601). Same as `%Y-%m-%d`. |
-| `%v` | ` 8-Jul-2001` | Day-month-year format. Same as `%e-%b-%Y`. |
+| Variable | Example | Description |
+| :------: | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `%Y` | `2001` | The full proleptic Gregorian year, zero-padded to 4 digits. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-). |
+| `%C` | `20` | The proleptic Gregorian year divided by 100, zero-padded to 2 digits. [^1] |
+| `%y` | `01` | The proleptic Gregorian year modulo 100, zero-padded to 2 digits. [^1] |
+| `%m` | `07` | Month number (01--12), zero-padded to 2 digits. |
+| `%b` | `Jul` | Abbreviated month name. Always 3 letters. |
+| `%B` | `July` | Full month name. Also accepts corresponding abbreviation in parsing. |
+| `%h` | `Jul` | Same as `%b`. |
+| `%d` | `08` | Day number (01--31), zero-padded to 2 digits. |
+| `%e` | ` 8` | Same as `%d` but space-padded. Same as `%_d`. |
+| `%a` | `Sun` | Abbreviated weekday name. Always 3 letters. |
+| `%A` | `Sunday` | Full weekday name. Also accepts corresponding abbreviation in parsing. |
+| `%w` | `0` | Sunday = 0, Monday = 1, ..., Saturday = 6. |
+| `%u` | `7` | Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601) |
+| `%U` | `28` | Week number starting with Sunday (00--53), zero-padded to 2 digits. [^2] |
+| `%W` | `27` | Same as `%U`, but week 1 starts with the first Monday in that year instead. |
+| `%G` | `2001` | Same as `%Y` but uses the year number in ISO 8601 week date. [^3] |
+| `%g` | `01` | Same as `%y` but uses the year number in ISO 8601 week date. [^3] |
+| `%V` | `27` | Same as `%U` but uses the week number in ISO 8601 week date (01--53). [^3] |
+| `%j` | `189` | Day of the year (001--366), zero-padded to 3 digits. |
+| `%D` | `07/08/01` | Month-day-year format. Same as `%m/%d/%y`. |
+| `%x` | `07/08/01` | Locale's date representation (e.g., 12/31/99). |
+| `%F` | `2001-07-08` | Year-month-day format (ISO 8601). Same as `%Y-%m-%d`. |
+| `%v` | ` 8-Jul-2001` | Day-month-year format. Same as `%e-%b-%Y`. |
### Time specifiers
-| Variable | Example | Description |
-| :------: | :------------ | :----------------------------------------------------------------------------------------------------------------------- |
-| `%H` | `00` | Hour number (00--23), zero-padded to 2 digits. |
-| `%k` | ` 0` | Same as `%H` but space-padded. Same as `%_H`. |
-| `%I` | `12` | Hour number in 12-hour clocks (01--12), zero-padded to 2 digits. |
-| `%l` | `12` | Same as `%I` but space-padded. Same as `%_I`. |
-| `%P` | `am` | `am` or `pm` in 12-hour clocks. |
-| `%p` | `AM` | `AM` or `PM` in 12-hour clocks. |
-| `%M` | `34` | Minute number (00--59), zero-padded to 2 digits. |
-| `%S` | `60` | Second number (00--60), zero-padded to 2 digits. [^4] |
-| `%f` | `26490000` | Number of nanoseconds since last whole second. [^7] |
-| `%.f` | `.026490` | Decimal fraction of a second. Consumes the leading dot. [^7] |
-| `%.3f` | `.026` | Decimal fraction of a second with a fixed length of 3. |
-| `%.6f` | `.026490` | Decimal fraction of a second with a fixed length of 6. |
-| `%.9f` | `.026490000` | Decimal fraction of a second with a fixed length of 9. |
-| `%3f` | `026` | Decimal fraction of a second like `%.3f` but without the leading dot. |
-| `%6f` | `026490` | Decimal fraction of a second like `%.6f` but without the leading dot. |
-| `%9f` | `026490000` | Decimal fraction of a second like `%.9f` but without the leading dot. |
-| `%R` | `00:34` | Hour-minute format. Same as `%H:%M`. |
-| `%T` | `00:34:60` | Hour-minute-second format. Same as `%H:%M:%S`. |
-| `%X` | `00:34:60` | Locale's time representation (e.g., 23:13:48). |
-| `%r` | `12:34:60 AM` | Locale's 12 hour clock time. (e.g., 11:11:04 PM). Falls back to `%X` if the locale does not have a 12 hour clock format. |
+| Variable | Example | Description |
+| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `%H` | `00` | Hour number (00--23), zero-padded to 2 digits. |
+| `%k` | ` 0` | Same as `%H` but space-padded. Same as `%_H`. |
+| `%I` | `12` | Hour number in 12-hour clocks (01--12), zero-padded to 2 digits. |
+| `%l` | `12` | Same as `%I` but space-padded. Same as `%_I`. |
+| `%P` | `am` | `am` or `pm` in 12-hour clocks. |
+| `%p` | `AM` | `AM` or `PM` in 12-hour clocks. |
+| `%M` | `34` | Minute number (00--59), zero-padded to 2 digits. |
+| `%S` | `60` | Second number (00--60), zero-padded to 2 digits. [^4] |
+| `%f` | `26490000` | Number of nanoseconds since last whole second. [^7] |
+| `%.f` | `.026490` | Decimal fraction of a second. Consumes the leading dot. [^7] |
+| `%.3f` | `.026` | Decimal fraction of a second with a fixed length of 3. |
+| `%.6f` | `.026490` | Decimal fraction of a second with a fixed length of 6. |
+| `%.9f` | `.026490000` | Decimal fraction of a second with a fixed length of 9. |
+| `%3f` | `026` | Decimal fraction of a second like `%.3f` but without the leading dot. |
+| `%6f` | `026490` | Decimal fraction of a second like `%.6f` but without the leading dot. |
+| `%9f` | `026490000` | Decimal fraction of a second like `%.9f` but without the leading dot. |
+| `%R` | `00:34` | Hour-minute format. Same as `%H:%M`. |
+| `%T` | `00:34:60` | Hour-minute-second format. Same as `%H:%M:%S`. |
+| `%X` | `00:34:60` | Locale's time representation (e.g., 23:13:48). |
+| `%r` | `12:34:60 AM` | Locale's 12 hour clock time. (e.g., 11:11:04 PM). Falls back to `%X` if the locale does not have a 12 hour clock format. |
### Time zone specifiers
-| Variable | Example | Description |
-| :------: | :---------- | :----------------------------------------------------------------------------------------------------------------- |
-| `%Z` | `ACST` | Local time zone name. Skips all non-whitespace characters during parsing. Identical to `%:z` when formatting. [^8] |
-| `%z` | `+0930` | Offset from the local time to UTC (with UTC being `+0000`). |
-| `%:z` | `+09:30` | Same as `%z` but with a colon. |
-| `%::z` | `+09:30:00` | Offset from the local time to UTC with seconds. |
-| `%:::z` | `+09` | Offset from the local time to UTC without minutes. |
-| `%#z` | `+09` | _Parsing only:_ Same as `%z` but allows minutes to be missing or present. |
+| Variable | Example | Description |
+| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `%Z` | `ACST` | Local time zone name. Skips all non-whitespace characters during parsing. Identical to `%:z` when formatting. [^8] |
+| `%z` | `+0930` | Offset from the local time to UTC (with UTC being `+0000`). |
+| `%:z` | `+09:30` | Same as `%z` but with a colon. |
+| `%::z` | `+09:30:00` | Offset from the local time to UTC with seconds. |
+| `%:::z` | `+09` | Offset from the local time to UTC without minutes. |
+| `%#z` | `+09` | *Parsing only:* Same as `%z` but allows minutes to be missing or present. |
### Date and time specifiers
| Variable | Example | Description |
| :------: | :--------------------------------- | :--------------------------------------------------------------------- |
-| `%c` | `Sun Jul 8 00:34:60 2001` | Locale's date and time (e.g., Thu Mar 3 23:05:25 2005). |
+| `%c` | `Sun Jul 8 00:34:60 2001` | Locale's date and time (e.g., Thu Mar 3 23:05:25 2005). |
| `%+` | `2001-07-08T00:34:60.026490+09:30` | ISO 8601 / RFC 3339 date & time format. [^5] |
| `%s` | `994518299` | UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC. [^6] |
@@ -181,77 +216,68 @@ The following is adapted from the
It is possible to override the default padding behavior of numeric specifiers `%?`.
This is not allowed for other specifiers and results in the `BAD_FORMAT` error.
-| Modifier | Description |
-| -------- | ------------------------------------------------------------------------------------- |
-| `%-?` | Suppresses any padding including spaces and zeroes. (e.g. `%j` = `012`, `%-j` = `12`) |
-| `%_?` | Uses spaces as a padding. (e.g. `%j` = `012`, `%_j` = ` 12`) |
-| `%0?` | Uses zeroes as a padding. (e.g. `%e` = ` 9`, `%0e` = `09`) |
+Modifier | Description
+-------- | -----------
+`%-?` | Suppresses any padding including spaces and zeroes. (e.g. `%j` = `012`, `%-j` = `12`)
+`%_?` | Uses spaces as a padding. (e.g. `%j` = `012`, `%_j` = ` 12`)
+`%0?` | Uses zeroes as a padding. (e.g. `%e` = ` 9`, `%0e` = `09`)
Notes:
-[^1]:
- `%C`, `%y`:
- This is floor division, so 100 BCE (year number -99) will print `-1` and `99` respectively.
+[^1]: `%C`, `%y`:
+ This is floor division, so 100 BCE (year number -99) will print `-1` and `99` respectively.
+[^2]: `%U`:
+ Week 1 starts with the first Sunday in that year.
+ It is possible to have week 0 for days before the first Sunday.
-[^2]:
- `%U`:
- Week 1 starts with the first Sunday in that year.
- It is possible to have week 0 for days before the first Sunday.
+[^3]: `%G`, `%g`, `%V`:
+ Week 1 is the first week with at least 4 days in that year.
+ Week 0 does not exist, so this should be used with `%G` or `%g`.
-[^3]:
- `%G`, `%g`, `%V`:
- Week 1 is the first week with at least 4 days in that year.
- Week 0 does not exist, so this should be used with `%G` or `%g`.
+[^4]: `%S`:
+ It accounts for leap seconds, so `60` is possible.
-[^4]:
- `%S`:
- It accounts for leap seconds, so `60` is possible.
+[^5]: `%+`: Same as `%Y-%m-%dT%H:%M:%S%.f%:z`, i.e. 0, 3, 6 or 9 fractional
+ digits for seconds and colons in the time zone offset.
+
+
+ This format also supports having a `Z` or `UTC` in place of `%:z`. They
+ are equivalent to `+00:00`.
+
+
+ Note that all `T`, `Z`, and `UTC` are parsed case-insensitively.
+
+
+ The typical `strftime` implementations have different (and locale-dependent)
+ formats for this specifier. While Chrono's format for `%+` is far more
+ stable, it is best to avoid this specifier if you want to control the exact
+ output.
-[^5]:
- `%+`: Same as `%Y-%m-%dT%H:%M:%S%.f%:z`, i.e. 0, 3, 6 or 9 fractional
- digits for seconds and colons in the time zone offset.
-
-
- This format also supports having a `Z` or `UTC` in place of `%:z`. They
- are equivalent to `+00:00`.
-
-
- Note that all `T`, `Z`, and `UTC` are parsed case-insensitively.
-
-
- The typical `strftime` implementations have different (and locale-dependent)
- formats for this specifier. While Chrono's format for `%+` is far more
- stable, it is best to avoid this specifier if you want to control the exact
- output.
+[^6]: `%s`:
+ This is not padded and can be negative.
+ For the purpose of Chrono, it only accounts for non-leap seconds
+ so it slightly differs from ISO C `strftime` behavior.
-[^6]:
- `%s`:
- This is not padded and can be negative.
- For the purpose of Chrono, it only accounts for non-leap seconds
- so it slightly differs from ISO C `strftime` behavior.
+[^7]: `%f`, `%.f`:
+
+ `%f` and `%.f` are notably different formatting specifiers.
+ `%f` counts the number of nanoseconds since the last whole second, while `%.f` is a fraction of a
+ second.
+ Example: 7μs is formatted as `7000` with `%f`, and formatted as `.000007` with `%.f`.
-[^7]:
- `%f`, `%.f`:
-
- `%f` and `%.f` are notably different formatting specifiers.
- `%f` counts the number of nanoseconds since the last whole second, while `%.f` is a fraction of a
- second.
- Example: 7μs is formatted as `7000` with `%f`, and formatted as `.000007` with `%.f`.
-
-[^8]:
- `%Z`:
- Since `chrono` is not aware of timezones beyond their offsets, this specifier
- **only prints the offset** when used for formatting. The timezone abbreviation
- will NOT be printed. See [this issue](https://github.com/chronotope/chrono/issues/960)
- for more information.
-
-
- Offset will not be populated from the parsed data, nor will it be validated.
- Timezone is completely ignored. Similar to the glibc `strptime` treatment of
- this format code.
-
-
- It is not possible to reliably convert from an abbreviation to an offset,
- for example CDT can mean either Central Daylight Time (North America) or
- China Daylight Time.
- \*/
+[^8]: `%Z`:
+ Since `chrono` is not aware of timezones beyond their offsets, this specifier
+ **only prints the offset** when used for formatting. The timezone abbreviation
+ will NOT be printed. See [this issue](https://github.com/chronotope/chrono/issues/960)
+ for more information.
+
+
+ Offset will not be populated from the parsed data, nor will it be validated.
+ Timezone is completely ignored. Similar to the glibc `strptime` treatment of
+ this format code.
+
+
+ It is not possible to reliably convert from an abbreviation to an offset,
+ for example CDT can mean either Central Daylight Time (North America) or
+ China Daylight Time.
+*/
\ No newline at end of file
diff --git a/content/influxdb/clustered/admin/databases/create.md b/content/influxdb/clustered/admin/databases/create.md
index 607fd2d50..5ad5598ed 100644
--- a/content/influxdb/clustered/admin/databases/create.md
+++ b/content/influxdb/clustered/admin/databases/create.md
@@ -18,7 +18,7 @@ list_code_example: |
```
related:
- /influxdb/clustered/reference/cli/influxctl/database/create/
- - /influxdb/cloud-dedicated/admin/custom-partitions/
+ - /influxdb/clustered/admin/custom-partitions/
---
Use the [`influxctl database create` command](/influxdb/clustered/reference/cli/influxctl/database/create/)
@@ -32,12 +32,18 @@ to create a database in your {{< product-name omit=" Clustered" >}} cluster.
- _Optional_: Database table (measurement) limit _(default is 500)_
- _Optional_: Database column limit _(default is 250)_
- _Optional_: [InfluxDB tags](/influxdb/clustered/reference/glossary/#tag)
- to use in the partition template _(supports up to 7 different tags)_
+ to use in the partition template
+ - _Optional_: [InfluxDB tag buckets](/influxdb/clustered/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+ to use in the partition template
- _Optional_: A [Rust strftime date and time string](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates)
that specifies the time format in the partition template and determines
the time interval to partition by _(default is `%Y-%m-%d`)_
- Database name _(see [Database naming restrictions](#database-naming-restrictions))_
+ {{% note %}}
+_{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
+ {{% /note %}}
+
{{% code-placeholders "DATABASE_NAME|30d|500|200" %}}
```sh
influxctl database create \
@@ -46,6 +52,8 @@ influxctl database create \
--max-columns 250 \
--template-tag tag1 \
--template-tag tag2 \
+ --template-tag-bucket tag3,100 \
+ --template-tag-bucket tag4,300 \
--template-timeformat '%Y-%m-%d' \
DATABASE_NAME
```
@@ -209,8 +217,8 @@ format in the InfluxDB v3 storage engine. By default, data is partitioned by day
but, depending on your schema and workload, customizing the partitioning
strategy can improve query performance.
-Use the `--template-tag` and `--template-timeformat` flags to define partition
-template parts used to generate partition keys for the database.
+Use the `--template-tag`, `--template-tag-bucket, and `--template-timeformat`
+flags to define partition template parts used to generate partition keys for the database.
For more information, see [Manage data partitioning](/influxdb/clustered/admin/custom-partitions/).
{{% note %}}
diff --git a/content/influxdb/clustered/admin/tables/create.md b/content/influxdb/clustered/admin/tables/create.md
index 41b301915..cf0ee0c4e 100644
--- a/content/influxdb/clustered/admin/tables/create.md
+++ b/content/influxdb/clustered/admin/tables/create.md
@@ -31,18 +31,26 @@ to a table, you must manually create the table before you write any data to it.
2. Run the `influxctl table create` command and provide the following:
- _Optional_: [InfluxDB tags](/influxdb/clustered/reference/glossary/#tag)
- to use in the partition template _(supports up to 7 different tags)_
+ to use in the partition template
+ - _Optional_: [InfluxDB tag buckets](/influxdb/clustered/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
+ to use in the partition template
- _Optional_: A [Rust strftime date and time string](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates)
that specifies the time format in the partition template and determines
the time interval to partition by _(default is `%Y-%m-%d`)_
- The name of the database to create the table in
- The name of the table to create
+ {{% note %}}
+_{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
+ {{% /note %}}
+
{{% code-placeholders "(DATABASE|TABLE)_NAME" %}}
```sh
influxctl table create \
--template-tag tag1 \
--template-tag tag2 \
+ --template-tag-bucket tag3,100 \
+ --template-tag-bucket tag4,300 \
--template-timeformat '%Y-%m-%d' \
DATABASE_NAME \
TABLE_NAME
@@ -57,8 +65,8 @@ format in the InfluxDB v3 storage engine. By default, data is partitioned by day
but, depending on your schema and workload, customizing the partitioning
strategy can improve query performance.
-Use the `--template-tag` and `--template-timeformat` flags to define partition
-template parts used to generate partition keys for the table.
+Use the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags to define partition template parts used to generate partition keys for the table.
If no template flags are provided, the table uses the partition template of the
target database.
For more information, see [Manage data partitioning](/influxdb/clustered/admin/custom-partitions/).
diff --git a/content/influxdb/clustered/reference/cli/influxctl/database/create.md b/content/influxdb/clustered/reference/cli/influxctl/database/create.md
index 1878db65f..06aae21ff 100644
--- a/content/influxdb/clustered/reference/cli/influxctl/database/create.md
+++ b/content/influxdb/clustered/reference/cli/influxctl/database/create.md
@@ -51,10 +51,12 @@ The retention period value cannot be negative or contain whitespace.
#### Custom partitioning
-You can override the default partition template (`%Y-%m-%d`) of the database with
-the `--template-tag` and `--template-timeformat` flags when you create the database.
-Provide a time format using [Rust strftime](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates)
-and include specific tags to use in the partition template.
+You can override the default partition template (`%Y-%m-%d`) of the database
+with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags when you create the database.
+Provide a time format using [Rust strftime](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values
+into a specified number of "buckets."
+Each of these can be used as part of the partition template.
Be sure to follow [partitioning best practices](/influxdb/clustered/admin/custom-partitions/best-practices/).
## Usage
@@ -71,14 +73,15 @@ influxctl database create [flags]
## Flags
-| Flag | | Description |
-| :--- | :---------------------- | :------------------------------------------------------------------- |
-| | `--retention-period` | Database retention period (default is 0s or infinite) |
-| | `--max-tables` | Maximum tables per database (default is 500, 0 uses default) |
-| | `--max-columns` | Maximum columns per table (default is 250, 0 uses default) |
-| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
-| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
-| `-h` | `--help` | Output command help |
+| Flag | | Description |
+| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| | `--retention-period` | Database retention period (default is 0s or infinite) |
+| | `--max-tables` | Maximum tables per database (default is 500, 0 uses default) |
+| | `--max-columns` | Maximum columns per table (default is 250, 0 uses default) |
+| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
+| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) |
+| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
+| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb/clustered/reference/cli/influxctl/#global-flags)._
@@ -124,9 +127,24 @@ the time format `%Y wk:%W`:
influxctl database create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,1000 \
--template-timeformat '%Y wk:%W' \
mydb
```
_For more information about custom partitioning, see
[Manage data partitioning](/influxdb/clustered/admin/custom-partitions/)._
+
+{{% expand "View command updates" %}}
+
+#### v2.7.0 {date="2024-03-26"}
+
+- Introduce the `--template-tag-bucket` flag to group tag values into buckets
+ and partition by each tag bucket.
+
+#### v2.5.0 {date="2024-03-04"}
+
+- Introduce the `--template-tag` and `--template-timeformat` flags that define
+ a custom partition template for a database.
+
+{{% /expand %}}
diff --git a/content/influxdb/clustered/reference/cli/influxctl/table/create.md b/content/influxdb/clustered/reference/cli/influxctl/table/create.md
index 60bb0a303..3317a46c0 100644
--- a/content/influxdb/clustered/reference/cli/influxctl/table/create.md
+++ b/content/influxdb/clustered/reference/cli/influxctl/table/create.md
@@ -17,9 +17,11 @@ database in an {{< product-name omit=" Clustered" >}} cluster.
#### Custom partitioning
You can override the default partition template (the partition template of the target database)
-with the `--template-tag` and `--template-timeformat` flags when you create the table.
-Provide a time format using [Rust strftime](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates)
-and include specific tags to use in the partition template.
+with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat`
+flags when you create the table.
+Provide a time format using [Rust strftime](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values
+into a specified number of "buckets."
+Each of these can be used as part of the partition template.
Be sure to follow [partitioning best practices](/influxdb/clustered/admin/custom-partitions/best-practices/).
## Usage
@@ -37,11 +39,12 @@ influxctl table create [flags]
## Flags
-| Flag | | Description |
-| :--- | :---------------------- | :------------------------------------------------------------------- |
-| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
-| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
-| `-h` | `--help` | Output command help |
+| Flag | | Description |
+| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) |
+| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) |
+| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) |
+| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb/clustered/reference/cli/influxctl/#global-flags)._
@@ -50,7 +53,7 @@ _Also see [`influxctl` global flags](/influxdb/clustered/reference/cli/influxctl
## Examples
- [Create a table](#create-a-table)
-- [Create a table with with a custom partition template](#create-a-table-with-with-a-custom-partition-template)
+- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template)
In the following examples, replace:
@@ -67,7 +70,7 @@ influxctl table create DATABASE_NAME TABLE_NAME
```
{{% /code-placeholders %}}
-### Create a table with with a custom partition template
+### Create a table with a custom partition template
The following example creates a new table and applies a partition
template that partitions by two tags (`room` and `sensor-type`) and by week using
@@ -78,6 +81,7 @@ the time format `%Y wk:%W`:
influxctl table create \
--template-tag room \
--template-tag sensor-type \
+ --template-tag-bucket customerID,1000 \
--template-timeformat '%Y wk:%W' \
DATABASE_NAME \
TABLE_NAME
@@ -86,3 +90,12 @@ influxctl table create \
_For more information about custom partitioning, see
[Manage data partitioning](/influxdb/clustered/admin/custom-partitions/)._
+
+{{% expand "View command updates" %}}
+
+#### v2.7.0 {date="2024-03-26"}
+
+- Introduce the `--template-tag-bucket` flag to group tag values into buckets
+ and partition by each tag bucket.
+
+{{% /expand %}}
diff --git a/data/products.yml b/data/products.yml
index fe2d52922..0fd56b5ac 100644
--- a/data/products.yml
+++ b/data/products.yml
@@ -55,7 +55,7 @@ influxdb_cloud_dedicated:
list_order: 3
latest: cloud-dedicated
link: "https://www.influxdata.com/contact-sales-form/"
- latest_cli: 2.6.0
+ latest_cli: 2.7.0
placeholder_host: cluster-id.influxdb.io
influxdb_clustered: