Result Suggestions Guide
How can I build result suggestions?
A Result Suggestion provides recommended results as a person is searching.
By contrast, a Query Suggestion provides recommended queries.
Query Suggestions have their own endpoint. Result suggestions do not.
Why? A result suggestion refines a typical search query.
We'll break down how it works.
Search in a Nutshell
First, a look at a typical search experience. The US National Parks data set will help demonstrate...
A search query for "mountains":
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "mountains"
}'
... Without any parameters returns a set of full documents:
{
"nps_link": {
"raw": "https://www.nps.gov/grba/index.htm"
},
"title": {
"raw": "Great Basin"
},
"date_established": {
"raw": "1986-10-27T06:00:00+00:00"
},
"world_heritage_site": {
"raw": "false"
},
"states": {
"raw": [
"Nevada"
]
},
"description": {
"raw": "Based around Nevada's second tallest mountain, Wheeler Peak, Great Basin National Park contains 5,000-year-old bristlecone pines, a rock glacier, and the limestone Lehman Caves. Due to its remote location, the park has some of the country's darkest night skies. Wildlife includes the Townsend's big-eared bat, pronghorn, and Bonneville cutthroat trout."
},
"visitors": {
"raw": 144846
},
"id": {
"raw": "park_great-basin"
},
"location": {
"raw": "38.98,-114.3"
},
"square_km": {
"raw": 312.3
},
"acres": {
"raw": 77180
},
"_meta": {
"score": 16.878096
}
## ... Truncated!
}
The documents - by default - return all fields and all relevant documents.
But that's often not what we want.
The typical flow of a search experience has three steps.
- A person types into the search bar, hits enter.
- Results appear.
- A person clicks on a result.
The results that appear during a typical experience are usually "rich" in appearance.
A shoe might show a picture, available colours, sizes, styles, exposing more - but not all - of the overall shoe document.
A park might show a picture, link, title, states, description, visitors, and location but not the other fields.
The other fields will be used for sorting or other filtration methods.
Therefore, the "returned" object is a stylized depiction of a smaller object:
{
"nps_link": {
"raw": "https://www.nps.gov/grba/index.htm"
},
"title": {
"raw": "Great Basin"
},
"states": {
"raw": [
"Nevada"
]
},
"description": {
"raw": "Based around Nevada's second tallest mountain, Wheeler Peak, Great Basin National Park contains 5,000-year-old bristlecone pines, a rock glacier, and the limestone Lehman Caves. Due to its remote location, the park has some of the country's darkest night skies. Wildlife includes the Townsend's big-eared bat, pronghorn, and Bonneville cutthroat trout."
},
"visitors": {
"raw": 144846
},
"location": {
"raw": "38.98,-114.3"
}
}
This same principal of shrinking your objects applies to how you would think about Result Suggestion.
Ping? Pong!
When a person tries a search, we can place an "in between" phase -- the Result Suggestion phase.
The main search query is built to return a certain "size" of object, like so:
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "mountains",
"result_fields": {
"title": {
"snippet": {
"size": 20,
"fallback": true
}
},
"description": {
"raw": {
"size": 200
},
"snippet": {
"size": 100
}
},
"states": {
"raw" : {},
"snippet": {
"size": 20,
"fallback": true
}
},
"visitors": {
"raw" : {
"size": 20
}
},
"location": {
"raw" : {
"size": 20
}
},
"nps_link": {
"raw" : {
"size": 20
}
}
}
}'
The main query is what would fire when someone types a full query and hits enter.
Your result suggestion query will be smaller and it will be invoked at a different interval.
You can have an "as you type" search API request that searches through - and returns - a smaller object.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "mountains",
"search_fields": {
"title": {},
"description": {},
},
"result_fields": {
"title": {
"snippet": {
"size": 20,
"fallback": true
}
},
"description": {
"raw": {
"size": 200
},
"snippet": {
"size": 100
}
}
}'
This smallest first query will provide a recommended set of results.
It searches only two fields and returns only two character limited fields.
It's lightweight enough to make predictive search feel "fluid".
The "main query" will only fire when a person hits enter within the search bar to complete a search.
Query Suggestions + Result Suggestions
If you are feeling creative, you can use the Query Suggestion endpoint to fuel your result suggestion queries.
The query suggestion endpoint responds with a concise recommendation which is tied to actual documents:
{
"results": {
"documents": [
{
"suggestion": "mountains"
}
]
},
"meta": {
"request_id": "914f909793379ed5af9379b4401f19be"
}
}
The request uses partial queries to determine if one more or more documents match.
A person may be typing "moun" -- and then be suggested "mountains" as a query.
You can use the query suggestion response.
Put together, the flow is like this:
- A person begins to type.
- Query Suggestions find documents based on the person's partially typed query, makes a suggestion.
- The query suggestion fuels a fast "result suggestion" query, relevant results appear.
- The person clicks a result, delighted the experience felt "predictive".
- OR: The person finishes their query, hits enter, and sees the full, "rich" search results.
Combining these methods will help you build fluid, responsive, multi-dimensional search experiences.
Stuck? Looking for help? Contact support or check out the App Search community forum!