---
title: Table
description: Manage table schemas in an InfluxDB 3 Enterprise database.
url: https://docs.influxdata.com/influxdb3/enterprise/api/table/
estimated_tokens: 2969
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

`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

`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": [],
  "retention_period": "30d",
  "table": "TABLE",
  "tags": [
    "example"
  ]
}'
```

#### Responses

200Success. The table has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database not found.

PUT`/api/v3/configure/table`

### Update a table

Updates table configuration, such as retention period.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

The name of the database containing the table.

`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

The name of the table to update.

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "https://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "retention_period": "30d",
  "table": "TABLE"
}'
```

#### Responses

200Success. The table has been updated.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Table 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.

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

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