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

[Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml)

Manage table schemas in an InfluxDB 3 Core 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.

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

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

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.

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

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

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.

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.

#### Related

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