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.
The Unwind stage decomposes array fields into separate documents, producing one output document per array element. This is the retriever pipeline equivalent of MongoDB’s $unwind, Snowflake’s LATERAL FLATTEN, and Spark’s explode().
Stage Category : APPLY (Expands documents)Transformation : N documents → M documents (where M ≥ N, one per array element)
When to Use Use Case Description Tag expansion Decompose multi-tag documents for per-tag analysis Segment decomposition Flatten video/audio segments into individual results Author attribution Expand author lists for per-author scoring Chunk flattening Convert grouped chunks back into individual documents Category expansion Expand multi-category items for faceted search
When NOT to Use Scenario Recommended Alternative Filtering documents attribute_filter or llm_filterRestructuring without expansion json_transformSorting documents sort_attribute or sort_relevanceGrouping documents group_by (inverse operation)
Parameters Parameter Type Default Description fieldstring required Dot-notation path to the array field to unwind preserve_null_and_emptyboolean falseKeep documents where array is null/missing/empty include_array_indexstring nullField name to store the element’s array index output_fieldstring nullPlace unwound element in this field instead of replacing
Configuration Examples Basic Tag Unwind
With Array Index Tracking
Output to Separate Field
{ "stage_type" : "apply" , "stage_id" : "unwind" , "parameters" : { "field" : "metadata.tags" } }
How It Works
For each input document, extracts the array value at the specified field path
If the value is an array with K elements, produces K output documents
Each output document preserves all original fields, with the array field replaced by a single element
Documents with null/empty arrays are either dropped or preserved based on preserve_null_and_empty
Non-array values are passed through unchanged
Use include_array_index when you need to reconstruct the original order later, such as when reassembling video segments after per-segment scoring.
Metric Value Latency < 5ms Memory Proportional to output count Cost Free Complexity O(total array elements)
Common Pipeline Patterns Per-Tag Scoring [ { "stage_type" : "filter" , "stage_id" : "feature_search" , "parameters" : { "feature_uris" : [{ "input" : { "text" : "{{INPUT.query}}" }, "uri" : "mixpeek://text_extractor@v1/embedding" }], "limit" : 50 } }, { "stage_type" : "apply" , "stage_id" : "unwind" , "parameters" : { "field" : "metadata.tags" , "include_array_index" : "tag_index" } }, { "stage_type" : "group" , "stage_id" : "group_by" , "parameters" : { "field" : "metadata.tags" } } ]
Segment-Level Retrieval [ { "stage_type" : "filter" , "stage_id" : "feature_search" , "parameters" : { "feature_uris" : [{ "input" : { "text" : "{{INPUT.query}}" }, "uri" : "mixpeek://text_extractor@v1/embedding" }], "limit" : 20 } }, { "stage_type" : "apply" , "stage_id" : "unwind" , "parameters" : { "field" : "content.segments" , "output_field" : "current_segment" } }, { "stage_type" : "sort" , "stage_id" : "rerank" , "parameters" : { "inference_name" : "baai_bge_reranker_v2_m3" , "query" : "{{INPUT.query}}" , "document_field" : "current_segment" } } ]
Error Handling Error Behavior Field path doesn’t exist Document dropped (or preserved if preserve_null_and_empty=true) Field is not an array Document passed through unchanged Empty array Document dropped (or preserved with null if preserve_null_and_empty=true) Null field value Same as empty array behavior
JSON Transform - Restructure document fields without expansionGroup By - Inverse operation: group documents by field valueDeduplicate - Remove duplicates after expansion 
