Tables

Download InfluxDB Clustered API Spec

Manage tables in an InfluxDB 3 Clustered database, including creating tables with custom column schemas.

POST /databases/{databaseName}/tables

Create a database table

Parameters

Path parameters

databaseName required string

The name of the database to create the database table for

Request body required

Content-Type: application/json

name required string

The name of the cluster database table

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.

Example request Ask AI about this

curl --request POST \
  "https://console.influxdata.com/api/v0/databases/{databaseName}/tables" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "name": "NAME",
  "partitionTemplate": [
    "PARTITIONTEMPLATE"
  ]
}'

Responses

200 The cluster database table was successfully created

databaseName required string

The name of the cluster database

name required string

The name of the cluster database table

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>

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/{databaseName}/tables/{tableId}/undelete

Undelete a database table

Restores a previously deleted database table.

This operation can only be performed on tables that have been soft-deleted and are still within the recovery window.

Parameters

Path parameters

databaseName required string

The name of the database that the table belongs to

tableId required integer <int64>

The ID of the table to undelete

Example request Ask AI about this

curl --request PUT \
  "https://console.influxdata.com/api/v0/databases/{databaseName}/tables/{tableId}/undelete" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 The cluster database table was successfully undeleted

databaseName required string

The name of the cluster database

id required integer <int64>

The ID of the table

name required string

The name of the cluster database table

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>

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}/tables/{tableName}

Delete a database table

Parameters

Path parameters

databaseName required string

The name of the database that the database table belongs to

tableName required string

The name of the database table to delete

Example request Ask AI about this

curl --request DELETE \
  "https://console.influxdata.com/api/v0/databases/{databaseName}/tables/{tableName}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 The cluster database table was successfully deleted

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}/tables/{tableName}/rename

Rename a database table

Parameters

Path parameters

databaseName required string

The name of the database that the database table belongs to

tableName required string

The name of the database table to rename

Request body required

Content-Type: application/json

name required string

The name of the cluster database table

Example request Ask AI about this

curl --request PUT \
  "https://console.influxdata.com/api/v0/databases/{databaseName}/tables/{tableName}/rename" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "name": "NAME"
}'

Responses

200 The cluster database table was successfully renamed

databaseName required string

The name of the cluster database

id required integer <int64>

The ID of the table

name required string

The name of the cluster database table

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>

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!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB Clustered and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue

Tables

Create a database table

Parameters

Path parameters

Request body required

Responses

Undelete a database table

Parameters

Path parameters

Responses

Delete a database table

Parameters

Path parameters

Responses

Rename a database table

Parameters

Path parameters

Request body required

Responses

Support and feedback

InfluxDB OSS 2.9.0: API tokens are hashed by default

Key enhancements in Explorer 1.9

InfluxDB 3.11 is now available

InfluxDB 3 Enterprise 3.11: A significant performance upgrade for complex time series workloads

Telegraf Controller 1.1 now available

InfluxDB OSS 1.13.0 is now available

InfluxDB Enterprise 1.13.0 is now available

InfluxDB Docker latest tag changing to InfluxDB 3 Core

Create a database table

Parameters

Path parameters

Request body required

Responses

Undelete a database table

Parameters

Path parameters

Responses

Delete a database table

Parameters

Path parameters

Responses

Rename a database table

Parameters

Path parameters

Request body required

Responses

Related

Support and feedback

What is your InfluxDB cluster URL?

AWS

GCP

Azure

Default

Custom

Thank you for your feedback!

InfluxDB OSS 2.9.0: API tokens are hashed by default

Key enhancements in Explorer 1.9

InfluxDB 3.11 is now available

InfluxDB 3 Enterprise 3.11: A significant performance upgrade for complex time series workloads

Telegraf Controller 1.1 now available

InfluxDB OSS 1.13.0 is now available

InfluxDB Enterprise 1.13.0 is now available

InfluxDB Docker latest tag changing to InfluxDB 3 Core