Databases

Download InfluxDB Cloud Dedicated API Spec
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 required string
The ID of the account to get the databases for
clusterId required string
The ID of the cluster to get the databases for
Example request Ask AI about this
curl --request GET \
  "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 The cluster databases were successfully retrieved
400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
500 Internal Server Error
code required integer
message required string
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 required string
The ID of the account to create the database for
clusterId required string
The ID of the cluster to create the database for

Request body required

Content-Type: application/json
maxColumnsPerTable integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables integer <int32>
The maximum number of tables for the cluster database
Default: 500
name required string
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:

[
  {
    "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=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

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

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

200 The cluster database was successfully created
accountId required string <uuid>
clusterId required string <uuid>
maxColumnsPerTable required integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables required integer <int32>
The maximum number of tables for the cluster database
Default: 500
name required string
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:

[
  {
    "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=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

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 required integer <int64>

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

400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
409 Conflict
code required integer
message required string
500 Internal Server Error
code required integer
message required string
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 required string
The ID of the account that the database belongs to
clusterId required string
The ID of the cluster that the database belongs to
databaseId required string
The ID of the database to undelete
Example request Ask AI about this
curl --request PUT \
  "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseId}/undelete" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 The cluster database was successfully undeleted
accountId required string <uuid>
clusterId required string <uuid>
id required integer <int64>
The ID of the cluster database
maxColumnsPerTable required integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables required integer <int32>
The maximum number of tables for the cluster database
Default: 500
name required string
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:

[
  {
    "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=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

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

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

400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
500 Internal Server Error
code required integer
message required string
PATCH /accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}

Update a database

Parameters

Path parameters
accountId required string
The ID of the account that the database belongs to
clusterId required string
The ID of the cluster that the database belongs to
databaseName required string
The name of the database to update

Request body required

Content-Type: application/json
maxColumnsPerTable integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables integer <int32>
The maximum number of tables for the cluster database
Default: 500
retentionPeriod integer <int64>

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

200 The cluster database was successfully updated.
accountId required string <uuid>
clusterId required string <uuid>
maxColumnsPerTable required integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables required integer <int32>
The maximum number of tables for the cluster database
Default: 500
name required string
The name of the cluster database
retentionPeriod required integer <int64>

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

400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
500 Internal Server Error
code required integer
message required string
DELETE /accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}

Delete a database

Parameters

Path parameters
accountId required string
The ID of the account that the database belongs to
clusterId required string
The ID of the cluster that the database belongs to
databaseName required string
The name of the database to delete
Example request Ask AI about this
curl --request DELETE \
  "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 No Content
400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
500 Internal Server Error
code required integer
message required string
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 required string
The ID of the account that the database belongs to
clusterId required string
The ID of the cluster that the database belongs to
databaseName required string
The name of the database to rename

Request body required

Content-Type: application/json
name required string
The name of the cluster database
Example request Ask AI about this
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

200 The cluster database was successfully renamed
accountId required string <uuid>
clusterId required string <uuid>
id required integer <int64>
The ID of the cluster database
maxColumnsPerTable required integer <int32>
The maximum number of columns per table for the cluster database
Default: 200
maxTables required integer <int32>
The maximum number of tables for the cluster database
Default: 500
name required string
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:

[
  {
    "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=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

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

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

400 Bad Request
code required integer
message required string
401 Unauthorized
code required integer
message required string
403 Forbidden
code required integer
message required string
404 Not Found
code required integer
message required string
409 Conflict
code required integer
message required string
500 Internal Server Error
code required integer
message required string

Was this page helpful?

Thank you for your feedback!