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

Merge branch 'master' into 5949-add-api-reference-examples-to-influxdb3

pull/6002/head
Jameelah Mercer 2025-05-12 11:44:59 -07:00 committed by GitHub
parent 5ee9686efb 16e141c068
commit 8988fb6fb3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
54 changed files with 2015 additions and 918 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/copilot-instructions.md vendored
View File

@ -103,11 +103,13 @@ GitHub Copilot should help document InfluxData products by creating clear, accur
product_version:
weight: # Page order (1-99, 101-199, etc.)
```
- Follow the shortcode documentation in `CONTRIBUTING.md`
- Follow the shortcode examples in `content/example.md` and the documentation
for docs-v2 contributors in `CONTRIBUTING.md`
- Use provided shortcodes correctly:
- Notes/warnings: `{{% note %}}`, `{{% warn %}}`
- Product-specific: `{{% enterprise %}}`, `{{% cloud %}}`
- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}`
- Tabbed content for code examples (without additional text): `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}`
- Version links: `{{< latest >}}`, `{{< latest-patch >}}`
- API endpoints: `{{< api-endpoint >}}`
- Required elements: `{{< req >}}`

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:

2
content/influxdb3/cloud-dedicated/_index.md
View File

@ -18,7 +18,7 @@ The InfluxDB time series platform is designed to handle high write and query loa
Learn how to use and leverage InfluxDB Cloud Dedicated for your specific
time series use case.
<a class="btn" href="{{< cta-link >}}">Request an InfluxDB Cloud Dedicated cluster</a>
<a class="btn" href="{{< cta-link >}}">Run an {{% product-name %}} proof of concept (PoC)</a>
<a class="btn" href="/influxdb3/cloud-dedicated/get-started/">Get started with InfluxDB Cloud Dedicated</a>
## InfluxDB 3

43
content/influxdb3/cloud-dedicated/admin/account/_index.md Normal file
View File

@ -0,0 +1,43 @@
---
title: View account information
seotitle: View {{% product-name %}} account information
description: >
Use the Admin UI for {{% product-name %}} to view information for your {{% product-name omit="InfluxDB " %}} account.
Your {{% product-name %}} account is a collection of {{% product-name omit="Clustered "%}} clusters and associated resources.
menu:
influxdb3_cloud_dedicated:
parent: Administer InfluxDB Cloud
weight: 99
influxdb3/cloud-dedicated/tags: [clusters]
---
Use the Admin UI for {{% product-name %}} to view information for your {{% product-name omit="InfluxDB " %}} account.
Your {{% product-name %}} account is a collection of {{% product-name omit="Clustered "%}} clusters and associated resources.
- [Access the Admin UI](#access-the-admin-ui)
- [View account information](#view-account-information)
- [View cluster information](#view-cluster-information)
- [Access operational dashboards](#access-operational-dashboards)
- [Administer management tokens](#administer-management-tokens)
## Access the Admin UI
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).
## View account information
After you log in to the Admin UI, the Account Management portal displays the following information about your account:
- Account ID
- Contract status
- Contract start date
- The [list of clusters](/influxdb3/cloud-dedicated/admin/clusters/list/?t=admin-ui) associated with the account
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-account-info.png" alt="InfluxDB Cloud Dedicated Admin UI account information" />}}

55
content/influxdb3/cloud-dedicated/admin/clusters/get.md
View File

@ -1,7 +1,7 @@
---
title: Get cluster information
description: >
Use the
Use the Admin UI or the
[`influxctl cluster get <CLUSTER_ID>` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/cluster/get/) to view information about your InfluxDB Cloud Dedicated cluster.
menu:
influxdb3_cloud_dedicated:
@ -13,8 +13,55 @@ list_code_example: |
```
---
Use the [`influxctl cluster get` CLI command](/influxdb3/cloud-dedicated/reference/cli/influxctl/get/)
to view information about your {{< product-name omit=" Clustered" >}} cluster.
Use the Admin UI or the [`influxctl cluster get` CLI command](/influxdb3/cloud-dedicated/reference/cli/influxctl/get/) to view information about your
{{< product-name omit=" Clustered" >}} cluster, including:
- Cluster ID
- Cluster name
- Cluster URL
- Cluster status
- Cluster size (standard or custom)
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
{{% /tabs %}}
{{% tab-content %}}
## Access the Cloud Dedicated Admin UI
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).
After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and lists all clusters associated with your account.
3. **Search** for the cluster or use the sort button and column headers to sort the cluster list and find the cluster.
### View cluster details
The cluster list displays the following cluster details:
- Cluster ID and name
- Status (ready, provisioning, etc.)
- Size (standard or custom)
- URL endpoint
### Cluster management tools
The options button (3 vertical dots) to the right of any cluster provides additional tools for cluster management:
- Copy Cluster ID
- Copy Cluster URL
- Observe in Grafana _(only if your cluster has enabled operational dashboards. For more information, see how to [monitor your cluster](/influxdb3/cloud-dedicated/admin/monitor-your-cluster/).)_
{{% /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), and then [configure a connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster.
2. Run `influxctl cluster get` with the following:
@ -74,3 +121,5 @@ The output is the cluster as a JSON object that includes additional fields such
"category": 1
}
```
{{% /tab-content %}}
{{< /tabs-wrapper >}}

44
content/influxdb3/cloud-dedicated/admin/clusters/list.md
View File

@ -1,7 +1,7 @@
---
title: List clusters
description: >
Use the [`influxctl cluster list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/cluster/list/)
Use the Admin UI or the [`influxctl cluster list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/cluster/list/)
to view information about InfluxDB Cloud Dedicated clusters associated with your account ID.
menu:
influxdb3_cloud_dedicated:
@ -15,10 +15,45 @@ aliases:
- /influxdb3/cloud-dedicated/admin/clusters/list/
---
Use the [`influxctl cluster list` CLI command](/influxdb3/cloud-dedicated/reference/cli/influxctl/list/)
view information about all {{< product-name omit=" Clustered" >}} clusters associated with your account ID.
Use the Admin UI or the [`influxctl cluster list` CLI command](/influxdb3/cloud-dedicated/reference/cli/influxctl/list/)
to view information about all {{< product-name omit=" Clustered" >}} clusters associated with your account ID.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
{{% /tabs %}}
{{% tab-content %}}
## Access the Cloud Dedicated Admin UI
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).
After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and lists all clusters associated with your account.
3. You can **Search** clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
### View cluster details
The cluster list displays the following cluster details:
- Cluster ID and name
- Status (ready, provisioning, etc.)
- Size (standard or custom)
- URL endpoint
{{% /tab-content %}}
{{% tab-content %}}
## Use the CLI
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 a connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster.
2. Run `influxctl cluster list` with the following:
- _Optional_: [Output format](#output-formats)
@ -69,3 +104,6 @@ The output is a JSON array of cluster objects that include additional fields suc
}
]
```
{{% /tab-content %}}
{{< /tabs-wrapper >}}

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
-->

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

@ -1,10 +1,10 @@
---
title: Create a database
description: >
Use the [`influxctl database create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/)
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/
@ -70,8 +32,116 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/)
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 %}}
[Admin UI](#)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
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 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 **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" />
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](#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.
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 ----------------------------->
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:
{{% 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 %}}
@ -79,41 +149,30 @@ or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to crea
[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):
<!------------------------------- 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.
- `--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`.
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. 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|(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 \
@ -121,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:
@ -365,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
@ -407,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
@ -423,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 >}}
@ -446,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.
@ -454,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 >}}

27
content/influxdb3/cloud-dedicated/admin/databases/delete.md
View File

@ -1,7 +1,7 @@
---
title: Delete a database
description: >
Use the [`influxctl database delete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete/)
Use the Admin UI, the [`influxctl database delete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to delete a database from your InfluxDB Cloud Dedicated cluster.
Provide the name of the database you want to delete.
@ -28,7 +28,7 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/)
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to delete a database from your {{< product-name omit=" Clustered" >}} cluster.
@ -47,10 +47,33 @@ to delete a database from your {{< product-name omit=" Clustered" >}} cluster.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
The InfluxDB Cloud Dedicated administrative UI includes a portal for
managing databases.
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 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 options button (three vertical dots) to the right of the token you want to revoke.
The options menu displays.
5. In the options menu, click **Delete Database**. The **Delete Database** dialog displays.
6. In the **Delete Database** dialog, check the box to confirm that you "understand the risk of this action".
7. Click the **Delete Database** button to delete the database.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-delete-database.png" alt="Create database dialog" />}}
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->

48
content/influxdb3/cloud-dedicated/admin/databases/list.md
View File

@ -1,7 +1,7 @@
---
title: List databases
description: >
Use the [`influxctl database list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list/)
Use the Admin UI, the [`influxctl database list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list/), or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to list databases in your InfluxDB Cloud Dedicated cluster.
menu:
influxdb3_cloud_dedicated:
@ -25,15 +25,57 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/)
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to create a database in your {{< product-name omit=" Clustered" >}} cluster.
Use the Admin UI, the [`influxctl database list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to list databases in your {{< product-name omit=" Clustered" >}} cluster.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
## Access the Cloud Dedicated Admin UI
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).
After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and lists all clusters associated with your account.
3. You can **Search** for clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
4. Click the cluster row to view the list of databases associated with the cluster.
The database list displays the following database details:
- Name
- Database ID
- Max tables
- Max columns per table
- Retention period
You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-list-databases.png" alt="List databases" />}}
### Database management tools
The options button (3 vertical dots) to the right of any database provides additional tools:
- **Copy Database ID**: Copy the database ID to your clipboard
- **Set Retention Period**: Set the retention period for the database
- **Delete Database**: Delete the database
### Manage database tables
To view database details and manage database tables, click the database row in the list.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->

26
content/influxdb3/cloud-dedicated/admin/databases/update.md
View File

@ -1,7 +1,7 @@
---
title: Update a database
description: >
Use the [`influxctl database update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update/)
Use the Admin UI, the [`influxctl database update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to update attributes for a database in your InfluxDB Cloud Dedicated cluster.
Provide the database name and the attributes to update.
@ -38,15 +38,37 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/)
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to update attributes such as retention period, column limits, and table limits for a database in your {{< product-name omit=" Clustered" >}} cluster.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
The InfluxDB Cloud Dedicated administrative UI includes a portal for
managing databases.
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).
After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and lists all clusters associated with your account.
3. Click a cluster row to view the list of databases associated with the cluster. You can **Search** for clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
4. Find the database you want to update.
You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list.
5. To set the retention period, click the options button (3 vertical dots) to the right of the database.
6. In the options menu, click **Set Retention Period**.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
Use the [`influxctl database update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update/)

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

@ -1,23 +1,34 @@
---
title: Create a table
description: >
Use 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/
---
Use the [`influxctl table create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/)
Use the Admin UI or the [`influxctl table create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/)
to create a table in a specified database in your
{{< product-name omit=" Clustered" >}} cluster.
@ -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.

46
content/influxdb3/cloud-dedicated/admin/tables/list.md
View File

@ -1,7 +1,7 @@
---
title: List tables
description: >
Use the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database)
Use the Admin UI, the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database),
or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/cloud-dedicated/query-data/influxql/explore-schema/#list-measurements-in-a-database)
to list tables in a database.
menu:
@ -25,13 +25,53 @@ related:
- /influxdb3/cloud-dedicated/query-data/influxql/explore-schema/
---
Use the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database)
Use the Admin UI, the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database),
or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/cloud-dedicated/query-data/influxql/explore-schema/#list-measurements-in-a-database)
to list tables in a database.
> [!Note]
> With {{< product-name >}}, tables and measurements are synonymous.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#admin-ui)
[influxctl](#influxctl)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------>
The InfluxDB Cloud Dedicated administrative UI includes a portal for managing
tables. You can view the list of tables associated with a database and
their details, including:
- Name
- Table ID
- Table size (in bytes)
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).
After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and lists all clusters associated with your account.
3. In the cluster list, find the cluster that contains the database and table. You can **Search** for clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
4. Click the cluster row to view the list of databases associated with the cluster.
5. In the database list, find the database that contains the table. You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list.
6. Click the database row to view the list of tables associated with the database.
7. The table list displays the following table details:
- Name
- Table ID
- Table size (in bytes)
8. You can **Search** for tables by name or ID to filter the list and use the sort button and column headers to sort the list.
You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ------------------------------>
###### SQL
```sql
@ -78,3 +118,5 @@ Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to query
{{% /tab-content %}}
{{< /tabs-wrapper >}}

29
content/influxdb3/cloud-dedicated/admin/tokens/_index.md
View File

@ -16,34 +16,5 @@ aliases:
InfluxDB uses token authentication to authorize access to data in your
{{< product-name omit=" Clustered" >}} cluster.
There are two types of tokens:
- [Database tokens](#database-tokens)
- [Management tokens](#management-tokens)
#### Database tokens
Database tokens grant read and write permissions to one or more databases
and allows for actions like writing and querying data.
All read and write actions performed against time series data in your
{{< product-name omit=" Clustered" >}} cluster must be authorized using a database token.
#### Management tokens
Management tokens grant permission to perform administrative actions such as
managing users, databases, and database tokens.
Management tokens allow clients, such as the
[`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
to perform administrative actions.
> [!Note]
> #### Store secure tokens in a secret store
>
> Token strings are returned _only_ on token creation.
> We recommend storing database tokens in a **secure secret store**.
> For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os).
---
{{< children hlevel="h2" readmore=true hr=true >}}

37
content/influxdb3/cloud-dedicated/admin/tokens/database/create.md
View File

@ -1,7 +1,7 @@
---
title: Create a database token
description: >
Use the [`influxctl token create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/create/)
Use the Admin UI, the [`influxctl token create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/create/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to create a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) for reading and writing data in your InfluxDB Cloud Dedicated cluster.
Provide a token description and permissions for databases.
@ -52,16 +52,49 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/)
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 token](/influxdb3/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster.
{{< 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 database tokens.
1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://{{< influxdb/host >}}/">https://{{< influxdb/host >}}</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. After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and the list of clusters associated with your account.
4. Find the cluster that you want to create a database token for. You can **Search** clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
5. Click the row for the cluster.
6. Click the **Database Tokens** button in the upper right corner of the Cluster screen.
7. In the Database Tokens portal, click the **New Database Token** button.
The **Create Database Token** dialog displays.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-database-token.png" alt="Create database token dialog" />}}
8. Add a token description.
The description is used to identify the token in the list of tokens.
9. To create a token that expires, enable the **Expiration** toggle,
and then select the expiration date and time.
10. Set the token permissions:
- Select the database or **All Databases** for the permission
- Use the **Read** and **Write** buttons under **Actions** to toggle these permissions on or off for the selected database.
11. Click the **Create Token** button. The dialog displays the **Token secret** string and the description you provided.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
Use the [`influxctl token create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/create/)

43
content/influxdb3/cloud-dedicated/admin/tokens/database/list.md
View File

@ -1,7 +1,7 @@
---
title: List database tokens
description: >
Use the [`influxctl token list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/list/)
Use the Admin UI, the [`influxctl token list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/list/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to list database tokens in your InfluxDB Cloud Dedicated cluster.
menu:
@ -35,7 +35,7 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/)
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to list database tokens in your {{< product-name omit=" Clustered" >}} cluster.
@ -46,10 +46,49 @@ to list database tokens in your {{< product-name omit=" Clustered" >}} cluster.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#admin-ui-list-tokens)
[influxctl](#)
[Management API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN ADMIN UI ------------------------------->
The InfluxDB Cloud Dedicated administrative UI includes a portal for creating and managing database tokens.
Administrators can use this portal to:
- View token details
- Add read and write permissions for specific databases to a token
- Edit a token's existing read and write permissions for a database
- Create a database token
- Revoke a database token
1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://{{< influxdb/host >}}/">https://{{< influxdb/host >}}</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. After you log in, the Account Management screen displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and the list of clusters associated with your account.
4. Click the cluster row that you want to manage tokens for. You can **Search** clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
5. Click the **Database Tokens** button in the upper right corner of the Cluster screen.
The Database Tokens portal lists all database tokens associated with the cluster
and provides the following information about each token:
- Token ID
- Description
- Databases
- Status (Active or Revoked)
- Created At date
- Expires At date
You can **Search** tokens by description or ID to filter the list and use the sort button and column headers to sort the list.
{{% /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), and then [configure an `influxctl` connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster.2. In your terminal, run the `influxctl token list` command and provide the following:

42
content/influxdb3/cloud-dedicated/admin/tokens/database/revoke.md
View File

@ -1,9 +1,9 @@
---
title: Revoke a database token
description: >
Use the [`influxctl token revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/revoke/)
Use the Admin UI, the [`influxctl token revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/revoke/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to revoke a database token associated with your {{% product-name omit-" Clustered" %}}
to revoke a database token associated with your {{% product-name omit=" Clustered" %}}
cluster and remove all permissions associated with the token.
Provide the ID of the database token you want to revoke.
menu:
@ -39,10 +39,48 @@ to revoke a database token associated with your
{{< 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 database tokens.
Administrators can use this portal to:
- View token details
- Add read and write permissions for specific databases to a token
- Edit a token's existing read and write permissions for a database
- Create a database token
- Revoke a database token
1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://{{< influxdb/host >}}/">https://{{< influxdb/host >}}</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. After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and the [list of clusters](/influxdb3/cloud-dedicated/admin/clusters/list/) associated with your account.
4. Click the row for the cluster that contains the database you want to manage tokens for. You can **Search** clusters by name or ID to filter the list and use the sort button and column headers to sort the list.
5. Click the **Database Tokens** button in the upper right corner of the Cluster screen.
6. The Database Tokens portal displays the [list of database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/list/) associated with the cluster.
Use the sort and filter options above the list to find a specific token.
7. Click the **Options** button (three vertical dots) to the right of the token you want to revoke.
8. In the options menu, click **Revoke Token**.
The **Revoke Database Token** dialog displays.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-revoke-database-token.png" alt="Revoke database token dialog" />}}
9. Check the box to confirm that you understand the risk.
10. Click the **Revoke Token** button.
The token is revoked and filtered from the list of active tokens.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
Use the [`influxctl token revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/revoke/)

63
content/influxdb3/cloud-dedicated/admin/tokens/database/update.md
View File

@ -1,9 +1,9 @@
---
title: Update a database token
description: >
Use the [`influxctl token update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/update/)
Use the Admin UI, the [`influxctl token update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/update/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to update a database token's permissions in your InfluxDB Cloud Dedicated cluster.
to update a database token's permissions in your {{< product-name omit=" Clustered" >}} cluster.
menu:
influxdb3_cloud_dedicated:
parent: Database tokens
@ -52,17 +52,74 @@ related:
- /influxdb3/cloud-dedicated/reference/api/
---
Use the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/)
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/)
to update a database token's permissions {{< product-name omit=" Clustered" >}} cluster.
{{< 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 database tokens.
Through this portal, administrators can edit a token's permissions to:
- Add read and write permissions for specific databases
- Edit a token's existing read and write permissions for a database
### Open the Edit Database Token dialog
1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://{{< influxdb/host >}}/">https://{{< influxdb/host >}}</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. After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/)
and the [list of clusters](/influxdb3/cloud-dedicated/admin/clusters/list/) associated with your account.
Use the sort and filter options above the list to find a specific cluster.
4. Click the row for the cluster that contains the database you want to manage tokens for.
5. Click the **Database Tokens** button in the upper right corner of the Cluster screen.
6. The Database Tokens portal displays the [list of database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/list/) associated with the cluster.
Use the sort and filter options above the list to find a specific token.
7. Click the **Options** button (three vertical dots) to the right of the token you want to edit.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-database-token-options-menu.png" alt="Database token option menu" />}}
8. Click **Edit Token** in the dropdown menu. The **Edit Database Token** dialog displays.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-edit-database-token.png" alt="Edit Database Token dialog" />}}
9. In the **Edit Database Token** dialog, you can edit the token's **Description** and permissions.
### Edit token permissions
1. [Open the Edit Database Token dialog](#open-the-edit-database-token-dialog) for the database token.
The **Edit Database Token** dialog displays the token's existing permissions.
Each permission consists of:
- A database (specific database name or **All Databases**)
- Action permissions (Read and Write)
2. To change which database a permission applies to, click the **Database** dropdown and select a different database or **All Databases**.
3. To adjust the access level of the permission, use the **Read** and **Write** buttons under **Actions** to toggle these permissions on or off for the selected database.
### Add token permissions
1. [Open the Edit Database Token dialog](#open-the-edit-database-token-dialog) for the database token.
2. In the dialog, click **Add Permission**.
3. For the new permission, select a database from the dropdown.
4. Toggle the **Read** and **Write** buttons to set the access level.
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
Use the [`influxctl token update` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/update/)
to update a database token's permissions in your {{< product-name omit=" Clustered" >}} cluster.

40
content/influxdb3/cloud-dedicated/admin/tokens/management/create.md
View File

@ -1,7 +1,7 @@
---
title: Create a management token
description: >
Use the [`influxctl management create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create)
Use the Admin UI or the [`influxctl management create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create)
to manually create a management token.
menu:
influxdb3_cloud_dedicated:
@ -18,6 +18,8 @@ list_code_example: |
--description "Example token description"
```
---
Use the Admin UI or the [`influxctl management create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create)
to manually create a management token.
By default, management tokens are short-lived tokens issued by an OAuth2 identity
provider that grant a specific user administrative access to your
@ -37,6 +39,40 @@ interaction with your identity provider.
> and authorized through your OAuth2 identity provider to manually create a
> management token.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#admin-ui)
[influxctl](#influxctl)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------BEGIN ADMIN UI ------------------------------>
The InfluxDB Cloud Dedicated administrative UI includes a portal for creating
and managing management tokens.
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. Click the **Management Tokens** button in the upper right corner of the Account Management portal.
4. In the Management Tokens portal, click the **New Management Token** button.
The **Create Management Token** dialog displays.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-management-token.png" alt="Create management token dialog" />}}
5. You can optionally set the following fields:
- **Expiration date**: Set an expiration date for the token
- **Expiration time**: Set an expiration time for the token
- **Description**: Enter a description for the token
-
If an expiration isn't set, the token does not expire until revoked.
6. Click the **Create Token** button. The dialog displays the **Token secret** string and the description you provided.
{{% /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. Use the [`influxctl management create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create/)
to manually create a management token. Provide the following:
@ -61,6 +97,8 @@ Replace the following:
`{{< datetime/current-date offset=1 >}}`.
- {{% code-placeholder-key %}}`TOKEN_DESCRIPTION`{{% /code-placeholder-key %}}:
Management token description.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
Once created, the command returns the management token string.

41
content/influxdb3/cloud-dedicated/admin/tokens/management/list.md
View File

@ -1,7 +1,7 @@
---
title: List management tokens
description: >
Use the [`influxctl management list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/list/)
Use the Admin UI or the [`influxctl management list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/list/)
to list manually-created management tokens.
menu:
influxdb3_cloud_dedicated:
@ -17,9 +17,44 @@ list_code_example: |
```
---
Use the [`influxctl management list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/list)
Use the Admin UI or the [`influxctl management list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/list)
to list manually-created management tokens.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#admin-ui)
[influxctl](#influxctl)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------BEGIN ADMIN UI------------------------------>
The InfluxDB Cloud Dedicated administrative UI includes a portal for creating
and managing management tokens.
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. To list management tokens, click the **Management Tokens** button in the upper right corner of the Account Management portal.
The Management Tokens portal displays the following information about each token:
- Status
- Description
- Token ID
- Created date
- Expiration date
You can **Search** tokens by description or ID to filter the list and use the sort button and column headers to sort the list.
{{% /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 `influxctl management list` with the following:
@ -40,6 +75,8 @@ influxctl management list --format json
> Revoked tokens still appear when listing management tokens, but they are no
> longer valid for any operations.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Output formats
The `influxctl management list` command supports two output formats: `table` and `json`.

32
content/influxdb3/cloud-dedicated/admin/tokens/management/revoke.md
View File

@ -1,7 +1,7 @@
---
title: Revoke a management token
description: >
Use the [`influxctl management revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/revoke/)
Use the Admin UI or the [`influxctl management revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/revoke/)
to revoke a management token and remove all access associated with the token.
Provide the ID of the management token you want to revoke.
menu:
@ -16,9 +16,35 @@ list_code_example: |
```
---
Use the [`influxctl management revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/revoke/)
Use the Admin UI or the [`influxctl management revoke` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/revoke/)
to revoke a management token and remove all access associated with the token.
{{< tabs-wrapper >}}
{{% tabs %}}
[Admin UI](#admin-ui)
[influxctl](#influxctl)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------BEGIN ADMIN UI ------------------------------>
The {{% product-name %}} administrative UI includes a portal for managing management tokens.
1. To access the {{< product-name omit="InfluxDB " >}} Admin UI, visit the following URL in your browser:
<pre>
<a href="https://{{< influxdb/host >}}/">https://{{< influxdb/host >}}</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. To revoke a management token, click the **Management Tokens** button in the upper right corner of the Account Management portal.
4. **Search** for the token or use the sort button and column headers to sort the token list and find the token you want to revoke.
5. Click the options button (three vertical dots) to the right of the token you want to revoke.
The options menu displays.
6. In the options menu, click **Revoke Token**.
7. In the **Revoke Management Token** dialog, check the box to confirm you "Understand the risk of this action".
8. Click the **Revoke Token** button to revoke the token.
The token is revoked and filtered from the list of active tokens.
{{% /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 management list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/list)
to output tokens with their IDs.
@ -43,6 +69,8 @@ influxctl management revoke --force TOKEN_ID
Replace {{% code-placeholder-key %}}`TOKEN_ID`{{% /code-placeholder-key %}} with
the ID of the token you want to revoke.
{{% /tab-content %}}
{{% /tabs-wrapper %}}
> [!Note]
> #### Revoked tokens are included when listing management tokens

2
content/influxdb3/cloud-dedicated/get-started/_index.md
View File

@ -17,6 +17,8 @@ provides nearly unlimited series cardinality,
improved query performance, and interoperability with widely used data
processing tools and platforms.
<a class="btn" href="{{< cta-link >}}">Run an {{% product-name %}} proof of concept (PoC)</a>
**Time series data** is a sequence of data points indexed in time order. Data
points typically consist of successive measurements made from the same source
and are used to track changes over time. Examples of time series data include:

100
content/influxdb3/cloud-dedicated/reference/admin-ui.md Normal file
View File

@ -0,0 +1,100 @@
---
title: Administrative UI
seotitle: Administrative UI for {{% product-name %}}
description: >
The Administrative (Admin) UI for {{% product-name %}} is a browser-based, no-code way to manage your {{% product-name %}} environment and perform administrative tasks, such as creating and managing clusters, databases, and tokens.
menu:
influxdb3_cloud_dedicated:
parent: Reference
weight: 6
---
The Administrative (Admin) UI for {{% product-name %}} is a browser-based, no-code way to manage your {{% product-name %}} environment and perform administrative tasks, such as creating and managing clusters, databases, and tokens.
- [Access the Admin UI](#access-the-admin-ui)
- [Account management](#account-management)
- [Resource management](#resource-management)
- [Manage clusters](#manage-clusters)
- [Manage databases](#manage-databases)
- [Manage tables](#manage-tables)
- [Manage database tokens](#manage-database-tokens)
- [Additional Features](#additional-features)
## Access the Admin UI
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-login.png" alt="InfluxDB Cloud Dedicated Admin UI login page" />}}
Customers can access the Admin UI at [console.influxdata.com](http://console.influxdata.com) using the credentials provided by InfluxData.
If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com).
After you log in to the Admin UI, the Account Management portal provides an entrypoint to view your account information and manage your {{% product-name %}} resources.
## Account management
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-clusters-options.png" alt="InfluxDB Cloud Dedicated Admin UI account management cluster list" />}}
- View account details and associated clusters
- Create, view, and manage management tokens for account-level operations
- Access contract information (status, start date)
For more information, see the following:
- [View account information](/influxdb3/cloud-dedicated/admin/account/)
- [Manage management tokens](/influxdb3/cloud-dedicated/admin/tokens/)
## Resource management
The Admin UI lets you manage {{% product-name %}} resources, such as databases,
tables, and tokens, associated with a cluster.
- [Manage clusters](#manage-clusters)
- [Manage databases](#manage-databases)
- [Manage tables](#manage-tables)
- [Manage database tokens](manage-database-tokens)
### Manage clusters
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-clusters-options.png" alt="InfluxDB Cloud Dedicated Admin UI cluster options" />}}
- View cluster IDs, statuses, creation date, and sizing information
- Access Grafana dashboards for operational monitoring (if enabled for the account)
- View and manage resources (such as databases, tables, and database tokens) associated with a cluster
For more information, see [Manage clusters](/influxdb3/cloud-dedicated/admin/clusters/).
### Manage databases
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-databases.png" alt="InfluxDB Cloud Dedicated Admin UI cluster resources databases list" />}}
- Create and delete databases
- Update retention periods
- Configure maximum tables and columns per table
- View and manage tables associated with a database
For more information, see [Manage databases](/influxdb3/cloud-dedicated/admin/databases/).
### Manage tables
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-tables.png" alt="InfluxDB Cloud Dedicated Admin UI database tables list" />}}
- View tables associated with databases
- See table IDs and sizes
- Create new tables
For more information, see [Manage tables](/influxdb3/cloud-dedicated/admin/tables/).
### Manage database tokens
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-database-tokens.png" alt="InfluxDB Cloud Dedicated Admin UI manage database tokens portal" />}}
- Create and manage authentication tokens for database-level operations
- Edit permissions or revoke existing tokens
- Control access with granular read and write permissions
For more information, see [Manage database tokens](/influxdb3/cloud-dedicated/admin/tokens/).
### Additional Features
- Help center for access to documentation
- One-click connections to InfluxData sales and support

5
content/influxdb3/cloud-dedicated/reference/cli/_index.md
View File

@ -10,10 +10,11 @@ menu:
parent: Reference
name: CLIs
weight: 104
draft: true
---
InfluxDB provides command line tools designed to manage and work with your
InfluxDB Cloud Dedicated cluster from the command line.
The following command line interfaces (CLIs) are available:
{{< children >}}

12
content/influxdb3/cloud-dedicated/reference/cli/influxctl/_index.md
View File

@ -9,12 +9,16 @@ menu:
name: influxctl
parent: CLIs
weight: 101
aliases:
- /influxdb3/cloud-dedicated/reference/cli/
influxdb3/cloud-dedicated/tags: [cli]
---
The `influxctl` command line interface (CLI) writes to, queries, and performs
administrative tasks in an {{< product-name omit=" Clustered" >}} cluster.
administrative tasks in an {{< product-name omit=" Clustered" >}} cluster and
provides a scriptable way to manage your {{% product-name %}} resources.
- [Key features](#key-features)
- [Usage](#usage)
- [Commands](#commands)
- [Global flags](#global-flags)
@ -22,6 +26,12 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster.
- [Configure connection profiles](#configure-connection-profiles)
- [Authentication](#authentication)
## Key features
- Authentication via environment variables or config file
- JSON output for scripting and automation
- Can be integrated into CI/CD pipelines
## Usage
```sh

40
content/influxdb3/cloud-dedicated/reference/cli/influxctl/cluster/create.md
View File

@ -9,42 +9,4 @@ weight: 301
draft: true
---
The `influxctl cluster create` command creates an {{% product-name omit=" Clustered" %}} cluster.
## Usage
```sh
influxctl cluster create [flags]
```
## Flags
| Flag | | Description |
| :--- | ------------------------- | :-------------------------------------------------------------------------------------------- |
| | `--region` | {{< req >}}: Region to create cluster in |
| | `--category` | {{< req >}}: Cluster category (`contract`, `internal`, `unpaid_poc`, `paid_poc`, or `system`) |
| | `--ingestor-units` | Ingestor units _(default is 0)_ |
| | `--ingestor-granularity` | Ingestor granularity _(default is 0)_ |
| | `--compactor-units` | Compactor units _(default is 0)_ |
| | `--compactor-granularity` | Compactor granularity _(default is 0)_ |
| | `--query-units` | Query units _(default is 0)_ |
| | `--query-granularity` | Query granularity _(default is 0)_ |
| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._
{{% /caption %}}
## Examples
##### Create an InfluxDB Cloud Dedicated cluster
```sh
influxctl cluster create \
--region us-west-2 \
--category internal \
--ingestor-units 3 \
--compactor-units 1 \
--query-units 1 \
example-cluster-name
```
<!-- // NOTE This command is for InfluxData internal use only. -->

45
content/influxdb3/cloud-dedicated/reference/cli/influxctl/cluster/update.md
View File

@ -9,47 +9,4 @@ weight: 301
draft: true
---
The `influxctl cluster update` command updates an {{% product-name omit=" Clustered" %}} cluster.
## Usage
```sh
influxctl cluster update [flags] <CLUSTER_ID>
```
## Arguments
| Argument | Description |
| :------------- | :----------------------- |
| **CLUSTER_ID** | ID of the [cluster](/influxdb3/cloud-dedicated/reference/glossary/#cluster) to get |
## Flags
| Flag | | Description |
| :--- | ------------------------- | :-------------------------------------------------------------------------------------------- |
| | `--state` | {{< req >}}: Cluster state (`ready` or `deleted`) |
| | `--category` | {{< req >}}: Cluster category (`contract`, `internal`, `unpaid_poc`, `paid_poc`, or `system`) |
| | `--ingestor-units` | Ingestor units _(default is 0)_ |
| | `--ingestor-granularity` | Ingestor granularity _(default is 0)_ |
| | `--compactor-units` | Compactor units _(default is 0)_ |
| | `--compactor-granularity` | Compactor granularity _(default is 0)_ |
| | `--query-units` | Query units _(default is 0)_ |
| | `--query-granularity` | Query granularity _(default is 0)_ |
| `-h` | `--help` | Output command help |
{{% caption %}}
_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._
{{% /caption %}}
## Examples
##### Update an InfluxDB Cloud Dedicated cluster
```sh
influxctl cluster update \
--state ready \
--category contract \
--ingestor-units 3 \
--compactor-units 1 \
--query-units 1 \
```
<!-- // NOTE This command is for InfluxData internal use only. -->

2
content/influxdb3/clustered/_index.md
View File

@ -18,7 +18,7 @@ The InfluxDB time series platform is designed to handle high write and query loa
Learn how to use and leverage InfluxDB Clustered for your specific
time series use case.
<a class="btn" href="{{< cta-link >}}">Contact InfluxData Sales</a>
<a class="btn" href="{{< cta-link >}}">Run an {{% product-name %}} proof of concept (PoC)</a>
<a class="btn" href="/influxdb3/clustered/get-started/">Get started with InfluxDB Clustered</a>
## InfluxDB 3

17
content/influxdb3/core/extend-plugin.md Normal file
View File

@ -0,0 +1,17 @@
---
title: Extend plugins with API features and state management
description: |
The Processing engine includes an API that allows your plugins to interact with your data, build and write line protocol, and maintain state between executions.
menu:
influxdb3_core:
name: Extend plugins
parent: Processing engine and Python plugins
weight: 4
influxdb3/core/tags: [processing engine, plugins, API, python]
source: /shared/extended-plugin-api.md
---
<!--
// SOURCE content/shared/extended-plugin-api.md
-->

16
content/influxdb3/enterprise/extend-plugin.md Normal file
View File

@ -0,0 +1,16 @@
---
title: Extend plugins with API features and state management
description: |
The Processing engine includes an API that allows your plugins to interact with your data, build and write line protocol, and maintain state between executions.
menu:
influxdb3_enterprise:
name: Extend plugins
parent: Processing engine and Python plugins
weight: 4
influxdb3/enterprise/tags: [processing engine, plugins, API, python]
source: /shared/extended-plugin-api.md
---
<!--
// SOURCE content/shared/extended-plugin-api.md
-->

2
content/influxdb3/enterprise/plugins.md
View File

@ -5,7 +5,7 @@ description: |
code on different events in an {{< product-name >}} instance.
menu:
influxdb3_enterprise:
name: Processing Engine and Python plugins
name: Processing engine and Python plugins
weight: 4
influxdb3/enterprise/tags: [processing engine, python]
related:

323
content/shared/extended-plugin-api.md Normal file
View File

@ -0,0 +1,323 @@
The Processing Engine includes a shared API that your plugins can use to interact with data, write new records in line protocol format, and maintain state between executions. These capabilities let you build plugins that transform, analyze, and respond to time series data as it flows through your database.
The plugin API lets you:
- [Write data](#write-data)
- [Query data](#query-data)
- [Log messages for monitoring and debugging](#log-messages-for-monitoring-and-debugging)
- [Maintain state with the in-memory cache](#maintain-state-with-in-memory-cache)
- [Store and retrieve cached data](#store-and-retrieve-cached-data)
- [Use TTL appropriately](#use-ttl-appropriately)
- [Share data across plugins](#share-data-across-plugins)
- [Build a counter](#building-a-counter)
- [Guidelines for in-memory caching](#guidelines-for-in-memory-caching)
- [Consider cache limitations](#consider-cache-limitations)
## Get started with the shared API
Each plugin automatically has access to the shared API through the `influxdb3_local` object. You don’t need to import any libraries. The API becomes available as soon as your plugin runs.
## Write data
To write data into your database, use the `LineBuilder` API to create line protocol data:
```python
# Create a line protocol entry
line = LineBuilder("weather")
line.tag("location", "us-midwest")
line.float64_field("temperature", 82.5)
line.time_ns(1627680000000000000)
# Write the data to the database
influxdb3_local.write(line)
```
InfluxDB 3 buffers your writes while the plugin runs and flushes them when the plugin completes.
{{% expand-wrapper %}}
{{% expand "View the `LineBuilder` Python implementation" %}}
```python
from typing import Optional
from collections import OrderedDict
class InfluxDBError(Exception):
"""Base exception for InfluxDB-related errors"""
pass
class InvalidMeasurementError(InfluxDBError):
"""Raised when measurement name is invalid"""
pass
class InvalidKeyError(InfluxDBError):
"""Raised when a tag or field key is invalid"""
pass
class InvalidLineError(InfluxDBError):
"""Raised when a line protocol string is invalid"""
pass
class LineBuilder:
def __init__(self, measurement: str):
if ' ' in measurement:
raise InvalidMeasurementError("Measurement name cannot contain spaces")
self.measurement = measurement
self.tags: OrderedDict[str, str] = OrderedDict()
self.fields: OrderedDict[str, str] = OrderedDict()
self._timestamp_ns: Optional[int] = None
def _validate_key(self, key: str, key_type: str) -> None:
"""Validate that a key does not contain spaces, commas, or equals signs."""
if not key:
raise InvalidKeyError(f"{key_type} key cannot be empty")
if ' ' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain spaces")
if ',' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain commas")
if '=' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain equals signs")
def tag(self, key: str, value: str) -> 'LineBuilder':
"""Add a tag to the line protocol."""
self._validate_key(key, "tag")
self.tags[key] = str(value)
return self
def uint64_field(self, key: str, value: int) -> 'LineBuilder':
"""Add an unsigned integer field to the line protocol."""
self._validate_key(key, "field")
if value < 0:
raise ValueError(f"uint64 field '{key}' cannot be negative")
self.fields[key] = f"{value}u"
return self
def int64_field(self, key: str, value: int) -> 'LineBuilder':
"""Add an integer field to the line protocol."""
self._validate_key(key, "field")
self.fields[key] = f"{value}i"
return self
def float64_field(self, key: str, value: float) -> 'LineBuilder':
"""Add a float field to the line protocol."""
self._validate_key(key, "field")
# Check if value has no decimal component
self.fields[key] = f"{int(value)}.0" if value % 1 == 0 else str(value)
return self
def string_field(self, key: str, value: str) -> 'LineBuilder':
"""Add a string field to the line protocol."""
self._validate_key(key, "field")
# Escape quotes and backslashes in string values
escaped_value = value.replace('"', '\\"').replace('\\', '\\\\')
self.fields[key] = f'"{escaped_value}"'
return self
def bool_field(self, key: str, value: bool) -> 'LineBuilder':
"""Add a boolean field to the line protocol."""
self._validate_key(key, "field")
self.fields[key] = 't' if value else 'f'
return self
def time_ns(self, timestamp_ns: int) -> 'LineBuilder':
"""Set the timestamp in nanoseconds."""
self._timestamp_ns = timestamp_ns
return self
def build(self) -> str:
"""Build the line protocol string."""
# Start with measurement name (escape commas only)
line = self.measurement.replace(',', '\\,')
# Add tags if present
if self.tags:
tags_str = ','.join(
f"{k}={v}" for k, v in self.tags.items()
)
line += f",{tags_str}"
# Add fields (required)
if not self.fields:
raise InvalidLineError(f"At least one field is required: {line}")
fields_str = ','.join(
f"{k}={v}" for k, v in self.fields.items()
)
line += f" {fields_str}"
# Add timestamp if present
if self._timestamp_ns is not None:
line += f" {self._timestamp_ns}"
return line
```
{{% /expand %}}
{{% /expand-wrapper %}}
## Query data
Your plugins can execute SQL queries and process results directly:
```python
# Simple query
results = influxdb3_local.query("SELECT * FROM metrics WHERE time > now() - INTERVAL '1 hour'")
# Parameterized query for safer execution
params = {"table": "metrics", "threshold": 90}
results = influxdb3_local.query("SELECT * FROM $table WHERE value > $threshold", params)
```
Query results are a `List` of `Dict[String, Any]`, where each dictionary represents a row. Column names are keys, and column values are the corresponding values.
## Log messages for monitoring and debugging
Use the shared API's `info`, `warn`, and `error` functions to log messages from your plugin. Each function accepts one or more arguments, converts them to strings, and logs them as a space-separated message.
Add logging to monitor plugin execution and assist with debugging:
```python
influxdb3_local.info("Starting data processing")
influxdb3_local.warn("Could not process some records")
influxdb3_local.error("Failed to connect to external API")
# Log structured data
obj_to_log = {"records": 157, "errors": 3}
influxdb3_local.info("Processing complete", obj_to_log)
```
The system writes all log messages to the server logs and stores them in [system tables](/influxdb3/version/reference/cli/influxdb3/show/system/summary/), where you can query them using SQL.
## Maintain state with the in-memory cache
The Processing Engine provides an in-memory cache that enables your plugins to persist and retrieve data between executions.
Access the cache using the `cache` property of the shared API:
```python
# Basic usage pattern
influxdb3_local.cache.METHOD(PARAMETERS)
```
`cache` provides the following methods to retrieve and manage cached values:
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `put` | `key` (str): The key to store the value under<br>`value` (Any): Any Python object to cache<br>`ttl` (Optional[float], default=None): Time in seconds before expiration<br>`use_global` (bool, default=False): If True, uses global namespace | None | Stores a value in the cache with an optional time-to-live |
| `get` | `key` (str): The key to retrieve<br>`default` (Any, default=None): Value to return if key not found<br>`use_global` (bool, default=False): If True, uses global namespace | Any | Retrieves a value from the cache or returns default if not found |
| `delete` | `key` (str): The key to delete<br>`use_global` (bool, default=False): If True, uses global namespace | bool | Deletes a value from the cache. Returns True if deleted, False if not found |
### Understanding cache namespaces
The cache system offers two distinct namespaces:
| Namespace | Scope | Best For |
| --- | --- | --- |
| **Trigger-specific** (default) | Isolated to a single trigger | Plugin state, counters, timestamps specific to one plugin |
| **Global** | Shared across all triggers | Configuration, lookup tables, service states that should be available to all plugins |
### Common cache operations
- [Store and retrieve cached data](#store-and-retrieve-cached-data)
- [Store cached data with expiration](#store-cached-data-with-expiration)
- [Share data across plugins](#share-data-across-plugins)
- [Build a counter](#build-a-counter)
### Store and retrieve cached data
```python
# Store a value
influxdb3_local.cache.put("last_run_time", time.time())
# Retrieve a value with a default if not found
last_time = influxdb3_local.cache.get("last_run_time", default=0)
# Delete a cached value
influxdb3_local.cache.delete("temporary_data")
```
### Store cached data with expiration
```python
# Cache with a 5-minute TTL (time-to-live)
influxdb3_local.cache.put("api_response", response_data, ttl=300)
```
### Share data across plugins
```python
# Store in the global namespace
influxdb3_local.cache.put("config", {"version": "1.0"}, use_global=True)
# Retrieve from the global namespace
config = influxdb3_local.cache.get("config", use_global=True)
```
### Building a counter
You can track how many times a plugin has run:
```python
# Get current counter or default to 0
counter = influxdb3_local.cache.get("execution_count", default=0)
# Increment counter
counter += 1
# Store the updated value
influxdb3_local.cache.put("execution_count", counter)
influxdb3_local.info(f"This plugin has run {counter} times")
```
## Guidelines for in-memory caching
To get the most out of the in-memory cache, follow these guidelines:
- [Use the trigger-specific namespace](#use-the-trigger-specific-namespace)
- [Use TTL appropriately](#use-ttl-appropriately)
- [Cache computation results](#cache-computation-results)
- [Warm the cache](#warm-the-cache)
- [Consider cache limitations](#consider-cache-limitations)
### Use the trigger-specific namespace
The Processing Engine provides a cache that supports stateful operations while maintaining isolation between different triggers. For most use cases, use the trigger-specific namespace to keep plugin state isolated. Use the global namespace only when you need to share data across triggers.
### Use TTL appropriately
Set appropriate expiration times based on how frequently your data changes:
```python
# Cache external API responses for 5 minutes
influxdb3_local.cache.put("weather_data", api_response, ttl=300)
```
### Cache computation results
Store the results of expensive calculations that you frequently utilize:
```python
# Cache aggregated statistics
influxdb3_local.cache.put("daily_stats", calculate_statistics(data), ttl=3600)
```
### Warm the cache
For critical data, prime the cache at startup. This can be especially useful for global namespace data where multiple triggers need the data:
```python
# Check if cache needs to be initialized
if not influxdb3_local.cache.get("lookup_table"):
influxdb3_local.cache.put("lookup_table", load_lookup_data())
```
### Consider cache limitations
- **Memory Usage**: Since the system stores cache contents in memory, monitor your memory usage when caching large datasets.
- **Server Restarts**: Because the server clears the cache on restart, design your plugins to handle cache initialization (as noted above).
- **Concurrency**: Be cautious of accessing inaccurate or out-of-date data when multiple trigger instances might simultaneously update the same cache key.
## Next Steps
With an understanding of the InfluxDB 3 Shared Plugin API, you can start building data workflows that transform, analyze, and respond to your time series data.
To find example plugins you can extend, visit the [influxdb3_plugins repository](https://github.com/influxdata/influxdb3_plugins) on GitHub.

636
content/shared/v3-core-plugins/_index.md
View File

@ -1,54 +1,72 @@
Use the InfluxDB 3 Processing engine to run Python code directly in your
{{% product-name %}} database to automatically process data and respond to database events.
Use the Processing Engine in {{% product-name %}} to extend your database with custom Python code. Trigger your code on write, on a schedule, or on demand to automate workflows, transform data, and create API endpoints.
The Processing engine is an embedded Python VM that runs inside your InfluxDB 3 database and lets you:
## What is the Processing Engine?
- Process data as it's written to the database
- Run code on a schedule
- Create API endpoints that execute Python code
- Maintain state between executions with an in-memory cache
The Processing Engine is an embedded Python virtual machine that runs inside your {{% product-name %}} database. You configure _triggers_ to run your Python _plugin_ code in response to:
Learn how to create, configure, run, and extend Python plugins that execute when specific events occur.
- **Data writes** - Process and transform data as it enters the database
- **Scheduled events** - Run code at defined intervals or specific times
- **HTTP requests** - Expose custom API endpoints that execute your code
1. [Set up the Processing engine](#set-up-the-processing-engine)
2. [Add a Processing engine plugin](#add-a-processing-engine-plugin)
- [Get example plugins](#get-example-plugins)
- [Create a plugin](#create-a-plugin)
3. [Create a trigger to run a plugin](#create-a-trigger-to-run-a-plugin)
- [Create a trigger for data writes](#create-a-trigger-for-data-writes)
- [Create a trigger for scheduled events](#create-a-trigger-for-scheduled-events)
- [Create a trigger for HTTP requests](#create-a-trigger-for-http-requests)
- [Use community plugins from GitHub](#use-community-plugins-from-github)
You can use the Processing Engine's in-memory cache to manage state between executions and build stateful applications directly in your database.
This guide walks you through setting up the Processing Engine, creating your first plugin, and configuring triggers that execute your code on specific events.
## Before you begin
Ensure you have:
- A working InfluxDB 3 Core instance
- Access to command line
- Python installed if you're writing your own plugin
- Basic knowledge of the InfluxDB CLI
Once you have all the prerequisites in place, follow these steps to implement the Processing Engine for your data automation needs.
1. [Set up the Processing Engine](#set-up-the-processing-engine)
2. [Add a Processing Engine plugin](#add-a-processing-engine-plugin)
- [Use example plugins](#use-example-plugins)
- [Create a custom plugin](#create-a-custom-plugin)
3. [Set up a trigger](#set-up-a-trigger)
- [Understand trigger types](#understand-trigger-types)
- [Use the create trigger command](#use-the-create-trigger-command)
- [Trigger specification examples](#trigger-specification-examples)
4. [Advanced trigger configuration](#advanced-trigger-configuration)
- [Access community plugins from GitHub](#access-community-plugins-from-github)
- [Pass arguments to plugins](#pass-arguments-to-plugins)
- [Control trigger execution](#control-trigger-execution)
- [Configure error handling for a trigger](#configure-error-handling-for-a-trigger)
- [Extend plugins with API features and state management](#extend-plugins-with-api-features-and-state-management)
- [Install Python dependencies](#install-python-dependencies)
- [Install Python dependencies](#install-python-dependencies)
## Set up the Processing engine
## Set up the Processing Engine
To enable the Processing engine, start your InfluxDB server with the `--plugin-dir` option:
To activate the Processing Engine, start your {{% product-name %}} server with the `--plugin-dir` flag. This flag tells InfluxDB where to load your plugin files.
{{% code-placeholders "NODE_ID|OBJECT_STORE_TYPE|PLUGIN_DIR" %}}
```bash
influxdb3 serve \
--node-id node0 \
--object-store [OBJECT_STORE_TYPE] \
--plugin-dir /path/to/plugins
--NODE_ID \
--object-store OBJECT_STORE_TYPE \
--plugin-dir PLUGIN_DIR
```
Replace `/path/to/plugins` with the directory where you want to store your Python plugin files. All plugin files must be located in this directory or its subdirectories.
{{% /code-placeholders %}}
In the example above, replace the following:
- {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}: Unique identifier for your instance
- {{% code-placeholder-key %}}`OBJECT_STORE_TYPE`{{% /code-placeholder-key %}}: Type of object store (for example, file or s3)
- {{% code-placeholder-key %}}`PLUGIN_DIR`{{% /code-placeholder-key %}}: Absolute path to the directory where plugin files are stored. Store all plugin files in this directory or its subdirectories.
### Configure distributed environments
If you're running multiple {{% product-name %}} instances (distributed deployment):
When running {{% product-name %}} in a distributed setup, follow these steps to configure the Processing Engine:
1. Decide where plugins should run
1. Decide where each plugin should run
- Data processing plugins, such as WAL plugins, run on ingester nodes
- HTTP-triggered plugins run on nodes handling API requests
- Scheduled plugins can run on any configured node
2. Enable plugins on selected instances
2. Enable plugins on the correct instance
3. Maintain identical plugin files across all instances where plugins run
- Use shared storage or file synchronization tools to keep plugins consistent
@ -57,43 +75,58 @@ If you're running multiple {{% product-name %}} instances (distributed deploymen
>
> Configure your plugin directory on the same system as the nodes that run the triggers and plugins.
## Add a Processing Engine plugin
## Add a Processing engine plugin
A plugin is a Python script that defines a specific function signature for a trigger (_trigger spec_). When the specified event occurs, InfluxDB runs the plugin.
A plugin is a Python file that contains a specific function signature that corresponds to a trigger type.
Plugins:
### Choose a plugin strategy
- Receive plugin-specific arguments (such as written data, call time, or an HTTP request)
- Can receive keyword arguments (as `args`) from _trigger arguments_
- Can access the `influxdb3_local` shared API for writing, querying, and managing state
You have two main options for adding plugins to your InfluxDB instance:
Get started using example plugins or create your own:
- [Use example plugins](#use-example-plugins) - Quickly get started with prebuilt plugins
- [Create a custom plugin](#create-a-custom-plugin) - Build your own for specialized use cases
- [Get example plugins](#get-example-plugins)
- [Create a plugin](#create-a-plugin)
### Use example plugins
### Get example plugins
InfluxData provides a public repository of example plugins that you can use immediately.
InfluxData maintains a repository of contributed plugins that you can use as-is or as a starting point for your own plugin.
#### Browse plugin examples
#### From local files
Visit the [influxdb3_plugins repository](https://github.com/influxdata/influxdb3_plugins) to find examples for:
You can copy example plugins from the [influxdb3_plugins repository](https://github.com/influxdata/influxdb3_plugins) to your local plugin directory:
- **Data transformation**: Process and transform incoming data
- **Alerting**: Send notifications based on data thresholds
- **Aggregation**: Calculate statistics on time series data
- **Integration**: Connect to external services and APIs
- **System monitoring**: Track resource usage and health metrics
#### Add example plugins
You can either copy a plugin or retrieve it directly from the repository:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Copy locally](#)
[Fetch via gh:](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
# Clone the repository
git clone https://github.com/influxdata/influxdb3_plugins.git
# Copy example plugins to your plugin directory
cp -r influxdb3_plugins/examples/wal_plugin/* /path/to/plugins/
# Copy a plugin to your configured plugin directory
cp influxdb3_plugins/examples/schedule/system_metrics/system_metrics.py /path/to/plugins/
```
{{% /code-tab-content %}}
#### Directly from GitHub
You can use plugins directly from GitHub without downloading them first by using the `gh:` prefix in the plugin filename:
{{% code-tab-content %}}
```bash
# Use a plugin directly from GitHub
# To retrieve and use a plugin directly from GitHub,
# use the `gh:` prefix in the plugin filename:
influxdb3 create trigger \
--trigger-spec "every:1m" \
--plugin-filename "gh:examples/schedule/system_metrics/system_metrics.py" \
@ -101,26 +134,61 @@ influxdb3 create trigger \
system_metrics
```
> [!Note]
> #### Find and contribute plugins
>
> The plugins repository includes examples for various use cases:
>
> - **Data transformation**: Process and transform incoming data
> - **Alerting**: Send notifications based on data thresholds
> - **Aggregation**: Calculate statistics on time series data
> - **Integration**: Connect to external services and APIs
> - **System monitoring**: Track resource usage and health metrics
>
> Visit [influxdata/influxdb3_plugins](https://github.com/influxdata/influxdb3_plugins)
> to browse available plugins or contribute your own.
{{% /code-tab-content %}}
### Create a plugin
{{< /code-tabs-wrapper >}}
1. Create a `.py` file in your plugins directory
2. Define a function with one of the following signatures:
Plugins have various functions such as:
#### For data write events
- Receive plugin-specific arguments (such as written data, call time, or an HTTP request)
- Access keyword arguments (as `args`) passed from _trigger arguments_ configurations
- Access the `influxdb3_local` shared API to write data, query data, and managing state between executions
For more information about available functions, arguments, and how plugins interact with InfluxDB, see the [Extended Plugin API documentation](/influxdb3/shared/v3-core-plugins/).
### Create a custom plugin
To build custom functionality, you can create your own Processing Engine plugin.
#### Prerequisites
Before you begin, make sure:
- The Processing Engine is enabled on your {{% product-name %}} instance.
- You’ve configured the `--plugin-dir` where plugin files are stored.
- You have access to that plugin directory.
#### Steps to create a plugin:
- [Choose your plugin type](#choose-your-plugin-type)
- [Create your plugin file](#create-your-plugin-file)
- [Next Steps](#next-steps)
#### Choose your plugin type
Choose a plugin type based on your automation goals:
| Plugin Type | Best For | Trigger Type |
|-------------|----------|-------------|
| **Data write** | Processing data as it arrives | `table:` or `all_tables` |
| **Scheduled** | Running code at specific times | `every:` or `cron:` |
| **HTTP request** | Creating API endpoints | `path:` |
#### Create your plugin file
- Create a `.py` file in your plugins directory
- Add the appropriate function signature based on your chosen plugin type
- Write your processing logic inside the function
After writing your plugin, [create a trigger](#use-the-create-trigger-command) to connect it to a database event and define when it runs.
#### Create a data write plugin
Use a data write plugin to process data as it's written to the database. Ideal use cases include:
- Data transformation and enrichment
- Alerting on incoming values
- Creating derived metrics
```python
def process_writes(influxdb3_local, table_batches, args=None):
@ -139,7 +207,13 @@ def process_writes(influxdb3_local, table_batches, args=None):
influxdb3_local.write(line)
```
#### For scheduled events
#### Create a scheduled plugin
Scheduled plugins run at defined intervals. Use them for:
- Periodic data aggregation
- Report generation
- System health checks
```python
def process_scheduled_call(influxdb3_local, call_time, args=None):
@ -155,7 +229,13 @@ def process_scheduled_call(influxdb3_local, call_time, args=None):
influxdb3_local.warn("No recent metrics found")
```
#### For HTTP requests
#### Create an HTTP request plugin
HTTP request plugins respond to API calls. Use them for:
- Creating custom API endpoints
- Webhooks for external integrations
- User interfaces for data interaction
```python
def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None):
@ -174,25 +254,55 @@ def process_request(influxdb3_local, query_parameters, request_headers, request_
return {"status": "success", "message": "Request processed"}
```
After adding your plugin, you can [install Python dependencies](#install-python-dependencies) or learn how to [extend plugins with API features and state management](#extend-plugins-with-api-features-and-state-management).
#### Next steps
## Create a trigger to run a plugin
After writing your plugin:
A trigger connects your plugin to a specific database event.
The plugin function signature in your plugin file determines which _trigger specification_
you can choose for configuring and activating your plugin.
- [Create a trigger](#use-the-create-trigger-command) to connect your plugin to database events
- [Install any Python dependencies](#install-python-dependencies) your plugin requires
- Learn how to [extend plugins with the API](/influxdb3/version/extend-plugin/)
Create a trigger with the `influxdb3 create trigger` command.
## Set up a trigger
### Understand trigger types
| Plugin Type | Trigger Specification | When Plugin Runs |
|------------|----------------------|-----------------|
| Data write | `table:<TABLE_NAME>` or `all_tables` | When data is written to tables |
| Scheduled | `every:<DURATION>` or `cron:<EXPRESSION>` | At specified time intervals |
| HTTP request | `path:<ENDPOINT_PATH>` | When HTTP requests are received |
### Use the create trigger command
Use the `influxdb3 create trigger` command with the appropriate trigger specification:
{{% code-placeholders "SPECIFICATION|PLUGIN_FILE|DATABASE_NAME|TRIGGER_NAME" %}}
```bash
influxdb3 create trigger \
--trigger-spec SPECIFICATION \
--plugin-filename PLUGIN_FILE \
--database DATABASE_NAME \
TRIGGER_NAME
```
{{% /code-placeholders %}}
In the example above, replace the following:
- {{% code-placeholder-key %}}`SPECIFICATION`{{% /code-placeholder-key %}}: Trigger specification
- {{% code-placeholder-key %}}`PLUGIN_FILE`{{% /code-placeholder-key %}}: Plugin filename relative to your configured plugin directory
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database
- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: Name of the new trigger
> [!Note]
> When specifying a local plugin file, the `--plugin-filename` parameter
> _is relative to_ the `--plugin-dir` configured for the server.
> You don't need to provide an absolute path.
### Create a trigger for data writes
### Trigger specification examples
Use the `table:<TABLE_NAME>` or the `all_tables` trigger specification to configure
and run a [plugin for data write events](#for-data-write-events)--for example:
#### Data write example
```bash
# Trigger on writes to a specific table
@ -211,15 +321,11 @@ influxdb3 create trigger \
all_data_processor
```
The trigger runs when the database flushes ingested data for the specified tables
to the Write-Ahead Log (WAL) in the Object store (default is every second).
The trigger runs when the database flushes ingested data for the specified tables to the Write-Ahead Log (WAL) in the Object store (default is every second).
The plugin receives the written data and table information.
### Create a trigger for scheduled events
Use the `every:<DURATION>` or the `cron:<CRONTAB_EXPRESSION>` trigger specification
to configure and run a [plugin for scheduled events](#for-scheduled-events)--for example:
#### Scheduled events example
```bash
# Run every 5 minutes
@ -239,9 +345,7 @@ influxdb3 create trigger \
The plugin receives the scheduled call time.
### Create a trigger for HTTP requests
For an [HTTP request plugin](#for-http-requests), use the `request:<ENDPOINT_PATH>` trigger specification to configure and enable a [plugin for HTTP requests](#for-http-requests)--for example:
#### HTTP requests example
```bash
# Create an endpoint at /api/v3/engine/webhook
@ -252,7 +356,7 @@ influxdb3 create trigger \
webhook_processor
```
The trigger makes your endpoint available at `/api/v3/engine/<ENDPOINT_PATH>`.
Access your endpoint available at `/api/v3/engine/<ENDPOINT_PATH>`.
To run the plugin, send a `GET` or `POST` request to the endpoint--for example:
```bash
@ -261,22 +365,10 @@ curl http://{{% influxdb/host %}}/api/v3/engine/webhook
The plugin receives the HTTP request object with methods, headers, and body.
### Use community plugins from GitHub
You can reference plugins directly from the GitHub repository by using the `gh:` prefix:
```bash
# Create a trigger using a plugin from GitHub
influxdb3 create trigger \
--trigger-spec "every:1m" \
--plugin-filename "gh:examples/schedule/system_metrics/system_metrics.py" \
--database my_database \
system_metrics
```
### Pass arguments to plugins
Use trigger arguments to pass configuration from a trigger to the plugin it runs. You can use this for:
- Threshold values for monitoring
- Connection properties for external services
- Configuration settings for plugin behavior
@ -344,300 +436,91 @@ influxdb3 create trigger \
auto_disable_processor
```
## Extend plugins with API features and state management
## Advanced trigger configuration
The Processing engine includes API capabilities that allow your plugins to
interact with InfluxDB data and maintain state between executions.
These features let you build more sophisticated plugins that can transform, analyze, and respond to data.
After creating basic triggers, you can enhance your plugins with these advanced features:
### Use the shared API
### Access community plugins from GitHub
All plugins have access to the shared API to interact with the database.
Skip downloading plugins by referencing them directly from GitHub:
#### Write data
```bash
# Create a trigger using a plugin from GitHub
influxdb3 create trigger \
--trigger-spec "every:1m" \
--plugin-filename "gh:examples/schedule/system_metrics/system_metrics.py" \
--database my_database \
system_metrics
```
Use the `LineBuilder` API to create line protocol data:
This approach:
- Ensures you're using the latest version
- Simplifies updates and maintenance
- Reduces local storage requirements
### Configure your triggers
#### Pass configuration arguments
Provide runtine configuration to your plugins:
```bash
# Pass threshold and email settings to a plugin
Provide runtime configuration to your plugins:
--trigger-spec "every:1h" \
--plugin-filename "threshold_check.py" \
--trigger-arguments threshold=90,notify_email=admin@example.com \
--database my_database \
threshold_monitor
```
Your plugin accesses these values through the `args` parameter:
```python
# Create a line protocol entry
line = LineBuilder("weather")
line.tag("location", "us-midwest")
line.float64_field("temperature", 82.5)
line.time_ns(1627680000000000000)
# Write the data to the database
influxdb3_local.write(line)
def process_scheduled_call(influxdb3_local, call_time, args=None):
if args and "threshold" in args:
threshold = float(args["threshold"])
email = args.get("notify_email", "default@example.com")
# Use the arguments in your logic
influxdb3_local.info(f"Checking threshold {threshold}, will notify {email}")
```
Writes are buffered while the plugin runs and are flushed when the plugin completes.
#### Set execution mode
{{% expand-wrapper %}}
{{% expand "View the `LineBuilder` Python implementation" %}}
Choose between synchronous (default) or asynchronous execution:
```python
from typing import Optional
from collections import OrderedDict
class InfluxDBError(Exception):
"""Base exception for InfluxDB-related errors"""
pass
class InvalidMeasurementError(InfluxDBError):
"""Raised when measurement name is invalid"""
pass
class InvalidKeyError(InfluxDBError):
"""Raised when a tag or field key is invalid"""
pass
class InvalidLineError(InfluxDBError):
"""Raised when a line protocol string is invalid"""
pass
class LineBuilder:
def __init__(self, measurement: str):
if ' ' in measurement:
raise InvalidMeasurementError("Measurement name cannot contain spaces")
self.measurement = measurement
self.tags: OrderedDict[str, str] = OrderedDict()
self.fields: OrderedDict[str, str] = OrderedDict()
self._timestamp_ns: Optional[int] = None
def _validate_key(self, key: str, key_type: str) -> None:
"""Validate that a key does not contain spaces, commas, or equals signs."""
if not key:
raise InvalidKeyError(f"{key_type} key cannot be empty")
if ' ' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain spaces")
if ',' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain commas")
if '=' in key:
raise InvalidKeyError(f"{key_type} key '{key}' cannot contain equals signs")
def tag(self, key: str, value: str) -> 'LineBuilder':
"""Add a tag to the line protocol."""
self._validate_key(key, "tag")
self.tags[key] = str(value)
return self
def uint64_field(self, key: str, value: int) -> 'LineBuilder':
"""Add an unsigned integer field to the line protocol."""
self._validate_key(key, "field")
if value < 0:
raise ValueError(f"uint64 field '{key}' cannot be negative")
self.fields[key] = f"{value}u"
return self
def int64_field(self, key: str, value: int) -> 'LineBuilder':
"""Add an integer field to the line protocol."""
self._validate_key(key, "field")
self.fields[key] = f"{value}i"
return self
def float64_field(self, key: str, value: float) -> 'LineBuilder':
"""Add a float field to the line protocol."""
self._validate_key(key, "field")
# Check if value has no decimal component
self.fields[key] = f"{int(value)}.0" if value % 1 == 0 else str(value)
return self
def string_field(self, key: str, value: str) -> 'LineBuilder':
"""Add a string field to the line protocol."""
self._validate_key(key, "field")
# Escape quotes and backslashes in string values
escaped_value = value.replace('"', '\\"').replace('\\', '\\\\')
self.fields[key] = f'"{escaped_value}"'
return self
def bool_field(self, key: str, value: bool) -> 'LineBuilder':
"""Add a boolean field to the line protocol."""
self._validate_key(key, "field")
self.fields[key] = 't' if value else 'f'
return self
def time_ns(self, timestamp_ns: int) -> 'LineBuilder':
"""Set the timestamp in nanoseconds."""
self._timestamp_ns = timestamp_ns
return self
def build(self) -> str:
"""Build the line protocol string."""
# Start with measurement name (escape commas only)
line = self.measurement.replace(',', '\\,')
# Add tags if present
if self.tags:
tags_str = ','.join(
f"{k}={v}" for k, v in self.tags.items()
)
line += f",{tags_str}"
# Add fields (required)
if not self.fields:
raise InvalidLineError(f"At least one field is required: {line}")
fields_str = ','.join(
f"{k}={v}" for k, v in self.fields.items()
)
line += f" {fields_str}"
# Add timestamp if present
if self._timestamp_ns is not None:
line += f" {self._timestamp_ns}"
return line
```
{{% /expand %}}
{{% /expand-wrapper %}}
#### Query data
Execute SQL queries and get results:
```python
# Simple query
results = influxdb3_local.query("SELECT * FROM metrics WHERE time > now() - INTERVAL '1 hour'")
# Parameterized query for safer execution
params = {"table": "metrics", "threshold": 90}
results = influxdb3_local.query("SELECT * FROM $table WHERE value > $threshold", params)
```bash
# Allow multiple trigger instances to run simultaneously
influxdb3 create trigger \
--trigger-spec "table:metrics" \
--plugin-filename "heavy_process.py" \
--run-asynchronous \
--database my_database \
async_processor
```
The shared API `query` function returns results as a `List` of `Dict[String, Any]`, where the key is the column name and the value is the column value.
Use asynchronous execution when:
#### Log information
- Processing might take longer than the trigger interval
- Multiple events need to be handled simultaneously
- Performance is more important than sequential execution
The shared API `info`, `warn`, and `error` functions accept multiple arguments,
convert them to strings, and log them as a space-separated message to the database log,
which is output in the server logs and captured in system tables that you can
query using SQL.
#### Configure error handling
Add logging to track plugin execution:
```python
influxdb3_local.info("Starting data processing")
influxdb3_local.warn("Could not process some records")
influxdb3_local.error("Failed to connect to external API")
# Log structured data
obj_to_log = {"records": 157, "errors": 3}
influxdb3_local.info("Processing complete", obj_to_log)
Control how your trigger responds to errors:
```bash
# Automatically retry on error
influxdb3 create trigger \
--trigger-spec "table:important_data" \
--plugin-filename "critical_process.py" \
--error-behavior retry \
--database my_database \
critical_processor
```
#### Use the in-memory cache
The Processing engine provides an in-memory cache system that enables plugins to persist and retrieve data between executions.
Use the shared API `cache` property to access the cache API.
```python
# Basic usage pattern
influxdb3_local.cache.METHOD(PARAMETERS)
```
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `put` | `key` (str): The key to store the value under<br>`value` (Any): Any Python object to cache<br>`ttl` (Optional[float], default=None): Time in seconds before expiration<br>`use_global` (bool, default=False): If True, uses global namespace | None | Stores a value in the cache with an optional time-to-live |
| `get` | `key` (str): The key to retrieve<br>`default` (Any, default=None): Value to return if key not found<br>`use_global` (bool, default=False): If True, uses global namespace | Any | Retrieves a value from the cache or returns default if not found |
| `delete` | `key` (str): The key to delete<br>`use_global` (bool, default=False): If True, uses global namespace | bool | Deletes a value from the cache. Returns True if deleted, False if not found |
##### Cache namespaces
The cache system offers two distinct namespaces:
| Namespace | Scope | Best For |
| --- | --- | --- |
| **Trigger-specific** (default) | Isolated to a single trigger | Plugin state, counters, timestamps specific to one plugin |
| **Global** | Shared across all triggers | Configuration, lookup tables, service states that should be available to all plugins |
##### Store and retrieve cached data
```python
# Store a value
influxdb3_local.cache.put("last_run_time", time.time())
# Retrieve a value with a default if not found
last_time = influxdb3_local.cache.get("last_run_time", default=0)
# Delete a cached value
influxdb3_local.cache.delete("temporary_data")
```
##### Store cached data with expiration
```python
# Cache with a 5-minute TTL (time-to-live)
influxdb3_local.cache.put("api_response", response_data, ttl=300)
```
##### Share data across plugins
```python
# Store in the global namespace
influxdb3_local.cache.put("config", {"version": "1.0"}, use_global=True)
# Retrieve from the global namespace
config = influxdb3_local.cache.get("config", use_global=True)
```
##### Track state between executions
```python
# Get current counter or default to 0
counter = influxdb3_local.cache.get("execution_count", default=0)
# Increment counter
counter += 1
# Store the updated value
influxdb3_local.cache.put("execution_count", counter)
influxdb3_local.info(f"This plugin has run {counter} times")
```
#### Best practices for in-memory caching
- [Use the trigger-specific namespace](#use-the-trigger-specific-namespace)
- [Use TTL appropriately](#use-ttl-appropriately)
- [Cache computation results](#cache-computation-results)
- [Warm the cache](#warm-the-cache)
- [Consider cache limitations](#consider-cache-limitations)
##### Use the trigger-specific namespace
The cache is designed to support stateful operations while maintaining isolation between different triggers. Use the trigger-specific namespace for most operations and the global namespace only when data sharing across triggers is necessary.
##### Use TTL appropriately
Set realistic expiration times based on how frequently data changes.
```python
# Cache external API responses for 5 minutes
influxdb3_local.cache.put("weather_data", api_response, ttl=300)
```
##### Cache computation results
Store the results of expensive calculations that need to be utilized frequently.
```python
# Cache aggregated statistics
influxdb3_local.cache.put("daily_stats", calculate_statistics(data), ttl=3600)
```
##### Warm the cache
For critical data, prime the cache at startup. This can be especially useful for global namespace data where multiple triggers need the data.
```python
# Check if cache needs to be initialized
if not influxdb3_local.cache.get("lookup_table"):
influxdb3_local.cache.put("lookup_table", load_lookup_data())
```
##### Consider cache limitations
- **Memory Usage**: Since cache contents are stored in memory, monitor your memory usage when caching large datasets.
- **Server Restarts**: Because the cache is cleared when the server restarts, design your plugins to handle cache initialization (as noted above).
- **Concurrency**: Be cautious of accessing inaccurate or out-of-date data when multiple trigger instances might simultaneously update the same cache key.
## Install Python dependencies
### Install Python dependencies
If your plugin needs additional Python packages, use the `influxdb3 install` command:
@ -654,6 +537,7 @@ docker exec -it CONTAINER_NAME influxdb3 install package pandas
This creates a Python virtual environment in your plugins directory with the specified packages installed.
{{% show-in "enterprise" %}}
### Connect Grafana to your InfluxDB instance
When configuring Grafana to connect to an InfluxDB 3 Enterprise instance:

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

4
data/products.yml
View File

@ -49,7 +49,7 @@ influxdb3_cloud_dedicated:
versions: [cloud-dedicated]
list_order: 3
latest: cloud-dedicated
link: "https://www.influxdata.com/contact-sales-form/"
link: "https://www.influxdata.com/contact-sales-cloud-dedicated/"
latest_cli: 2.10.0
placeholder_host: cluster-id.a.influxdb.io
ai_sample_questions:
@ -65,7 +65,7 @@ influxdb3_clustered:
versions: [clustered]
list_order: 3
latest: clustered
link: "https://www.influxdata.com/contact-sales-influxdb-clustered"
link: "https://www.influxdata.com/contact-sales-influxdb-clustered/"
placeholder_host: cluster-host.com
ai_sample_questions:
- How do I use a Helm chart to configure Clustered?

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-account-info.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-clusters-options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 510 KiB

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

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-create-database-token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 137 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 159 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-create-management-token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 99 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 412 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-database-token-options-menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-database-tokens.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 572 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-databases.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 554 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-delete-database.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 145 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-edit-database-token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 116 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-list-databases.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-login.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-management-tokens-portal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-management-tokens.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 862 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-revoke-database-token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 134 KiB

BIN
static/img/influxdb3/cloud-dedicated-admin-ui-tables.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 458 KiB