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
import Nebula from '@nebula-ai/sdk';
const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });
// Simple equality
const { results } = await client.memories.search({
query: 'machine learning',
collection_ids: ['docs'],
filters: { 'metadata.category': 'research' },
});
// Multiple conditions with $and
const { results: results2 } = await client.memories.search({
query: 'reports',
collection_ids: ['tasks'],
filters: {
$and: [
{ 'metadata.priority': { $gte: 7 } },
{ 'metadata.status': { $in: ['pending', 'active'] } },
{ created_at: { $gte: '2024-01-01' } },
],
},
});
// Array operations
const { results: results3 } = await client.memories.search({
query: 'candidates',
collection_ids: ['hr'],
filters: { 'metadata.skills': { $contains: ['python', 'ml'] } },
});
# Simple equality
curl -X POST "https://api.zeroset.com/v1/memories/search" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "machine learning",
"collection_ids": ["docs"],
"filters": {"metadata.category": "research"}
}'
# Multiple conditions with $and
curl -X POST "https://api.zeroset.com/v1/memories/search" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "reports",
"collection_ids": ["tasks"],
"filters": {
"$and": [
{"metadata.priority": {"$gte": 7}},
{"metadata.status": {"$in": ["pending", "active"]}},
{"created_at": {"$gte": "2024-01-01"}}
]
}
}'
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
- Search Guide - Semantic search strategies
- Memory Operations - Core CRUD operations