Skip to main content
Mapagam

Filtering with Metadata

1. Using Equality Filters ($eq operator)

Example: $eq

res = index.query(vector=qv, top_k=5,
    filter={"source": {"$eq": "wiki"}})

# Shorthand:
filter={"source": "wiki"}
UseNote
Categorical matchExact equality only
Type-sensitiveNumber vs string distinct

2. Using Inequality Filters ($ne operator)

Example: $ne

filter={"status": {"$ne": "archived"}}
OperatorEffect
$neExcludes vectors where field equals value

3. Using Greater Than Filters ($gt, $gte)

Example: Range

filter={"views": {"$gt": 100}}
filter={"timestamp": {"$gte": 1716000000}}
OpMeaning
$gtStrictly greater
$gteGreater or equal

4. Using Less Than Filters ($lt, $lte)

Example: Range

filter={"price": {"$lte": 99.99}}
OpMeaning
$ltStrictly less
$lteLess or equal

5. Using In Filters ($in operator)

Example: $in

filter={"category": {"$in": ["tech", "science", "ml"]}}

6. Using Not In Filters ($nin operator)

Example: $nin

filter={"language": {"$nin": ["es", "fr"]}}
OpNotes
$inField matches any value in list
$ninField matches none

7. Combining Filters with AND ($and operator)

Example: $and

filter={"$and": [
    {"published": True},
    {"views": {"$gt": 100}},
    {"language": "en"},
]}

# Implicit AND (default for multiple keys):
filter={"published": True, "language": "en"}

8. Combining Filters with OR ($or operator)

Example: $or

filter={"$or": [
    {"featured": True},
    {"views": {"$gt": 1000}},
]}

9. Filtering Array Fields ($in with arrays)

Example: Array Field

# metadata: {tags: ["ml", "vectors", "db"]}
filter={"tags": {"$in": ["ml", "ai"]}}  # matches if any overlap
PatternMatch Rule
$in on list fieldMatch if array contains any listed value
$eq on list fieldMatch if array contains exactly the value

10. Understanding Indexed Metadata Performance

FieldPerformance
Indexed (default serverless)Fast O(log n) filter
Non-indexed (pod selective)Returned but not filterable
High-cardinality stringsSlower filter; large index

11. Optimizing Filter Performance

TipEffect
Most-selective firstReduces candidate set early
Avoid wide $in lists10s of values OK; 1000s slow
Use booleans/enumsFaster than strings
Pre-aggregate rangese.g., decade bucket vs raw year

12. Handling Complex Filter Queries

Example: Nested $and / $or

filter={"$and": [
    {"published": True},
    {"$or": [
        {"featured": True},
        {"views": {"$gte": 1000}},
    ]},
]}
Warning: Deeply nested filters with high cardinality may slow queries. Test with realistic data volumes.

Was this article helpful?

Related Cheat Sheets