influxdb3 create distinct_cache
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
influxdb3 create distinct_cache [OPTIONS] \
--database <DATABASE_NAME> \
--token <AUTH_TOKEN>
--table <TABLE> \
--columns <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) | |
--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) | |
-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 |
Prerequisites
Before creating a distinct value cache, make sure you:
Create a table that includes the columns you want to cache
Have a valid authentication token
Examples
Before running the following commands, replace the placeholder values with your own:
DATABASE_NAME: The database nameTABLE_NAME: The name of the table to cache values fromCACHE_NAME: The name of the distinct value cache to createCOLUMN_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.
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.
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
--columnis 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
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Core and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.