In this Article

Learn how to use the Azure Cognitive Search, prepare your application data to make it searchable, and improve performance and quality of your search results. In the last articles of this series, we created an index and filled it with data from the PokeApi. Now it is time to show you how you can search this index and integrate the search into your application.

Article Series

  1. Part 1: Introduction to Azure Cognitive Search
  2. Part 2: The search index
  3. Part 3: Index your Data
  4. Part 4: Integrate Azure Cognitive Search Into Your Application

To search the data, Azure Cognitive Search offers different ways (also different query types) to query your index. The most common query type is the normal search. But there are other options for using Azure Cognitive Search to do autocomplete or suggestion searches. The result set is limited to the requested fields for these specific search types, and the search behavior differs from the standard search.

Search Your Data with the REST API

The simplest way to query the index of an Azure Cognitive Search instance is to use the Rest API. You can issue a GET or POST request to the URI https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]. The Rest API can only be used via HTTPs. Additionally, two mandatory parameters must be set when calling the API.

  • api-version: The version of the API of Azure Cognitive Search you are using. Consult the list of API versions for further details
  • api-key: The API key to authenticate your request. You can find it in the Azure Portal

The API version always has to be included in the URI as a query parameter. The api-key can be sent as a query parameter or as an http-header. This depends on what key you are using (see below). If you don't send these parameters, you will get the status code 403 (Forbidden) or 400 (Bad Request) as a response. There are two different types of keys you can use to work with the API (or the SDKs):

  • Admin: The admin key is a key which has full access to all functionality of the Azure Cognitive Search. You are able to manage indexes, indexers, and data sources and query the index. This type of key is used in my Azure Function that deletes and creates the index and indexer. If you are using the REST API this key must be sent as HTTP header api-key.
  • Query: The query key is a read-only key to query the index and retrieve data. With this key, you are not allowed to modify the index or the indexer. This key is most suitable to use it in your application to query the Azure Cognitive Search. This type of key is used in the demo page that searches the index with the PokeAPI data. The Query key has to be sent as query parameter api-key.

Additional to these keys, the REST API is also secured by the CORS definitions that we had defined when we created the index. To do a simple search, there is additional information that has to be sent to the server. These parameters can be sent as query parameters (HTTP) or as request body (POST):

  • search: Search term you are searching for. There are two different kinds of how the syntax of the search term can look like. The default query syntax allows operators like * or and. If a more complex syntax is needed, you have to send a second parameter:

    • queryType: Values are simple or full. Simple is the default query syntax. Then full syntax allows using a more complex query syntax.
  • skip/take: Skip and take a number of result items. Useful if you want to page your search results.
  • count: Boolean if a count field should be included in the result.
  • orderBy: By which property should the search result be ordered.

Besides a regular search, you can also use two other search types:

  • SuggestSearch: This search type can be used to do a simple search after matches close to the search term.
  • Autocomplete: This search type can be used to do a search for autocompletion.

Both search types are using different URIs and have another search result than the default search. Also, these search types have the possibility to add pre/post highlighting tags, so you can directly use the response in your html/application.

Besides the REST API, there are also SDKs for different programming languages like .NET, JAVA, JavaScript, or Python. The SDKs are a wrapper around the REST API, so you have support creating the requests to query the index.

Integrate the Search in Your .NET API

If you want to include the search into your existing API, you can use the .NET SDK. To use this SDK, just add the (Microsoft.Azure.Search)[https://www.nuget.org/packages/Microsoft.Azure.Search/] (Version 10 is used in this article series). New features will be implemented only in version 11 of the API. There also will be a change of the package name. It will be released under the name Azure.Search.Documents instead of Microsoft.Azure.Search. To query the search index, you first have to create some data models you can work with. For the demo search, there are three models necessary:

public partial class Pokemon
{
  [System.ComponentModel.DataAnnotations.Key]
  [IsSortable, IsRetrievable(true)]
  public string Id { get; set; }
  
  [IsFilterable, IsFacetable, IsRetrievable(true), IsSortable]
  public int Height { get; set; }

  [Analyzer(AnalyzerName.AsString.StandardLucene)]
  [IsFilterable, IsRetrievable(true), IsSearchable, IsSortable]
  public string Name { get; set; }
  
  public Sprites Sprites { get; set; }
  
  public Type[] Types { get; set; }
  
  [IsFacetable, IsFilterable, IsRetrievable(true)]
  public int Weight { get; set; }
  
}

public partial class Sprites
{
  [JsonProperty("front_default")]
  [IsRetrievable(true)]
  public string FrontDefault { get; set; }
}

public partial class Type
{
  [JsonProperty("type")]
  [IsFacetable, IsFilterable, IsRetrievable(true), IsSortable]
  public string Name { get; set; }
}

The Pokemon class is the main data model. There are two complex properties in this data model that need extra classes: Sprites and Type. For each property, you can define search attributes like if the property is filterable or sortable. These are the same properties that are set in the first article where I described the index in a JSON file.

To search the index, you have to create a SearchServiceClient. For this, you just need your serviceName and your apiKey. With the created SearchServiceClient, you can get an ISearchIndexClient by calling the GetClient method with the index name as a parameter.

On this ISearchIndexClient, you can call the Search method on the Documents property. The method is typed. This is because by adding the type, you have full typings in the search results. As parameters of the search method, you have to pass the searchTerm (Pikachu) and the search parameters. The search parameters are the same search parameters you can use in the Rest API (see above). You will get a list of results on which you can access the documents that are typed because of the typed Search method call.

var serviceClient = new SearchServiceClient("sj-search",new SearchCredentials("apiKey"));
var indexClient = serviceClient.Indexes.GetClient("pokeapi-index").
var results = indexClient.Documents.Search<Pokemon>("Pikachu", new SearchParameters());

foreach (SearchResult<Pokemon> result in results.Results)
{
    // Document is of type T = Pokemon
    Console.WriteLine(result.Document);
}

Integrating the search into your own API offers you the possibility to hide the search behind your own URI and also hide the API key from the application users. Also you are able to secure the search query access with protecting your API calls with some authentication.

A Small Demo Application

To demonstrate how the search works, I have used the Azure Portal to create a demo application that searches the PokeApi index and shows the result. The Azure Portal offers the possibility to create such a demo application to test your index. You can find the demo application on GitHub. To execute the demo application, just open the AzSearch.html in your browser. You will see an empty page with a search field. Now you can search for a Pokemon. For example, just type Pik*, and you will get a suggestion of all available Pokemon starting with Pik. Hitting enter will show you a full list of all found pokemon including preview pictures. In the left column of the page, you will see a slider where you can filter by the Pokemon's weight.

If you are open the development tools of your browser and look into the network tab, you can see the search request for the search and the suggestion.

Demo application with network tab

Conclusion

In this article series, you saw how to use the Azure Cognitive Search. I created an index, and filled it with data. In this last article of the series, I showed you two different ways (REST API, .NET SDK) to search your data and query the index. Now you should be able to index and search your data. This article series was only a first look into the Azure Cognitive Search. There are many additional options you can use to make your search faster and more specific. Sign up for our monthly newsletter to receive our latest articles, webinar dates, screencasts, and more.

I hope this introduction could help create an overview of the Azure Cognitive Search and help you with the entry in this topic.

Have fun!

Kostenloses Azure-Whitepaper zu Diensten und Containern

Thorsten Hans hat zum Thema 'Azure als Anwendungsplattform - Dienste und Container' ein Whitepaper erstellt, in dem er kompakt alles Wissenswertes zusammengefasst hat.

Melden Sie sich kostenlos zu unserem Newsletter an, um das Whitepaper zum Download zu erhalten.

Related Articles

 | Steffen Jahr

Article Series Part 1: Introduction to Azure Cognitive Search Part 2: The Search Index Part 3: Index your Data ⬅ Part 4: Integrate Azure Cognitive Search Into Your Application If you want to search your data, the index we created in the last article has to be filled with…

Read article
 | Steffen Jahr

Article Series Part 1: Introduction to Azure Cognitive Search Part 2: The Search Index ⬅ Part 3: Index Your Data Part 4: Integrate Azure Cognitive Search Into Your Application Introduction to the Azure Cognitive Search Index One of the essential parts of Azure Cognitive Search is…

Read article
 | Steffen Jahr

With this article series, you will learn what Azure Cognitive Search is, and how to use it. See the essential steps and make your application's data searchable, improve search performance and the quality of search results. As this is the first article of the series, it provides…

Read article