In Haystack, how do you express AND/OR conditions in a metadata filter?

## Two node types, arbitrarily nested Everything in a Haystack filter is one of two dict shapes. **Comparison node** — exactly three keys: `{"field": "meta.type", "operator": "==", "value": "article"}` **Logical node** — exactly two keys: `{"operator": "AND", "conditions": [ <node>, <node>, ... ]}` Because `conditions` accepts nodes of either kind, nesting is free: an `OR` of two `AND`s is just a logical node whose conditions are logical nodes. There is no special syntax for grouping and no operator precedence to remember — the structure *is* the precedence. ## The operators Comparison operators are `==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not in`. The membership operators take a list as their `value`: `{"field": "meta.type", "operator": "in", "value": ["report", "memo"]}` means "the document's type is one of these". Note the direction — it reads as *field in value*, so `value` is always the collection. Logical operators are `"AND"`, `"OR"`, `"NOT"`, written uppercase as strings. ## The meta. prefix This is the single most common mistake. `Document` has top-level attributes (`content`, `id`, `score`, `embedding`) and a `meta` dict for everything you attached. Metadata fields must be addressed through that dict: `"meta.year"`, `"meta.file_path"`, `"meta.tenant_id"`. Writing `{"field": "year", ...}` is asking about a top-level Document field named `year`, which does not exist — depending on the store you get either an error or, worse, an empty result set that looks like "retrieval found nothing" rather than "your filter is malformed". The fastest way to catch this: run the filter directly against the store with `filter_documents(filters=...)` and check the count before you ever put it in a pipeline. `filter_documents` performs no ranking, no embedding and no retrieval — it is pure metadata selection, which makes it the right debugging tool. ## Where filters are used The same dict is accepted in three places: `DocumentStore.filter_documents(filters=...)` for direct selection, retrievers' `filters` run-time input, and — on most retrievers — a `filters` constructor argument that acts as a default. Where both a constructor default and a run-time value exist, the run-time value is what applies to that run, so the constructor form is best reserved for an invariant such as a tenant scope you never want overridden by accident. ## What the store does with it Haystack defines the filter format; each `DocumentStore` implementation translates it into its backend's own query language — Elasticsearch/OpenSearch query DSL, a Qdrant filter, a SQL `WHERE` clause for pgvector, and so on. `InMemoryDocumentStore` evaluates it in Python. Two consequences follow. First, portability is good but not absolute: comparison semantics on missing keys, on `None`, and on nested meta paths can differ between backends, so a filter that behaves one way in tests against the in-memory store deserves a check against the real one. Second, filter performance is entirely the backend's problem — a filter over an unindexed metadata field in a database-backed store is a scan, which is why filterable fields want to be low-cardinality scalars rather than long free text. ## Legacy syntax Haystack 1.x used a MongoDB-flavoured shape: `{"type": {"$eq": "article"}}`, with `$and`, `$or`, `$in`. Haystack 2 replaced it with the explicit `field`/`operator`/`value` form described here, and 3.x keeps that form. Most training material and half the blog posts on the internet still show the old shape, so recognising and rejecting it is a genuine interview discriminator. If you meet the old syntax in a codebase you are migrating, the translation is mechanical: each `{key: {"$op": v}}` becomes a comparison node with `meta.` prepended to the key, and each `$and`/`$or` becomes a logical node. ## Practical shape Filters are plain Python dicts, so build them programmatically — a helper that assembles the `conditions` list from whatever scoping the request carries (tenant, language, date window) is far more maintainable than string-formatting a filter, and it makes the mandatory conditions impossible to forget. Keep the mandatory security scope as the outermost `AND` so that no caller-supplied condition can widen it.