pandas-dev/pandas · error · ValueError

query term is not valid [{self}]

Error message

query term is not valid [{self}]

What it means

Raised by FilterBinOp.evaluate in pandas.core.computation.pytables when self.is_valid is False - meaning the left-hand side of the operator is not present in env.queryables. is_valid checks `self.lhs.value in self.queryables`. This is the filter-path counterpart to the NameError at pytables.py:91: the column name does not resolve to a queryable field. It is a ValueError and includes the offending term in [{self}].

Source

Thrown at pandas/core/computation/pytables.py:340

    def invert(self) -> Self:
        """invert the filter"""
        if self.filter is not None:
            self.filter = (
                self.filter[0],
                self.generate_filter_op(invert=True),
                self.filter[2],
            )
        return self

    def format(self):
        """return the actual filter format"""
        return [self.filter]

    # error: Signature of "evaluate" incompatible with supertype "BinOp"
    def evaluate(self) -> Self | None:  # type: ignore[override]
        if not self.is_valid:
            raise ValueError(f"query term is not valid [{self}]")

        rhs = self.conform(self.rhs)
        values = list(rhs)

        if self.op not in ["==", "!="]:
            if not self.is_in_table:
                raise TypeError(
                    f"passing a filterable condition to a non-table indexer [{self}]"
                )
            return None

        if self.is_in_table and len(values) <= self._max_selectors:
            return None
        filter_op = self.generate_filter_op()
        self.filter = (self.lhs.value, filter_op, Index(values))
        return self

    def generate_filter_op(self, invert: bool = False):

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Declare the column as a data_column at write time: store.put('df', df, format='table', data_columns=['colname']).
2. List available queryables to confirm spelling: print(store.get_storer('df').data_columns).
3. If you only need filtering once, read the frame and filter in pandas: df[df['col'].isin([1,2,3])].
4. Check whether you are querying the correct key/group inside the HDF file (store.keys()).

Example fix

# before
store.select('df', where='city == ["NYC", "LA"]')  # ValueError: query term is not valid

# after
df.to_hdf(path, 'df', format='table', data_columns=['city'])
store.select('df', where='city == ["NYC", "LA"]')

def assert_filter_column(store, key, column):
    storer = store.get_storer(key)
    data_cols = list(storer.data_columns or [])
    idx_cols = [getattr(a, 'name', None) for a in (storer.index_axes or [])]
    if column not in data_cols + idx_cols:
        raise ValueError(f'{column!r} not queryable; data_columns={data_cols}')

def is_filterable_column(store, key, column) -> bool:
    try:
        storer = store.get_storer(key)
        return column in (storer.data_columns or [])
    except Exception:
        return False

try:
    store.select('df', where=f'{col} == [1,2,3]')
except ValueError as e:
    if 'query term is not valid' in str(e):
        df = store.get('df')
        result = df[df[col].isin([1, 2, 3])]
    else:
        raise

When it happens

Trigger: store.select('df', where='unknown_col == [1,2,3]') where 'unknown_col' is not a data_column or index. Also when an equality list is built against a column that was never declared queryable.

Common situations: Schema mismatch between writer and reader; column renamed; querying a column that exists in the frame but was not stored as a data_column; copy-paste errors in the where string.

Related errors

• name {self.name!r} is not defined
• arithmetic operations are not supported inside an HDFStore '
• Cannot compare {conv_val} of type {type(conv_val)} to {kind}
• passing a filterable condition to a non-table indexer [{self
• unable to collapse Joint Filters

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/bd3275918ba99e3a. Report an issue: GitHub.