**TL;DR:** Symptom: query with a filter returns empty but unfiltered query works. Check field names, value types, and operator shapes; one wrong type poisons the whole filter. Confirm it 1. Fetch a known record and print its metadata keys and value types.

## The fix

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.

5. Fix the field name or type to match what is actually stored.

6. If metadata was stored with inconsistent types across records (some string, some number), re-ingest with normalized types.

7. Keep a schema document for metadata fields; filters are only as reliable as the schema.

## When to use this

- This covers exactly what the title says: Pinecone diagnosis.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.

## When not to use this

- You are doing a different workflow with Pinecone; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.

## Compatibility

- Not pinned to a specific version; follows current Pinecone behavior.