Quick Start

Need to quickly boost some results? Start here:

{
  "query": {
    "text": {
      "query": "championship",
      "path": "heroMedia.title",
      "score": {
        "boost": 2.0
      }
    }
  }
}

Choosing the right score modification:

┌─────────────────────────────────────────────────────────┐
│ Do you need time-based relevance (recent = higher)?    │
│                                                         │
│ YES → Use `function` with Gaussian decay               │
│ NO → Continue below                                     │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ Do you want to multiply the existing relevance score?   │
│                                                         │
│ YES → Use `boost`                                       │
│ NO → Continue below                                     │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ Do you want all matches to have the same score?        │
│                                                         │
│ YES → Use `constant`                                    │
│ NO → Use `function` for custom logic                   │
└─────────────────────────────────────────────────────────┘

Performance: boost ≈ constant > function (arithmetic) > function (Gaussian)

Most common patterns:

1. Boost important fields: boost: 2.0 - 5.0
2. Equal priority: constant: 100
3. Recent articles preferred: function with gauss

boost

The boost option multiplies the score of articles that match a query by a specified factor. For example, you can use boost to give higher relevance to certain fields or search terms.

Performance: Boost is the most efficient score modification option.

Typical use cases:

• Boost specific fields (e.g., title matches more important than content matches)
• Increase relevance of certain tags or categories
• Prioritise featured or pinned content

Score ranges: Relevance scores typically range from 1-20, but can be higher for very relevant matches. Common boost values:

• 1.5-3.0 - Moderate boost for slightly more important matches
• 3.0-10.0 - Strong boost for very important matches
• 10.0+ - Extreme boost for critical matches

Note:

• The boost value must be a positive number.
• A boost value of 1.0 means no change to the score.
• Higher boost values increase the score proportionally.
• Cannot be combined with constant or function in the same score object.

Fields

The boost option takes the following fields:

Example

{
  "query": {
    "text": {
      "path": "heroMedia.title",
      "query": "tournament final",
      "score": {
        "boost": {
          "value": 2.0
        }
      }
    }
  }
}

Alternatively, you can use a shorthand syntax:

{
  "query": {
    "text": {
      "path": "heroMedia.title",
      "query": "tournament final",
      "score": {
        "boost": 2.0
      }
    }
  }
}

constant

The constant option replaces the base score of matching articles with a fixed constant value. This is useful when you want all matching articles to have the same score regardless of their text relevance.

Performance: Very efficient, similar to boost.

Typical use cases:

• Equalising scores for specific filters (e.g., all pinned articles get score 100)
• Overriding relevance for exact matches
• Creating consistent scoring for non-text-based matches

Note: Cannot be combined with boost or function in the same score object.

Fields

The constant option takes the following fields:

Example

{
  "query": {
    "text": {
      "path": "heroMedia.title",
      "query": "betting",
      "score": {
        "constant": {
          "value": 5.0
        }
      }
    }
  }
}

Alternatively, you can use a shorthand syntax:

{
  "query": {
    "text": {
      "path": "heroMedia.title",
      "query": "betting",
      "score": {
        "constant": 5.0
      }
    }
  }
}

function

The function option provides advanced score manipulation using mathematical expressions. This is more powerful than boost or constant but also more computationally expensive.

Performance: Functions are the most computationally expensive score modification option, especially Gaussian decay. Use when the flexibility is needed.

Typical use cases:

• Time-based relevance decay (recent articles score higher)
• Complex scoring formulae combining multiple factors
• Non-linear score adjustments

Note: Cannot be combined with boost or constant in the same score object.

Expressions

Use the following expressions with the function option to modify the score of articles:

• Arithmetic expressions - Add, multiply, min, or max a series of numbers
• Constant expressions - Apply a fixed numeric value in the function score
• Gaussian decay expressions - Reduce scores by multiplying them at a specified rate

Important: Unless otherwise specified, all expressions replace the original score of matching articles. To modify the original score instead of replacing it, include the original score using {"score": "relevance"} in your expression where appropriate.

Arithmetic

Arithmetic expressions perform basic mathematical operations on numeric values to replace the score of matching articles.

add

The add expression sums a list of numeric values.

Example

{
  "function": {
    "add": [{ "score": "relevance" }, { "constant": 3.0 }]
  }
}

In this example, the final score is the sum of the original relevance score and a constant value of 3.0.

multiply

The multiply expression multiplies a list of numeric values.

Example

{
  "function": {
    "multiply": [{ "score": "relevance" }, { "constant": 2.0 }]
  }
}

min

The min expression returns the minimum value from a list of numeric values.

Example

{
  "function": {
    "min": [{ "score": "relevance" }, { "constant": 10.0 }]
  }
}

In this example, the final score is capped at a maximum of 10.0 (whichever is smaller: the relevance score or 10.0).

max

The max expression returns the maximum value from a list of numeric values.

Example

{
  "function": {
    "max": [{ "score": "relevance" }, { "constant": 1.0 }]
  }
}

In this example, the final score is at least 1.0 (whichever is larger: the relevance score or 1.0).

Constant

Constant expressions allow you to replace the score of matching articles with a fixed numeric value.

Example

{
  "function": {
    "constant": 4.0
  }
}

Gaussian

Gaussian decay expressions reduce the scores of articles based on their distance from a specified origin point. This is useful for scenarios like time-based relevance, such as prioritising recently published articles.

How it works: Articles closer to the origin maintain higher scores, whilst articles further away see their scores gradually reduced using a bell curve distribution.

Fields

The Gaussian decay expression takes the following fields:

Example interpretation:

• origin: "now", scale: "30d", decay: 0.5 - Articles 30 days old have 50% of their score
• origin: "now", scale: "30d", decay: 0.5, offset: "7d" - Articles 0-7 days old maintain full score; at 37 days old they have 50% score

Example

{
  "function": {
    "gauss": {
      "path": "publishDate",
      "origin": "now",
      "scale": "10d",
      "decay": 0.5,
      "offset": "5d"
    }
  }
}

Example usage

Boost recent articles

This example applies time-based scoring to all articles (no search query). Articles are sorted by recency with a gradual decay.

{
  "score": {
    "function": {
      "gauss": {
        "path": "publishDate",
        "origin": "now",
        "scale": "30d",
        "decay": 0.5
      }
    }
  }
}

Note: When no operator is specified in the request, all documents are matched and scored using the function.

Boost recent articles relative to search relevance

To boost recent articles whilst still considering their original relevance score, you can combine the original score with a Gaussian decay function using the multiply expression:

{
  "query": {
    "text": {
      "query": "championship",
      "path": "content.text",
      "score": {
        "function": {
          "multiply": [
            { "score": "relevance" },
            {
              "gauss": {
                "path": "publishDate",
                "origin": "now",
                "scale": "30d",
                "decay": 0.5
              }
            }
          ]
        }
      }
    }
  }
}

Boost articles with "breaking" in the title

{
  "query": {
    "text": {
      "query": "breaking",
      "path": "heroMedia.title",
      "score": {
        "boost": 2.0
      }
    }
  }
}

Valid Score Modification Combinations

Only one score modification type can be used per score object:

Valid:

• boost alone
• constant alone
• function alone
• Multiple score modifications in different clauses of a compound query

Invalid:

• boost + constant in the same score object
• boost + function in the same score object
• constant + function in the same score object

Example of multiple score modifications (valid):

{
  "compound": {
    "should": [
      {
        "text": {
          "query": "championship",
          "path": "heroMedia.title",
          "score": {
            "boost": 3.0
          }
        }
      },
      {
        "equal": {
          "path": "pinned",
          "value": true,
          "score": {
            "constant": 100
          }
        }
      }
    ]
  }
}

Performance Considerations

Score modification performance (fastest to slowest):

1. boost - Simple multiplication, minimal overhead
2. constant - Direct assignment, minimal overhead
3. function (arithmetic) - Add/multiply operations, moderate overhead
4. function (Gaussian) - Complex calculations involving date math and decay curves, highest overhead

Recommendations:

• Use boost for simple score adjustments when possible
• Reserve function for cases where time-based decay or complex formulae are necessary
• Consider the trade-off between query performance and scoring sophistication
• For high-traffic endpoints, prefer boost over Gaussian functions when acceptable