# Diagnosis
## Symptom
Filtered query returns no matches; the same query without `filter` returns results.
## Likely cause
The filter references a field name that does not exist on the records, compares with the wrong type (string vs number), or uses an operator shape the field does not support.
## Confirm it
1. Fetch a known record and print its metadata keys and value types.
2. Compare each filter clause against those exact keys and types.
3. Test clauses one at a time: add them incrementally until matches vanish; the last clause added is the culprit.
4. Check operator shapes: `$in` needs a list, `$gt` needs a number, `$exists` needs a boolean.
## Fix
1. Fix the field name or type to match what is actually stored.
2. If metadata was stored with inconsistent types across records (some string, some number), re-ingest with normalized types.
3. Keep a schema document for metadata fields; filters are only as reliable as the schema.
## Verify the fix
Re-run the filtered query and assert matches return; then run the full original filter to confirm every clause contributes.