diff --git a/api-docs/influxdb3/cloud-dedicated/management/openapi.yml b/api-docs/influxdb3/cloud-dedicated/management/openapi.yml
index 74868b46b..95bcfb27c 100644
--- a/api-docs/influxdb3/cloud-dedicated/management/openapi.yml
+++ b/api-docs/influxdb3/cloud-dedicated/management/openapi.yml
@@ -397,6 +397,26 @@ paths:
post:
operationId: CreateClusterDatabase
summary: Create a database
+ description: |
+ Create a database for a cluster.
+
+ The database name must be unique within the cluster.
+
+ **Default maximum number of columns**: 250
+ **Default maximum number of tables**: 500
+
+ The retention period is specified in nanoseconds. For example, to set a retention period of 1 hour, use `3600000000000`.
+
+ InfluxDB Cloud Dedicated lets you define a [custom partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) strategy for each database and table.
+ A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
+ By default, data is partitioned by day,
+ but, depending on your schema and workload, customizing the partitioning
+ strategy can improve query performance.
+
+ To use custom partitioning, you define a [partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
+ If a table doesn't have a custom partition template, it inherits the database's template.
+ The partition template is set at the time of database creation and cannot be changed later.
+ For more information, see [Custom partitions](/influxdb3/cloud-dedicated/admin/custom-partitions/).
tags:
- Databases
parameters:
@@ -779,6 +799,18 @@ paths:
post:
operationId: CreateClusterDatabaseTable
summary: Create a database table
+ description: |
+ Create a database table in a database. The database must already exist. With InfluxDB Cloud Dedicated, tables and measurements are synonymous.
+
+ Typically, tables are created automatically on write using the measurement name
+ specified in line protocol written to InfluxDB.
+ However, to apply a [custom partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/)
+ to a table, you must manually [create the table with custom partitioning](/influxdb3/cloud-dedicated/admin/tables/#create-a-table-with-custom-partitioning) before you write any data to it.
+
+ Partitioning defaults to `%Y-%m-%d` (daily).
+ 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.
tags:
- Tables
parameters:
@@ -1185,6 +1217,14 @@ paths:
get:
operationId: GetDatabaseToken
summary: Get a database token
+ description: |
+ Retrieve metadata details for a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/).
+
+ #### Store secure tokens in a secret store
+
+ We recommend storing database tokens in a **secure secret store**.
+
+ Token strings are viewable _only_ on token creation and aren't stored by InfluxDB; you can't recover a lost token.
tags:
- Database tokens
parameters:
@@ -1299,6 +1339,8 @@ paths:
patch:
operationId: UpdateDatabaseToken
summary: Update a database token
+ description: |
+ Update the description and permissions of a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/).
tags:
- Database tokens
parameters:
@@ -1317,7 +1359,6 @@ paths:
- name: tokenId
in: path
description: The ID of the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) to update
- required: true
schema:
$ref: '#/components/schemas/UuidV4'
requestBody:
@@ -1625,9 +1666,9 @@ components:
description: |
A template for [partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) a cluster database.
- Each template part is evaluated in sequence, concatinating the final
- partition key from the output of each part, delimited by the partition
- key delimiter `|`.
+ Each partition template part is evaluated in sequence.
+ The outputs from each part are concatenated with the
+ `|` delimiter to form the final partition key.
For example, using the partition template below:
diff --git a/content/influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md b/content/influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
index 6a8db4cae..9edb5b012 100644
--- a/content/influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
+++ b/content/influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
@@ -14,5 +14,6 @@ source: /shared/v3-distributed-admin-custom-partitions/define-custom-partitions.
---
diff --git a/content/influxdb3/cloud-dedicated/admin/databases/create.md b/content/influxdb3/cloud-dedicated/admin/databases/create.md
index 8f6b66334..2af42d58a 100644
--- a/content/influxdb3/cloud-dedicated/admin/databases/create.md
+++ b/content/influxdb3/cloud-dedicated/admin/databases/create.md
@@ -4,7 +4,7 @@ description: >
Use the Admin UI, the [`influxctl database create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to create a new InfluxDB database in your InfluxDB Cloud Dedicated cluster.
- Provide a database name and an optional retention period.
+ You can create a database with an optional retention period and custom partitioning.
menu:
influxdb3_cloud_dedicated:
parent: Manage databases
@@ -12,57 +12,19 @@ weight: 201
list_code_example: |
##### CLI
- ```sh
+ ```bash
influxctl database create \
--retention-period 30d \
- --max-tables 500 \
- --max-columns 250 \
DATABASE_NAME
```
##### API
- ```sh
+ ```bash
curl \
--location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
- --request POST \
- --header "Accept: application/json" \
- --header 'Content-Type: application/json' \
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
- --data '{
- "name": "'DATABASE_NAME'",
- "maxTables": 500,
- "maxColumnsPerTable": 250,
- "retentionPeriod": 2592000000000,
- "partitionTemplate": [
- {
- "type": "tag",
- "value": "TAG_KEY_1"
- },
- {
- "type": "tag",
- "value": "TAG_KEY_2"
- },
- {
- "type": "bucket",
- "value": {
- "tagName": "TAG_KEY_3",
- "numberOfBuckets": 100
- }
- },
- {
- "type": "bucket",
- "value": {
- "tagName": "TAG_KEY_4",
- "numberOfBuckets": 300
- }
- },
- {
- "type": "time",
- "value": "%Y-%m-%d"
- }
- ]
- }'
+ --json '{ "name": "DATABASE_NAME" }'
```
related:
- /influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/
@@ -72,6 +34,18 @@ related:
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to create a database in your {{< product-name omit=" Clustered" >}} cluster.
+You can create a database with an optional retention period and custom partitioning.
+
+- [Create a database](#create-a-database)
+- [Create a database with custom partitioning](#create-a-database-with-custom-partitioning)
+- [Partition template requirements and guidelines](#partition-template-requirements-and-guidelines)
+- [Database attributes](#database-attributes)
+ - [Retention period syntax](#retention-period-syntax)
+ - [Database naming restrictions](#database-naming-restrictions)
+ - [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
+ - [Table and column limits](#table-and-column-limits)
+
+## Create a database
{{< tabs-wrapper >}}
{{% tabs %}}
@@ -79,68 +53,121 @@ or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to crea
[influxctl](#)
[Management API](#)
{{% /tabs %}}
+
{{% tab-content %}}
-The InfluxDB Cloud Dedicated administrative UI includes a portal for creating
-and managing databases.
-
-1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
-
+1. Open the {{< product-name >}} Admin UI at
https://console.influxdata.com
+
2. Use the credentials provided by InfluxData to log into the Admin UI.
If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com).
-3. In the cluster list, find the cluster you want to create a database in. You
+
+3. In the cluster list, find and click the cluster you want to create a database in. You
can sort on column headers or use the **Search** field to find a specific cluster.
-4. Click the row for the cluster that you want to create a database in.
-5. Click the **New Database** button in the upper right corner of the cluster details page.
+
+4. Click the **New Database** button in the upper right corner of the cluster details page.
The **Create Database** dialog displays.
- 
-6. In the **Create Database** dialog, provide the following information:
+
+
+5. In the **Create Database** dialog, provide the following information:
- **Database name**: The name of the database to create. See [Database naming restrictions](#database-naming-restrictions).
- - **Retention period**: The retention period for the database. See [Retention period syntax (influxctl CLI)](#retention-period-syntax-influxctl-cli).
+ - **Retention period**: The retention period for the database. See [Retention period syntax](#retention-period-syntax).
- **Max tables**: The maximum number of tables (measurements) allowed in the database. Default is 500.
- **Max columns per table**: The maximum number of columns allowed in each table (measurement). Default is 250.
-7. Click the **Create Database** button to create the database.
+
+6. Click the **Create Database** button to create the database.
The new database displays in the list of databases for the cluster.
{{% /tab-content %}}
+
{{% tab-content %}}
-Use the [`influxctl database create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/)
-to create a database in your {{< product-name omit=" Clustered" >}} cluster.
+1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl), and then [configure an `influxctl` connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster.
-1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl), and then [configure an `influxctl` connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster.
+2. Run the `influxctl database create` command:
-2. In your terminal, run the `influxctl database create` command and provide the following:
-
- - _Optional_: Database [retention period](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)
- Default is `infinite` (`0`).
- - _Optional_: Database table (measurement) limit. Default is `500`.
- - _Optional_: Database column limit. Default is `250`.
- - _Optional_: [InfluxDB tags](/influxdb3/cloud-dedicated/reference/glossary/#tag)
- to use in the partition template. Limit is 7 total tags or tag buckets.
- - _Optional_: [InfluxDB tag buckets](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
- to use in the partition template. Limit is 7 total tags or tag buckets.
- - _Optional_: A [Rust strftime date and time string](/influxdb3/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._
-
-
-
-
-{{% code-placeholders "DATABASE_NAME|30d|500|100|300|(TAG_KEY(_\d)?)" %}}
-
-```sh
+{{% code-placeholders "DATABASE_NAME|30d" %}}
+```bash
+influxctl database create \
+ --retention-period 30d \
+ DATABASE_NAME
+```
+{{% /code-placeholders %}}
+
+Replace {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}} with your desired database name.
+{{% /tab-content %}}
+
+{{% tab-content %}}
+
+_This example uses [cURL](https://curl.se/) to send a Management HTTP API request, but you can use any HTTP client._
+
+1. If you haven't already, follow the instructions to [install cURL](https://everything.curl.dev/install/index.html) for your system.
+2. In your terminal, use cURL to send a request to the following {{% product-name %}} endpoint:
+
+{{% api-endpoint method="POST"
+endpoint="https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases"
+api-ref="/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabase" %}}
+
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|MANAGEMENT_TOKEN|DATABASE_NAME" %}}
+```bash
+curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "DATABASE_NAME"
+ }'
+```
+{{% /code-placeholders %}}
+
+Replace the following:
+
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the [account](/influxdb3/cloud-dedicated/admin/account/) ID for the cluster _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the [cluster](/influxdb3/cloud-dedicated/admin/clusters/) ID _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
+- {{% code-placeholder-key %}}`MANAGEMENT_TOKEN`{{% /code-placeholder-key %}}: a valid [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: name for the new database
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
+Partitioning defaults to `%Y-%m-%d` (daily).
+
+## Create a database with custom partitioning
+
+{{< product-name >}} lets you define a [custom partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) strategy for each database and table.
+A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
+By default, data is partitioned by day,
+but, depending on your schema and workload, customizing the partitioning
+strategy can improve query performance.
+
+To use custom partitioning, you define a [partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
+If a table doesn't have a custom partition template, it inherits the database's template.
+
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[influxctl](#)
+[Management API](#)
+{{% /tabs %}}
+{{% tab-content %}}
+
+1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/get-started/setup/#download-install-and-configure-the-influxctl-cli).
+2. Use the following `influxctl database create` command flags to specify the
+[partition template parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates):
+
+ - `--template-timeformat`: A [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
+ string that specifies the time part in the partition template and determines
+ the time interval to partition by.
+ - `--template-tag`: An [InfluxDB tag]
+ to use in the partition template.
+ - `--template-tag-bucket`: An [InfluxDB tag](/influxdb3/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`.
+
+{{% code-placeholders "DATABASE_NAME|30d|(TAG_KEY(_\d)?)|100|300" %}}
+```bash
influxctl database create \
--retention-period 30d \
- --max-tables 500 \
- --max-columns 250 \
--template-tag TAG_KEY_1 \
--template-tag TAG_KEY_2 \
--template-tag-bucket TAG_KEY_3,100 \
@@ -148,233 +175,128 @@ influxctl database create \
--template-timeformat '%Y-%m-%d' \
DATABASE_NAME
```
-
{{% /code-placeholders %}}
-Replace the following in your command:
+Replace the following:
-- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb3/cloud-dedicated/admin/databases/)
-- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys from your data
-
-## Database attributes
-
-- [Database attributes](#database-attributes)
- - [Retention period syntax (influxctl CLI)](#retention-period-syntax-influxctl-cli)
- - [Custom partitioning (influxctl CLI)](#custom-partitioning-influxctl-cli)
-- [Database attributes](#database-attributes-1)
- - [Retention period syntax (Management API)](#retention-period-syntax-management-api)
- - [Custom partitioning (Management API)](#custom-partitioning-management-api)
- - [Database naming restrictions](#database-naming-restrictions)
- - [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
- - [Table and column limits](#table-and-column-limits)
-
-### Retention period syntax (influxctl CLI)
-
-Use the `--retention-period` flag to define the
-[retention period](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)
-for the database.
-The retention period value is a time duration value made up of a numeric value
-plus a duration unit.
-For example, `30d` means 30 days.
-A zero duration (`0d`) retention period is infinite and data won't expire.
-The retention period value cannot be negative or contain whitespace.
-
-{{< flex >}}
-{{% flex-content "half" %}}
-
-#### Valid durations units include
-
-- **m**: minute
-- **h**: hour
-- **d**: day
-- **w**: week
-- **mo**: month
-- **y**: year
-
-{{% /flex-content %}}
-{{% flex-content "half" %}}
-
-#### Example retention period values
-
-- `0d`: infinite/none
-- `3d`: 3 days
-- `6w`: 6 weeks
-- `1mo`: 1 month (30 days)
-- `1y`: 1 year
-- `30d30d`: 60 days
-- `2.5d`: 60 hours
-
-{{% /flex-content %}}
-{{< /flex >}}
-
-### Custom partitioning (influxctl CLI)
-
-{{< product-name >}} lets you define a custom partitioning strategy for each database.
-A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
-format in the InfluxDB 3 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`, `--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](/influxdb3/cloud-dedicated/admin/custom-partitions/).
-
-
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create
+- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys to partition by
+- {{% code-placeholder-key %}}`TAG_KEY_3`, `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys for bucketed partitioning
+- {{% code-placeholder-key %}}`100`, `300`{{% /code-placeholder-key %}}: number of buckets to group tag values into
+- {{% code-placeholder-key %}}`'%Y-%m-%d'`{{% /code-placeholder-key %}}: [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) string that specifies the time part in the partition template
{{% /tab-content %}}
{{% tab-content %}}
-
+
_This example uses [cURL](https://curl.se/) to send a Management HTTP API request, but you can use any HTTP client._
1. If you haven't already, follow the instructions to [install cURL](https://everything.curl.dev/install/index.html) for your system.
2. In your terminal, use cURL to send a request to the following {{% product-name %}} endpoint:
- {{% api-endpoint endpoint="https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" method="post" api-ref="/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabase" %}}
+{{% api-endpoint method="POST"
+endpoint="https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases"
+api-ref="/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabase" %}}
- In the URL, provide the following credentials:
+In the request body, include the `partitionTemplate` property and specify the [partition template parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates) as an array of objects--for example:
- - `ACCOUNT_ID`: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the cluster belongs to _(see how to [list cluster details](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
- - `CLUSTER_ID`: The ID of the [cluster](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that you want to manage _(see how to [list cluster details](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
-
- Provide the following request headers:
-
- - `Accept: application/json` to ensure the response body is JSON content
- - `Content-Type: application/json` to indicate the request body is JSON content
- - `Authorization: Bearer` and a [Management API token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your cluster _(see how to [create a management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for Management API requests)_.
-
- In the request body, provide the following parameters:
-
- - _Optional:_ Database [retention period](/influxdb3/cloud-dedicated/admin/databases/#retention-periods) in nanoseconds.
- Default is `0` (infinite).
- - _Optional_: Database table (measurement) limit. Default is `500`.
- - _Optional_: Database column limit. Default is `250`.
- - _Optional_: [InfluxDB tags](/influxdb3/cloud-dedicated/reference/glossary/#tag)
- to use in the partition template. Limit is 7 total tags or tag buckets.
- - _Optional_: [InfluxDB tag buckets](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
- to use in the partition template. Limit is 7 total tags or tag buckets.
- - _Optional_: A supported [Rust strftime date and time string](/influxdb3/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._
-
-The following example shows how to use the Management API to create a database with custom partitioning:
-
-
-
-
-{{% code-placeholders "DATABASE_NAME|2592000000000|500|100|300|250|ACCOUNT_ID|CLUSTER_ID|MANAGEMENT_TOKEN|(TAG_KEY(_\d)?)" %}}
-
-```sh
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|DATABASE_NAME|MANAGEMENT_TOKEN|(TAG_KEY(_\d)?)|100|300|%Y-%m-%d" %}}
+```bash
curl \
- --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
- --request POST \
- --header "Accept: application/json" \
- --header 'Content-Type: application/json' \
- --header "Authorization: Bearer MANAGEMENT_TOKEN" \
- --data '{
- "name": "'DATABASE_NAME'",
- "maxTables": 500,
- "maxColumnsPerTable": 250,
- "retentionPeriod": 2592000000000,
- "partitionTemplate": [
- {
- "type": "tag",
- "value": "TAG_KEY_1"
- },
- {
- "type": "tag",
- "value": "TAG_KEY_2"
- },
- {
- "type": "bucket",
- "value": {
- "tagName": "TAG_KEY_3",
- "numberOfBuckets": 100
- }
- },
- {
- "type": "bucket",
- "value": {
- "tagName": "TAG_KEY_4",
- "numberOfBuckets": 300
- }
- },
- {
- "type": "time",
- "value": "%Y-%m-%d"
- }
- ]
- }'
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "DATABASE_NAME",
+ "maxTables": 500,
+ "maxColumnsPerTable": 250,
+ "retentionPeriod": 2592000000000,
+ "partitionTemplate": [
+ { "type": "tag", "value": "TAG_KEY_1" },
+ { "type": "tag", "value": "TAG_KEY_2" },
+ { "type": "bucket", "value": { "tagName": "TAG_KEY_3", "numberOfBuckets": 100 } },
+ { "type": "bucket", "value": { "tagName": "TAG_KEY_4", "numberOfBuckets": 300 } },
+ { "type": "time", "value": "%Y-%m-%d" }
+ ]
+ }'
```
-
{{% /code-placeholders %}}
-Replace the following in your request:
+Replace the following:
-- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the ID of the {{% product-name %}} [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database for
-- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the ID of the {{% product-name %}} [cluster](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database for
-- {{% code-placeholder-key %}}`MANAGEMENT TOKEN`{{% /code-placeholder-key %}}: a [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
-- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb3/cloud-dedicated/admin/databases/)
-- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys from your data
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the [account](/influxdb3/cloud-dedicated/admin/account/) ID for the cluster _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the [cluster](/influxdb3/cloud-dedicated/admin/clusters/) ID _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
+- {{% code-placeholder-key %}}`MANAGEMENT_TOKEN`{{% /code-placeholder-key %}}: a valid [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: name for the new database
+- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys to partition by
+- {{% code-placeholder-key %}}`TAG_KEY_3`, `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys for bucketed partitioning
+- {{% code-placeholder-key %}}`100`, `300`{{% /code-placeholder-key %}}: number of buckets to group tag values into
+- {{% code-placeholder-key %}}`'%Y-%m-%d'`{{% /code-placeholder-key %}}: [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) string that specifies the time part in the partition template
+
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
+## Partition template requirements and guidelines
+
+Always specify 1 time part in your template.
+A template has a maximum of 8 parts: 1 time part and up to 7 total tag and tag bucket parts.
+
+For more information about partition template requirements and restrictions, see [Partition templates](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
+
+> [!Warning]
+> #### Partition templates can only be applied on create
+>
+> You can only apply a partition template when creating a database.
+> You can't update a partition template on an existing database.
## Database attributes
-- [Database attributes](#database-attributes)
- - [Retention period syntax (influxctl CLI)](#retention-period-syntax-influxctl-cli)
- - [Custom partitioning (influxctl CLI)](#custom-partitioning-influxctl-cli)
-- [Database attributes](#database-attributes-1)
- - [Retention period syntax (Management API)](#retention-period-syntax-management-api)
- - [Custom partitioning (Management API)](#custom-partitioning-management-api)
- - [Database naming restrictions](#database-naming-restrictions)
- - [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
- - [Table and column limits](#table-and-column-limits)
+### Retention period syntax
-### Retention period syntax (Management API)
+Specify how long InfluxDB retains data before automatically removing it.
-Use the `retentionPeriod` property to specify the
-[retention period](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)
-for the database.
-The retention period value is an integer (``) that represents the number of nanoseconds.
-For example, `2592000000000` means 30 days.
-A zero (`0`) retention period is infinite and data won't expire.
-The retention period value cannot be negative or contain whitespace.
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[influxctl CLI](#)
+[Management API](#)
+{{% /tabs %}}
-#### Example retention period values
+{{% tab-content %}}
+Use the `--retention-period` flag to define the retention period as a duration.
+For example, `30d` means 30 days. A zero duration (`0d`) keeps data indefinitely.
+{{< flex >}}
+{{% flex-content "half" %}}
+#### Valid duration units
+- **m**: minute
+- **h**: hour
+- **d**: day
+- **w**: week
+- **mo**: month
+- **y**: year
+{{% /flex-content %}}
+
+{{% flex-content "half" %}}
+#### Example values
+- `0d`: infinite/none
+- `3d`: 3 days
+- `6w`: 6 weeks
+- `1mo`: 1 month (30 days)
+- `1y`: 1 year
+{{% /flex-content %}}
+{{< /flex >}}
+{{% /tab-content %}}
+
+{{% tab-content %}}
+Use the `retentionPeriod` property to specify the retention period as nanoseconds.
+For example, `2592000000000` means 30 days. A value of `0` keeps data indefinitely.
+
+#### Example values
- `0`: infinite/none
- `259200000000000`: 3 days
- `2592000000000000`: 30 days
- `31536000000000000`: 1 standard year (365 days)
-
-### Custom partitioning (Management API)
-
-{{< product-name >}} lets you define a custom partitioning strategy for each database.
-A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
-format in the InfluxDB 3 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 [`partitionTemplate`](/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabase)
-property to define an array of partition template parts used to generate
-partition keys for the database.
-
-For more information, see [Manage data partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/).
-
-
{{% /tab-content %}}
{{< /tabs-wrapper >}}
-> [!Warning]
->
-> #### Partition templates can only be applied on create
->
-> You can only apply a partition template when creating a database.
-> You can't update a partition template on an existing database.
-
### Database naming restrictions
Database names must adhere to the following naming restrictions:
@@ -392,11 +314,9 @@ and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp).
In {{% product-name %}}, databases and retention policies have been merged into
_databases_, where databases have a retention period, but retention policies
are no longer part of the data model.
-Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
-database and retention policy (DBRP) to be queryable with InfluxQL.
**When naming a database that you want to query with InfluxQL**, use the following
-naming convention to automatically map v1 DBRP combinations to an {{% product-name %}} database:
+naming convention:
```text
database_name/retention_policy_name
@@ -434,15 +354,13 @@ cluster in the following ways:
{{< expand-wrapper >}}
{{% expand "**May improve query performance** View more info" %}}
-
Schemas with many measurements that contain
[focused sets of tags and fields](/influxdb3/cloud-dedicated/write-data/best-practices/schema-design/#design-for-performance) can make it easier for the query engine to
identify what partitions contain the queried data, resulting in better
query performance.
-
{{% /expand %}}
-{{% expand "**More PUTs into object storage** View more info" %}}
+{{% expand "**More PUTs into object storage** View more info" %}}
By default, {{< product-name >}} partitions
data by measurement and time range and stores each partition as a Parquet
file in your cluster's object store. By increasing the number of measurements
@@ -450,16 +368,14 @@ file in your cluster's object store. By increasing the number of measurements
more `PUT` requests into your object store as InfluxDB creates more partitions.
Each `PUT` request incurs a monetary cost and will increase the operating cost of
your cluster.
-
{{% /expand %}}
-{{% expand "**More work for the compactor** View more info" %}}
+{{% expand "**More work for the compactor** View more info" %}}
To optimize storage over time, your {{< product-name omit=" Clustered" >}}
cluster contains a compactor that routinely compacts Parquet files in object storage.
With more tables and partitions to compact, the compactor may need to be scaled
(either vertically or horizontally) to keep up with demand, adding to the
operating cost of your cluster.
-
{{% /expand %}}
{{< /expand-wrapper >}}
@@ -473,7 +389,6 @@ cluster in the following ways:
{{< expand-wrapper >}}
{{% expand "May adversely affect query performance" %}}
-
At query time, the InfluxDB query engine identifies what table contains the queried
data and then evaluates each row in the table to match the conditions of the query.
The more columns that are in each row, the longer it takes to evaluate each row.
@@ -481,6 +396,5 @@ The more columns that are in each row, the longer it takes to evaluate each row.
Through performance testing, InfluxData has identified 250 columns as the
threshold beyond which query performance may be affected
(depending on the shape of and data types in your schema).
-
{{% /expand %}}
-{{< /expand-wrapper >}}
+{{< /expand-wrapper >}}
\ No newline at end of file
diff --git a/content/influxdb3/cloud-dedicated/admin/tables/create.md b/content/influxdb3/cloud-dedicated/admin/tables/create.md
index 120ec35ca..4d15fdf71 100644
--- a/content/influxdb3/cloud-dedicated/admin/tables/create.md
+++ b/content/influxdb3/cloud-dedicated/admin/tables/create.md
@@ -1,17 +1,28 @@
---
title: Create a table
description: >
- Use the Admin UI or the [`influxctl table create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/)
- to create a new table in a specified database your InfluxDB cluster.
- Provide the database name and a table name.
+ Use the Admin UI, the [`influxctl table create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/), or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
+ for {{< product-name >}} to create a new table in a specified database your InfluxDB cluster.
+ Create a table with the same partitioning as the database or with a custom partition template.
menu:
influxdb3_cloud_dedicated:
parent: Manage tables
weight: 201
list_code_example: |
- ```sh
+
+ ##### CLI
+ ```bash
influxctl table create
```
+
+
+ ##### API
+ ```bash
+ curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/DATABASE_NAME/tables/" \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{ "name": "TABLE_NAME" }'
+ ```
related:
- /influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/
- /influxdb3/cloud-dedicated/admin/custom-partitions/
@@ -25,26 +36,165 @@ With {{< product-name >}}, tables and measurements are synonymous.
Typically, tables are created automatically on write using the measurement name
specified in line protocol written to InfluxDB.
However, to apply a [custom partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/)
-to a table, you must manually create the table before you write any data to it.
+to a table, you must manually [create the table with custom partitioning](#create-a-table-with-custom-partitioning) before you write any data to it.
-1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
-2. Run the `influxctl table create` command and provide the following:
+Partitioning defaults to `%Y-%m-%d` (daily).
+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.
- - _Optional_: [InfluxDB tags](/influxdb3/cloud-dedicated/reference/glossary/#tag)
- to use in the partition template
- - _Optional_: [InfluxDB tag buckets](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates)
- to use in the partition template
- - _Optional_: A supported [Rust strftime date and time string](/influxdb3/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
+- [Create a table](#create-a-table)
+- [Create a table with custom partitioning](#create-a-table-with-custom-partitioning)
+- [Partition template requirements and guidelines](#partition-template-requirements-and-guidelines)
- > [!Note]
- > _{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
+## Create a table
+
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[Admin UI](#)
+[influxctl](#)
+[Management API](#)
+{{% /tabs %}}
+{{% tab-content %}}
+
+The InfluxDB Cloud Dedicated administrative UI includes a portal for creating
+and managing tables.
+
+1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
+
+
+ https://console.influxdata.com
+
+2. Use the credentials provided by InfluxData to log into the Admin UI.
+ If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com).
+3. In the cluster list, find and click the cluster you want to create a database in. You
+ can sort on column headers or use the **Search** field to find a specific cluster.
+4. In the database list, find and click the database you want to create a table in. You
+ can sort on column headers or use the **Search** field to find a specific database.
+4. Click the **New Table** button above the table list.
+ The **Create table** dialog displays.
+5. In the **Create table** dialog, provide a **Table name**.
+6. Toggle **Use default partitioning** to **On**
+7. Click the **Create Table** button.
+{{% /tab-content %}}
+
+{{% tab-content %}}
+
+1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
+2. Run the `influxctl table create` command:
{{% code-placeholders "(DATABASE|TABLE)_NAME" %}}
-```sh
+```bash
+# Create a table with the same partitioning as the database
+influxctl table create \
+ DATABASE_NAME \
+ TABLE_NAME
+```
+{{% /code-placeholders %}}
+
+Replace:
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the database to create the table in
+- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name for your new table
+{{% /tab-content %}}
+
+{{% tab-content %}}
+
+_This example uses [cURL](https://curl.se/) to send a Management HTTP API request, but you can use any HTTP client._
+
+1. If you haven't already, follow the instructions to [install cURL](https://everything.curl.dev/install/index.html) for your system.
+2. In your terminal, use cURL to send a request to the following {{% product-name %}} endpoint:
+
+{{% api-endpoint method="POST"
+endpoint="https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/DATABASE_NAME/tables"
+api-ref="/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabaseTable" %}}
+
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|DATABASE_NAME|TABLE_NAME|MANAGEMENT_TOKEN" %}}
+```bash
+# Create a table with the same partitioning as the database
+curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/DATABASE_NAME/tables" \
+ --request POST \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "TABLE_NAME"
+ }'
+```
+{{% /code-placeholders %}}
+
+Replace the following:
+
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the account ID for the cluster
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the cluster ID
+- {{% code-placeholder-key %}}`MANAGEMENT_TOKEN`{{% /code-placeholder-key %}}: a valid management token
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the database to create the table in
+- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name for your new table
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
+## Create a table with custom partitioning
+
+{{< product-name >}} lets you define a [custom partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) strategy for each database and table.
+A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
+By default, data is partitioned by day,
+but, depending on your schema and workload, customizing the partitioning
+strategy can improve query performance.
+
+To use custom partitioning, you define a [partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
+If a table doesn't have a custom partition template, it inherits the database's template.
+
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[Admin UI](#)
+[influxctl](#)
+[Management API](#)
+{{% /tabs %}}
+{{% tab-content %}}
+
+1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
+
+
+ https://console.influxdata.com
+
+2. Use the credentials provided by InfluxData to log into the Admin UI.
+ If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com).
+3. In the cluster list, find and click the cluster you want to create a database in. You
+ can sort on column headers or use the **Search** field to find a specific cluster.
+4. In the database list, find and click the database you want to create a table in. You
+ can sort on column headers or use the **Search** field to find a specific database.
+4. Click the **New Table** button above the table list.
+ The **Create table** dialog displays.
+ 
+5. In the **Create table** dialog, provide a **Table name**.
+6. Make sure the **Use default partitioning** toggle is set to **Off**
+7. Provide the following:
+
+ - **Custom partition template time format**: The time part for partitioning data.
+ - _Optional_: **Custom partition template tag parts**: The tag parts for partitioning data.
+ - _Optional_: **Custom partition template tag bucket parts**: The tag bucket parts for partitioning data.
+8. _Optional_: To add more parts to the partition template, click the **Add Tag** button.
+9. Click the **Create Table** button to create the table.
+ The new table displays in the list of tables for the cluster.
+{{% /tab-content %}}
+
+{{% tab-content %}}
+
+1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/get-started/setup/#download-install-and-configure-the-influxctl-cli).
+2. Use the following `influxctl table create` command flags to specify the
+[partition template parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates):
+
+ - `--template-timeformat`: A [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates)
+ string that specifies the time part in the partition template and determines
+ the time interval to partition by.
+ - `--template-tag`: An [InfluxDB tag]
+ to use in the partition template.
+ - `--template-tag-bucket`: An [InfluxDB tag](/influxdb3/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`.
+
+{{% code-placeholders "DATABASE_NAME|30d|(TAG_KEY(_\d)?)|100|300" %}}
+```bash
+# Create a table with custom partitioning
influxctl table create \
--template-tag tag1 \
--template-tag tag2 \
@@ -56,22 +206,72 @@ influxctl table create \
```
{{% /code-placeholders %}}
-### Custom partitioning
+Replace the following:
-{{< product-name >}} lets you define a custom partitioning strategy for each table.
-A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/)
-format in the InfluxDB 3 storage engine. By default, data is partitioned by day,
-but, depending on your schema and workload, customizing the partitioning
-strategy can improve query performance.
+- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys to partition by
+- {{% code-placeholder-key %}}`TAG_KEY_3`, `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys for bucketed partitioning
+- {{% code-placeholder-key %}}`100`, `300`{{% /code-placeholder-key %}}: number of buckets to group tag values into
+- {{% code-placeholder-key %}}`'%Y-%m-%d'`{{% /code-placeholder-key %}}: [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) string that specifies the time part in the partition template
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/cloud-dedicated/admin/databases/) to create the table in
+- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name you want for the new table
+{{% /tab-content %}}
-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](/influxdb3/cloud-dedicated/admin/custom-partitions/).
+{{% tab-content %}}
+
+_This example uses [cURL](https://curl.se/) to send a Management HTTP API request, but you can use any HTTP client._
+
+1. If you haven't already, follow the instructions to [install cURL](https://everything.curl.dev/install/index.html) for your system.
+2. In your terminal, use cURL to send a request to the following {{% product-name %}} endpoint:
+
+{{% api-endpoint method="POST"
+endpoint="https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/DATABASE_NAME/tables"
+api-ref="/influxdb3/cloud-dedicated/api/management/#operation/CreateClusterDatabaseTable" %}}
+
+In the request body, include the `partitionTemplate` property and specify the [partition template parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates) as an array of objects--for example:
+
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|DATABASE_NAME|MANAGEMENT_TOKEN|TABLE_NAME|(TAG_KEY(_\d)?)|100|300|%Y-%m-%d" %}}
+```bash
+# Create a table with custom partitioning
+curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/DATABASE_NAME/tables" \
+ --request POST \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "TABLE_NAME",
+ "partitionTemplate": [
+ { "type": "tag", "value": "TAG_KEY_1" },
+ { "type": "tag", "value": "TAG_KEY_2" },
+ { "type": "bucket", "value": { "tagName": "TAG_KEY_3", "numberOfBuckets": 100 } },
+ { "type": "bucket", "value": { "tagName": "TAG_KEY_4", "numberOfBuckets": 300 } },
+ { "type": "time", "value": "%Y-%m-%d" }
+ ]
+ }'
+```
+{{% /code-placeholders %}}
+
+Replace the following:
+
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the [account](/influxdb3/cloud-dedicated/admin/account/) ID for the cluster _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the [cluster](/influxdb3/cloud-dedicated/admin/clusters/) ID _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
+- {{% code-placeholder-key %}}`MANAGEMENT_TOKEN`{{% /code-placeholder-key %}}: a valid [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/cloud-dedicated/admin/databases/) to create the table in
+- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name you want for the new table
+- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys to partition by
+- {{% code-placeholder-key %}}`TAG_KEY_3`, `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb3/cloud-dedicated/reference/glossary/#tag) keys for bucketed partitioning
+- {{% code-placeholder-key %}}`100`, `300`{{% /code-placeholder-key %}}: number of buckets to group tag values into
+- {{% code-placeholder-key %}}`'%Y-%m-%d'`{{% /code-placeholder-key %}}: [Rust strftime date and time](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) string that specifies the time part in the partition template
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
+## Partition template requirements and guidelines
+
+Always specify 1 time part in your template.
+A template has a maximum of 8 parts: 1 time part and up to 7 total tag and tag bucket parts.
+
+For more information about partition template requirements and restrictions, see [Partition templates](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
> [!Warning]
> #### Partition templates can only be applied on create
->
+>
> You can only apply a partition template when creating a table.
-> There is no way to update a partition template on an existing table.
+> You can't update a partition template on an existing table.
diff --git a/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md b/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md
index c09edf5da..16761a292 100644
--- a/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md
+++ b/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md
@@ -1,4 +1,4 @@
-Use the [`influxctl` CLI](/influxdb/version/reference/cli/influxctl/)
+Use the Admin UI, the [`influxctl` CLI](/influxdb/version/reference/cli/influxctl/), or the [Management HTTP API](/influxdb/version/api/management/)
to define custom partition strategies when creating a database or table.
By default, {{< product-name >}} partitions data by day.
@@ -12,52 +12,27 @@ table.
- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template)
- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template)
+- [Partition template requirements and guidelines](#partition-template-requirements-and-guidelines)
- [Example partition templates](#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](/influxdb/version/admin/custom-partitions/partition-templates/#tag-part-templates):
-
-- `--template-tag`: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag)
- to use in the partition template.
-- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/version/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/version/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.
->
-> _View [partition template part restrictions](/influxdb/version/admin/custom-partitions/partition-templates/#restrictions)._
-
-> [!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-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
+The following examples show how to create a new `example-db` database and apply 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`:
-
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[influxctl](#)
+[Management API](#)
+{{% /tabs %}}
+
+{{% tab-content %}}
+
+
-```sh
+```bash
influxctl database create \
--template-tag room \
--template-tag sensor-type \
@@ -66,33 +41,156 @@ influxctl database create \
example-db
```
+The following command flags identify
+[partition template parts](/influxdb/version/admin/custom-partitions/partition-templates/#tag-part-templates):
+
+- `--template-timeformat`: A [Rust strftime date and time](/influxdb/version/admin/custom-partitions/partition-templates/#time-part-templates)
+ string that specifies the time part in the partition template and determines
+ the time interval to partition by.
+- `--template-tag`: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag)
+ to use in the partition template.
+- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/version/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`.
+
+
+{{% /tab-content %}}
+{{% tab-content %}}
+
+
+
+
+
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|MANAGEMENT_TOKEN" %}}
+```bash
+curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "example-db",
+ "maxTables": 500,
+ "maxColumnsPerTable": 250,
+ "retentionPeriod": 2592000000000,
+ "partitionTemplate": [
+ { "type": "tag", "value": "room" },
+ { "type": "tag", "value": "sensor-type" },
+ { "type": "bucket", "value": { "tagName": "customerID", "numberOfBuckets": 500 } },
+ { "type": "time", "value": "%Y-%m-%d" }
+ ]
+ }'
+```
+{{% /code-placeholders %}}
+
+Replace the following in your request:
+
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the [account](/influxdb3/cloud-dedicated/admin/account/) ID for the cluster _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the [cluster](/influxdb3/cloud-dedicated/admin/clusters/) ID _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
+- {{% code-placeholder-key %}}`MANAGEMENT TOKEN`{{% /code-placeholder-key %}}: a valid [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
+
+The `partitionTemplate` property in the request body
+is an array of JSON objects that identify the [partition template parts](/influxdb/version/admin/custom-partitions/partition-templates/#tag-part-templates).
+
+
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
## 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
+The following example creates a new `example-table` table in the `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 month using the time format `%Y-%m`:
-
-
+{{< tabs-wrapper >}}
+{{% tabs %}}
+[Admin UI](#)
+[influxctl](#)
+[Management API](#)
+{{% /tabs %}}
+{{% tab-content %}}
+
+The {{< product-name >}} Admin UI lets you apply a custom partition template when creating a table.
+1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
-{{% code-placeholders "DATABASE_NAME" %}}
+
+ https://console.influxdata.com
+
+2. In the cluster list, click the cluster you want to manage.
+3. Create the `example-db` database or click the row of an existing database.
+4. Click the **New Table** button above the table list.
-```sh
+In the **Create Table** dialog:
+
+1. Set **Table name** to `example-table`.
+2. If the **Use default partitioning** toggle is on, turn it off to enable custom partitioning.
+3. Under **Custom partition template time format**, set the time format to `%Y-%m`.
+4. Under **Custom partition template parts**:
+5. In the **Partition template part type** dropdown, click **Tag**, set **Tag name** to `room`.
+6. Click **Add Tag**.
+7. In the **Partition template part type** dropdown, click **Tag**, set **Tag name** to `sensor-type`.
+8. Click **Add Tag**.
+9. In the **Partition template part type** dropdown, click **Bucket**, set **Tag name** to `customerID` and **Buckets** to `500`.
+10. Click **Create Table** to apply the template.
+
+{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-custom-partitioned-table.png" alt="Create table dialog with custom partitioning example values" />}}
+{{% /tab-content %}}
+{{% tab-content %}}
+
+```bash
influxctl table create \
--template-tag room \
--template-tag sensor-type \
--template-tag-bucket customerID,500 \
--template-timeformat '%Y-%m' \
- DATABASE_NAME \
+ example-db \
example-table
```
+
+{{% /tab-content %}}
+{{% tab-content %}}
+
+
+{{% code-placeholders "ACCOUNT_ID|CLUSTER_ID|MANAGEMENT_TOKEN" %}}
+```bash
+curl \
+ --location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases/example-db/tables" \
+ --request POST \
+ --header "Authorization: Bearer MANAGEMENT_TOKEN" \
+ --json '{
+ "name": "example-table",
+ "partitionTemplate": [
+ { "type": "tag", "value": "room" },
+ { "type": "tag", "value": "sensor-type" },
+ { "type": "bucket", "value": { "tagName": "customerID", "numberOfBuckets": 500 } },
+ { "type": "time", "value": "%Y-%m" }
+ ]
+ }'
+```
{{% /code-placeholders %}}
-Replace the following in your command:
+Replace the following in your request:
-- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/version/admin/databases/)
+- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: the [account](/influxdb3/cloud-dedicated/admin/account/) ID for the cluster _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_
+- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the [cluster](/influxdb3/cloud-dedicated/admin/clusters/) ID _(list details via the [Admin UI](/influxdb3/cloud-dedicated/admin/clusters/list/) or [CLI](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json))_.
+- {{% code-placeholder-key %}}`MANAGEMENT_TOKEN`{{% /code-placeholder-key %}}: a valid [management token](/influxdb3/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster
+
+
+{{% /tab-content %}}
+{{< /tabs-wrapper >}}
+
+## Partition template requirements and guidelines
+
+Always specify 1 time part in your template.
+A template has a maximum of 8 parts: 1 time part and up to 7 total tag and tag bucket parts.
+
+For more information about partition template requirements and restrictions, see [Partition templates](/influxdb/version/admin/custom-partitions/partition-templates/).
+
+> [!Warning]
+> #### Partition templates can only be applied on create
+>
+> You can only apply a partition template when creating a database.
+> You can't update a partition template on an existing database.
+- [Template part types](#template-part-types)
+- [Requirements and guidelines](#requirements-and-guidelines)
- [Restrictions](#restrictions)
- [Template part size limit](#template-part-size-limit)
+ - [Partition key size limit](#partition-key-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)
+
+## Template part types
+
+InfluxDB supports three types of partition template parts:
+
+- **Tag part**: Partitions data by the unique values of an [InfluxDB tag](/influxdb/version/reference/glossary/#tag).
+ For example, using `region` as a tag part creates separate partitions for each region value (us-west, us-east, eu-central).
+
+- **Tag bucket part**: Partitions data by "buckets" of [InfluxDB tag](/influxdb/version/reference/glossary/#tag) values.
+ Instead of creating a partition for every unique tag value, tag values are hashed and grouped into a specified number of buckets.
+ Use this for high-cardinality tags or when the number of distinct values is unknown.
+
+- {{< req type="key" >}} **Time part**: Partitions data by time intervals using a Rust strftime date and time format string.
+ The smallest time unit in your format determines the granularity of time partitioning (yearly with `%Y`,
+ monthly with `%Y-%m`, or daily with `%Y-%m-%d`).
+
+## Requirements and guidelines
+
+When creating a partition template:
+
+1. **Include exactly one time part**
+ - Always specify a [time part](#time-part-templates) in your template
+ - With `influxctl`, always include `--template-timeformat` with a valid format
+ - Without a time part, InfluxDB won't compact partitions, impacting performance
+ - If you include more than one time part, InfluxDB uses the smallest unit of time
+
+2. **Tag and tag bucket limitations**
+ - Include up to seven [tag](#tag-part-templates) and [tag bucket](#tag-bucket-part-templates) parts
+ - Don't use the same tag key in both a tag part and a tag bucket part--for example,
+ if your template uses `region` as a tag part, you cannot use `region` as a tag bucket part
+
+3. **Maximum template parts**: 8 total (1 time part + up to 7 tag and tag bucket parts)
## Restrictions
@@ -59,18 +80,17 @@ characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Gl
## Tag part templates
-Tag part templates consist of a _tag key_ to partition by.
+Tag part templates consist of a [_tag key_](/influxdb3/cloud-dedicated/reference/glossary/#tag) to partition by.
Generated partition keys include the unique _tag value_ specific to each partition.
A partition template may include a given tag key only once in template parts
-that operate on tags (tag value and tag bucket)--for example:
-
-If a template partitions on unique values of `tag_A`, then
+that operate on tags (tag value and tag bucket)--for example,
+if a template partitions on unique values of `tag_A`, then
you can't use `tag_A` as a tag bucket part.
## Tag bucket part templates
-Tag bucket part templates consist of a _tag key_ to partition by and the
+Tag bucket part templates consist of a [_tag key_](/influxdb3/cloud-dedicated/reference/glossary/#tag) to partition by and the
_number of "buckets" to partition tag values into_--for example:
```
@@ -95,9 +115,8 @@ each partition.
> unknown number of distinct values.
A partition template may include a given tag key only once in template parts
-that operate on tags (tag value and tag bucket)--for example:
-
-If a template partitions on unique values of `tag_A`, then
+that operate on tags (tag value and tag bucket)--for example,
+if a template partitions on unique values of `tag_A`, then
you can't use `tag_A` as a tag bucket part.
## Time part templates
diff --git a/static/img/influxdb3/cloud-dedicated-admin-ui-create-custom-partitioned-table.png b/static/img/influxdb3/cloud-dedicated-admin-ui-create-custom-partitioned-table.png
new file mode 100644
index 000000000..d644a58ba
Binary files /dev/null and b/static/img/influxdb3/cloud-dedicated-admin-ui-create-custom-partitioned-table.png differ