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

[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 body required

Content-Type: `application/json`

`columns` required string\[\]

`db` required string

`max_age` integer

Optional maximum age in seconds.

`max_cardinality` integer

Optional maximum cardinality.

`name` string

Optional cache name.

`node_spec` string

`table` required string

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

201 Success. 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.

409 Conflict. 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` required string

The name of the database.

`table` required string

The name of the table containing the distinct cache.

`name` required string

The name of the distinct cache to delete.

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"
```

#### Responses

200 Success. The distinct cache has been deleted.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

404 Cache not found.

POST `/api/v3/configure/last_cache`

### Create last cache

Creates a last cache for a table.

#### Request body required

Content-Type: `application/json`

`count` integer

Optional count.

`db` required string

`key_columns` string\[\]

Optional list of key columns.

`name` string

Optional cache name.

`node_spec` string

`table` required string

`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

201 Success. Last cache created.

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

401 Unauthorized access.

`data` object

`error` string

404 Cache not found.

DELETE `/api/v3/configure/last_cache`

### Delete last cache

Deletes a last cache.

#### Parameters

##### Query parameters

`db` required string

The name of the database.

`table` required string

The name of the table containing the last cache.

`name` required string

The name of the last cache to delete.

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"
```

#### Responses

200 Success. The last cache has been deleted.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

404 Cache not found.

POST `/api/v3/configure/table`

### Create a table

Creates a new table within a database.

#### Request body required

Content-Type: `application/json`

`db` required string

`fields` required object\[\]

`name` required string

`type` required string

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` required string

`tags` required string\[\]

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

200 Success. The table has been created.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

404 Database not found.

PUT `/api/v3/configure/table`

### Update a table

Updates table configuration, such as retention period.

#### Request body required

Content-Type: `application/json`

`db` required string

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` required string

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

200 Success. The table has been updated.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

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

#### Parameters

##### Query parameters

`db` required string

The name of the database.

`table` required string

`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

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

401 Unauthorized access.

`data` object

`error` string

404 Table 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 body required

Content-Type: `application/json`

`columns` required string\[\]

The columns to use for the file index.

`db` required string

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

200 Success. The file index has been created.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

404 Database 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 body required

Content-Type: `application/json`

`db` required string

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

200 Success. The file index has been deleted.

400 Bad request.

401 Unauthorized access.

`data` object

`error` string

404 Database, 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` required string

The database name.

`table` required string

The table name.

`duration` required string

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

204 Success. The table retention period has been set.

400 Bad request. Invalid duration format.

401 Unauthorized access.

`data` object

`error` string

404 Database 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` required string

The database name.

`table` required string

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

204 Success. The table retention period has been cleared.

401 Unauthorized access.

`data` object

`error` string

404 Database or table not found.

#### Related

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