Search

Airweave’s search subsystem provides a unified query interface across heterogeneous data sources inside a collection. The pipeline transforms natural‑language queries into ranked results via a deterministic sequence of specialized operators that can be individually configured or disabled for fine‑grained control. This page summarizes each operator, its defaults, and minimal examples.

Operators

Query Expansion

Query expansion mitigates vocabulary mismatch by generating semantically equivalent reformulations of the original query, improving recall across documents that express similar concepts with different terminology. Practically, the system expands the query into semantically adjacent variants, sampling a broader neighborhood in vector and keyword space.

Configuration Parameter: expansion_strategy

• auto (default): Dynamically selects expansion based on OpenAI API availability
• llm: Generates up to 4 query variations using GPT-4o-mini
• no_expansion: Disables expansion for exact query matching

1
from airweave import AirweaveSDK
2
3
client = AirweaveSDK(api_key="your-api-key")
4
5
# Automatic expansion generates variations for improved recall
6
results = await client.collections.search_collection_advanced(
7
    readable_id="your-collection-id",
8
    search_request={
9
        "query": "customer churn analysis",
10
        "expansion_strategy": "llm"
11
    }
12
)

Embedding Generation

Maps queries to dense and/or sparse representations depending on the search method. Dense embeddings permit semantic similarity; sparse embeddings approximate lexical BM25. In hybrid mode both representations are produced and fused downstream.

Configuration Parameter: search_method

• hybrid (default): Combines dense semantic vectors with sparse BM25 representations via Reciprocal Rank Fusion
• neural: Utilizes transformer-based embeddings for pure semantic similarity
• keyword: Employs BM25 term frequency statistics for lexical matching

1
# Hybrid search leverages both semantic understanding and keyword precision
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "authentication flow security vulnerabilities",
6
        "search_method": "hybrid"  # Combines neural + BM25 for best results
7
    }
8
)

Metadata Filtering

Qdrant’s native filtering system enables precise subsetting of the search space based on structured metadata fields. This operation applies boolean predicates to document attributes before similarity computation, ensuring efficient retrieval within constrained domains.

Configuration Parameter: filter (Qdrant Filter object)

1
from qdrant_client.http.models import Filter, FieldCondition, MatchValue, DatetimeRange, MatchAny
2
from datetime import datetime, timezone, timedelta
3
4
# 1. Filter by specific source (case-sensitive!)
5
results = await client.collections.search_collection_advanced(
6
    readable_id="your-collection-id",
7
    search_request={
8
        "query": "deployment issues",
9
        "filter": {
10
            "must": [{
11
                "key": "source_name",
12
                "match": {"value": "GitHub"}  # Must match exactly
13
            }]
14
        }
15
    }
16
)
17
18
# 2. Multiple sources with date range
19
results = await client.collections.search_collection_advanced(
20
    readable_id="your-collection-id",
21
    search_request={
22
        "query": "customer feedback",
23
        "filter": {
24
            "must": [
25
                {
26
                    "key": "source_name",
27
                    "match": {"any": ["Zendesk", "Intercom", "Slack"]}
28
                },
29
                {
30
                    "key": "created_at",
31
                    "range": {
32
                        "gte": (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
33
                    }
34
                }
35
            ]
36
        }
37
    }
38
)
39
40
# 3. Exclude resolved/closed items
41
results = await client.collections.search_collection_advanced(
42
    readable_id="your-collection-id",
43
    search_request={
44
        "query": "bug reports",
45
        "filter": {
46
            "must_not": [{
47
                "key": "status",
48
                "match": {"any": ["resolved", "closed", "done"]}
49
            }]
50
        }
51
    }
52
)

Query Interpretation (Beta)

This advanced natural language understanding component automatically extracts structured constraints from unstructured queries. The system employs large language models to identify temporal expressions, entity references, and status indicators, dynamically generating appropriate filter predicates.

Configuration Parameter: enable_query_interpretation

• false (default): Disabled to prevent unintended filtering
• true: Enables automatic filter extraction from natural language

Implementation Example:

1
# Query interpretation extracts structured filters from natural language
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "open asana tickets from last week",
6
        "enable_query_interpretation": True
7
    }
8
)
9
# Automatically generates filters:
10
# - source_name = "Asana"
11
# - status != "completed" / "done" / "closed"
12
# - created_at >= 7 days ago
13
14
# Another example
15
results = await client.collections.search_collection_advanced(
16
    readable_id="your-collection-id",
17
    search_request={
18
        "query": "critical bugs from GitHub this month",
19
        "enable_query_interpretation": True
20
    }
21
)
22
# Generates: source="GitHub", priority="critical", created_at>=30d

Recency Bias

Temporal relevance scoring adjusts document rankings based on creation or modification timestamps. Internally, a decay configuration is derived from the collection’s observed time span (subject to any active filter) and composed into Qdrant formula scoring. This preserves relevance while enforcing temporal preference. The penalty is defined as:

final_score = similarity × (1 - recency_bias + recency_bias × recency_bias)

where recency_bias ∈ [0,1] maps oldest→0 and newest→1 within the observed span.

Configuration Parameter: recency_bias (float: 0.0-1.0)

• 0.3 (default): Moderate recency preference
• 0.0: Pure semantic similarity without temporal influence
• 1.0: Maximum recency weight within semantic matches

1
# Email search with strong recency preference
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "project updates",
6
        "recency_bias": 0.7  # Recent emails heavily prioritized
7
    }
8
)

Vector search

The core retrieval mechanism performs approximate nearest neighbor search in high-dimensional embedding spaces. This operation orchestrates the actual database query, handling multi-vector fusion, result deduplication, and score normalization.

Pagination parameters control result set size and navigation through large result collections:

• limit (int: 1-1000, default: 20): Maximum documents per response
• offset (int: ≥0, default: 0): Skip count for pagination

1
response = await client.collections.search_collection(
2
    readable_id="your-collection-id",
3
    query="data retention policies",
4
    limit=50,
5
    offset=50, # Results 51-100
6
)

Score Threshold Filtering

Post-retrieval filtering eliminates results below a specified similarity threshold, ensuring minimum quality standards for returned documents. This parameter acts as a quality gate rather than a separate operation.

Configuration Parameter: score_threshold (float: 0.0-1.0)

• None (default): No score filtering
• 0.7: Returns only high-confidence matches

1
# High-precision retrieval for critical queries
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "security vulnerability CVE-2024",
6
        "score_threshold": 0.8  # Only highly relevant matches
7
    }
8
)

Result Reranking

Reranking employs large language models to perform pairwise relevance assessment between query and retrieved documents. This computationally intensive operation refines the initial ranking by considering deeper semantic relationships and contextual nuances.

Configuration Parameter: enable_reranking

• true (default): Applies LLM-based relevance scoring
• false: Retains original vector similarity ranking

1
# Disable reranking for latency-sensitive applications
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "user authentication methods",
6
        "enable_reranking": False  # Skip 10-second reranking delay
7
    }
8
)

Response Generation

Synthesizes a natural language answer from the retrieved context. The completion model is invoked only when explicitly requested and requires an OpenAI API key in the environment. Source attribution is encouraged via structured prompts.

Configuration Parameter: response_type

• raw (default): Returns structured JSON with document payloads
• completion: Generates coherent natural language summary via LLM

1
# Get AI-synthesized answer
2
results = await client.collections.search_collection_advanced(
3
    readable_id="your-collection-id",
4
    search_request={
5
        "query": "What are our customer refund policies?",
6
        "response_type": "completion"
7
    }
8
)
9
# Access results.completion for natural language answer

API Endpoints

GET /collections/{id}/search: Simple search using all operator defaults (link).

POST /collections/{id}/search: Advanced search exposing all operators for full configurability. Use this when you need precise control over search behavior (link).

Default Configuration

The system employs empirically optimized defaults for common use cases: