Azure Search – How to Add Suggestions (auto-complete) to your Search Applications

What are Search Suggestions?

For many mobile applications and web sites, search is the primary means by which a user finds what they are looking for.  As a result, the search box needs to be effective in helping users find content quickly.  One way to do this is called suggestions or auto-complete.  This is the process of suggesting potential term matches in response to what the user types in the search box.  An example of this is shown below from the Microsoft Store when you type the letters ‘sur’.

Getting Started with Suggestions

In this post I want to show you how to leverage suggestions and other new capabilities that enhance this experience, like images and fuzzy search. The tutorial I’m walking you through is an MVC4 based website that allows a user to search through a list of vegetables.  The data I used to create my index came from WikiPedia and I am also using the Twitter Type-Ahead java script library to make a nice looking search box.  Using these components along with Azure Search, we’ll have a website that not only has type-ahead but also the ability to extend the suggestions with images, as shown here.

Requirements

This tutorial assumes you have access to:

• An Azure Search Service (learn more here)
• Visual Studio 2012 or higher
• Download Source Code for sample
• It is highly recommended that you have first completed the tutorial: Create your first search solution using Azure Search

Configuring the Azure Search Suggestions Sample

At this point you should have downloaded the sample project and opened it up in Visual Studio.  In the sample Visual Studio project, you will need to add the connection information for your Azure Search service.

• Open up app.config within the CreateIndex project and make changes to the SearchServiceName and SearchServiceApiKey values to reflect your Azure Search service and Azure Search Service API Key which can be found in the Azure Portal.
• Open up web.config within the AzureSearchSuggestionsDemo project and also make changes to the SearchServiceName and SearchServiceApiKey values

Creating the Vegetables Index

Now that you have the application configured, you can launch the CreateIndex application.

• Press F5 to launch the application

This application will do the following steps:

• Delete the vegetables index if it previously existed in your Azure Search service
• Create a new search index called Vegetables using the schema.json file included in the project
• Load the documents stored in the project file documents.json into this index

If successful, you should see output in the console window as follows: Creating index... Loading documents into index... Complete.  Press <enter> to continue: This tutorial does not go through the details of creating a search index.  If you would like to learn more about this, please visit the following tutorial: Create your first search solution using Azure Search

Running the Azure Search Suggestions Sample

Now that you have your Azure Search index “vegetables” created, you can launch the ASP.NET MVC application (F5) AzureSearchSuggestionsDemo, which will do the following: 1)      Load a page with a search box allowing you to search for vegetables. 2)      Try typing in a few letters to see the results of the suggestions that come back from Azure Search.  Note: a first time search takes a few seconds.

How Suggestions Works through Code

Now that we have seen the sample, let’s walk through the key components of how this works.

• Stop the application and open up the file Index.cshtml under the folder \Views\Home

Most of the code in this page leverages the Twitter typeahead.js library.  This is a library that does most of the heavy lifting in presenting a nice looking search box and makes it really easy to make asynchronous ajax calls to Azure Search.  In addition, the typeahead.js library uses handlebars.js which simplifies how we format the output of the suggestions.  For example, in our application, we are using the following formatting:

<p><img src="{{thumbnail}}" style="height:40px;width:60px;">&nbsp;<strong>{{name}}</strong>&nbsp;-&nbsp;{{species}}</p>

This allows us to display images along with text in the search suggestions.  We’ll drill into this more in the next section. A final thing to note is the following reference which allows us to make a call to the MVC controller function Suggest within the HomeController.cs file.  It also passes as a parameter ‘q’ whatever the user types in the text box as well as setting the parameter fuzzy to false.

remote: '/home/suggest?q=%QUERY&type=name&fuzzy=false'

Extending the Sample to Support Fuzzy Matching

Fuzzy search is a feature recently added to Azure Search suggestions, which allows you to get results based on close matches even if the user misspells a word in the search box.

To try this, change the following line from this:

remote: '/home/suggest?q=%QUERY&type=name&fuzzy=false'

to this:

remote: '/home/suggest?q=%QUERY&type=name&fuzzy=true'

 Save the changes and launch the application (F5).

• Try typing something such as ‘arta’ and notice how results come back, even though they are not an exact match to the letters you typed.

Home Controller

Now that we have reviewed the JavaScript code for the sample, let’s take a look at the C# controller code that executes the search suggestion requests.

• Open the file HomeController.cs under the Controller directory

The first thing you will notice is that this controller calls: SuggestionSearch _suggestSearch = new SuggestionSearch(); This does a number of things including creating an authenticated HTTP client to the Azure Search service.  If you would like to learn more about how this works, please visit the following tutorial: Create your first search solution using Azure Search

• Move to the Suggest function

This function is very simple and really just takes the parameter q (which is the characters the user typed into the search box, as well as the Boolean value for fuzzy search and passes it to _suggestSearch.Suggest.

• Open up the SuggestionsSearch.cs file in the Root of the project and move to the Suggest function

Using the parameters received, an Azure Search REST API call is executed.  The results of the suggestions are then loaded into a list object, List<Suggestion> suggestionList. Notice in the Suggestion class that there is a string called thumbnail.  In the Azure Search vegetable index, this is a URL reference to a PNG image.  Since it does not make sense to store binary images in Azure Search (images are not full text searchable) we’re storing thumbnails in the project (as seen in the \Images directory) or even better in something like Azure Blob Storage. Once this list is created, it is passed back to the Home Controller Suggest function, which is in turn returned to Index.cshtml in JSON format, where it is then parsed and loaded into the search box as suggestions.

• (Optional) You might want to add a breakpoint to the start of the Suggest function in the SuggestionsSearch.cs file and run (F5) the application again.  Notice what happens as you type characters into the search box.

Final Thoughts – Connecting to a Search Results Page

You might have noticed that when you select an item from the search box, no search results come back – the sample is just showing search term formulation features. To take this sample further, you should add code that executes the search and returns results. There are multiple ways to handle this, but the most common approach is to execute a search when the user clicks “enter” in the search box.  In the current index.cshtml file, you will see a reference to the following code:

.on('typeahead:selected', function (obj, datum) {

console.log(obj);

console.log(datum);

})

Whenever you choose one of the suggested search terms, this code is called.  To execute search and get results back, replace the console.log code with an ajax call that performs this task. For more information on how to create a search results page, please refer to the following tutorial: Create your first search solution using Azure Search. There is also a lot more information on how to extend the typeahead.js library here. For more information on Azure Search, please visit Azure Search Documentation. Please keep the feedback coming. Liam Cavanagh can be contacted at his blog or through twitter.