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