Metadata Filtering with Where Clauses

~20 min · chroma, filtering

Level 0Scout

0 XP0/41 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Filter operators Chroma supports

Chroma's where argument speaks a small JSON DSL. The operators that matter:

$eq, $ne — equality
$gt, $gte, $lt, $lte — numeric / string comparisons
$in, $nin — set membership
$and, $or — logical combinators

Substring search on documents

Use where_document for full-text contains/regex against the chunk text itself. This is your escape hatch when vector search misses something obvious — fall back to where_document={'$contains': 'OAuth'} and you have basic keyword filtering inside Chroma.

Code

Combine vector search with metadata filter·python

res = docs.query(
    query_embeddings=q_vec,
    n_results=5,
    where={
        '$and': [
            {'project':  {'$eq':  'cwkPippa'}},
            {'doc_type': {'$in':  ['markdown', 'code']}},
            {'updated_at': {'$gte': '2026-04-01'}},
        ],
    },
    where_document={'$contains': 'embedding'},
    include=['documents', 'metadatas', 'distances'],
)

External links

Exercise

Build a query that returns only chunks from the last 7 days of one project, containing the substring 'OAuth', ranked by semantic similarity to a query of your choice. Confirm the filter halves the candidate count and that ranking still feels right.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousAdd, Query, and the Three Result Modes Next →Updating, Deleting, and Re-embedding

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.