Add scoring profiles to boost search scores

Scoring profiles are used to boost the ranking of matching documents based on criteria. In this article, learn how to specify and assign a scoring profile that boosts a search score based on parameters that you provide. You can create scoring profiles based on:

• Weighted string fields, where boosting is based on a match found in a designated field. For example, matches found in a "Subject" field are considered more relevant than the same match found in a "Description" field.

• Functions for numeric fields, including dates and geographic coordinates. Functions for numeric content support boosting on distance (applies to geographic coordinates), freshness (applies to datetime fields), range, and magnitude.

• Functions for string collections (tags). A tags function boosts a document's search score if any item in the collection is matched by the query.

You can add a scoring profile to an index by editing its JSON definition in the Azure portal or programmatically through APIs like Create or Update Index REST or equivalent index update APIs in any Azure SDK. There's no index rebuild requirements so you can add, modify, or delete a scoring profile with no effect on indexed documents.

Prerequisites

• A search index with text or numeric (nonvector) fields.

Rules for scoring profiles

You can use scoring profiles in keyword search, vector search, hybrid search, and semantic search (reranking). However, scoring profiles only apply to nonvector fields, so make sure your index has text or numeric fields that can be boosted or weighted.

You can have up to 100 scoring profiles within an index (see service Limits), but you can only specify one profile at time in any given query.

You can use semantic ranker with scoring profiles. Currently in preview, you can apply a scoring profile after semantic ranking. Otherwise, when multiple ranking or relevance features are in play, semantic ranking is the last step. How search scoring works provides an illustration.

Extra rules apply specifically to functions.

Scoring profile definition

A scoring profile is defined in an index schema. It consists of weighted fields, functions, and parameters.

The following definition shows a simple profile named "geo". This example boosts results that have the search term in the hotelName field. It also uses the distance function to favor results that are within 10 kilometers of the current location. If someone searches on the term 'inn', and 'inn' happens to be part of the hotel name, documents that include hotels with 'inn' within a 10-kilometer radius of the current location appear higher in the search results.

"scoringProfiles": [
  {  
    "name":"geo",
    "text": {  
      "weights": {  
        "hotelName": 5
      }                              
    },
    "functions": [
      {  
        "type": "distance",
        "boost": 5,
        "fieldName": "location",
        "interpolation": "logarithmic",
        "distance": {
          "referencePointParameter": "currentLocation",
          "boostingDistance": 10
        }                        
      }                                      
    ]                     
  }            
]

To use this scoring profile, your query is formulated to specify scoringProfile parameter in the request. If you're using the REST API, queries are specified through GET and POST requests. In the following example, "currentLocation" has a delimiter of a single dash (-). It's followed by longitude and latitude coordinates, where longitude is a negative value.

POST /indexes/hotels/docs&api-version=2024-07-01
{
    "search": "inn",
    "scoringProfile": "geo",
    "scoringParameters": ["currentLocation--122.123,44.77233"]
}

Query parameters, including scoringParameters, are described in Search Documents (REST API).

For more scenarios, see the examples for freshness and distance and weighted text and functions in this article.

Add a scoring profile to a search index

1. Start with an index definition. You can add and update scoring profiles on an existing index without having to rebuild it. Use a Create or Update Index request to post a revision.

2. Paste in the template provided in this article.

3. Provide a name that adheres to naming conventions.

4. Specify boosting criteria. A single profile can contain text weighted fields, functions, or both.

You should work iteratively, using a data set that helps you prove or disprove the efficacy of a given profile.

Scoring profiles can be defined in the Azure portal as shown in the following screenshot, or programmatically through REST APIs or in Azure SDKs, such as the ScoringProfile class in .NET or Python client libraries.

Template

This section shows the syntax and template for scoring profiles. For a description of properties, see the REST API reference.

"scoringProfiles": [  
  {   
    "name": "name of scoring profile",   
    "text": (optional, only applies to searchable fields) {   
      "weights": {   
        "searchable_field_name": relative_weight_value (positive #'s),   
        ...   
      }   
    },   
    "functions": (optional) [  
      {   
        "type": "magnitude | freshness | distance | tag",   
        "boost": # (positive or negative number used as multiplier for raw score != 1),   
        "fieldName": "(...)",   
        "interpolation": "constant | linear (default) | quadratic | logarithmic",   

        "magnitude": {
          "boostingRangeStart": #,   
          "boostingRangeEnd": #,   
          "constantBoostBeyondRange": true | false (default)
        }  

        // ( - or -)  

        "freshness": {
          "boostingDuration": "..." (value representing timespan over which boosting occurs)   
        }  

        // ( - or -)  

        "distance": {
          "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)   
          "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)   
        }   

        // ( - or -)  

        "tag": {
          "tagsParameter":  "..."(parameter to be passed in queries to specify a list of tags to compare against target field)   
        }
      }
    ],   
    "functionAggregation": (optional, applies only when functions are specified) "sum (default) | average | minimum | maximum | firstMatching"   
  }   
],   
"defaultScoringProfile": (optional) "...", 

Use text-weighted fields

Use text-weighted fields when field context is important and queries include searchable string fields. For example, if a query includes the term "airport", you might want "airport" in the HotelName field rather than the Description field.

Weighted fields are name-value pairs composed of a searchable field and a positive number that is used as a multiplier. If the original field score of HotelName is 3, the boosted score for that field becomes 6, contributing to a higher overall score for the parent document itself.

"scoringProfiles": [  
    {  
      "name": "boostSearchTerms",  
      "text": {  
        "weights": {  
          "HotelName": 2,  
          "Description": 5 
        }  
      }  
    }
]

Use functions

Use functions when simple relative weights are insufficient or don't apply, as is the case of distance and freshness, which are calculations over numeric data. You can specify multiple functions per scoring profile. For more information about the EDM data types used in Azure AI Search, see Supported data types.

Magnitude is the computed distance between a field's value (such as a date or location) and a reference point (such as "now" or a target location). It's the input to the scoring function and determines how much boost is applied.

Freshness and distance scoring are special cases of magnitude-based scoring, where the magnitude is automatically computed from a datetime or geographic field. For intuitive boosting that promotes newer or closer values over older or farther values, use a negative boost value (see the example for more details).

Rules for using functions

• Functions can only be applied to fields that are attributed as filterable.
• Function type ("freshness", "magnitude", "distance", "tag") must be lower case.
• Functions can't include null or empty values.
• Functions can only have a single field per function definition. To use magnitude twice in the same profile, provide two definitions magnitude, one for each field.

Set interpolations

Interpolations set the shape of the slope used for boosting freshness and distance.

When the boost value is positive, scoring is high to low, and the slope is always decreasing. With negative boosts, the slope is increasing (newer documents get higher scores). The interpolation values determines the curve of the upward or downward slope and how aggressively the boost score changes in response to date or distance changes. The following interpolations can be used:

Set boostingDuration for freshness function

boostingDuration is an attribute of the freshness function. You use it to set an expiration period after which boosting stops for a particular document. For example, to boost a product line or brand for a 10-day promotional period, you would specify the 10-day period as "P10D" for those documents.

boostingDuration must be formatted as an XSD "dayTimeDuration" value (a restricted subset of an ISO 8601 duration value). The pattern for this is: "P[nD][T[nH][nM][nS]]".

The following table provides several examples.

For more examples, see XML Schema: Datatypes (W3.org web site).

Example: boosting by freshness or distance

In Azure AI Search, freshness scoring converts date and values into a numeric magnitude—a single number representing how far a document's date is from the current time. The older the date, the larger the magnitude. This leads to a counter-intuitive behavior: more recent documents have smaller magnitudes, which means that positive boosting factors favor older documents unless you explicitly invert the boost direction.

This same logic applies to distance boosting, where farther locations yield larger magnitudes.

To boost by freshness or distance, use negative boosting values to prioritize newer dates or closer locations. Inverting the boost direction through a negative boosting factor penalizes larger magnitudes (older dates), effectively boosting more recent ones. For example, assume a boosting function like b * (1 - x) (where x is the normalized magnitude from 0 to 1) that gives higher scores to smaller magnitudes (that is, newer dates).

The shape of the boost curve (constant, linear, logarithmic, quadratic) affects how aggressively scores change across the range. With a negative factor, the curve’s behavior flips—for example, a quadratic curve tapers off more slowly for older dates, while a logarithmic curve shifts more sharply at the far end.

Here's an example scoring profile that demonstrates how to address counter-intuitive freshness scoring using negative boosting and explains how magnitude works in this context.

"scoringProfiles": [
  {
    "name": "freshnessBoost",
    "text": {
      "weights": {
        "content": 1.0
      }
    },
    "functions": [
      {
        "type": "freshness",
        "fieldName": "lastUpdated",
        "boost": -2.0,
        "interpolation": "quadratic",
        "parameters": {
          "boostingDuration": "365D"
        }
      }
    ]
  }
]

• "fieldName": "lastUpdated" is the datetime field used to calculate freshness.
• "boost": -2.0 is a negative boosting factor, which inverts the default behavior. Since older dates have larger magnitudes, this penalizes them and boosts newer documents.
• "interpolation": "quadratic" means the boost effect is stronger for documents closer to the current date and tapers off more sharply for older ones.
• "boostingDuration": "365D" defines the time window over which freshness is evaluated.

Example: boosting by weighted text and functions

The following example shows the schema of an index with two scoring profiles (boostGenre, newAndHighlyRated). Any query against this index that includes either profile as a query parameter uses the profile to score the result set.

The boostGenre profile uses weighted text fields, boosting matches found in albumTitle, genre, and artistName fields. The fields are boosted 1.5, 5, and 2 respectively. Why is genre boosted so much higher than the others? If search is conducted over data that is somewhat homogeneous (as is the case with 'genre' in the musicstoreindex), you might need a larger variance in the relative weights. For example, in the musicstoreindex, 'rock' appears as both a genre and in identically phrased genre descriptions. If you want genre to outweigh genre description, the genre field needs a much higher relative weight.

{  
  "name": "musicstoreindex",  
  "fields": [  
    { "name": "key", "type": "Edm.String", "key": true },  
    { "name": "albumTitle", "type": "Edm.String" },  
    { "name": "albumUrl", "type": "Edm.String", "filterable": false },  
    { "name": "genre", "type": "Edm.String" },  
    { "name": "genreDescription", "type": "Edm.String", "filterable": false },  
    { "name": "artistName", "type": "Edm.String" },  
    { "name": "orderableOnline", "type": "Edm.Boolean" },  
    { "name": "rating", "type": "Edm.Int32" },  
    { "name": "tags", "type": "Collection(Edm.String)" },  
    { "name": "price", "type": "Edm.Double", "filterable": false },  
    { "name": "margin", "type": "Edm.Int32", "retrievable": false },  
    { "name": "inventory", "type": "Edm.Int32" },  
    { "name": "lastUpdated", "type": "Edm.DateTimeOffset" }  
  ],  
  "scoringProfiles": [  
    {  
      "name": "boostGenre",  
      "text": {  
        "weights": {  
          "albumTitle": 1.5,  
          "genre": 5,  
          "artistName": 2  
        }  
      }  
    },  
    {  
      "name": "newAndHighlyRated",  
      "functions": [  
        {  
          "type": "freshness",  
          "fieldName": "lastUpdated",  
          "boost": -10,  
          "interpolation": "quadratic",  
          "freshness": {  
            "boostingDuration": "P365D"  
          }  
        },  
        {
          "type": "magnitude",  
          "fieldName": "rating",  
          "boost": 10,  
          "interpolation": "linear",  
          "magnitude": {  
            "boostingRangeStart": 1,  
            "boostingRangeEnd": 5,  
            "constantBoostBeyondRange": false  
          }  
        }  
      ]  
    }  
  ],  
  "suggesters": [  
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": [ "albumTitle", "artistName" ]  
    }  
  ]   
}