# Score modification

This document explains how search results can be scored and ranked, using `boost`, `constant`, and `function` options.

# Quick Start

**Need to quickly boost some results?** Start here:

```json
{
  "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:

| Field   | Type  | Description                             | Required |
| ------- | ----- | --------------------------------------- | -------- |
| `value` | float | The boost factor to apply to the score. | Yes      |

### Example

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

Alternatively, you can use a shorthand syntax:

```json
{
  "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:

| Field   | Type  | Description                              | Required |
| ------- | ----- | ---------------------------------------- | -------- |
| `value` | float | The constant score to assign to matches. | Yes      |

## Example

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

Alternatively, you can use a shorthand syntax:

```json
{
  "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

```json
{
  "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

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

#### `min`

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

##### Example

```json
{
  "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

```json
{
  "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

```json
{
  "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:

| Field    | Type   | Description                                                                                                                                                                                         | Required |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `origin` | string | The reference point from which to calculate distance.                                                                                                                                               | Yes      |
| `scale`  | string | The distance from the origin at which the score will be reduced by half.                                                                                                                            | Yes      |
| `decay`  | float  | The rate at which the score decays. Default is `0.5`. A value of `0.5` means at `scale` distance, the score is multiplied by 0.5 (reduced by 50%). Lower values (e.g., `0.1`) create steeper decay. | No       |
| `offset` | string | The distance from the origin before decay starts. Default is `0`. Articles within this offset from origin maintain full score before decay begins.                                                  | No       |
| `path`   | string | The field to which the decay function is applied (typically a date field).                                                                                                                          | Yes      |

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

```json
{
  "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.

```json
{
  "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:

```json
{
  "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

```json
{
  "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):**

```json
{
  "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