Highlights
Highlights enable you to show the user exactly why the current result is relevant, by highlighting specific info about the result such as the text or image that matched the query, or the section of audio or video that is relevant. For example, the sentence or paragraph of text that answers the question, or which image out of the 10 images is the best match.
This information is returned inside the highlights field of the API. There is a list of highlights for each result in the search results. Highlights are not returned by default, to request them use result_fields=highlights in the API call.
Text Highlights
Text Highlights allow you to easily surface the most semantically relevant text sections from within an object. By guiding users directly to the sections of an object that best match their query, Highlights can improve the search experience, especially for documents with lots of text, such as PDFs, articles, books, or transcripts to name a few. However, this functionality may incur higher costs because an object will be split into multiple sub-objects.
Configure Index for Text Highlights
Enable text highlights by setting "text": true within the "highlights" object in the index configuration (see more details on configuring the index here). This flag will trigger our system to autonomously split each searchable field of your objects in the Object Store into individual highlight sections that are encoded and indexed to enable precise matching to user queries. Highlights will be available for any field you list as searchable. However, lists and nested dictionary fields are not yet searchable for highlights.
Highlights maintain maximum contextual integrity without overloading character limits or your budget. We construct highlights out of “segments” of text from the object. By default, segments are constructed based on sentences, delineated by a . or newline (\n).
You can customize how the text is split for each field using regular expressions through the segment_delimiter parameter. For example, in the snippet below, the “transcript” field is configured to start a new segment whenever the regular expression “\n\n” is encountered. Note that multiple segments may be combined into a single highlight for increased efficiency.
Configuring index to support highlights
curl -X 'POST' https://api.objective.inc/v1/indexes \
-H 'Authorization: Bearer $APIKEY' \
-H 'Content-Type: application/json' \
-d {
"configuration": {
"index_type": {
"name": "text",
"highlights": {
"text": true
}
},
"fields": {
"searchable": {
"allow": ["title", "transcript"]
},
"segment_delimiter": {"transcript": "\n\n"}
}
}
}
# Response
{
"id": "idx_rHlXLhCTma74w1E_xbRXl",
}
Search Requests
Text Highlights allow developers to return the text from within an object that most closely matches the user’s search query. To retrieve highlights, search an index with the results_fields=highlights parameter. The search results will return up to 250 of the most relevant highlights and aggregate them by object. Objects will be ranked by their maximum relevance scores, prioritizing objects with highly relevant individual highlights. See more on text searches.
To retrieve highlights in your search results, you’ll need to call Objective’s Search API and list highlights as one of the result_fields.
curl 'https://api.objective.inc/v1/indexes/idx_rHlXLhCTma74w1E_xbRXl/search?query=city%20by%20the%20ocean&object_fields=*&result_fields=highlights' \
-H 'Authorization: Bearer sk_NefoODAZoyA45KsLsQu6J'
{
"results": [
{
"id": "123",
"object": {...},
"highlights": [
{
"highlight_type": "text",
"references": [
{
"source": "...",
"position": {
"start_char": 1116,
"end_char": 1909
}
}
],
"highlight": {
"text": "..."
}
},... # other highlights for object 123
]
},
{
"id": "...",
"object": {...},
"highlights": [...]
}
]
}
Example use cases
Highlights can be used in many different use cases. Below are a few examples.
Show the best product variant
When you have multiple variants of a product, dynamically show the best version based on what the user is searching for. For example, consider a dress product with green and red colors where the default thumbnail is the red variant. If a user searches for “green dress”, this product is a relevant result, however when the user sees the thumbnail they will think it is irrelevant due to the photo being of a red dress. Using Highlights we can dynamically update the thumbnail to the green photo to indicate to the user why this is a great result.
✨ Customer spotlight: Podfoods uses Highlights to improve product variants. See example search: “Lemon soda”:
Podfoods before
Podfoods after
Show the most relevant aspect of the product
When a user searches for a specific aspect of a product, show them the portion of the product that matches what they’re looking for best. For example, consider a user searching for “dresses with open backs”. Often times the thumbnail photo for a dress will be front facing, which doesn’t give any indication whether the dress has an open back or not. Using Highlights we can dynamically select the photo that shows the back of the dress and show this to the user to help them understand which dresses are relevant to their search.
Example: Show the most relevant photo to the query “cross back dresses”:
Highlight Objects
There are different kinds of objects within Highlights depending on the type of content that is most relevant.
Text
"highlight_type": "text" objects highlight text that is most relevant to the query. In addition to the highlighted text, these objects contain fields that provide context about the origin of the highlight:
positiongives the offset in the text where the highlight was found.sourcelists the field from which the highlighted text originated.
"highlights": [
{
"highlights_type": "text",
"references": [
{
"source": "transcript",
"position": {
"start_char": 1116,
"end_char": 1909
}
}
],
"highlight": {
"text": "sample highlight text..."
}
}
]
Image
{
"reference_type": "image",
"media_identifier": "https://www.example.com/img.jpg"
}