The Semantic Search stage finds documents by meaning using dense vector embeddings. It converts your query into a vector using the same embedding model used during indexing, then finds the most similar documents using approximate nearest neighbor (ANN) search.
Stage Category : FILTER (Reduces document set)Transformation : Collection → top_k documents (ranked by similarity)
When to Use Use Case Description Natural language search ”wireless headphones with noise cancellation” Conceptual matching Find docs with similar meaning, not just keywords Cross-modal search Text query → find matching videos/images Multilingual search Query in one language, find docs in another RAG retrieval Retrieve context for LLM generation
When NOT to Use Scenario Recommended Alternative Exact phrase matching hybrid_search with text weightKeyword-heavy queries hybrid_search or full-text searchProduct SKUs/model numbers structured_filter on exact fieldsVery short queries (1-2 words) hybrid_search for better recall
Parameters Parameter Type Default Description querystring Required Search query (supports templates like {{INPUT.query}}) vector_indexstring Required Name of the vector index to search top_kinteger 100Number of candidates to retrieve min_scorefloat 0.0Minimum similarity score threshold (0.0-1.0) filtersobject nullPre-filter conditions (applied before vector search)
Vector Index Selection The vector_index must match an index created by a feature extractor:
Feature Extractor Index Name Dimensions text_extractor_v1text_extractor_v1_embedding1024 multimodal_extractor_v1multimodal_extractor_v1_multimodal_embedding1408 multimodal_extractor_v1multimodal_extractor_v1_transcription_embedding1024
Configuration Examples Basic Text Search
With Minimum Score
With Pre-Filter
Multimodal Search (Text to Video)
Dynamic Query from Input
{ "stage_type" : "filter" , "stage_id" : "semantic_search" , "parameters" : { "query" : "{{INPUT.query}}" , "vector_index" : "text_extractor_v1_embedding" , "top_k" : 100 } }
How It Works
Query Embedding : Your query is converted to a vector using the same model that indexed the documentsANN Search : Approximate nearest neighbor search finds the top_k most similar vectorsScore Calculation : Cosine similarity is computed (0.0 = orthogonal, 1.0 = identical)Filtering : Optional pre-filters are applied to narrow the search spaceRanking : Results are returned sorted by similarity score (highest first)
Output Each returned document includes:
Field Type Description document_idstring Unique document identifier scorefloat Similarity score (0.0-1.0) contentstring Document content metadataobject Document metadata
Metric Value Latency 5-50ms for millions of vectors top_k range 1-10,000 Index type HNSW (Hierarchical Navigable Small World) Distance metric Cosine similarity
Use larger top_k values (100-500) when planning to rerank results with the rerank stage. The reranker will select the best final results from this candidate pool.
Pre-Filtering Pre-filters are applied before vector search, using indexed metadata fields:
{ "filters" : { "AND" : [ { "field" : "metadata.status" , "operator" : "eq" , "value" : "published" }, { "field" : "metadata.date" , "operator" : "gte" , "value" : "2024-01-01" } ] } }
Supported operators: eq, ne, gt, lt, gte, lte, in, nin, contains, exists
Common Pipeline Patterns Two-Stage Retrieval (Retrieve + Rerank) [ { "stage_type" : "filter" , "stage_id" : "semantic_search" , "parameters" : { "query" : "{{INPUT.query}}" , "vector_index" : "text_extractor_v1_embedding" , "top_k" : 100 } }, { "stage_type" : "sort" , "stage_id" : "rerank" , "parameters" : { "model" : "bge-reranker-v2-m3" , "top_n" : 10 } } ]
Semantic Search + Structured Filter [ { "stage_type" : "filter" , "stage_id" : "semantic_search" , "parameters" : { "query" : "{{INPUT.query}}" , "vector_index" : "text_extractor_v1_embedding" , "top_k" : 200 } }, { "stage_type" : "filter" , "stage_id" : "structured_filter" , "parameters" : { "conditions" : { "field" : "metadata.price" , "operator" : "lte" , "value" : "{{INPUT.max_price}}" } } } ]
