You can specify boost conditions in your search request to promote or demote certain documents in your search results. When a document fulfills the specified conditions, boost values are applied to it and the results are ordered accordingly. You can also specify custom numerical values and timestamp values that let you order the results based on parameters such as popularity and freshness.
The boost specification in a search request is different from a boost control
that's attached to a serving config. The boost specification in the
boostSpec
field overrides the boost control defined in the boostAction
field of a serving config. For more information about boost controls, see
About boost controls.
This page describes the following types of boost specifications:
You can apply these boost specifications to query media search apps and generic search apps that contain structured, unstructured, and website data. These specifications are not applicable to healthcare search apps.
Boost with a fixed condition
To boost results by a fixed amount based on whether they satisfy a condition, do the following:
Specify the boost specification in the
boostSpec
field when you send aservingConfigs.search
request.{ "boostSpec": { "conditionBoostSpecs": { "condition": "BOOST_CONDITION", "boost": "BOOST_VALUE" } } }
The specification contains the following parameters:
BOOST_CONDITION
: a text filter expression to select the documents to which boost is applied. The filter must evaluate to a boolean value.BOOST_VALUE
: a floating point number between -1 and 1. When the value is negative, results are demoted (they appear lower down in the results). When the value is positive, results are promoted (they appear higher up in the results).
Example use case
Suppose your data store contains data about hotels and their star ratings. You want to
boost hotels with star ratings greater than or equal to three. The star rating is
available in the star_rating
numerical field. You can specify the condition
in the boostSpec
as star_rating >= 3.0
and a boost value of 0.7 to boost
all hotels with star_rating
of 3.0 or higher by an equal amount.
{
"boostSpec": {
"conditionBoostSpecs": {
"condition": "star_rating>=3.0",
"boost": 0.7
}
}
}
Boost using custom numerical attributes
You can boost results based on custom numerical attributes in a piecewise linear manner by specifying control points and their corresponding boost values.
To specify a boost specification using custom numerical attributes, do the following:
Specify the boost specification in the
boostSpec
field when you send aservingConfigs.search
request.{ "boostSpec": { "conditionBoostSpecs": { "condition": "BOOST_CONDITION", "boostControlSpec": { "attributeType": "NUMERICAL", "interpolationType": "LINEAR", "fieldName": "CUSTOM_ATTRIBUTE_FIELD_NAME", "controlPoints": [ { "attributeValue": CUSTOM_ATTRIBUTE_VALUE_1, "boostAmount": BOOST_AMOUNT_1 }, { "attributeValue": CUSTOM_ATTRIBUTE_VALUE_2, "boostAmount": BOOST_AMOUNT_2 } ] } } } }
The specification contains the following parameters:
BOOST_CONDITION
: a text filter expression to select the documents to which boost is applied. The filter must evaluate to a boolean value.CUSTOM_ATTRIBUTE_FIELD_NAME
: the field name of the custom numerical attribute whose value decides the boost amount.CUSTOM_ATTRIBUTE_VALUE
: the numerical value of the custom attribute for a given control point with a string data type. For example,"3.3"
or"12"
.BOOST_AMOUNT
: the boost amount mapped to the custom attribute for a given control point.
When a document in the search result meets the specified condition, a boost amount is applied as follows:
Attribute value | Boost amount |
---|---|
Less than the first control point | Is equal to the boost amount of the first control point |
Equal to control point | Is equal to the mapped boost amount |
Between control points | Is calculated by linear interpolation |
Greater than the last control point | Is equal to the boost amount of the last control point |
Example use case
Suppose your data store contains data about hotels and their star ratings. You want to boost the hotel search results in proportion to their star ratings. You can define the boost specification as follows:
{
"boostSpec": {
"conditionBoostSpecs": {
"condition": "star_rating >= 3.0",
"boostControlSpec": {
"attributeType": "NUMERICAL",
"interpolationType": "LINEAR",
"fieldName": "star_rating",
"controlPoints": [
{
"attributeValue": "3.5",
"boostAmount": 0.4
},
{
"attributeValue": "4.0",
"boostAmount": 0.5
},
{
"attributeValue": "4.5",
"boostAmount": 0.7
}
]
}
}
}
}
For this scenario, the search results are boosted as follows:
Star rating | Boost amount |
---|---|
less than or equal to 3.5 | 0.4 |
between 3.5 and 4.0 | between 0.4 and 0.5, calculated using linear interpolation |
equal to 4.0 | 0.5 |
between 4.0 and 4.5 | between 0.5 and 0.7, calculated using linear interpolation |
greater than or equal to 4.5 | 0.7 |
Boost according to freshness
You can boost results based on datetime attributes in a piecewise linear manner by specifying control points and their corresponding boost values.
To specify a boost specification using custom datetime attributes, do the following:
Specify the boost specification in the
boostSpec
field when you send aservingConfigs.search
request.{ "boostSpec": { "conditionBoostSpecs": { "condition": "BOOST_CONDITION", "boostControlSpec": { "fieldName": "DATETIME_FIELD_NAME", "attributeType": "FRESHNESS", "interpolationType": "LINEAR", "controlPoints": [ { "attributeValue": DURATION_VALUE_1, "boostAmount": BOOST_AMOUNT_1 }, { "attributeValue": DURATION_VALUE_2, "boostAmount": BOOST_AMOUNT_2 } ] } } } }
The specification contains the following parameters:
BOOST_CONDITION
: a text filter expression to select the documents to which boost is applied. The filter must evaluate to a boolean value.DATETIME_FIELD_NAME
: the field name of a customDATETIME
attribute, such as date of publication or date of last update, or a predefined Google-inferred attribute, such asdatePublished
.DURATION_VALUE
: the duration value indayTimeDuration
data type that decides the freshness of a document. This is calculated as the duration between the datetime when the search is performed and the datetime of the custom attribute of a document.BOOST_AMOUNT
: the boost amount mapped to the custom datetime attribute for a given control point.
When a document in the search result meets the specified condition, a boost amount is applied as follows:
Duration value | Boost amount |
---|---|
Less than the first control point | Is equal to the boost amount of the first control point |
Equal to a given control point | Is equal to the mapped boost amount |
Between control points | Is calculated by linear interpolation |
Greater than the last control point | Is equal to the boost amount of the last control point |
Example use case using a custom datetime attribute
Suppose your data store contains structured data where each document has a publication date. You want to boost the search results in proportion to their freshness. You can define the boost specification as follows:
{
"boostSpec": {
"conditionBoostSpecs": {
"condition": "true",
"boostControlSpec": {
"fieldName": "publication_date",
"attributeType": "FRESHNESS",
"interpolationType": "LINEAR",
"controlPoints": [
{
"attributeValue": "7d",
"boostAmount": 0.9
},
{
"attributeValue": "30d",
"boostAmount": 0.7
},
{
"attributeValue": "60d",
"boostAmount": 0.4
},
{
"attributeValue": "90d",
"boostAmount": 0
}
]
}
}
}
}
For this scenario, the search results are boosted as follows:
Freshness | Boost amount |
---|---|
less than or equal to 7 days | 0.9 |
between 7 and 30 days | between 0.9 and 0.7, calculated using linear interpolation |
equal to 30 days | 0.7 |
between 30 and 60 days | between 0.7 and 0.4, calculated using linear interpolation |
equal to 60 days | 0.4 |
between 60 and 90 days | between 0.4 and 0.0, calculated using linear interpolation |
greater than or equal to 90 days | 0.0 |
Example use case using a Google-inferred page date
When crawling through the web pages in your website data store, Google infers page data using the properties that apply to your content. Vertex AI Search adds these inferred page data properties to your schema. This inferred data includes the following predefined date properties:
datePublished
: the date and time when the page was first publisheddateModified
: the date and time when the page was most recently modified
These properties are indexed automatically. You can directly use these date
properties to enrich your search without adding them to your schema.
You can use these predefined properties to boost your page. For example, you can
define the boost specification by setting the fieldName
field to
pageModified
as follows:
{
"boostSpec": {
"conditionBoostSpecs": {
"condition": "true",
"boostControlSpec": {
"fieldName": "dateModified",
"attributeType": "FRESHNESS",
"interpolationType": "LINEAR",
"controlPoints": [
{
"attributeValue": "7d",
"boostAmount": 0.9
},
{
"attributeValue": "30d",
"boostAmount": 0.7
}
]
}
}
}
}
As a best practice, Google recommends that your domain owner or website administrator updates these properties for your web pages and manually refresh your website data store after the update. For more information, see the Help Google Search know the best date for your web page blog post and learn How structured data works in Google Search.
To add custom structured data attributes to enrich your index, see Add custom structured data attributes to the data store schema
What's next
Make a search request with the boost specification
in the boostSpec
field.