Documentation

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]
  • Copy
  • Fill window

Arguments

  • CACHE_NAME: (Optional) A name to assign to the cache. If omitted, the CLI generates a name automatically.

Options

OptionDescription
-H--hostHost 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-cardinalityMaximum number of distinct value combinations to hold in the cache
--max-ageMaximum age of an entry in the cache entered as a human-readable duration–for example: 30d, 24h
--tls-caPath to a custom TLS certificate authority (for testing or self-signed certificates)
-h--helpPrint help information
--help-allPrint 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 VariableOption
INFLUXDB3_HOST_URL--host
INFLUXDB3_DATABASE_NAME--database
INFLUXDB3_AUTH_TOKEN--token

Prerequisites

Before creating a distinct value cache, make sure you:

  1. Create a database

  2. Create a 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.

influxdb3 create distinct_cache \
  --database 
DATABASE_NAME
\
--table
TABLE_NAME
\
--column
COLUMN_NAME
\
CACHE_NAME
  • Copy
  • Fill window

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
  • Copy
  • Fill window

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

Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

Now Generally Available

InfluxDB 3 Core and Enterprise

Start fast. Scale faster.

Get the Updates

InfluxDB 3 Core is an open source, high-speed, recent-data engine that collects and processes data in real-time and persists it to local disk or object storage. InfluxDB 3 Enterprise builds on Core’s foundation, adding high availability, read replicas, enhanced security, and data compaction for faster queries and optimized storage. A free tier of InfluxDB 3 Enterprise is available for non-commercial at-home or hobbyist use.

For more information, check out: