{"record":{"id":"693956172f30f7bc","repo":"MemPalace/mempalace","slug":"where-document-must-be-a-dict","errorCode":null,"errorMessage":"where_document must be a dict","messagePattern":"where_document must be a dict","errorType":"exception","errorClass":"UnsupportedFilterError","httpStatus":null,"severity":"error","filePath":"mempalace/backends/milvus.py","lineNumber":180,"sourceCode":"            raise UnsupportedFilterError(f\"operator {key!r} not supported by milvus\")\n        else:\n            parts.append(_translate_field(key, value))\n    return \" and \".join(part for part in parts if part)\n\n\ndef translate_where(where: Optional[dict]) -> str:\n    \"\"\"Translate the portable metadata where DSL into a Milvus filter string.\"\"\"\n    if not where:\n        return \"\"\n    return _translate_clause(where)\n\n\ndef translate_where_document(where_document: Optional[dict]) -> str:\n    \"\"\"Translate the portable document filter subset into a Milvus filter.\"\"\"\n    if not where_document:\n        return \"\"\n    if not isinstance(where_document, dict):\n        raise UnsupportedFilterError(\"where_document must be a dict\")\n    parts = []\n    for key, value in where_document.items():\n        if key == \"$contains\":\n            parts.append(f\"{FIELD_DOCUMENT} like {_like_value(value)}\")\n        elif key == \"$and\":\n            if not isinstance(value, list) or not value:\n                raise UnsupportedFilterError(\"$and requires a non-empty list of clauses\")\n            nested = [translate_where_document(item) for item in value]\n            parts.append(\"(\" + \" and \".join(part for part in nested if part) + \")\")\n        elif key == \"$or\":\n            if not isinstance(value, list) or not value:\n                raise UnsupportedFilterError(\"$or requires a non-empty list of clauses\")\n            nested = [translate_where_document(item) for item in value]\n            parts.append(\"(\" + \" or \".join(part for part in nested if part) + \")\")\n        else:\n            raise UnsupportedFilterError(f\"where_document operator {key!r} not supported\")\n    return \" and \".join(part for part in parts if part)\n","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/MemPalace/mempalace/blob/06cb6987f02610784fefbad4b2bd5d026d164ba6/mempalace/backends/milvus.py#L162-L198","documentation":"Raised by translate_where_document() when where_document is truthy but not a dict. The document filter only supports a small object shape ($contains, $and, $or), so passing a string, list, or other type fails with UnsupportedFilterError before translation. Falsy values (None, {}, \"\") are fine and produce an empty filter.","triggerScenarios":"where_document=\"$contains palace\" (operator string instead of dict), where_document=[\"palace\"], or a JSON-parsed value that is a list at the top level.","commonSituations":"Copy-pasting the substring directly instead of the {$contains: ...} wrapper; wrappers that accept shorthand strings; porting ChromaDB examples incorrectly.","solutions":["Always pass the object form: where_document={\"$contains\": \"palace\"}","Add a wrapper that converts a bare string s to {\"$contains\": s}","Validate JSON-decoded where_document payloads with isinstance checks before querying"],"exampleFix":"// before\nresults = collection.query(query_texts=[q], where_document=\"palace\")\n\n// after\nresults = collection.query(query_texts=[q], where_document={\"$contains\": \"palace\"})","handlingStrategy":"type-guard","validationCode":"def normalize_where_document(wd):\n    if not wd:\n        return None\n    if isinstance(wd, str):\n        return {\"$contains\": wd}\n    if not isinstance(wd, dict):\n        raise TypeError(f\"where_document must be a dict, got {type(wd).__name__}\")\n    return wd","typeGuard":"def is_where_document_dict(wd) -> bool:\n    return wd is None or wd == {} or isinstance(wd, dict)","tryCatchPattern":"from mempalace.backends.base import UnsupportedFilterError\ntry:\n    collection.query(query_texts=[q], where_document=wd, n_results=k)\nexcept UnsupportedFilterError as e:\n    if \"where_document must be a dict\" in str(e):\n        wd = {\"$contains\": str(wd)}\n        return collection.query(query_texts=[q], where_document=wd, n_results=k)\n    raise","preventionTips":["Always wrap substrings: {\"$contains\": s}","Add a string-shorthand adapter at your API boundary","Validate user-supplied where_document JSON schemas"],"tags":["milvus","filter","where-document","type-validation"],"backgroundTag":null,"analyzedSha":"06cb6987f02610784fefbad4b2bd5d026d164ba6","analyzedAt":"2026-08-15T03:03:36.213Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}