---
title: Table
description: Manage table schemas in an InfluxDB 3 Enterprise database.
url: https://docs.influxdata.com/influxdb3/enterprise/api/table/
estimated_tokens: 3471
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/api/table/
---

[Download InfluxDB 3 Enterprise API Spec](/openapi/influxdb3-enterprise-openapi.yml)

Manage table schemas in an InfluxDB 3 Enterprise database.

POST`/api/v3/configure/distinct_cache`

### Create distinct cache

Creates a distinct cache for a table.

#### Request bodyrequired

Content-Type:`application/json`

`columns`requiredstring[]

`db`requiredstring

`max_age`integer

Optional maximum age in seconds.

`max_cardinality`integer

Optional maximum cardinality.

`name`string

Optional cache name.

`node_spec`string or object

Specifies which nodes in a multi-node InfluxDB 3 Enterprise cluster
handle the cache or trigger.
Accepts the string `all` or an object that lists specific node IDs.
If omitted, defaults to `all`.

Default:`all`

Example:`"all"`

One of:string

Create the cache or trigger on all nodes in the cluster.

Allowed:`all`

Or:object

Create the cache or trigger only on the specified nodes.

`nodes`requiredstring[]

Node IDs (the `--node-id` value each node was started with).
Each node must exist and must run in `process` mode.

`table`requiredstring

Example request body

```json
{
  "columns": [
    "tag1",
    "tag2"
  ],
  "db": "mydb",
  "max_age": 3600,
  "max_cardinality": 1000,
  "table": "mytable"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/configure/distinct_cache" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"columns":["tag1","tag2"],"db":"mydb","max_age":3600,"max_cardinality":1000,"table":"mytable"}'
```

#### Responses

201Success. The distinct cache has been created.

400

Bad request.

The server responds with status `400` if the request would overwrite an existing cache with a different configuration.

409Conflict. A distinct cache with this configuration already exists.

DELETE`/api/v3/configure/distinct_cache`

### Delete distinct cache

Deletes a distinct cache.

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

`table`requiredstring

The name of the table containing the distinct cache.

`name`requiredstring

The name of the distinct cache to delete.

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/distinct_cache?db=DB&table=TABLE&name=NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success. The distinct cache has been deleted.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Cache not found.

POST`/api/v3/configure/last_cache`

### Create last cache

Creates a last cache for a table.

#### Request bodyrequired

Content-Type:`application/json`

`count`integer

Optional count.

`db`requiredstring

`key_columns`string[]

Optional list of key columns.

`name`string

Optional cache name.

`node_spec`string or object

Specifies which nodes in a multi-node InfluxDB 3 Enterprise cluster
handle the cache or trigger.
Accepts the string `all` or an object that lists specific node IDs.
If omitted, defaults to `all`.

Default:`all`

Example:`"all"`

One of:string

Create the cache or trigger on all nodes in the cluster.

Allowed:`all`

Or:object

Create the cache or trigger only on the specified nodes.

`nodes`requiredstring[]

Node IDs (the `--node-id` value each node was started with).
Each node must exist and must run in `process` mode.

`table`requiredstring

`ttl`integer

Optional time-to-live in seconds.

`value_columns`string[]

Optional list of value columns.

Example request body

```json
{
  "count": 100,
  "db": "mydb",
  "key_columns": [
    "tag1"
  ],
  "table": "mytable",
  "ttl": 3600,
  "value_columns": [
    "field1"
  ]
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/configure/last_cache" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"count":100,"db":"mydb","key_columns":["tag1"],"table":"mytable","ttl":3600,"value_columns":["field1"]}'
```

#### Responses

201Success. Last cache created.

400Bad request. A cache with this name already exists or the request is malformed.

401Unauthorized access.

`data`object

`error`string

404Cache not found.

DELETE`/api/v3/configure/last_cache`

### Delete last cache

Deletes a last cache.

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

`table`requiredstring

The name of the table containing the last cache.

`name`requiredstring

The name of the last cache to delete.

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/last_cache?db=DB&table=TABLE&name=NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success. The last cache has been deleted.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Cache not found.

POST`/api/v3/configure/table`

### Create a table

Creates a new table within a database.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

`fields`requiredobject[]

`name`requiredstring

`type`requiredstring

Allowed:`utf8`, `int64`, `uint64`, `float64`, `bool`

`retention_period`string

The retention period for the table. Specifies how long data in this table should be retained.
Use duration format (for example, “1d”, “1h”, “30m”, “7d”).

Example:`"30d"`

`table`requiredstring

`tags`requiredstring[]

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "fields": [
    {
      "name": "NAME",
      "type": "utf8"
    }
  ],
  "retention_period": "30d",
  "table": "TABLE",
  "tags": [
    "TAGS"
  ]
}'
```

#### Responses

200Success. The table has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database not found.

PATCH`/api/v3/configure/table`

### Add columns to a table

Adds tag and field columns to an existing table.

The change is additive: a column that already exists with the requested type is left unchanged.
No other table settings are modified.
The request must name at least one tag or field.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

`fields`object[]

`name`requiredstring

`type`requiredstring

Allowed:`utf8`, `int64`, `uint64`, `float64`, `bool`

`table`requiredstring

`tags`string[]

Example request[Ask AI about this](#)

```sh
curl --request PATCH \
  "https://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "fields": [
    {
      "name": "NAME",
      "type": "utf8"
    }
  ],
  "table": "TABLE",
  "tags": [
    "TAGS"
  ]
}'
```

#### Responses

200Success. The columns have been added to the table. The response body is empty.

400Bad request. The request names no tags or fields, or is otherwise invalid.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

DELETE`/api/v3/configure/table`

### Delete a table

Soft deletes a table.
The table is scheduled for deletion and unavailable for querying.
Use the `hard_delete_at` parameter to schedule a hard deletion.
Use the `data_only` parameter to delete data while preserving the table schema and resources.

#### Deleting a table cannot be undone

Deleting a table is a destructive action.
Once a table is deleted, data stored in that table cannot be recovered.

#### Soft-deleted tables keep a renamed, visible entry until hard deletion

A soft delete renames the table to `<table_name>-<deleted_at_timestamp>` instead of removing it.
Until the table is hard deleted, this renamed entry still appears in `SHOW TABLES` output and in`information_schema.tables` queries. Filter out names that end in a deleted-at timestamp to account for
these renamed entries when listing or counting tables.

Deleting an already-deleted table returns `409 Conflict`. There’s no API to remove the renamed entry
directly; only a scheduled or immediate (`hard_delete_at=now`) hard deletion removes it.

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

`table`requiredstring

`data_only`boolean

Delete only data while preserving the table schema and all associated resources
(last value caches, distinct value caches).
When `false` (default), the entire table is deleted.

`hard_delete_at`string \<date-time\>

Schedule the table for hard deletion at the specified time.
If not provided, the table will be soft deleted.
Use ISO 8601 format (for example, “2025-12-31T23:59:59Z”).

Also accepts special string values:

* `now` — hard delete immediately
* `never` — soft delete only (default behavior)
* `default` — use the system default hard deletion time

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/table?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success (no content). The table has been deleted.

401Unauthorized access.

`data`object

`error`string

404Table not found.

409Conflict. The table is already deleted.

POST`/api/v3/enterprise/configure/file_index`

### Create a file index

Creates a file index for a database or table.

A file index improves query performance by indexing data files based on specified columns, enabling the query engine to skip irrelevant files during query execution.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`columns`requiredstring[]

The columns to use for the file index.

`db`requiredstring

The database name.

`table`string

The table name. If omitted, the file index applies to the database.

Example request body

```json
{
  "columns": [
    "tag1",
    "tag2"
  ],
  "db": "mydb",
  "table": "mytable"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/file_index" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"columns":["tag1","tag2"],"db":"mydb","table":"mytable"}'
```

#### Responses

200Success. The file index has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

DELETE`/api/v3/enterprise/configure/file_index`

### Delete a file index

Deletes a file index from a database or table.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

The database name.

`table`string

The table name. If omitted, deletes the database-level file index.

Example request body

```json
{
  "db": "mydb",
  "table": "mytable"
}
```

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/configure/file_index" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"db":"mydb","table":"mytable"}'
```

#### Responses

200Success. The file index has been deleted.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database, table, or file index not found.

POST`/api/v3/enterprise/configure/table/retention_period`

### Set table retention period

Sets or updates the retention period for a specific table.

Use this endpoint to control how long data in a table is retained independently of the database-level retention period.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update table](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)

#### Parameters

##### Query parameters

`db`requiredstring

The database name.

`table`requiredstring

The table name.

`duration`requiredstring

The retention period as a human-readable duration (for example, “30d”, “24h”, “1y”).

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/table/retention_period?db=DB&table=TABLE&duration=DURATION" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success. The table retention period has been set.

400Bad request. Invalid duration format.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

DELETE`/api/v3/enterprise/configure/table/retention_period`

### Clear table retention period

Removes the retention period from a specific table, reverting to the database-level retention period (or infinite retention if no database-level retention is set).

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update table](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)

#### Parameters

##### Query parameters

`db`requiredstring

The database name.

`table`requiredstring

The table name.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/configure/table/retention_period?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success. The table retention period has been cleared.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

#### Related

* [Manage tables](/influxdb3/enterprise/admin/tables/)
* [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)