# 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.