Stage Category: GROUP (Groups documents)Transformation: N documents → G groups (where G = unique field values)
When to Use
| Use Case | Description |
|---|---|
| Category grouping | Group products by category |
| Author aggregation | Group articles by author |
| Date grouping | Group by day/month/year |
| Source organization | Group by data source |
When NOT to Use
| Scenario | Recommended Alternative |
|---|---|
| Semantic similarity grouping | cluster |
| Statistical aggregations only | aggregate |
| Removing duplicates | deduplicate |
| Top-N per group | Use with sample |
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
group_by_field | string | source_object_id | Field to group by (dot notation supported) |
max_per_group | integer | 10 | Maximum documents to keep per group |
output_mode | string | all | first (top doc per group), all (grouped), flatten (flat list) |
Configuration Examples
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.category"
}
}
}
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.author",
"max_per_group": 5
}
}
}
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.brand",
"max_per_group": 1,
"output_mode": "first"
}
}
}
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.publish_date"
}
}
}
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.source.type",
"max_per_group": 3
}
}
}
Output Schema
{
"groups": [
{
"key": "electronics",
"count": 25,
"documents": [
{
"document_id": "doc_123",
"content": "Latest smartphone review...",
"score": 0.95,
"metadata": {"category": "electronics", "price": 999}
},
{
"document_id": "doc_456",
"content": "Laptop comparison guide...",
"score": 0.89,
"metadata": {"category": "electronics", "price": 1299}
}
]
},
{
"key": "clothing",
"count": 18,
"documents": [...]
}
],
"metadata": {
"total_groups": 5,
"total_documents": 100,
"field": "metadata.category"
}
}
Performance
| Metric | Value |
|---|---|
| Latency | 5-20ms |
| Memory | O(N) |
| Cost | Free |
| Scalability | Efficient |
Common Pipeline Patterns
Search + Group by Category
[
{
"stage_name": "semantic_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 100 }
],
"final_top_k": 100
}
}
},
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.category",
"max_per_group": 5
}
}
}
]
Grouped Results with Aggregations
[
{
"stage_name": "hybrid_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 200 }
],
"final_top_k": 200
}
}
},
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.brand",
"max_per_group": 10
}
}
},
{
"stage_name": "aggregate",
"stage_type": "reduce",
"config": {
"stage_id": "aggregate",
"parameters": {
"aggregations": [
{"type": "avg", "field": "metadata.price", "name": "avg_price"},
{"type": "avg", "field": "metadata.rating", "name": "avg_rating"}
],
"group_by": "metadata.brand"
}
}
}
]
Author-Grouped Search
[
{
"stage_name": "semantic_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 100 }
],
"final_top_k": 100
}
}
},
{
"stage_name": "document_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "document_enrich",
"parameters": {
"target_collection_id": "authors",
"target_field": "author_id",
"source_field": "metadata.author_id",
"output_field": "author"
}
}
},
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "author.name",
"max_per_group": 3
}
}
}
]
Time-Based Grouping
[
{
"stage_name": "structured_filter",
"stage_type": "filter",
"config": {
"stage_id": "attribute_filter",
"parameters": {
"conditions": {
"field": "metadata.date",
"operator": "gte",
"value": "2024-01-01"
}
}
}
},
{
"stage_name": "code_execution",
"stage_type": "apply",
"config": {
"stage_id": "code_execution",
"parameters": {
"code": "def transform(doc):\n date = doc.get('metadata', {}).get('date', '')\n doc['metadata']['month'] = date[:7] # YYYY-MM\n return doc"
}
}
},
{
"stage_name": "group_by",
"stage_type": "group",
"config": {
"stage_id": "group_by",
"parameters": {
"group_by_field": "metadata.month"
}
}
}
]
Document Sorting Within Groups
Documents within each group are automatically sorted by relevancescore (highest first), then limited to max_per_group.
Output Modes
output_mode | Description |
|---|---|
all (default) | Return all documents (up to max_per_group) grouped by field |
first | Return only the top-scoring document per group (deduplication) |
flatten | Return all documents as a flat list (drops group structure) |
Handling Missing Values
Documents missing thegroup_by_field value are grouped under a null key.
Error Handling
| Error | Behavior |
|---|---|
| Missing field | Documents grouped under “null” key |
| Empty results | Return empty groups array |
| Invalid field path | Stage fails |
Group By vs Cluster
| Aspect | Group By | Cluster |
|---|---|---|
| Grouping basis | Field value | Embedding similarity |
| Groups known | Yes (field values) | No (discovered) |
| Speed | Fast | Slower |
| Use case | Category organization | Theme discovery |
Related
- Aggregate - Statistical aggregations
- Cluster - Semantic grouping
- Sample - Select from groups
- Sort Attribute - Simple sorting