> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: searchscore, scoredetails, vectorsearchscore
-->

# Score the Documents in the Results

Every document returned by a MongoDB Search or MongoDB Vector Search query is assigned a score based on relevance, and the documents included in a result set are returned in order from highest score to lowest.

## Usage

To include the score of each document in your search results, use the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage in your aggregation pipeline.

- For the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage, the `score` field takes the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression, which requires the `searchScore` value. You can also specify the `searchScoreDetails` value for the `scoreDetails` field [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression for a detailed breakdown of the score.

- For the [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch) stage, the `score` field takes the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression, which requires the `vectorSearchScore` value to return the score of each document in your vector search results.

**Note:**

You can use:

- `searchScore` only in [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) queries

- `vectorSearchScore` only in [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch) queries

If you use `searchScore` and `vectorSearchScore` in any other query, MongoDB logs a warning starting in MongoDB v8.2.

**Example:**

The following query uses a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage to add a field named `score` to the returned documents:

### Search Score

```javascript
db.movies.aggregate([
  {
    "$search": {
      "text": {
        <operator-specification>
      }
    }
  },
  {
    "$project": {
      "<field-to-include>": 1,
      "<field-to-exclude>": 0,
      "score": { "$meta": "searchScore" }
    }
  }
])
```

## Behavior

The score assigned to a returned document is part of the document's metadata. You can use a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage in your aggregation pipeline to include each returned document's score along with the result set. Documents return from highest score to lowest. Many factors can influence a document's score, including the following:

- Position of the search term in the document.

- Frequency of occurrence of the search term in the document.

- Type of [operator](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-fts-operators) or [analyzer](https://www.mongodb.com/docs/search/indexes/analyzers/overview.md#std-label-analyzers-ref) a MongoDB Search query uses.

To learn more about the Lucene scoring algorithm, see [Lucene documentation.](https://lucene.apache.org/core/3_5_0/scoring.html)

### Additional Options

In addition to the default scoring behavior, MongoDB Search supports the following options:

- [Modifying](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-options) the score assigned to certain documents.

- Returning a detailed breakdown of the score by using the [score details](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-score-details) option.

- [Normalizing](https://www.mongodb.com/docs/search/query/score/customize-score.md#std-label-fts-normalize-score) the search score.

### Considerations

If multiple documents in the results have identical scores, the ordering of the documents in the results is non-deterministic. If you want your MongoDB Search results to have a determined order, include the [sort](https://www.mongodb.com/docs/search/query/sort.md#std-label-sort-ref) option in your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage to sort the results by a unique field. You can use the [sort](https://www.mongodb.com/docs/search/query/sort.md#std-label-sort-ref) option to also return an ascending sort of the results by score. To learn more, see [Sort MongoDB Search Results](https://www.mongodb.com/docs/search/query/sort.md#std-label-sort-ref) and [Sort by Score Examples.](https://www.mongodb.com/docs/search/query/sort.md#std-label-sort-by-score-egs)

On [separate Search Nodes](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution.md#std-label-configure-search-nodes), each node assigns documents different internal Lucene IDs used for sorting when scores are identical. When sorting and [paginating](https://www.mongodb.com/docs/search/query/paginate-results.md#std-label-fts-paginate-results) results, the `mongot` process on the node that is processing the query might include documents from other nodes if their internal IDs have greater pagination order than the token. To prevent this, use [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) after [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) to exclude documents by their `_id`.

When querying array values, MongoDB Search assigns higher scores if more values in the array match the query.

## Tutorials

| For examples on how to use additional `score` options in your MongoDB Search queries, see the following pages: | [Modify the Score](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-options); [Return the Score Details](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-score-details); [Example Queries](https://www.mongodb.com/docs/search/query/score/customize-score.md#std-label-fts-normalize-score) |
| --- | --- |
| For examples on how to use the `score` field in some common MongoDB Search queries, see the following pages: | [Compound Query Examples](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-examples); [Embedded Document Examples](https://www.mongodb.com/docs/search/query/operators-collectors/embedded-document.md#std-label-embedded-document-query-examples); [String Sort Example](https://www.mongodb.com/docs/search/query/sort.md#std-label-fts-sort-eg-string) |