> ## 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.

# Sort Relevance

> Reorder documents by their relevance scores from previous stages

![Sort Relevance stage showing document reordering by relevance scores](https://mintcdn.com/mixpeek/TmiAqiYj-LwmWL2a/assets/retrievers/sort-relevance.svg?fit=max\&auto=format\&n=TmiAqiYj-LwmWL2a\&q=85\&s=feed410c224a3f23047428fbdb2c904f)

The Sort Relevance stage reorders documents based on their relevance scores from previous stages. This is useful when documents have been modified or filtered and need to be re-sorted by their original search scores.

> [!NOTE]
>
> **Stage Category**: SORT (Reorders documents)
>
> **Transformation**: N documents → N documents (reordered by relevance)

## When to Use

| Use Case | Description |
| - | - |
| **Post-filter sorting** | Re-sort after attribute\_filter removes documents |
| **Score normalization** | Apply consistent sorting after multi-stage processing |
| **Restoring order** | Return to relevance order after other sort operations |
| **Combining scores** | Sort by combined scores from multiple sources |

## When NOT to Use

| Scenario | Recommended Alternative |
| - | - |
| Sorting by metadata field | `sort_by_field` |
| Neural re-scoring | `rerank` |
| Results already sorted | Skip this stage |
| Diversifying results | `mmr` |

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_field` | string | `score` | Field containing relevance score |
| `direction` | string | `desc` | Sort direction: `desc` (highest first) or `asc` |
| `missing_score` | string | `bottom` | Where docs lacking a score go: `bottom`, `top`, or `preserve` |

## Configuration Examples

```json Basic Relevance Sort theme={null}
{
  "stage_name": "sort_relevance",
  "stage_type": "sort",
  "config": {
    "stage_id": "sort_relevance",
    "parameters": {
      "direction": "desc"
    }
  }
}
```

```json Custom Score Field theme={null}
{
  "stage_name": "sort_relevance",
  "stage_type": "sort",
  "config": {
    "stage_id": "sort_relevance",
    "parameters": {
      "score_field": "search_score",
      "direction": "desc"
    }
  }
}
```

```json Missing Score Handling theme={null}
{
  "stage_name": "sort_relevance",
  "stage_type": "sort",
  "config": {
    "stage_id": "sort_relevance",
    "parameters": {
      "score_field": "score",
      "direction": "desc",
      "missing_score": "bottom"
    }
  }
}
```

```json Ascending Order theme={null}
{
  "stage_name": "sort_relevance",
  "stage_type": "sort",
  "config": {
    "stage_id": "sort_relevance",
    "parameters": {
      "score_field": "distance",
      "direction": "asc"
    }
  }
}
```

## How It Works

1. **Extract Scores**: Read the score field from each document
2. **Sort**: Order documents by score (descending by default)
3. **Optionally Normalize**: Scale scores to 0-1 range
4. **Return**: Documents in new order

## Output Schema

```json theme={null}
{
  "document_id": "doc_123",
  "content": "Document content...",
  "score": 0.95,
  "sort_relevance": {
    "original_position": 3,
    "new_position": 1,
    "normalized_score": 1.0
  }
}
```

## Performance

| Metric | Value |
| - | - |
| **Latency** | \< 5ms |
| **Memory** | O(N) |
| **Cost** | Free |
| **Complexity** | O(N log N) |

## Common Pipeline Patterns

### Search + Filter + Re-sort

```json theme={null}
[
  {
    "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": "structured_filter",
    "stage_type": "filter",
    "config": {
      "stage_id": "attribute_filter",
      "parameters": {
        "field": "metadata.status",
        "operator": "eq",
        "value": "published"
      }
    }
  },
  {
    "stage_name": "sort_relevance",
    "stage_type": "sort",
    "config": {
      "stage_id": "sort_relevance",
      "parameters": {
        "direction": "desc"
      }
    }
  }
]
```

### Multi-Stage with Score Normalization

```json theme={null}
[
  {
    "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": 50 }
        ],
        "final_top_k": 50
      }
    }
  },
  {
    "stage_name": "llm_enrichment",
    "stage_type": "enrich",
    "config": {
      "stage_id": "llm_enrich",
      "parameters": {
        "model_name": "gpt-4o-mini",
        "prompt": "Extract key topics",
        "output_field": "topics"
      }
    }
  },
  {
    "stage_name": "sort_relevance",
    "stage_type": "sort",
    "config": {
      "stage_id": "sort_relevance",
      "parameters": {
        "direction": "desc"
      }
    }
  }
]
```

## Comparison with Other Sort Stages

| Stage | Purpose | Score Source |
| - | - | - |
| `sort_relevance` | Relevance scores | Search/fusion scores |
| `sort_by_field` | Metadata values | Any document field |
| `rerank` | Neural re-scoring | Cross-encoder model |
| `mmr` | Diversity | Relevance + diversity |

## Error Handling

| Error | Behavior |
| - | - |
| Missing score field | Use 0 as default |
| Non-numeric score | Move to end |
| Empty input | Return empty |
| Equal scores | Maintain original order |

## Related

* [Rerank](https://docs.mixpeek.com/docs/retrieval/stages/rerank.md) - Neural re-scoring
* [Sort Attribute](https://docs.mixpeek.com/docs/retrieval/stages/sort-attribute.md) - Metadata sorting
* [MMR](https://docs.mixpeek.com/docs/retrieval/stages/mmr.md) - Diversity-aware sorting


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.