MemPalace/mempalace · error · UnsupportedFilterError

where_document operator {key!r} not supported

Error message

where_document operator {key!r} not supported

What it means

Raised by sqlite_exact when a `where_document` filter uses an operator other than the supported `$contains`, `$and`, and `$or`. `where_document` matches the stored verbatim document text, and this backend only implements substring containment plus the two logical combinators. Any other `$`-prefixed key is rejected outright rather than guessed at.

Source

Thrown at mempalace/backends/sqlite_exact.py:231

def _matches_where_document(document: str, where_document: Optional[dict]) -> bool:
    if not where_document:
        return True
    if not isinstance(where_document, dict):
        return False
    for key, value in where_document.items():
        if key == "$contains":
            if str(value) not in document:
                return False
            continue
        if key == "$and":
            if not all(_matches_where_document(document, clause) for clause in value or []):
                return False
            continue
        if key == "$or":
            if not any(_matches_where_document(document, clause) for clause in value or []):
                return False
            continue
        raise UnsupportedFilterError(f"where_document operator {key!r} not supported")
    return True


def _validate_write_batch(
    *,
    documents: list[str],
    ids: list[str],
    metadatas: Optional[list[dict]],
    embeddings: Optional[list[list[float]]],
) -> None:
    n = len(ids)
    if len(documents) != n:
        raise ValueError(f"documents length {len(documents)} does not match ids length {n}")
    if metadatas is not None and len(metadatas) != n:
        raise ValueError(f"metadatas length {len(metadatas)} does not match ids length {n}")
    if embeddings is not None and len(embeddings) != n:
        raise ValueError(f"embeddings length {len(embeddings)} does not match ids length {n}")

View on GitHub (pinned to 06cb6987f0)

Solutions

  1. Rewrite the filter using only `$contains` under `$and`/`$or`, e.g. multiple `$contains` clauses under `$and` approximate an AND-of-substrings.
  2. For regex or negation, fetch with a `$contains` pre-filter (or none) and apply the regex in Python on the returned documents.
  3. If you require `$regex`, switch to the ChromaDB backend which supports richer where_document operators.

Example fix

# before
col.get(where_document={"$regex": "palace.*room"})

# after
rows = col.get(where_document={"$contains": "palace"})
result = [r for r in rows["documents"] if re.search(r"palace.*room", r)]
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_WD = {"$contains", "$and", "$or"}

def validate_where_document(wd: dict) -> None:
    for key in wd:
        if key not in SUPPORTED_WD:
            raise ValueError(f"where_document operator {key!r} unsupported; only $contains/$and/$or")

Type guard

def is_supported_where_document(wd: dict) -> bool:
    return all(k in {"$contains", "$and", "$or"} for k in wd)

Try / catch

try:
    col.get(where_document=wd)
except UnsupportedFilterError:
    text = wd.get("$regex") or next(iter(wd.values()), None)
    rows = col.get()
    results = [r for r in rows["documents"] if re.search(pattern, r)]

Prevention

When it happens

Trigger: Calling get/query/delete with `where_document={"$regex": "..."}`, `{"$eq": "..."}`, `{"$not": {"$contains": "..."}}`, or any operator outside {$contains, $and, $or}. Nested clauses inherit the same restriction.

Common situations: Porting ChromaDB `where_document` filters that use `$regex` or `$eq`; assuming full Mongo document-operator support; filters generated by an LLM or template that invents operator names.

Related errors

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/11067c8d0c816c20. Report an issue: GitHub.