--- title: influxdb3 create distinct_cache description: The influxdb3 create distinct_cache command creates a new distinct value cache. url: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/ estimated_tokens: 1704 product: InfluxDB 3 Core version: core publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/ date: '2026-07-11T10:53:18+00:00' lastmod: '2026-07-11T10:53:18+00:00' --- The `influxdb3 create distinct_cache` command creates a new distinct value cache for a specific table and column set in your InfluxDB 3 Core instance. Use this command to configure a cache that tracks unique values in specified columns. You must provide the database, token, table, and columns. Optionally, you can specify a name for the cache. ## Usage ```bash influxdb3 create distinct_cache [OPTIONS] \ --database \ --token --table \ --columns \ [CACHE_NAME] ``` ## Arguments * **`CACHE_NAME`**: *(Optional)* A name to assign to the cache. If omitted, the CLI generates a name automatically. ## Options |Option| | Description | |------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Core server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-t` | `--table` | *(Required)* Table to create the cache for | | | `--columns` |*(Required)* Comma-separated list of columns to cache distinct values for–for example: `col1,col2,col3` (see [Metadata cache hierarchy](#metadata-cache-hierarchy))| | |`--max-cardinality`| Maximum number of distinct value combinations to hold in the cache | | | `--max-age` | Maximum age of an entry in the cache entered as a human-readable duration–for example: `30d`, `24h` | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | `--tls-no-verify` | Disable TLS certificate verification. **Not recommended in production.** Useful for testing with self-signed certificates | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | #### Metadata cache hierarchy The distinct value cache has a hierarchical structure with a level for each specified column. The order specified in the `--columns` option determines the order of levels, from top-to-bottom, of the cache hierarchy. ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Prerequisites Before creating a distinct value cache, make sure you: 1. [Create a database](/influxdb3/core/reference/cli/influxdb3/create/database/) 2. [Create a table](/influxdb3/core/reference/cli/influxdb3/create/table/) that includes the columns you want to cache 3. Have a valid authentication token ## Examples Before running the following commands, replace the placeholder values with your own: * `DATABASE_NAME`: The database name * `TABLE_NAME`: The name of the table to cache values from * `CACHE_NAME`: The name of the distinct value cache to create * `COLUMN_NAME`: The column to cache distinct values from You can also set environment variables (such as `INFLUXDB3_AUTH_TOKEN`) instead of passing options inline. ### Create a distinct cache for one column Track unique values from a single column. This setup is useful for testing or simple use cases. ```bash influxdb3 create distinct_cache \ --database DATABASE_NAME \ --table TABLE_NAME \ --column COLUMN_NAME \ CACHE_NAME ``` ### Create a hierarchical cache with constraints Create a distinct value cache for multiple columns. The following example tracks unique combinations of `room` and `sensor_id`, and sets limits on the number of entries and their maximum age. ```bash influxdb3 create distinct_cache \ --database my_test_db \ --table my_sensor_table \ --columns room,sensor_id \ --max-cardinality 1000 \ --max-age 30d \ my_sensor_distinct_cache ``` ## Common pitfalls * `--column` is not valid. Use `--columns`. * Tokens must be included explicitly unless set via `INFLUXDB3_AUTH_TOKEN` * Table and column names must already exist or be recognized by the engine | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Core server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -t | --table | ( Required ) Table to create the cache for | | | --columns | ( Required ) Comma-separated list of columns to cache distinct values for–for example: col1,col2,col3 (see Metadata cache hierarchy ) | | | --max-cardinality | Maximum number of distinct value combinations to hold in the cache | | | --max-age | Maximum age of an entry in the cache entered as a human-readable duration–for example: 30d , 24h | | | --tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | | --tls-no-verify | Disable TLS certificate verification. Not recommended in production. Useful for testing with self-signed certificates | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify |