0
# Retrievers
1

2
Advanced retrieval strategies including fusion, hierarchical, and routing approaches for sophisticated document retrieval patterns and enhanced context gathering.
3

4
## Capabilities
5

6
### Base Retriever Interface
7

8
Foundation class for all retrieval strategies with standardized interface and configuration options.
9

10
```python { .api }
11
class BaseRetriever:
12
    """
13
    Base class for document retrievers.
14
    
15
    Args:
16
        callback_manager: Callback manager for events
17
        object_map: Object mapping for node resolution
18
        verbose: Enable verbose logging
19
    """
20
    def __init__(
21
        self,
22
        callback_manager=None,
23
        object_map=None,
24
        verbose=False,
25
        **kwargs
26
    ): ...
27
    
28
    def retrieve(self, str_or_query_bundle):
29
        """
30
        Retrieve relevant nodes for query.
31
        
32
        Args:
33
            str_or_query_bundle: Query string or QueryBundle object
34
            
35
        Returns:
36
            List[NodeWithScore]: Retrieved nodes with relevance scores
37
        """
38
    
39
    async def aretrieve(self, str_or_query_bundle):
40
        """Async version of retrieve method."""
41
    
42
    def get_modules(self):
43
        """Get retriever modules for introspection."""
44
```
45

46
### Vector Index Retrievers
47

48
Core retrievers for vector-based semantic similarity search with various configuration options.
49

50
```python { .api }
51
class VectorIndexRetriever(BaseRetriever):
52
    """
53
    Vector index retriever for semantic similarity search.
54
    
55
    Args:
56
        index: Vector store index instance
57
        similarity_top_k: Number of top similar nodes to retrieve
58
        vector_store_query_mode: Query mode ("default", "sparse", "hybrid")
59
        alpha: Alpha parameter for hybrid search
60
        doc_ids: Filter by specific document IDs
61
        filters: Metadata filters for retrieval
62
    """
63
    def __init__(
64
        self,
65
        index,
66
        similarity_top_k=2,
67
        vector_store_query_mode="default",
68
        alpha=None,
69
        doc_ids=None,
70
        filters=None,
71
        **kwargs
72
    ): ...
73

74
class VectorIndexAutoRetriever(BaseRetriever):
75
    """
76
    Auto-retriever with dynamic query analysis and metadata filtering.
77
    
78
    Args:
79
        index: Vector store index
80
        vector_store_info: Metadata about vector store schema
81
        similarity_top_k: Number of nodes to retrieve
82
        empty_query_top_k: Fallback retrieval count for empty queries
83
        max_top_k_comparisons: Maximum comparisons for auto-selection
84
    """
85
    def __init__(
86
        self,
87
        index,
88
        vector_store_info,
89
        similarity_top_k=2,
90
        empty_query_top_k=10,
91
        max_top_k_comparisons=10,
92
        **kwargs
93
    ): ...
94
```
95

96
**Vector Retriever Usage Example:**
97

98
```python
99
from llama_index.core.retrievers import VectorIndexRetriever
100
from llama_index.core.vector_stores import MetadataFilter, MetadataFilters
101

102
# Basic vector retrieval
103
vector_retriever = VectorIndexRetriever(
104
    index=vector_index,
105
    similarity_top_k=5
106
)
107

108
# Filtered retrieval
109
filters = MetadataFilters(filters=[
110
    MetadataFilter(key="document_type", value="research_paper"),
111
    MetadataFilter(key="year", value=2023, operator=">=")
112
])
113

114
filtered_retriever = VectorIndexRetriever(
115
    index=vector_index,
116
    similarity_top_k=3,
117
    filters=filters
118
)
119

120
# Retrieve documents
121
nodes = vector_retriever.retrieve("machine learning applications")
122
for node in nodes:
123
    print(f"Score: {node.score}, Content: {node.node.get_content()[:100]}...")
124
```
125

126
### Hierarchical and Auto-Merging Retrievers
127

128
Advanced retrievers that work with hierarchical document structures and automatic chunk merging.
129

130
```python { .api }
131
class AutoMergingRetriever(BaseRetriever):
132
    """
133
    Auto-merging retriever for hierarchical document chunks.
134
    
135
    Retrieves fine-grained chunks and automatically merges them into larger
136
    context windows when consecutive chunks are retrieved.
137
    
138
    Args:
139
        vector_retriever: Base vector retriever for initial retrieval
140
        storage_context: Storage context for document resolution
141
        similarity_top_k: Number of initial chunks to retrieve
142
        repack: Whether to repack merged nodes
143
    """
144
    def __init__(
145
        self,
146
        vector_retriever,
147
        storage_context,
148
        similarity_top_k=2,
149
        repack=True,
150
        **kwargs
151
    ): ...
152

153
class RecursiveRetriever(BaseRetriever):
154
    """
155
    Recursive retriever for nested document structures.
156
    
157
    Recursively retrieves from hierarchical indices, following references
158
    and building comprehensive context through multiple retrieval levels.
159
    
160
    Args:
161
        root_id: Root node identifier for recursive traversal
162
        retriever_dict: Dictionary mapping node IDs to retrievers
163
        query_transform_fn: Function to transform queries at each level
164
        max_depth: Maximum recursion depth
165
    """
166
    def __init__(
167
        self,
168
        root_id,
169
        retriever_dict,
170
        query_transform_fn=None,
171
        max_depth=10,
172
        **kwargs
173
    ): ...
174
```
175

176
**Hierarchical Retriever Example:**
177

178
```python
179
from llama_index.core.retrievers import AutoMergingRetriever
180
from llama_index.core.node_parser import HierarchicalNodeParser
181
from llama_index.core import VectorStoreIndex
182

183
# Create hierarchical document structure
184
node_parser = HierarchicalNodeParser.from_defaults(
185
    chunk_sizes=[2048, 512, 128]  # Multi-level chunking
186
)
187

188
# Build index with hierarchical nodes
189
documents = SimpleDirectoryReader("data").load_data()
190
nodes = node_parser.get_nodes_from_documents(documents)
191
index = VectorStoreIndex(nodes, storage_context=storage_context)
192

193
# Create auto-merging retriever
194
base_retriever = VectorIndexRetriever(
195
    index=index,
196
    similarity_top_k=6
197
)
198

199
auto_merging_retriever = AutoMergingRetriever(
200
    vector_retriever=base_retriever,
201
    storage_context=storage_context,
202
    similarity_top_k=6,
203
    repack=True
204
)
205

206
# Retrieve with automatic merging
207
merged_nodes = auto_merging_retriever.retrieve(
208
    "What are the latest developments in AI?"
209
)
210
```
211

212
### Query Fusion Retriever
213

214
Advanced retriever that generates multiple query variations and fuses results for comprehensive retrieval.
215

216
```python { .api }
217
class QueryFusionRetriever(BaseRetriever):
218
    """
219
    Query fusion retriever for comprehensive document retrieval.
220
    
221
    Generates multiple query variations, retrieves results for each,
222
    and fuses the results using advanced ranking algorithms.
223
    
224
    Args:
225
        retrievers: List of retrievers to query
226
        similarity_top_k: Number of nodes per retrieval
227
        num_queries: Number of query variations to generate
228
        mode: Fusion mode ("reciprocal_rerank", "relative_score", "simple")
229
        use_async: Enable asynchronous retrieval
230
        query_gen_prompt: Template for query generation
231
    """
232
    def __init__(
233
        self,
234
        retrievers,
235
        similarity_top_k=2,
236
        num_queries=4,
237
        mode="reciprocal_rerank",
238
        use_async=True,
239
        query_gen_prompt=None,
240
        **kwargs
241
    ): ...
242
```
243

244
**Query Fusion Example:**
245

246
```python
247
from llama_index.core.retrievers import QueryFusionRetriever
248

249
# Create multiple retrievers for fusion
250
vector_retriever = VectorIndexRetriever(index=vector_index, similarity_top_k=5)
251
keyword_retriever = KeywordTableRetriever(index=keyword_index, similarity_top_k=5)
252

253
# Create fusion retriever
254
fusion_retriever = QueryFusionRetriever(
255
    retrievers=[vector_retriever, keyword_retriever],
256
    similarity_top_k=3,
257
    num_queries=4,  # Generate 4 query variations
258
    mode="reciprocal_rerank",
259
    use_async=True
260
)
261

262
# Retrieve with query fusion
263
fused_results = fusion_retriever.retrieve("artificial intelligence applications")
264

265
# Results are automatically ranked and deduplicated
266
for node in fused_results:
267
    print(f"Fused Score: {node.score}")
268
```
269

270
### Router Retriever
271

272
Intelligent retriever that routes queries to appropriate specialized retrievers based on query analysis.
273

274
```python { .api }
275
class RouterRetriever(BaseRetriever):
276
    """
277
    Router retriever for intelligent retrieval routing.
278
    
279
    Analyzes queries and routes them to the most appropriate retriever
280
    from a collection of specialized retrievers.
281
    
282
    Args:
283
        selector: Selector for choosing appropriate retriever
284
        retriever_tools: List of retriever tools with descriptions
285
        default_retriever: Fallback retriever if routing fails
286
    """
287
    def __init__(
288
        self,
289
        selector,
290
        retriever_tools,
291
        default_retriever=None,
292
        **kwargs
293
    ): ...
294

295
class BaseSelector:
296
    """Base class for retriever selection logic."""
297
    
298
    def select(self, choices, query):
299
        """Select appropriate retriever based on query."""
300
```
301

302
**Router Retriever Example:**
303

304
```python
305
from llama_index.core.retrievers import RouterRetriever
306
from llama_index.core.tools import RetrieverTool
307
from llama_index.core.selectors import LLMSingleSelector
308

309
# Define specialized retrievers
310
technical_retriever = VectorIndexRetriever(
311
    index=technical_index,
312
    similarity_top_k=5
313
)
314

315
business_retriever = VectorIndexRetriever(
316
    index=business_index,
317
    similarity_top_k=5
318
)
319

320
# Create retriever tools with descriptions
321
retriever_tools = [
322
    RetrieverTool.from_defaults(
323
        retriever=technical_retriever,
324
        description="Technical documentation and API references"
325
    ),
326
    RetrieverTool.from_defaults(
327
        retriever=business_retriever,
328
        description="Business processes and company policies"
329
    )
330
]
331

332
# Create router with LLM-based selection
333
selector = LLMSingleSelector.from_defaults()
334
router_retriever = RouterRetriever(
335
    selector=selector,
336
    retriever_tools=retriever_tools,
337
    default_retriever=technical_retriever
338
)
339

340
# Route queries automatically
341
tech_results = router_retriever.retrieve("API authentication methods")
342
business_results = router_retriever.retrieve("expense reporting procedures")
343
```
344

345
### Transform Retriever
346

347
Retriever wrapper that applies transformations to queries or retrieved nodes for enhanced processing.
348

349
```python { .api }
350
class TransformRetriever(BaseRetriever):
351
    """
352
    Transform retriever for query and node processing.
353
    
354
    Applies transformations to queries before retrieval and/or to
355
    retrieved nodes before returning results.
356
    
357
    Args:
358
        retriever: Base retriever to wrap
359
        query_transform: Function to transform queries
360
        node_transform: Function to transform retrieved nodes
361
        transform_metadata: Whether to transform node metadata
362
    """
363
    def __init__(
364
        self,
365
        retriever,
366
        query_transform=None,
367
        node_transform=None,
368
        transform_metadata=True,
369
        **kwargs
370
    ): ...
371
```
372

373
**Transform Retriever Example:**
374

375
```python
376
from llama_index.core.retrievers import TransformRetriever
377

378
def expand_query(query_str):
379
    """Expand query with synonyms and related terms."""
380
    # Custom query expansion logic
381
    synonyms = {
382
        "AI": "artificial intelligence machine learning",
383
        "ML": "machine learning artificial intelligence"
384
    }
385
    
386
    expanded = query_str
387
    for term, expansion in synonyms.items():
388
        if term in query_str:
389
            expanded = f"{query_str} {expansion}"
390
    
391
    return expanded
392

393
def enhance_nodes(nodes):
394
    """Add custom metadata to retrieved nodes."""
395
    for node in nodes:
396
        # Add relevance category
397
        content = node.node.get_content().lower()
398
        if "technical" in content:
399
            node.node.metadata["category"] = "technical"
400
        elif "business" in content:
401
            node.node.metadata["category"] = "business"
402
    
403
    return nodes
404

405
# Create transform retriever
406
transform_retriever = TransformRetriever(
407
    retriever=base_retriever,
408
    query_transform=expand_query,
409
    node_transform=enhance_nodes
410
)
411

412
# Queries and results are automatically transformed
413
results = transform_retriever.retrieve("AI applications")
414
```
415

416
### Specialized Index Retrievers
417

418
Retrievers designed for specific index types with optimized retrieval strategies.
419

420
```python { .api }
421
class KeywordTableRetriever(BaseRetriever):
422
    """
423
    Keyword table retriever for exact keyword matching.
424
    
425
    Args:
426
        index: Keyword table index
427
        mode: Retrieval mode ("DEFAULT", "SIMPLE", "RAKE")
428
        max_chunks_per_query: Maximum chunks to return
429
    """
430
    def __init__(
431
        self,
432
        index,
433
        mode="DEFAULT",
434
        max_chunks_per_query=10,
435
        **kwargs
436
    ): ...
437

438
class KnowledgeGraphRAGRetriever(BaseRetriever):
439
    """
440
    Knowledge graph RAG retriever for graph-based retrieval.
441
    
442
    Args:
443
        storage_context: Storage context with graph store
444
        service_context: Service context (deprecated)
445
        entity_extract_fn: Function to extract entities from queries
446
        synonym_expand_fn: Function to expand entity synonyms
447
        retrieval_depth: Graph traversal depth
448
        max_entities: Maximum entities to extract per query
449
    """
450
    def __init__(
451
        self,
452
        storage_context,
453
        service_context=None,
454
        entity_extract_fn=None,
455
        synonym_expand_fn=None,
456
        retrieval_depth=2,
457
        max_entities=10,
458
        **kwargs
459
    ): ...
460

461
class TreeSelectLeafRetriever(BaseRetriever):
462
    """
463
    Tree index retriever that selects specific leaf nodes.
464
    
465
    Args:
466
        index: Tree index instance
467
        child_branch_factor: Number of child branches to explore
468
    """
469
    def __init__(
470
        self,
471
        index,
472
        child_branch_factor=1,
473
        **kwargs
474
    ): ...
475
```
476

477
### Postprocessor Integration
478

479
Retrievers with integrated postprocessing for result refinement and reranking.
480

481
```python { .api }
482
class BasePostprocessor:
483
    """Base class for retrieval postprocessors."""
484
    
485
    def postprocess_nodes(self, nodes, query_bundle=None):
486
        """Postprocess retrieved nodes."""
487

488
class SimilarityPostprocessor(BasePostprocessor):
489
    """
490
    Similarity-based postprocessor for score filtering.
491
    
492
    Args:
493
        similarity_cutoff: Minimum similarity score threshold
494
    """
495
    def __init__(self, similarity_cutoff=0.7): ...
496

497
class KeywordNodePostprocessor(BasePostprocessor):
498
    """
499
    Keyword-based postprocessor for content filtering.
500
    
501
    Args:
502
        required_keywords: Keywords that must be present
503
        exclude_keywords: Keywords that exclude nodes
504
    """
505
    def __init__(
506
        self,
507
        required_keywords=None,
508
        exclude_keywords=None
509
    ): ...
510

511
class SentenceEmbeddingOptimizer(BasePostprocessor):
512
    """
513
    Sentence embedding optimizer for context optimization.
514
    
515
    Args:
516
        embed_model: Embedding model for optimization
517
        percentile_cutoff: Percentile cutoff for sentence selection
518
        threshold_cutoff: Absolute threshold for sentence selection
519
    """
520
    def __init__(
521
        self,
522
        embed_model=None,
523
        percentile_cutoff=None,
524
        threshold_cutoff=None
525
    ): ...
526
```
527

528
**Postprocessor Usage Example:**
529

530
```python
531
from llama_index.core.postprocessor import (
532
    SimilarityPostprocessor,
533
    KeywordNodePostprocessor,
534
    SentenceEmbeddingOptimizer
535
)
536

537
# Create retriever with postprocessors
538
retriever = VectorIndexRetriever(
539
    index=index,
540
    similarity_top_k=10  # Retrieve more, then filter
541
)
542

543
# Chain multiple postprocessors
544
postprocessors = [
545
    SimilarityPostprocessor(similarity_cutoff=0.7),
546
    KeywordNodePostprocessor(required_keywords=["machine learning"]),
547
    SentenceEmbeddingOptimizer(percentile_cutoff=0.5)
548
]
549

550
# Use with query engine
551
query_engine = RetrieverQueryEngine.from_args(
552
    retriever=retriever,
553
    node_postprocessors=postprocessors
554
)
555

556
response = query_engine.query("machine learning applications")
557
```
558

559
### Ensemble and Multi-Modal Retrievers
560

561
Advanced retrievers for combining multiple retrieval strategies and handling multi-modal content.
562

563
```python { .api }
564
class EnsembleRetriever(BaseRetriever):
565
    """
566
    Ensemble retriever combining multiple retrieval strategies.
567
    
568
    Args:
569
        retrievers: List of retrievers to ensemble
570
        weights: Weights for each retriever (optional)
571
        combine_mode: How to combine results ("weighted_sum", "rank_fusion")
572
    """
573
    def __init__(
574
        self,
575
        retrievers,
576
        weights=None,
577
        combine_mode="rank_fusion",
578
        **kwargs
579
    ): ...
580

581
class MultiModalRetriever(BaseRetriever):
582
    """
583
    Multi-modal retriever for text and image content.
584
    
585
    Args:
586
        vector_retriever: Text vector retriever
587
        image_retriever: Image vector retriever
588
        mode: Retrieval mode ("text", "image", "both")
589
        fusion_strategy: Strategy for combining modalities
590
    """
591
    def __init__(
592
        self,
593
        vector_retriever,
594
        image_retriever=None,
595
        mode="both",
596
        fusion_strategy="score_fusion",
597
        **kwargs
598
    ): ...
599
```
600

601
### Custom Retriever Implementation
602

603
Framework for implementing custom retrieval strategies with full control over the retrieval process.
604

605
```python { .api }
606
class CustomRetriever(BaseRetriever):
607
    """
608
    Custom retriever implementation template.
609
    
610
    Args:
611
        custom_retrieve_fn: Custom retrieval function
612
        **kwargs: BaseRetriever arguments
613
    """
614
    def __init__(self, custom_retrieve_fn, **kwargs):
615
        super().__init__(**kwargs)
616
        self._custom_retrieve_fn = custom_retrieve_fn
617
    
618
    def _retrieve(self, query_bundle):
619
        """Custom retrieval logic."""
620
        return self._custom_retrieve_fn(query_bundle)
621
```
622

623
**Custom Retriever Example:**
624

625
```python
626
from llama_index.core.retrievers import BaseRetriever
627
from llama_index.core.schema import NodeWithScore
628

629
class SemanticCacheRetriever(BaseRetriever):
630
    """Custom retriever with semantic caching."""
631
    
632
    def __init__(self, base_retriever, cache_threshold=0.95, **kwargs):
633
        super().__init__(**kwargs)
634
        self.base_retriever = base_retriever
635
        self.cache = {}  # Simple in-memory cache
636
        self.cache_threshold = cache_threshold
637
    
638
    def _retrieve(self, query_bundle):
639
        query_str = query_bundle.query_str
640
        
641
        # Check semantic cache
642
        cached_result = self._check_cache(query_str)
643
        if cached_result:
644
            return cached_result
645
        
646
        # Retrieve from base retriever
647
        nodes = self.base_retriever.retrieve(query_bundle)
648
        
649
        # Cache results
650
        self._cache_results(query_str, nodes)
651
        
652
        return nodes
653
    
654
    def _check_cache(self, query_str):
655
        """Check if semantically similar query exists in cache."""
656
        # Implementation for semantic similarity check
657
        # Return cached results if similarity > threshold
658
        return None  # Placeholder
659
    
660
    def _cache_results(self, query_str, nodes):
661
        """Cache retrieval results."""
662
        self.cache[query_str] = nodes
663

664
# Use custom retriever
665
cached_retriever = SemanticCacheRetriever(
666
    base_retriever=vector_retriever,
667
    cache_threshold=0.95
668
)
669
```