influxdata/influxdb · error · CacheError

cannot use a column of type

Error message

cannot use a column of type {attempted} in a distinct value cache, only tags and string fields can be used

What it means

CacheError::NonTagOrStringColumn is returned when a distinct value cache is attempted on a column whose InfluxColumnType is neither a tag nor a string field. Distinct caches only work over string-valued data; numeric, timestamp, or boolean columns are rejected.

Solutions

1. Choose only tag columns or string field columns for the distinct cache
2. Inspect the table schema (schema::Schema) and filter candidate columns to InfluxColumnType::Tag and String field variants before creating the cache
3. Fix the SQL statement to name a string-valued column

Example fix

// before
let cols = vec![numeric_field_col_id];
provider.new_cache(table_id, cols)?;
// after
let ok = schema.fields().iter().any(|f| matches!(f.data_type(), InfluxColumnType::Tag | InfluxColumnType::Field(InfluxFieldType::String)));
assert!(ok, "column must be a tag or string field");

fn column_is_tag_or_string(col: &schema::Column) -> bool {
    matches!(col.data_type, InfluxColumnType::Tag | InfluxColumnType::Field(InfluxFieldType::String))
}

// Rust
match provider.new_cache(table_id, cols) {
    Err(ProviderError::Cache(CacheError::NonTagOrStringColumn { attempted })) => {
        bail!("column type {attempted:?} not allowed in distinct cache; use tags or string fields")
    }
    other => other,
}

When it happens

Trigger: CREATE DISTINCT CACHE or new_cache with a column id that resolves to a field of type integer/uint/float/boolean/timestamp instead of tag or string field.

Common situations: Misremembering which columns are tags; schema changes turned a former tag into a numeric field; hand-written cache configs referencing the wrong column.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• must pass a non-empty set of column ids
• cache error
• cannot overwrite an an existing cache
• column type mismatch for column
• error in distinct value cache

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/2f85066c92876abd. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_cache/src/distinct_cache/cache.rs:26

use arrow::{
    array::{ArrayRef, RecordBatch, StringViewBuilder},
    datatypes::{DataType, Field, SchemaBuilder, SchemaRef},
    error::ArrowError,
};
use indexmap::IndexMap;
use influxdb3_catalog::catalog::legacy;
use influxdb3_catalog::catalog::{MaxAge, MaxCardinality, TableDefinition};
use influxdb3_id::{ColumnId, ColumnIdentifier};
use influxdb3_wal::{FieldData, Row};
use iox_time::TimeProvider;
use observability_deps::tracing::debug;
use schema::{InfluxColumnType, InfluxFieldType};

#[derive(Debug, thiserror::Error)]
pub enum CacheError {
    #[error("must pass a non-empty set of column ids")]
    EmptyColumnSet,
    #[error(
        "cannot use a column of type {attempted} in a distinct value cache, only \
                    tags and string fields can be used"
    )]
    NonTagOrStringColumn { attempted: InfluxColumnType },
    #[error("cannot overwrite an an existing cache: {message}")]
    ConfigurationMismatch { message: String },
    #[error("unexpected error: {0}")]
    Unexpected(#[from] anyhow::Error),
}

/// A cache for storing distinct values for a set of columns in a table
#[derive(Debug)]
pub(crate) struct DistinctCache {
    time_provider: Arc<dyn TimeProvider>,
    /// The maximum number of unique value combinations in the cache
    max_cardinality: usize,
    /// The maximum age for entries in the cache
    max_age: Duration,

View on GitHub (pinned to 06200ef96b)