In previous articles, I have explained what is Azure search, what is Azure search index, how to create index and how to import data. If you are new to Azure search, then I would recommend you to go through those articles. Below are the links for ready reference:
- Introduction to Azure Search
- Creating First Azure Search Instance
- Let’s get started on Azure Search Index
- Setup Azure Search on SQL Azure Database
In this article, we will have a look at how does querying work in Azure Search service.
Anatomy of the Query
Azure search query is a construct. The query specifies which fields are in scope, how to search, which fields should be returned, whether to sort or filter and so on.
If all of these are unspecified, a query runs against all searchable fields as a full text search operation, returning an unscored result set in arbitrary order.
Query contains not only the phrases entered by user but also some additional details like which fields should be searched from the index, which fields should be returned, which field should be used for sorting or filtering.
URL
The URL is formed as shown below: https://<your-service-name>.search.windows.net/indexes/<your-index-name>/docs
- your-service-name: should be replaced with name of the Azure search service instance name. In our case it is adventure-works.
- your-index-name: the index name you specified while creating index or importing data.
The index name is in URL. That's why index name should be unique within an Azure search service instance.
The api-version querystring
There can be multiple versions of Azure search API existing at a time and that’s why this is required to be sent.
e.g https://adventure-works.search.windows.net/indexes/azuresql-index/docs?api-version=2017-11-11
The api-key Header
Either admin key or the query key, depending on which type of operation you are performing. This key is to authenticate you request.
This is sent in HTTP header.
Body
Below are some of the common parameters:
{ "queryType": "simple" "search": "seattle townhouse* +\"lake\"", "searchFields": "description, city", "count": "true", "select": "street, status, daysOnMarket, description", "top": "10", "orderby": "daysOnMarket", "searchMode": "any", "filter": "price ge 60 and price lt 300" }
- queryType: can have one of the two possible values – simple or full. Simple uses simple query parser optimal for full text search. Full uses Lucene query parser which provides advanced capabilities like fuzzy search, proximity search, wildcard search, etc.
- search: provides the match criteria, usually text but often accompanied by boolean operators. Single standalone terms are term queries. Quote-enclosed multi-part queries are key phrase queries.
- searchFields: the fields in index which should be searched
- count: bool field which tells Azure search to return the count of overall documents which matched with query
- select: tells which fields should be returned
- top: tells how many records should be returned
- orderby: tells the field on which the records should be sorted
- searchMode: can be either any or all. Search mode any is the default value. If any is sent, then it means return records which match any of the search criteria. If all is specified, then it means return records which match all of the search criteria.
- filter: additional filtering of records which matched to search criteria
Please note that these fields can be specified in the query string as shown in below snapshot. Every field name should be prefixed with “$” sign.
Sample C# Code
There are three steps to write a c# code:
- create SearchIndexClient instance
- create instance of SearchParameters
- call search method
Below snippet shows a sample code. Please note that IndexDetails class is the class which has properties corresponding to the fields in the index which you are using for querying.
//// Step 1 - create client string searchServiceName = configuration["SearchServiceName"]; string queryApiKey = configuration["SearchServiceQueryApiKey"]; SearchIndexClient indexClient = new SearchIndexClient( searchServiceName, "azuresql-index", new SearchCredentials(queryApiKey)); //// Step 2 - Create parameters SearchParameters parameters = new SearchParameters() { Select = new[] { "Name" } }; //// Step 3 - Search DocumentSearchResult<IndexDetails> results; results = indexClient.Documents.Search<IndexDetails>( "frame", parameters);
More Examples
There are some nice demo applications which are present in MSDN resources to understand how search works. Below are some of the links:
I hope you enjoyed this article. Please do comment and let me know your thoughts.