---
title: Create a Distinct Value Cache
description: Use the influxdb3 create distinct_cache command to create a Distinct Value Cache.
url: https://docs.influxdata.com/influxdb3/enterprise/admin/distinct-value-cache/create/
estimated_tokens: 1159
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/admin/distinct-value-cache/create/
date: '2025-08-29T08:44:59-06:00'
lastmod: '2025-08-29T08:44:59-06:00'
---

Use the [`influxdb3 create distinct_cache` command](/influxdb3/enterprise/reference/cli/influxdb3/create/distinct_cache/)to create a Distinct Value Cache (DVC). Provide the following:

* **Database** (`-d`, `--database`): *(Required)* The name of the database to
  associate the DVC with. You can also use the `INFLUXDB3_DATABASE_NAME`environment variable to specify the database.

* **Token** (`--token`): *(Required)* Your InfluxDB 3 Enterprise
  admin
  authentication token.
  You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify
  the token.

* **Table** (`-t`, `--table`): *(Required)* The name of the table to
  associate the DVC with.

* **Node specification** (`-n`, `--node-spec`): Specify which nodes the DVC
  should be configured on.

* **Columns** (`--columns`): *(Required)* Specify which columns to cache
  distinct values for. These are typically tag columns but can also be
  string fields.

* **Maximum cardinality** (`--max-cardinality`): Specify the maximum number of
  distinct value combinations to store in the cache. The default maximum
  cardinality is `100000`.

* **Maximum age** (`--max-age`): Specify the maximum age of distinct values to
  keep in the DVC in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form. The default maximum age is `24 hours`.

* **Cache name**: A unique name for the cache. If you don’t provide one,
  InfluxDB automatically generates a cache name for you.

```bash
influxdb3 create distinct_cache \
  --database DATABASE_NAME \
  --token AUTH_TOKEN \
  --table TABLE_NAME \
  --node-spec "nodes:NODE_LIST" \
  --columns COLUMNS \
  --max-cardinality MAX_CARDINALITY \
  --max-age MAX_AGE \
  DVC_NAME
```

## Use the HTTP API

To use the HTTP API to create a Distinct Value Cache, send a `POST` request to the `/api/v3/configure/distinct_cache` endpoint.

```
POST /api/v3/configure/distinct_cache
```

```bash
curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --json '{
    "db": "DATABASE_NAME",
    "table": "TABLE_NAME",
    "name": "DVC_NAME",
    "columns": ["COLUMNS"],
    "max_cardinality": MAX_CARDINALITY,
    "max_age": MAX_AGE
  }'
```

### Example

```
curl -X POST "https://localhost:8181/api/v3/configure/distinct_cache" \
  --header "Authorization: Bearer 00xoXX0xXXx0000XxxxXx0Xx0xx0" \
  --json '{
    "db": "example-db",
    "table": "wind_data",
    "name": "windDistinctCache",
    "columns": ["country", "county", "city"],
    "max_cardinality": 10000,
    "max_age": 86400
  }'
```

**Response codes:**

* `201` : Success. The distinct cache has been created.
* `204` : Not created. A distinct cache with this configuration already exists.
* `400` : Bad request.

#### API parameter differences

* **Columns format**: The API uses a JSON array (`["country", "county", "city"]`)
  instead of the CLI’s comma-delimited format (`country,county,city`).
* **Maximum age format**: The API uses seconds (`86400`) instead of the CLI’s[humantime format](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) (`24h`, `1 day`).

Replace the following:

* `DATABASE_NAME`:
  the name of the database to associate the DVC with

* `AUTH_TOKEN`:
  your InfluxDB 3 Enterprise admin

  authentication token

* `TABLE_NAME`:
  the name of the table to associate the DVC with

* `NODE_LIST`:
  a comma-delimited list of node IDs to configure the DVC on–for example:`node-01,node-02`.

* `COLUMNS`:
  a comma-delimited list of columns to cache distinct values for–for example:`country,county,city`

* `MAX_CARDINALITY`:
  the maximum number of distinct value combinations to cache–for example: `10000`

* `MAX_AGE`:
  the maximum age of distinct values to keep in the cache in[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)form–for example: `6h`, `1 day`, `1 week`

* `DVC_NAME`:
  a unique name for the DVC

The cache imports the distinct values from the table and starts caching them.

#### DVC size and persistence

The DVC is stored in memory, so it’s important to consider the size and
persistence of the cache. For more information, see[Important things to know about the Distinct Value Cache](/influxdb3/enterprise/admin/distinct-value-cache/#important-things-to-know-about-the-distinct-value-cache).

#### Related

* [influxdb3 create distinct\_cache](/influxdb3/enterprise/reference/cli/influxdb3/create/distinct_cache/)
* [Manage Distinct Value Caches with InfluxDB 3 Explorer](/influxdb3/explorer/manage-caches/distinct-value-caches/)

[cache](/influxdb3/enterprise/tags/cache/)