Databases

Download InfluxDB Clustered API Spec
Create and manage databases in an InfluxDB 3 Clustered cluster, including setting retention periods and custom partition templates.
GET /databases

Get all databases for a cluster

Example request Ask AI about this
curl --request GET \
  "https://console.influxdata.com/api/v0/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 /databases

Create a database

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 template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

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/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
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 template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

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 /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
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/databases/{databaseId}/undelete" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 The cluster database was successfully undeleted
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 template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

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 /databases/{databaseName}

Update a database

Parameters

Path parameters
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/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.
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 /databases/{databaseName}

Delete a database

Parameters

Path parameters
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/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 /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
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/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
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 template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

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!