pandas-dev/pandas · error · TypeError

where must be passed as a string, PyTablesExpr, or…

Error message

where must be passed as a string, PyTablesExpr, or list-like of PyTablesExpr

What it means

Raised by _validate_where when the `where` argument to a PyTablesExpr / HDFStore.select is not a str, a PyTablesExpr, or a list-like of those. The pytables query engine needs a string predicate (or a composable PyTablesExpr), so unsupported types (dict, int, None, a single scalar) are rejected early with a TypeError.

Solutions

Pass where as a query string: store.select('df', where="A > 5").
To combine multiple clauses, pass a list-like of PyTablesExpr or join strings with '&': where="(A>5) & (B<2)".
If you have a dict of column->value, convert it to a query string first (e.g. ' & '.join(f'{k}=={v!r}' for k,v in d.items())).

Example fix

// before
store.select('df', where={'A': 5, 'B': 2})

// after
store.select('df', where="A == 5 & B == 2")

Defensive patterns

Strategy: type-guard

Validate before calling

from pandas.core.dtypes.common import is_list_like
from pandas.core.computation.pytables import PyTablesExpr

def valid_where(w):
    return isinstance(w, (str, PyTablesExpr)) or (is_list_like(w) and all(isinstance(x, (str, PyTablesExpr)) for x in w))

Type guard

from pandas.core.computation.pytables import PyTablesExpr
from pandas.core.dtypes.common import is_list_like

def is_valid_where(w) -> bool:
    if isinstance(w, (str, PyTablesExpr)):
        return True
    return is_list_like(w) and all(isinstance(x, (str, PyTablesExpr)) for x in w)

Try / catch

try:
    store.select('df', where=w)
except TypeError as err:
    if 'where must be passed' in str(err):
        w = ' & '.join(f'{k}=={v!r}' for k, v in w.items()) if isinstance(w, dict) else str(w)
        store.select('df', where=w)
    else:
        raise

Prevention

Always build where clauses as query strings, never dicts.
Validate where with is_valid_where before calling select in library code.
Document the where contract in your wrapper functions.

When it happens

Trigger: Calling store.select('df', where={'A': 5}) (passing a dict instead of a query string); passing where=5 or where=None; passing a single bare column name that is not list-like; passing a numpy array of PyTablesExpr that is not recognised as list-like.

Common situations: Confusing the pytables where API (which takes a query string like 'A>5') with boolean-indexing dicts or DataFrame.query kwargs; migrating code from dict-based filters; passing a Python set or tuple expecting it to be treated as a value list (it is list-like, but the elements must be PyTablesExpr).

Related errors

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

Appendix: source

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

    """
    Validate that the where statement is of the right type.

    The type may either be String, Expr, or list-like of Exprs.

    Parameters
    ----------
    w : String term expression, Expr, or list-like of Exprs.

    Returns
    -------
    where : The original where clause if the check was successful.

    Raises
    ------
    TypeError : An invalid data type was passed in for w (e.g. dict).
    """
    if not (isinstance(w, (PyTablesExpr, str)) or is_list_like(w)):
        raise TypeError(
            "where must be passed as a string, PyTablesExpr, "
            "or list-like of PyTablesExpr"
        )

    return w


class PyTablesExpr(expr.Expr):
    """
    Hold a pytables-like expression, comprised of possibly multiple 'terms'.

    Parameters
    ----------
    where : string term expression, PyTablesExpr, or list-like of PyTablesExprs
    queryables : a "kinds" map (dict of column name -> kind), or None if column
        is non-indexable
    encoding : an encoding that will encode the query terms

View on GitHub (pinned to 3b7651241d)