Function score query in Elasticsearch

Introduction

A function score query lets you change how search results are scored or ranked by applying custom functions. This helps you show more relevant results based on your own rules.

You want to boost documents that have a higher value in a certain field, like popularity or rating.

You want to reduce the score of documents that are older or less relevant.

You want to combine a normal search with a custom scoring function to influence the order of results.

You want to apply multiple scoring functions with different weights to fine-tune ranking.

You want to add randomness to scores for A/B testing or varied results.

Syntax

Elasticsearch

{
  "function_score": {
    "query": { ... },
    "functions": [
      {
        "field_value_factor": {
          "field": "field_name",
          "factor": 1.2,
          "modifier": "sqrt"
        },
        "weight": 2
      },
      {
        "random_score": {}
      }
    ],
    "score_mode": "sum",
    "boost_mode": "multiply"
  }
}

The query part defines which documents to search.

The functions array contains scoring functions to adjust scores.

Examples

This boosts documents with higher popularity field values.

Elasticsearch

{
  "function_score": {
    "query": { "match": { "title": "elasticsearch" } },
    "functions": [
      {
        "field_value_factor": {
          "field": "popularity",
          "factor": 1.5
        }
      }
    ]
  }
}

This adds a random score to all documents to shuffle results.

Elasticsearch

{
  "function_score": {
    "query": { "match_all": {} },
    "functions": [
      {
        "random_score": {
          "seed": 12345
        }
      }
    ],
    "score_mode": "sum"
  }
}

This replaces the original score with a fixed weight for active documents.

Elasticsearch

{
  "function_score": {
    "query": { "term": { "status": "active" } },
    "functions": [
      {
        "weight": 3
      }
    ],
    "boost_mode": "replace"
  }
}

Sample Program

This query searches for documents with "coffee" in the description. It boosts scores based on the rating field using a logarithmic scale and adds extra weight to documents in the "beverages" category. The scores from functions are summed and then multiplied with the original score.

Elasticsearch

{
  "query": {
    "function_score": {
      "query": {
        "match": {
          "description": "coffee"
        }
      },
      "functions": [
        {
          "field_value_factor": {
            "field": "rating",
            "factor": 2,
            "modifier": "log1p"
          }
        },
        {
          "weight": 5,
          "filter": {
            "term": { "category": "beverages" }
          }
        }
      ],
      "score_mode": "sum",
      "boost_mode": "multiply"
    }
  }
}

Important Notes

You can combine multiple functions to fine-tune scoring.

Use score_mode to decide how function scores combine (sum, multiply, max, etc.).

Use boost_mode to decide how function scores combine with the original query score.

Summary

Function score query lets you customize how search results are ranked.

You can boost or reduce scores using field values, weights, or random scores.

It helps make search results more relevant to your needs.