pandas-dev/pandas · error · ValueError

query term is not valid

Error message

query term is not valid [{self}]

What it means

Raised in FilterBinOp.evaluate when self.is_valid is False at the start of evaluation. FilterBinOp represents a filterable term (used when the number of comparison values exceeds _max_selectors so PyTables uses an isin-style filter instead of an OR chain). is_valid encapsulates whether the term has a usable lhs/rhs and is_in_table state; an invalid term cannot produce a filter.

Solutions

  1. Ensure the queried column is a registered data_column: store.put('df', df, format='table', data_columns=['A']).
  2. Reduce the filter to a simple equality/in condition that FilterBinOp can validate.
  3. Read the data and filter in pandas: df = store.get('df'); df[df['A'].isin(values)].
  4. Inspect the term with print(store.select_as_coordinates(...)) on a minimal condition to isolate which side is invalid.

Example fix

// before
store.put('df', df, format='table')  # no data_columns
store.select('df', where='A in [1,2,3]')

// after
store.put('df', df, format='table', data_columns=['A'])
store.select('df', where='A in [1,2,3]')
Defensive patterns

Strategy: validation

Validate before calling

def filter_term_valid(store, key: str, column: str) -> bool:
    storer = store.get_storer(key)
    return column in (storer.data_columns or [])

assert filter_term_valid(store, 'df', 'A'), 'A must be a data_column to use as a filter term'

Type guard

def is_valid_filter_term(store, key: str, column: str) -> bool:
    storer = store.get_storer(key)
    return column in set(storer.data_columns or [])

Try / catch

try:
    store.select('df', where='A in huge_list')
except ValueError as e:
    if 'query term is not valid' in str(e):
        df = store.get('df')
        df[df['A'].isin(huge_list)]
    else:
        raise

Prevention

When it happens

Trigger: store.select('df', where='A in [huge_list]') when the FilterBinOp was constructed from a malformed term — e.g. the lhs column is missing from queryables, or the rhs failed conversion upstream. Also from inverting or combining filters in ways that leave the op without a valid lhs.value.

Common situations: Querying a column that exists in the table but was not declared a data_column (degraded filter). Using a filter term after the underlying Term failed to resolve. Internal calls that build a FilterBinOp manually without setting is_valid.

Related errors

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

Appendix: 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 3b7651241d)