Request payload for executing a retriever. Executes a predefined retriever with runtime inputs. The retriever uses the collections it was created with - collection overrides are not supported at execution time to ensure feature_uri and schema validation integrity. All filtering, pagination, and result shaping is handled by the individual stages based on the inputs provided. Use Cases: - Execute retriever with its configured collections - Pass inputs that stages use to determine filtering/pagination behavior Design Philosophy: - Retrievers are validated at creation time against their collections - Feature URIs, input schemas, and stage configs are tightly coupled to collections - Filters, limits, and offsets are NOT top-level request fields - These are handled by stages when they receive inputs - Example: A stage might read {INPUT.top_k} to determine result limit Examples: Simple query: {"inputs": {"query": "AI", "top_k": 50}} Different inputs for stage behavior: {"inputs": { "query": "machine learning", "top_k": 100, "min_score": 0.7, "published_after": "2024-01-01" }}
| Name | Type | Description | Notes |
|---|---|---|---|
| inputs | Dict[str, object] | Runtime inputs for the retriever mapped to the input schema. Keys must match the retriever's input_schema field names. Values depend on field types (text, vector, filters, etc.). REQUIRED unless all retriever inputs have defaults. Common input keys: - 'query': Text search query - 'embedding': Pre-computed vector for search - 'top_k': Number of results to return - 'min_score': Minimum relevance threshold - Any custom fields defined in input_schema Template Syntax (Jinja2): Namespaces (uppercase or lowercase): - `INPUT` / `input`: Query inputs (e.g., `{{INPUT.query}}`) - `DOC` / `doc`: Document fields (e.g., `{{DOC.payload.title}}`) - `CONTEXT` / `context`: Execution context - `STAGE` / `stage`: Stage configuration - `SECRET` / `secret`: Vault secrets (e.g., `{{SECRET.api_key}}`) Accessing Data: - Dot notation: `{{DOC.payload.metadata.title}}` - Bracket notation: `{{DOC.payload['special-key']}}` - Array index: `{{DOC.items[0]}}`, `{{DOC.tags[2]}}` - Array first/last: `{{DOC.items | first}}`, `{{DOC.items |
| pagination | Pagination | [optional] | |
| stream | bool | Enable streaming execution to receive real-time stage updates via Server-Sent Events (SSE). NOT REQUIRED - defaults to False for standard execution. When stream=True: - Response uses text/event-stream content type - Each stage completion emits a StreamStageEvent - Events include: stage_start, stage_complete, stage_error, execution_complete - Clients receive intermediate results and statistics as stages execute - Useful for progress tracking, debugging, and partial result display When stream=False (default): - Response returns after all stages complete - Returns a single RetrieverExecutionResponse with final results - Lower overhead for simple queries Use streaming when: - You want to show real-time progress to users - You need to display intermediate results - Pipeline has many stages or long-running operations - Debugging or monitoring pipeline performance Example streaming client (JavaScript): ```javascript const eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true'); eventSource.onmessage = (event) => { const stageEvent = JSON.parse(event.data); if (stageEvent.event_type === 'stage_complete') { console.log(`Stage ${stageEvent.stage_name} completed`); console.log(`Documents: ${stageEvent.documents.length}`); } }; ``` Example streaming client (Python): ```python import requests response = requests.post('/v1/retrievers/ret_123/execute', json={'inputs': {...}, 'stream': True}, stream=True) for line in response.iter_lines(): if line.startswith(b'data: '): event = json.loads(line[6:]) print(f"Stage {event['stage_name']}: {event['event_type']}") ``` | [optional] [default to False] |
from mixpeek.models.retriever_execution_request import RetrieverExecutionRequest
# TODO update the JSON string below
json = "{}"
# create an instance of RetrieverExecutionRequest from a JSON string
retriever_execution_request_instance = RetrieverExecutionRequest.from_json(json)
# print the JSON string representation of the object
print(RetrieverExecutionRequest.to_json())
# convert the object into a dict
retriever_execution_request_dict = retriever_execution_request_instance.to_dict()
# create an instance of RetrieverExecutionRequest from a dict
retriever_execution_request_from_dict = RetrieverExecutionRequest.from_dict(retriever_execution_request_dict)