apache/superset · error · ValueError

Operator '{operator_enum.value}' is not supported on relatio

Error message

Operator '{operator_enum.value}' is not supported on relationship column '{col_name}'. Use one of: eq, ne, in, nin, is_null, is_not_null.

What it means

Terminal ValueError from BaseDAO._apply_relationship_filter(): the operator supplied for a collection relationship is not one of eq, ne, in, nin, is_null, is_not_null. Scalar-oriented operators (sw, ew, like, gt, lt, ge, le, etc.) don't make sense on a collection of related rows, so they are rejected with an explicit message instead of producing a cryptic SQLAlchemy error at query time.

Source

Thrown at superset/daos/base.py:701

                    f"{type(value).__name__}. Use '{counterpart}' to match "
                    f"multiple related ids."
                )
            if operator_enum == ColumnOperatorEnum.eq:
                return query.filter(column.any(related_pk == value))
            return query.filter(~column.any(related_pk == value))
        if operator_enum == ColumnOperatorEnum.in_:
            values = value if isinstance(value, (list, tuple)) else [value]
            return query.filter(column.any(related_pk.in_(values)))
        if operator_enum == ColumnOperatorEnum.nin:
            values = value if isinstance(value, (list, tuple)) else [value]
            return query.filter(~column.any(related_pk.in_(values)))
        if operator_enum == ColumnOperatorEnum.is_null:
            # "has no related rows at all"
            return query.filter(~column.any())
        if operator_enum == ColumnOperatorEnum.is_not_null:
            # "has at least one related row"
            return query.filter(column.any())
        raise ValueError(
            f"Operator '{operator_enum.value}' is not supported on "
            f"relationship column '{col_name}'. Use one of: eq, ne, in, "
            f"nin, is_null, is_not_null."
        )

    @classmethod
    def get_filterable_columns_and_operators(cls) -> Dict[str, List[str]]:
        """
        Returns a dict mapping filterable columns (including hybrid/computed fields if
        present) to their supported operators. Used by MCP tools to dynamically expose
        filter options. Custom fields supported by the DAO but not present on the model
        should be documented here.
        """

        mapper = inspect(cls.model_cls)
        columns = {c.key: c for c in mapper.columns}
        # Collection relationships (m2m / one-to-many) are filterable via
        # `.any()` against the related model's primary key. Only advertise

View on GitHub (pinned to f4587218dd)

Solutions

Restrict relationship filters to eq/ne/in/nin/is_null/is_not_null (the error message lists them).
To filter by a related model's text field, query that model's DAO directly instead of through the relationship.
Fetch get_filterable_columns_and_operators() and honor the per-column operator list it advertises.

Example fix

# before
filters=[{"col": "editors", "opr": "like", "value": "bob"}]

# after
filters=[{"col": "editors", "opr": "is_not_null"}]  # or filter the related model's DAO directly

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_REL_OPS = {"eq", "ne", "in", "nin", "is_null", "is_not_null"}

def relationship_filters_valid(filters) -> bool:
    return all(f.get("opr") in SUPPORTED_REL_OPS for f in filters or [])

Type guard

def is_supported_rel_op(opr: str) -> bool:
    return opr in {"eq", "ne", "in", "nin", "is_null", "is_not_null"}

Try / catch

try:
    dao.find(query=", filters=filters)
except ValueError as ex:
    if 'not supported on relationship column' in str(ex):
        # drop or rewrite the offending operator, then retry
        ...

Prevention

Treat relationship columns as a distinct filter class in client code with its own operator whitelist.
For text searches on related entities, query the related DAO directly.
Encode the operator whitelist from the DAO's filterable-columns metadata, not from memory.

When it happens

Trigger: filters=[{"col": "<uselist relationship>", "opr": "like"|"sw"|"gt"|..., "value": ...}] passed to any DAO find/list call.

Common situations: Generic filter builders (API clients, MCP tools) applying the full ColumnOperatorEnum set uniformly to every column without distinguishing relationships from scalar columns.

Related errors

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/4791c2e380ce4995. Report an issue: GitHub.