Filter search results by metadata attributes using comparison and logical operators.
Operators Reference
| Operator | Description | Example |
|---|
$eq | Equals (default) | {"status": "active"} |
$ne | Not equals | {"status": {"$ne": "archived"}} |
$gt | Greater than | {"score": {"$gt": 80}} |
$gte | Greater than or equal | {"priority": {"$gte": 7}} |
$lt | Less than | {"age": {"$lt": 30}} |
$lte | Less than or equal | {"count": {"$lte": 100}} |
$in | Value in list | {"status": {"$in": ["a", "b"]}} |
$nin | Not in list | {"status": {"$nin": ["x", "y"]}} |
$like | Pattern match (case-sensitive) | {"title": {"$like": "Important%"}} |
$ilike | Pattern match (case-insensitive) | {"email": {"$ilike": "%@company.com"}} |
$overlap | Array has any | {"tags": {"$overlap": ["urgent", "important"]}} |
$contains | Array has all | {"skills": {"$contains": ["python", "ml"]}} |
$json_contains | JSONB structural match | {"config": {"$json_contains": {"enabled": true}}} |
$and | All conditions match | {"$and": [{...}, {...}]} |
$or | Any condition matches | {"$or": [{...}, {...}]} |
Use % as wildcard in $like and $ilike patterns.
Target metadata fields with the metadata. prefix (e.g., metadata.status). Nested fields are supported.
Set verbose: true in search_settings to include full metadata and internal IDs in search results.
Examples
from nebula import Nebula
nebula = Nebula()
# Simple equality
results = nebula.memories.search(
query="machine learning",
collection_ids=["docs"],
filters={"metadata.category": "research"},
).results
# Multiple conditions with $and
results = nebula.memories.search(
query="reports",
collection_ids=["tasks"],
filters={
"$and": [
{"metadata.priority": {"$gte": 7}},
{"metadata.status": {"$in": ["pending", "active"]}},
{"created_at": {"$gte": "2024-01-01"}},
]
},
).results
# Array operations
results = nebula.memories.search(
query="candidates",
collection_ids=["hr"],
filters={"metadata.skills": {"$contains": ["python", "ml"]}},
).results
Common Patterns
Date Ranges
from datetime import datetime, timedelta
# Last 30 days (filters on the row's created_at column)
start = (datetime.now() - timedelta(days=30)).isoformat()
filters = {"created_at": {"$gte": start}}
# Date range
filters = {
"$and": [
{"created_at": {"$gte": "2024-01-01"}},
{"created_at": {"$lte": "2024-12-31"}}
]
}
Multi-Status
# Include specific statuses
filters = {"metadata.status": {"$in": ["pending", "in_progress", "review"]}}
# Exclude specific statuses
filters = {"metadata.status": {"$nin": ["archived", "deleted"]}}
Nested Properties
# Filter nested object properties
filters = {
"metadata.user.profile.age": {"$gte": 25},
"metadata.user.location.city": "San Francisco"
}
Next Steps
