Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #6047 from influxdata/staging/6023-admin-ui-docs-for-cloud-dedicated 

feat(dedicated): Admin UI: Add create table, revise create database a…
pull/6049/head
Jason Stirnaman 2025-05-09 10:42:45 -05:00 committed by GitHub
parent 24bdf290ce 815514c53b
commit 01167ecb77
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 695 additions and 399 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
api-docs/influxdb3/cloud-dedicated/management/openapi.yml
View File

@ -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 table. 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:

3
content/influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md
View File

@ -14,5 +14,6 @@ source: /shared/v3-distributed-admin-custom-partitions/define-custom-partitions.
---
<!--
The content of this page is at /content/shared/v3-distributed-admin-custom-partitions/_define-custom-partitions.md
The content of this page is at
//SOURCE - content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md
-->

499
content/influxdb3/cloud-dedicated/admin/databases/create.md
View File

@ -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: |
<!--pytest.mark.skip-->
##### CLI
```sh
```bash
influxctl database create \
--retention-period 30d \
--max-tables 500 \
--max-columns 250 \
DATABASE_NAME
```
<!--pytest.mark.skip-->
##### 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,126 @@ or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to crea
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
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
<pre>
<a href="https://console.influxdata.com">https://console.influxdata.com</a>
</pre>
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 above the database list.
The **Create Database** dialog displays.
<img src="/img/influxdb3/cloud-dedicated-admin-ui-create-database.png" alt="Create database dialog" />
6. In the **Create Database** dialog, provide the following information:
<img src="/img/influxdb3/cloud-dedicated-admin-ui-create-database.png" alt="Create database dialog" />
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 %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
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._
<!--Skip tests for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{% 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 %}}
<!------------------------------- BEGIN MANAGEMENT API ----------------------->
_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 %}}
<!------------------------------- BEGIN INFLUXCTL CUSTOM ------------------->
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.
Use one of the following:
- `%Y-%m-%d` (daily)
- `%Y-%m` (monthly)
- `%Y` (annually)
- `--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 +180,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/).
<!-------------------------------- END INFLUXCTL ------------------------------>
- {{% 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 %}}
<!------------------------------- BEGIN cURL ---------------------------------->
<!------------------------------- BEGIN MANAGEMENT API --------------->
_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:
<!--Skip tests for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{% 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 (`<int32>`) 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/).
<!------------------------------- END cURL ------------------------------------>
{{% /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 +319,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 +359,13 @@ cluster in the following ways:
{{< expand-wrapper >}}
{{% expand "**May improve query performance** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
{{% expand "**More PUTs into object storage** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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 +373,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** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
{{% expand "**More work for the compactor** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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 +394,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 +401,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 >}}

269
content/influxdb3/cloud-dedicated/admin/tables/create.md
View File

@ -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
<!--pytest.mark.skip-->
##### CLI
```bash
influxctl table create <DATABASE_NAME> <TABLE_NAME>
```
<!--pytest.mark.skip-->
##### 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,170 @@ 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 %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
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:
<pre>
<a href="https://console.influxdata.com">https://console.influxdata.com</a>
</pre>
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 %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
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 %}}
<!------------------------------- BEGIN MANAGEMENT API ------------------------------>
_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 %}}
<!------------------------------- BEGIN ADMIN UI CUSTOM ------------------------------>
1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://console.influxdata.com">https://console.influxdata.com</a>
</pre>
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.
<img src="/img/influxdb3/cloud-dedicated-admin-ui-create-table.png" alt="Create table dialog" />
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 %}}
<!------------------------------- BEGIN INFLUXCTL CUSTOM ----------------------------->
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.
Use one of the following:
- `%Y-%m-%d` (daily)
- `%Y-%m` (monthly)
- `%Y` (annually)
- `--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 +211,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 %}}
<!------------------------------- BEGIN MANAGEMENT API CUSTOM ------------------------------>
_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.

200
content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md
View File

@ -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`:
<!--Skip database create and delete tests: namespaces aren't reusable-->
{{< tabs-wrapper >}}
{{% tabs %}}
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
<!--Skip tests for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
```sh
```bash
influxctl database create \
--template-tag room \
--template-tag sensor-type \
@ -66,33 +41,161 @@ 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.
Use one of the following:
- `%Y-%m-%d` (daily)
- `%Y-%m` (monthly)
- `%Y` (annually)
- `--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`.
<!-------------------------------- END INFLUXCTL ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN cURL ---------------------------------->
<!--Skip tests for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{% 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).
<!------------------------------- END cURL ------------------------------------>
{{% /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`:
<!--Skip database create and delete tests: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------BEGIN ADMIN UI ------------------------------>
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" %}}
<pre>
<a href="https://console.influxdata.com">https://console.influxdata.com</a>
</pre>
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 %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
```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
```
<!-------------------------------- END INFLUXCTL ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN cURL ---------------------------------->
{{% 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
<!------------------------------- END cURL ------------------------------------>
{{% /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.
<!--actual test
@ -131,6 +234,9 @@ with a `2024-01-01T00:00:00Z` timestamp:
prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000
```
The following tables show how the partition key is generated
based on the partition template parts you provide.
##### Partitioning by distinct tag values
| Description | Tag parts | Time part | Resulting partition key |

74
content/shared/v3-distributed-admin-custom-partitions/partition-templates.md
View File

@ -2,31 +2,57 @@ Use partition templates to define the patterns used to generate partition keys.
A partition key uniquely identifies a partition and is used to name the partition
Parquet file in the [Object store](/influxdb/version/reference/internals/storage-engine/#object-store).
A partition template consists of 1-8 _template parts_---dimensions to partition data by.
Three types of template parts exist:
A partition template defines how InfluxDB groups data into partitions by specifying 1-8 _template parts_.
Each template part represents a dimension to partition data by.
- **tag**: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag)
to partition by.
- **tag bucket**: An [InfluxDB tag](/influxdb/version/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.
- {{< req type="key" >}} **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.
> [!Note]
> A partition template must include 1 [time part](#time-part-templates)
> and can include up to 7 total [tag](#tag-part-templates) and [tag bucket](#tag-bucket-part-templates) parts.
<!-- TOC -->
- [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)
<!-- /TOC -->
- [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
- Use one of the following Rust strftime date and time strings:
- `%Y-%m-%d` (daily)
- `%Y-%m` (monthly)
- `%Y` (annually)
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 +85,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 +120,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

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-create-custom-partitioned-table.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 243 KiB