121 lines
5.7 KiB
Markdown
121 lines
5.7 KiB
Markdown
The `influxdb3 create distinct_cache` command creates a new distinct value cache for a specific table and column set in your {{< product-name >}} 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
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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 {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
|
| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on |
|
|
| | `--token` | _({{< req >}})_ Authentication token |
|
|
| `-t` | `--table` | _({{< req >}})_ Table to create the cache for |
|
|
| | `--columns` | _({{< req >}})_ 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) |
|
|
| `-h` | `--help` | Print help information |
|
|
| | `--help-all` | Print detailed help information |
|
|
|
|
> [!Important]
|
|
>
|
|
> #### 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:
|
|
|
|
1. [Create a database](/influxdb3/version/reference/cli/influxdb3/create/database/)
|
|
|
|
2. [Create a table](/influxdb3/version/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:
|
|
|
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
|
|
The database name
|
|
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}:
|
|
The name of the table to cache values from
|
|
- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}:
|
|
The name of the distinct value cache to create
|
|
- {{% code-placeholder-key %}}`COLUMN_NAME`{{% /code-placeholder-key %}}: The column to
|
|
cache distinct values from
|
|
|
|
You can also set environment variables (such as `INFLUXDB3_AUTH_TOKEN`) instead of passing options inline.
|
|
|
|
{{% code-placeholders "(DATABASE|TABLE|COLUMN|CACHE)_NAME" %}}
|
|
|
|
### Create a distinct cache for one column
|
|
|
|
Track unique values from a single column. This setup is useful for testing or simple use cases.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```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
|
|
```
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
## 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
|
|
|