> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Explain Retriever Execution Plan > Get a detailed execution plan for a retriever without actually executing it. Similar to MongoDB's explain plan or SQL's EXPLAIN command, this endpoint helps you understand performance characteristics, identify bottlenecks, estimate costs, and troubleshoot retrieval issues before running expensive queries. **What This Returns:** - Stage-by-stage execution plan (AFTER automatic optimizations) - Estimated costs (credits + time per stage) - Document flow projections (input/output counts per stage) - Efficiency metrics (selectivity ratios, cache likelihood) - Bottleneck identification (slowest/most expensive stages) - Optimization details (transformations applied by the optimizer) - Performance warnings and improvement suggestions **Key Features:** - **Cost Estimation**: See how many credits and milliseconds each stage will consume - **Bottleneck Detection**: Identify which stages dominate execution time - **Optimization Transparency**: Understand how your pipeline was optimized - **Cache Analysis**: See which stages are likely to hit cache - **Accuracy Troubleshooting**: Analyze stage efficiency and document flow - **Latency Analysis**: Break down estimated duration by stage **Important:** The execution_plan shows OPTIMIZED stages (after automatic transformations like filter push-down, stage fusion, and grouping optimization). Check optimization_details to understand what changed from your original configuration. **Use Cases:** - Debug slow retrievers by identifying bottleneck stages - Estimate costs before running expensive queries - Understand how the optimizer transformed your pipeline - Troubleshoot accuracy issues by analyzing stage selectivity - Compare different retriever configurations - Plan budget allocation for production workloads **Example Response:** ```json { "retriever_id": "ret_abc123", "retriever_name": "product_search", "execution_plan": [ { "stage_index": 0, "stage_name": "attribute_filter", "stage_type": "filter", "estimated_input": 10000, "estimated_output": 5000, "estimated_efficiency": 0.5, "estimated_cost_credits": 0.01, "estimated_duration_ms": 20, "cache_likely": true, "optimization_notes": ["Pushed down from stage 2"], "warnings": [] }, { "stage_index": 1, "stage_name": "semantic_search", "stage_type": "filter", "estimated_input": 5000, "estimated_output": 100, "estimated_efficiency": 0.02, "estimated_cost_credits": 0.5, "estimated_duration_ms": 200, "cache_likely": false, "optimization_notes": [], "warnings": ["High cost stage - consider reducing limit"] } ], "estimated_cost": { "total_credits": 0.51, "total_duration_ms": 220 }, "bottleneck_stages": ["semantic_search"], "optimization_applied": true, "optimization_details": { "original_stage_count": 3, "optimized_stage_count": 2, "optimization_time_ms": 8.2, "stage_reduction_pct": 33.3, "decisions": [ { "rule_type": "push_down_filters", "applied": true, "reason": "Moved attribute_filter before semantic_search to reduce search scope" } ] }, "optimization_suggestions": [ { "type": "reduce_limit", "stage": "semantic_search", "message": "Consider reducing limit to improve latency" } ] } ``` ## OpenAPI ````yaml post /v1/retrievers/{retriever_id}/execute/explain openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/retrievers/{retriever_id}/execute/explain: post: tags: - Retrievers summary: Explain Retriever Execution Plan description: >- Get a detailed execution plan for a retriever without actually executing it. Similar to MongoDB's explain plan or SQL's EXPLAIN command, this endpoint helps you understand performance characteristics, identify bottlenecks, estimate costs, and troubleshoot retrieval issues before running expensive queries. **What This Returns:** - Stage-by-stage execution plan (AFTER automatic optimizations) - Estimated costs (credits + time per stage) - Document flow projections (input/output counts per stage) - Efficiency metrics (selectivity ratios, cache likelihood) - Bottleneck identification (slowest/most expensive stages) - Optimization details (transformations applied by the optimizer) - Performance warnings and improvement suggestions **Key Features:** - **Cost Estimation**: See how many credits and milliseconds each stage will consume - **Bottleneck Detection**: Identify which stages dominate execution time - **Optimization Transparency**: Understand how your pipeline was optimized - **Cache Analysis**: See which stages are likely to hit cache - **Accuracy Troubleshooting**: Analyze stage efficiency and document flow - **Latency Analysis**: Break down estimated duration by stage **Important:** The execution_plan shows OPTIMIZED stages (after automatic transformations like filter push-down, stage fusion, and grouping optimization). Check optimization_details to understand what changed from your original configuration. **Use Cases:** - Debug slow retrievers by identifying bottleneck stages - Estimate costs before running expensive queries - Understand how the optimizer transformed your pipeline - Troubleshoot accuracy issues by analyzing stage selectivity - Compare different retriever configurations - Plan budget allocation for production workloads **Example Response:** ```json { "retriever_id": "ret_abc123", "retriever_name": "product_search", "execution_plan": [ { "stage_index": 0, "stage_name": "attribute_filter", "stage_type": "filter", "estimated_input": 10000, "estimated_output": 5000, "estimated_efficiency": 0.5, "estimated_cost_credits": 0.01, "estimated_duration_ms": 20, "cache_likely": true, "optimization_notes": ["Pushed down from stage 2"], "warnings": [] }, { "stage_index": 1, "stage_name": "semantic_search", "stage_type": "filter", "estimated_input": 5000, "estimated_output": 100, "estimated_efficiency": 0.02, "estimated_cost_credits": 0.5, "estimated_duration_ms": 200, "cache_likely": false, "optimization_notes": [], "warnings": ["High cost stage - consider reducing limit"] } ], "estimated_cost": { "total_credits": 0.51, "total_duration_ms": 220 }, "bottleneck_stages": ["semantic_search"], "optimization_applied": true, "optimization_details": { "original_stage_count": 3, "optimized_stage_count": 2, "optimization_time_ms": 8.2, "stage_reduction_pct": 33.3, "decisions": [ { "rule_type": "push_down_filters", "applied": true, "reason": "Moved attribute_filter before semantic_search to reduce search scope" } ] }, "optimization_suggestions": [ { "type": "reduce_limit", "stage": "semantic_search", "message": "Consider reducing limit to improve latency" } ] } ``` operationId: >- explain_retriever_execution_v1_retrievers__retriever_id__execute_explain_post parameters: - name: retriever_id in: path required: true schema: type: string description: >- Retriever ID or name to explain. The execution plan will show the OPTIMIZED version after automatic transformations. title: Retriever Id description: >- Retriever ID or name to explain. The execution plan will show the OPTIMIZED version after automatic transformations. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExplainRetrieverRequest' description: >- Optional hypothetical inputs for estimation. Provide sample inputs to see how the plan changes with different parameters (e.g., different top_k values, query complexity, filter combinations). If not provided, uses default/representative values. responses: '200': description: >- Detailed execution plan with stage-by-stage cost estimates, optimization details, bottleneck identification, and performance insights. Use this to troubleshoot slow queries, estimate costs, and understand optimizer transformations. content: application/json: schema: $ref: '#/components/schemas/ExplainRetrieverResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ExplainRetrieverRequest: properties: inputs: additionalProperties: true type: object title: Inputs description: >- Hypothetical inputs for tailored execution plan estimation. These values are used to analyze stage behavior and estimate costs. NOT REQUIRED - if omitted, default/representative values are used. Common inputs: - 'query': Search query text (for semantic search stages) - 'top_k': Number of results to return (affects search scope) - Filter parameters: Category, price range, etc. Examples: - {'query': 'laptop'} - Simple text query - {'query': 'laptop', 'top_k': 100} - Query with custom limit - {'query': 'laptop', 'category': 'electronics', 'price_max': 1000} - Query with filters Note: Inputs are for estimation only. No actual search is performed. examples: - query: test query top_k: 50 - category: electronics query: wireless headphones - embedding: - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 - 0.1 top_k: 100 - {} type: object title: ExplainRetrieverRequest description: >- Request to get execution plan for a retriever. Provides optional hypothetical inputs to tailor the execution plan estimation. The explain endpoint analyzes your retriever configuration and returns cost/latency estimates without actually executing the query. Use Cases: - See how plan changes with different input values - Estimate costs for different query patterns - Understand impact of parameter changes (e.g., top_k) - Test stage behavior with representative inputs Behavior: - If inputs are provided, they're used for tailored estimation - If inputs are not provided, default/representative values are used - Inputs do NOT need to match your input_schema exactly - No actual retrieval is performed (explain is analysis only) examples: - description: Explain with simple query input inputs: query: machine learning tutorials - description: Explain with query and custom limit inputs: query: red sports car top_k: 100 - description: Explain with multiple filter parameters inputs: category: electronics price_max: 200 query: wireless headphones - description: Explain with default inputs (empty) inputs: {} ExplainRetrieverResponse: properties: retriever_id: type: string title: Retriever Id description: Unique identifier of the retriever being explained. REQUIRED. examples: - ret_abc123 - ret_product_search_v2 retriever_name: type: string title: Retriever Name description: Human-readable name of the retriever. REQUIRED. examples: - product_search - customer_lookup estimated_cost: additionalProperties: type: number type: object title: Estimated Cost description: >- Estimated total cost breakdown for executing this retriever. Contains: 'total_credits' (credit cost), 'total_duration_ms' (latency). Sum of all stage costs. Use for budget planning. REQUIRED. examples: - total_credits: 0.51 total_duration_ms: 220 - total_credits: 15.5 total_duration_ms: 8500 execution_plan: items: $ref: '#/components/schemas/ExplainStagePlan' type: array title: Execution Plan description: >- Ordered list of stage execution plans showing the OPTIMIZED pipeline. Each entry shows cost, latency, document flow, and warnings for one stage. Stages execute in this order. REQUIRED (may be empty for invalid retrievers). optimization_suggestions: items: additionalProperties: true type: object type: array title: Optimization Suggestions description: >- Actionable suggestions for improving retriever performance. Each suggestion includes: 'type' (suggestion category), 'stage' (affected stage name), 'message' (human-readable description). Common types: 'reduce_limit', 'add_filter', 'reorder_stages', 'enable_cache'. OPTIONAL (empty if no suggestions). examples: - - message: Consider reducing limit from 1000 to 100 to improve latency stage: semantic_search type: reduce_limit - message: Add attribute filter before this expensive stage stage: llm_quality_filter type: add_filter total_estimated_stages: type: integer minimum: 0 title: Total Estimated Stages description: >- Total number of stages in the optimized execution plan. This may differ from your original stage count if optimizations were applied. Compare with optimization_details.original_stage_count to see reduction. REQUIRED. examples: - 2 - 5 - 10 bottleneck_stages: items: type: string type: array title: Bottleneck Stages description: >- Names of stages expected to dominate execution time. Includes stages with duration >= 80%% of the slowest stage. Focus optimization efforts on these stages. OPTIONAL (empty if all stages have similar duration). examples: - - semantic_search - - llm_quality_filter - rerank optimization_level: type: string title: Optimization Level description: >- Optimization level applied by the optimizer. Values: 'none' (no optimization), 'mvp' (basic optimizations), 'advanced' (all optimizations). REQUIRED. default: mvp examples: - none - mvp - advanced optimization_applied: type: boolean title: Optimization Applied description: >- Whether automatic pipeline optimizations were applied. When true, execution_plan shows OPTIMIZED stages (after transformations like filter push-down, stage fusion, grouping optimization). When false, execution_plan matches your original configuration. Check optimization_details to see what changed. REQUIRED. default: false optimization_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Optimization Details description: >- Detailed breakdown of optimization transformations applied. Only present when optimization_applied=true. Fields: - original_stage_count: Stage count before optimization - optimized_stage_count: Stage count after optimization - optimization_time_ms: Time spent on optimization (typically <100ms) - stage_reduction_pct: Percentage reduction in stage count - decisions: Array of optimization decisions Each decision contains: - rule_type: Optimization rule that fired - applied: Whether the rule was applied - reason: Human-readable explanation - stages_before/after: Stage counts before/after this rule Common rule types: - push_down_filters: Move filters earlier to reduce downstream work - group_by_push_down: Push grouping to database layer (10-100x faster) - merge_consecutive_filters: Combine adjacent filters - eliminate_redundant_sorts: Remove duplicate sort operations OPTIONAL (null when optimization_applied=false). examples: - decisions: - applied: true reason: >- Moved attribute_filter before semantic_search to reduce search scope by 50% rule_type: push_down_filters stages_after: 5 stages_before: 5 - applied: true reason: >- Merged group_by into feature_filter for database-level grouping (10x faster) rule_type: group_by_push_down stages_after: 3 stages_before: 5 optimization_time_ms: 8.2 optimized_stage_count: 3 original_stage_count: 5 stage_reduction_pct: 40 type: object required: - retriever_id - retriever_name - estimated_cost - total_estimated_stages title: ExplainRetrieverResponse description: >- Execution plan analysis for a retriever. Provides comprehensive diagnostics about retriever execution characteristics without actually running the query. Similar to MongoDB's explain plan or SQL's EXPLAIN command, this helps troubleshoot performance, estimate costs, and understand optimizer behavior. Use Cases: - Identify bottleneck stages before execution - Estimate costs for budget planning - Debug slow retrievers by analyzing stage efficiency - Understand optimizer transformations - Compare different retriever configurations - Troubleshoot accuracy issues via document flow analysis examples: - bottleneck_stages: - semantic_search description: Simple retriever with optimization applied estimated_cost: total_credits: 0.51 total_duration_ms: 220 execution_plan: - cache_likely: true estimated_cost_credits: 0 estimated_duration_ms: 20 estimated_efficiency: 0.5 estimated_input: 10000 estimated_output: 5000 optimization_notes: - Pushed down from stage 2 stage_index: 0 stage_name: attribute_filter stage_type: filter warnings: [] - cache_likely: false estimated_cost_credits: 0.5 estimated_duration_ms: 200 estimated_efficiency: 0.02 estimated_input: 5000 estimated_output: 100 optimization_notes: [] stage_index: 1 stage_name: semantic_search stage_type: filter warnings: [] optimization_applied: true optimization_details: decisions: - applied: true reason: Moved attribute_filter before semantic_search rule_type: push_down_filters optimization_time_ms: 8.2 optimized_stage_count: 2 original_stage_count: 3 stage_reduction_pct: 33.3 optimization_level: mvp optimization_suggestions: - message: Consider reducing limit to improve latency stage: semantic_search type: reduce_limit retriever_id: ret_abc123 retriever_name: product_search total_estimated_stages: 2 - bottleneck_stages: - llm_quality_filter description: Complex retriever with bottleneck LLM stage estimated_cost: total_credits: 15.5 total_duration_ms: 8500 execution_plan: - cache_likely: false estimated_cost_credits: 0.5 estimated_duration_ms: 200 estimated_efficiency: 0.01 estimated_input: 10000 estimated_output: 100 optimization_notes: [] stage_index: 0 stage_name: semantic_search stage_type: filter warnings: [] - cache_likely: false estimated_cost_credits: 15 estimated_duration_ms: 8000 estimated_efficiency: 0.1 estimated_input: 100 estimated_output: 10 optimization_notes: [] stage_index: 1 stage_name: llm_quality_filter stage_type: filter warnings: - High cost stage - consider reducing input count - Bottleneck stage - dominates execution time optimization_applied: false optimization_level: mvp optimization_suggestions: - message: Add attribute filter before this expensive LLM stage stage: llm_quality_filter type: add_filter retriever_id: ret_xyz789 retriever_name: advanced_search total_estimated_stages: 2 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ExplainStagePlan: properties: stage_index: type: integer minimum: 0 title: Stage Index description: >- Zero-based position of this stage in the execution pipeline. Stages execute sequentially in this order. REQUIRED. examples: - 0 - 1 - 2 stage_name: type: string title: Stage Name description: >- Human-readable name of this stage instance. Corresponds to the 'stage_name' field in your retriever configuration. Use this to map explain plan output back to your pipeline definition. REQUIRED. examples: - initial_filter - semantic_search - rerank_by_relevance stage_type: type: string title: Stage Type description: >- Stage type identifier indicating the category of operation. Common types: 'filter' (reduce documents), 'sort' (reorder), 'reduce' (aggregate), 'apply' (transform/enrich). REQUIRED. examples: - filter - sort - reduce - apply estimated_input: type: integer minimum: 0 title: Estimated Input description: >- Estimated number of documents entering this stage. This is the output count from the previous stage (or initial collection size). Used to project document flow through the pipeline. REQUIRED. examples: - 10000 - 5000 - 100 estimated_output: type: integer minimum: 0 title: Estimated Output description: >- Estimated number of documents leaving this stage. For filter stages, this is typically less than estimated_input. For sort/reduce stages, this may be the same or less. REQUIRED. examples: - 5000 - 100 - 10 estimated_efficiency: type: number minimum: 0 title: Estimated Efficiency description: >- Stage selectivity ratio (estimated_output / estimated_input). Values closer to 0 indicate aggressive filtering. Values closer to 1 indicate most documents pass through. Use this to identify stages that might be too restrictive or too permissive. REQUIRED. examples: - 0.5 - 0.02 - 0.9 estimated_cost_credits: type: number minimum: 0 title: Estimated Cost Credits description: >- Estimated credit cost for executing this stage. Credits are consumed for inference (embeddings, LLM calls), vector searches, and other computational operations. Filter/sort stages typically have near-zero cost. REQUIRED. examples: - 0 - 0.5 - 15 estimated_duration_ms: type: number minimum: 0 title: Estimated Duration Ms description: >- Estimated latency contribution of this stage in milliseconds. High values indicate potential bottlenecks. Sum across stages gives total estimated execution time. REQUIRED. examples: - 20 - 200 - 5000 cache_likely: type: boolean title: Cache Likely description: >- Whether this stage is likely to hit cache based on recent execution history. True = cache hit likely (near-zero actual latency/cost). False = cache miss likely (full cost incurred). Use this to understand when queries will be fast vs slow. REQUIRED. optimization_notes: items: type: string type: array title: Optimization Notes description: >- Human-readable notes about optimizations applied to this stage. Examples: 'Pushed down from stage 2', 'Merged with previous filter', 'Grouping pushed to database layer'. Empty if no optimizations were applied. OPTIONAL. examples: - - Pushed down from stage 3 to reduce search scope - - Merged with previous filter for efficiency - [] warnings: items: type: string type: array title: Warnings description: >- Performance warnings or potential issues with this stage. Examples: 'High cost stage - consider reducing limit', 'Very low efficiency - may need filter tuning', 'LLM stage without prior filtering - expensive'. Empty if no warnings. OPTIONAL. examples: - - High cost stage - consider reducing limit - - Very low selectivity (0.001) - may indicate poor filter tuning - [] type: object required: - stage_index - stage_name - stage_type - estimated_input - estimated_output - estimated_efficiency - estimated_cost_credits - estimated_duration_ms - cache_likely title: ExplainStagePlan description: >- Stage-level execution plan details for retriever explain endpoint. Provides detailed cost, performance, and optimization information for a single stage in the retriever pipeline. Use this to understand stage behavior, identify bottlenecks, and troubleshoot performance issues. This is analogous to a single row in MongoDB's explain plan output, showing how documents flow through the stage and what resources are consumed. examples: - cache_likely: true description: Fast filter stage with cache hit estimated_cost_credits: 0 estimated_duration_ms: 20 estimated_efficiency: 0.5 estimated_input: 10000 estimated_output: 5000 optimization_notes: - Pushed down from stage 2 stage_index: 0 stage_name: attribute_filter stage_type: filter warnings: [] - cache_likely: false description: Expensive semantic search stage estimated_cost_credits: 0.5 estimated_duration_ms: 200 estimated_efficiency: 0.02 estimated_input: 5000 estimated_output: 100 optimization_notes: [] stage_index: 1 stage_name: semantic_search stage_type: filter warnings: [] - cache_likely: false description: Bottleneck LLM stage with warnings estimated_cost_credits: 15 estimated_duration_ms: 8000 estimated_efficiency: 0.1 estimated_input: 100 estimated_output: 10 optimization_notes: [] stage_index: 2 stage_name: llm_quality_filter stage_type: filter warnings: - High cost stage - consider reducing input count - Bottleneck stage - dominates execution time ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ````