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

<Frame>
  <img src="https://mintcdn.com/mixpeek/TmiAqiYj-LwmWL2a/assets/retrievers/sort-relevance.svg?fit=max&auto=format&n=TmiAqiYj-LwmWL2a&q=85&s=feed410c224a3f23047428fbdb2c904f" alt="Sort Relevance stage showing document reordering by relevance scores" width="800" height="300" data-path="assets/retrievers/sort-relevance.svg" />
</Frame>

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)
</Note>

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

<CodeGroup>
  ```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"
      }
    }
  }
  ```
</CodeGroup>

## 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](/docs/retrieval/stages/rerank) - Neural re-scoring
* [Sort Attribute](/docs/retrieval/stages/sort-attribute) - Metadata sorting
* [MMR](/docs/retrieval/stages/mmr) - Diversity-aware sorting


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