--- title: Databases description: Create and manage databases in an InfluxDB 3 Cloud Dedicated cluster, including setting retention periods and custom partition templates. url: https://docs.influxdata.com/influxdb3/cloud-dedicated/api/management-api/databases/ estimated_tokens: 4416 product: InfluxDB 3 Cloud version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/cloud-dedicated/api/management-api/databases/ --- [Download Cloud Dedicated Management API Spec](/openapi/influxdb-cloud-dedicated-management-api.yml) Create and manage databases in an InfluxDB 3 Cloud Dedicated cluster, including setting retention periods and custom partition templates. GET`/accounts/{accountId}/clusters/{clusterId}/databases` ### Get all databases for a cluster #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account to get the databases for `clusterId`requiredstring The ID of the cluster to get the databases for Example request[Ask AI about this](#) ```sh curl --request GET \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The cluster databases were successfully retrieved 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring POST`/accounts/{accountId}/clusters/{clusterId}/databases` ### Create a database 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 strategy for each database and table. A *partition* is a logical grouping of data stored in Apache Parquet. 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. 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. #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account to create the database for `clusterId`requiredstring The ID of the cluster to create the database for #### Request bodyrequired Content-Type:`application/json` `maxColumnsPerTable`integer \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`integer \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. 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: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention Example request[Ask AI about this](#) ```sh curl --request POST \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "maxColumnsPerTable": 200, "maxTables": 500, "name": "NAME", "partitionTemplate": [ "PARTITIONTEMPLATE" ], "retentionPeriod": 0 }' ``` #### Responses 200The cluster database was successfully created `accountId`requiredstring \ `clusterId`requiredstring \ `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. 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: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`requiredinteger \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 409Conflict `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PUT`/accounts/{accountId}/clusters/{clusterId}/databases/{databaseId}/undelete` ### Undelete a database Restores a previously deleted database. This operation can only be performed on databases that have been soft-deleted and are still within the recovery window. #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account that the database belongs to `clusterId`requiredstring The ID of the cluster that the database belongs to `databaseId`requiredstring The ID of the database to undelete Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseId}/undelete" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The cluster database was successfully undeleted `accountId`requiredstring \ `clusterId`requiredstring \ `id`requiredinteger \ The ID of the cluster database `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. 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: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PATCH`/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}` ### Update a database #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account that the database belongs to `clusterId`requiredstring The ID of the cluster that the database belongs to `databaseName`requiredstring The name of the database to update #### Request bodyrequired Content-Type:`application/json` `maxColumnsPerTable`integer \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`integer \ The maximum number of tables for the cluster database Default:`500` `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "maxColumnsPerTable": 200, "maxTables": 500, "retentionPeriod": 0 }' ``` #### Responses 200The cluster database was successfully updated. `accountId`requiredstring \ `clusterId`requiredstring \ `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `retentionPeriod`requiredinteger \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring DELETE`/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}` ### Delete a database #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account that the database belongs to `clusterId`requiredstring The ID of the cluster that the database belongs to `databaseName`requiredstring The name of the database to delete Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204No Content 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PUT`/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}/rename` ### Rename a database Renames an existing database. This operation can only be performed on databases that are currently active. #### Parameters ##### Path parameters `accountId`requiredstring The ID of the account that the database belongs to `clusterId`requiredstring The ID of the cluster that the database belongs to `databaseName`requiredstring The name of the database to rename #### Request bodyrequired Content-Type:`application/json` `name`requiredstring The name of the cluster database Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}/rename" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME" }' ``` #### Responses 200The cluster database was successfully renamed `accountId`requiredstring \ `clusterId`requiredstring \ `id`requiredinteger \ The ID of the cluster database `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. 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: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 409Conflict `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring #### Related * [Manage databases](/influxdb3/cloud-dedicated/admin/databases/) * [Custom partitions](/influxdb3/cloud-dedicated/admin/custom-partitions/) * [Partition templates](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/) * [InfluxDB 3 API client libraries](/influxdb3/cloud-dedicated/reference/client-libraries/v3/)