---
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/core/admin/distinct-value-cache/create/
estimated_tokens: 3198
product: InfluxDB 3 Core
version: core
---

# Create a Distinct Value Cache

Use the [`influxdb3 create distinct_cache` command](/influxdb3/core/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 Core

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.
    
-   **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 \
  --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](/influxdb3/core/api/table/#operation/PostConfigureDistinctCache)

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

```bash
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 Core
    
    authentication token
    
-   `TABLE_NAME`: the name of the table to associate the DVC with
    
-   `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/core/admin/distinct-value-cache/#important-things-to-know-about-the-distinct-value-cache).

#### Related

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

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