Tables

Download InfluxDB Cloud Dedicated API Spec
Manage tables in an InfluxDB 3 Cloud Dedicated database, including creating tables with custom column schemas.
POST /accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}/tables

Create a database table

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 to a table, you must manually create the 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.

Parameters

Path parameters
accountId required string
The ID of the account to create the database table for
clusterId required string
The ID of the cluster to create the database table for
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 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.

Example request Ask AI about this
curl --request POST \
  "https://console.influxdata.com/api/v0/accounts/{accountId}/clusters/{clusterId}/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
accountId required string <uuid>
clusterId required string <uuid>
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 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.

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/{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
accountId required string
The ID of the account that the database table belongs to
clusterId required string
The ID of the cluster that the database table belongs to
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/accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}/tables/{tableId}/undelete" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 The cluster database table was successfully undeleted
accountId required string <uuid>
clusterId required string <uuid>
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 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.

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

Delete a database table

Parameters

Path parameters
accountId required string
The ID of the account that the database table belongs to
clusterId required string
The ID of the cluster that the database table belongs to
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/accounts/{accountId}/clusters/{clusterId}/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 /accounts/{accountId}/clusters/{clusterId}/databases/{databaseName}/tables/{tableName}/rename

Rename a database table

Parameters

Path parameters
accountId required string
The ID of the account that the database table belongs to
clusterId required string
The ID of the cluster that the database table belongs to
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/accounts/{accountId}/clusters/{clusterId}/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
accountId required string <uuid>
clusterId required string <uuid>
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 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.

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!