Search API result fields
editSearch API result fields
editUse Result Settings or the Search Settings API to add Result Fields to default search queries.
Change the fields which appear in search results and how their values are rendered.
Select from two ways to render text field values:
- Raw: An exact representation of the value within a field. And it is exact! It is not HTML escaped.
-
Snippet: A snippet is an HTML escaped representation of the value within a field, where query matches are captured in
<em>tags.
A raw field defaults to the full field with no character limit outside of max document size. A custom range must be at least 20 characters.
A snippet field defaults to 100 characters. A custom range must be between 20-1000 characters.
Only text fields provide these two options, as they are functions of the deep full-text search capabilities of App Search.
If the result_fields parameter is not given, the API will return the full, raw values for all fields.
Non-text fields are raw by default.
Raw Result Fields
editLearn about the XSS risks within the Sanitizaiton Guide.
Requests the exact value that was indexed.
Depending on the field type, results can be returned as either a string, number, or an array of both.
-
size(optional) - Length of the return value. Only can be used on text fields. Must be at least 20; defaults to the entire text field. If given for a different field type other than text, it will be silently ignored.
Example - Specifying result_fields of title and description.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "everglade",
"result_fields": {
"title": {
"raw": {}
},
"description": {
"raw": {
"size": 50
}
}
}
}'
Example Response
{
"meta": {
"alerts": [],
"warnings": [],
"page": {
"current": 1,
"total_pages": 1,
"total_results": 3,
"size": 10
},
"request_id": "2442cc5b3bd956b0339d5e604b562060"
},
"results": [
{
"title": {
"raw": "Everglades"
},
"description": {
"raw": "The Everglades are the largest tropical wilderness"
},
"id": {
"raw": "park_everglades"
},
"_meta": {
"score": 1.0028129
}
},
{
"title": {
"raw": "Voyageurs"
},
"description": {
"raw": "This park protecting four lakes near the Canada–US"
},
"id": {
"raw": "park_voyageurs"
},
"_meta": {
"score": 0.0062864386
}
},
{
"title": {
"raw": "Wrangell–St. Elias"
},
"description": {
"raw": "An over 8 million acres (32,375 km2) plot of"
},
"id": {
"raw": "park_wrangell–st.-elias"
},
"_meta": {
"score": 0.00437395
}
}
]
}
Returning Result Fields as Snippets (Highlights)
editRequests a snippet of a text field.
The query match will be wrapped in <em></em> tags, for highlighting, if a match exists.
Use escaped quotations to highlight only on exact, case insensitive matches.
Matches are HTML escaped prior to inserting <em></em> tags. Fallbacks are also HTML escaped.
If requesting a snippet on a non-text field, the snippet field will be null.
If there is no match for your query, the snippet field will be null.
Snippets on an array value will return the first match or null. There is no fallback support.
On synonyms: If a search finds a synonym for a query, the synonym will not be highlighted.
For example, if "path" and "trail" are synonyms and a query is done for "path", the term "trail" will not be highlighted.
-
size(optional) - Character length of the snippet returned. Must be at least 20; defaults to 100.
-
fallback(optional) - If true, return the raw text field if no snippet is found. If false, only use snippets.
Example - Specifying result_fields snippets for title, description, and states.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "everglade",
"result_fields": {
"title": {
"snippet": {
"size": 20,
"fallback": true
}
},
"description": {
"raw": {
"size": 200
},
"snippet": {
"size": 100
}
},
"states": {
"raw" : {},
"snippet": {
"size": 20,
"fallback": true
}
}
}
}'
Example Response
{
"meta": {
"alerts": [],
"warnings": [],
"page": {
## Truncated!
},
"request_id": "2fd235c15c28a697d70f9a5dc0bdb0fb"
},
"results": [
{
"title": {
"snippet": "<em>Everglades</em>"
},
"states": {
"raw": [
"Florida"
],
"snippet": "Florida"
},
"description": {
"raw": "The Everglades are the largest tropical wilderness in the United States. This mangrove and tropical rainforest ecosystem and marine estuary is home to 36 protected species, including the Florida",
"snippet": "The <em>Everglades</em> are the largest tropical wilderness in the United States. This mangrove and tropical"
},
"id": {
"raw": "park_everglades"
},
"_meta": {
"score": 1.0028129
}
},
{
"title": {
"snippet": "Voyageurs"
},
"states": {
"raw": [
"Minnesota"
],
"snippet": "Minnesota"
},
"description": {
"raw": "This park protecting four lakes near the Canada–US border is a site for canoeing, kayaking, and fishing. The park also preserves a history populated by Ojibwe Native Americans, French fur traders",
"snippet": null
},
"id": {
"raw": "park_voyageurs"
},
"_meta": {
"score": 0.0062864386
}
},
{
"title": {
"snippet": "Wrangell–St. Elias"
},
"states": {
"raw": [
"Alaska"
],
"snippet": "Alaska"
},
"description": {
"raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include",
"snippet": null
},
"id": {
"raw": "park_wrangell–st.-elias"
},
"_meta": {
"score": 0.00437395
}
}
]
}
Example - Highlight and match only an exact query: "Rocky Mountain". Will not match or highlight on "Rocky" or "Mountain" — only "Rocky Mountain".
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "\"Rocky Mountain\"",
"result_fields": {
"title": {
"snippet": {
"size": 20,
"fallback": true
}
},
"description": {
"raw": {
"size": 50
}
}
}
}'
Example Response
{
"meta": {
"alerts": [],
"warnings": [],
"page": {
"current": 1,
"total_pages": 1,
"total_results": 2,
"size": 10
},
"request_id": "d8ec5ddbb24be9de77d0190139ec8a49"
},
"results": [
{
"title": {
"snippet": "<em>Rocky</em> <em>Mountain</em>"
},
"description": {
"raw": "Bisected north to south by the Continental Divide,"
},
"id": {
"raw": "park_rocky-mountain"
},
"_meta": {
"score": 108.32677
}
},
{
"title": {
"snippet": "Glacier"
},
"description": {
"raw": "The U.S. half of Waterton-Glacier International"
},
"id": {
"raw": "park_glacier"
},
"_meta": {
"score": 65.18001
}
}
]
}
Errors
edit
|
If a result field requested does not exist in the current schema. If a request field JSON object is malformed. It must be an empty JSON object or have keys of |