Create a Distinct Value Cache

Use the influxdb3 create distinct_cache command 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 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.

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

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.

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