Skip to main content

​
Search Guide

Nebula provides powerful hybrid search that combines semantic (vector) and full-text search for optimal results. 
from nebula import Nebula

nebula = Nebula(api_key="your-api-key")

# Simple search
results = nebula.search(
    query="machine learning algorithms",
    collection_ids=["research-collection"],
    limit=10
)

for result in results:
    print(f"Score: {result.score:.3f}")
    print(f"Content: {result.content}")
    print(f"Metadata: {result.metadata}\n")
Search results include:
  • score: Relevance score (0-1, higher is better)
  • content: The memory content
  • metadata: Custom metadata
  • memory_id: Memory ID for retrieval
  • collection_id: Which collection it belongs to
  • created_at: Timestamp

​
Search with Metadata Filters

Combine semantic search with metadata filtering: 
# Search with filters
results = nebula.search(
    query="project updates",
    collection_ids=["work-collection"],
    filters={
        "priority": "high",
        "status": "active",
        "team": "engineering"
    },
    limit=20
)
See Metadata Filtering for advanced filter operators.

​
Hybrid Search Weights

Control the balance between semantic and full-text search: 
results = nebula.search(
    query="neural networks",
    collection_ids=["research-collection"],
    search_settings={
        "semantic_weight": 0.7,    # Semantic search weight
        "fulltext_weight": 0.3  # Keyword search weight
    },
    limit=10
)
Weight Guidelines:
  • semantic_weight: 0.8, fulltext_weight: 0.2 - Prefer semantic meaning (default)
  • semantic_weight: 0.5, fulltext_weight: 0.5 - Balanced
  • semantic_weight: 0.2, fulltext_weight: 0.8 - Prefer exact keyword matches
Default weights (0.8 semantic, 0.2 fulltext) work well for most use cases. Adjust only if needed.

​
Limits

Nebula always performs hybrid search. Per-type limits (semantic vs. keyword) are managed internally for optimal performance. Control the overall number of results with limit and adjust the balance using semantic_weight and fulltext_weight.

​
Advanced Search Options

​
Search Multiple Collections

# Search across multiple collections
results = nebula.search(
    query="customer feedback",
    collection_ids=["support-2024", "support-2023", "surveys"],
    limit=30
)

​
Search All Collections

Omit collection_ids to search across all accessible collections: 
# Search everything
results = nebula.search(
    query="product roadmap",
    limit=50
)
Searching all collections is slower than targeting specific collections.

​
Complex Metadata Filters

# Advanced filtering
results = nebula.search(
    query="bug reports",
    collection_ids=["issues-collection"],
    filters={
        "severity": {"$in": ["critical", "high"]},
        "status": {"$ne": "closed"},
        "created_date": {"$gte": "2024-01-01"}
    },
    limit=50
)
Available operators:
  • $eq: Equals
  • $ne: Not equals
  • $in: Value in array
  • $nin: Value not in array
  • $gt, $gte: Greater than (or equal)
  • $lt, $lte: Less than (or equal)
Full details in Metadata Filtering.

​
Search Best Practices

  1. Use natural language queries - “How do I reset my password?” works better than “password reset”
  2. Target specific collections - Faster and more relevant results
  3. Start with defaults - Only adjust weights if results aren’t good
  4. Leverage metadata filters - Narrow results by structured fields
  5. Set appropriate limits - Balance between coverage and performance
  6. Cache frequent queries - Store common search results

​
Next Steps