This post picks up where my previous post ‘Introducing Azure Search’ left off.
In this section I will describe the basics of how to use Azure Search through the REST API.
Creating an Index
In the Indexes section of this document an example index is provided. This index can be used as a body to the REST call above. Other index tasks that can be performed through the REST API include updating an index, deleting an index, listing the indexes in a search service, getting index stats and analysing text through an index. More information about the different index operations can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/index-operations.
After creating an index, you may want to test how text is analysed by the index, especially if you have used custom analysers or tokenisers. The REST call above can be made to show how text will be analysed. An example body is shown below:
The response from Azure will show how the text is analysed and tokenised. For example:
More information about analysing text can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/test-analyzer
The content of the above request should match the following form:
The response from Azure Search will include a status code and an error message if an error occurred. Potential errors include status codes 503 (search service is too busy to respond), 404 (document not found) and 422 (index temporarily unavailable). You can index multiple documents at a time within the POST request by specifying multiple objects within the value array. More information about document operations can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/document-operations including advanced operations such as enabling autocomplete and suggestions.
Within Azure Search there are 3 possible ways to search. Lucene querying allows all search capabilities of Azure Search, but simple querying excludes fuzzy and other advanced search options. OData expressions are available such as filtering and ordering of search results. Lucene or simple querying can be used in conjunction with OData expressions.
Searching using the REST API can be done via a GET request:
Or a post request:
A POST request should be used if the length of the URL exceeds sensible limits. Therefore use a POST request if large queries or filters are being constructed. The format of the POST body is as follows:
Azure also provides a search explorer to test possible queries against an index. Further information about the search explorer can be found here https://docs.microsoft.com/en-us/azure/search/search-explorer.
Simple querying is the default option when using Azure Search, but to set this value manually you must set “queryType=simple” in the request as a query parameter. Simple queries support “And”, “Or” and “Not” expressions. More information can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/simple-query-syntax-in-azure-search.
For more complicated searches consider using Lucene search terms. This can be done by setting “queryType=full” as a query parameter in the request. Examples of more complicated searches are wildcard, proximity, regular expressions and fuzzy searching. More information can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/lucene-query-syntax-in-azure-search.
OData operations can be specified alongside simple or Lucene searching. These include filtering, geographical operations and comparison operations. More information can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/odata-expression-syntax-for-azure-search.
Creating an Indexer and Data Source
First create a data source to be used by the
indexer when syncing data.
A PUT request can also be used to update a data source (if the specified data source does not exist then it will be created). The request body must be in the following format:
After creating the data source, an indexer can be created.
As with the data source a PUT request can be used to update an indexer. If the indexer specified in the PUT request does not exist it will be created. The body of indexer creation is as follows:
Indexers and data sources can be created, updated and deleted through the REST API. Stats and information can also be retrieved, including information about how successful the indexer has been on each run, and how often the indexer is run. More information about indexers and data sources, as well as information about different values in the request body, can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/indexer-operations.
There are lots of operations that can be performed through the REST API. Below I will briefly describe some of these additional operations.
Azure Search can provide suggestions based on the user’s search terms. The field being searched is specified, for example if the user is searching using “Bri” for a field representing a city then suggestions will return “Brighton”, “Bristol” and “Brisbane”. This functionality can be used as a search-as-you-type style search.
Another document operation provided by Azure Search is auto complete. This is similar to suggestions but returns values that are currently in the index.
Suggestions and autocomplete are more advanced features but other simple features such as document counting and single document lookup can be done through the REST API. Information about all document operations can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/document-operations.
Skillsets provide advanced natural language processing via cognitive AI skills. These skills can be built-in skills, custom skills or a combination of both. Skillsets are defined in the indexer and are used when the indexer is run. Information on defining a skillset, including an example can be found here https://docs.microsoft.com/en-gb/azure/search/cognitive-search-defining-skillset as well as information about how to create a skillset https://docs.microsoft.com/en-us/rest/api/searchservice/create-skillset.
Synonyms can be used to create custom rules to rewrite a search query. These operations are often used when mappings between certain search terms are known by the developer. For example if an index holds information about houses and one of the fields is a description of the house, a synonym mapping could be created between the words ‘large’, ‘spacious’ and ‘roomy’. When a user searches by any of these terms then matches will occur between all of the words. More information about creating and managing synonym maps can be found here https://docs.microsoft.com/en-us/rest/api/searchservice/synonym-map-operations.
SDK and Azure portal
Azure provide an SDK for .NET development as well as tutorials in how to use the REST API with Node.js and Java. These tutorials can be found using the below links https://docs.microsoft.com/en-us/azure/search/search-get-started-java, https://docs.microsoft.com/en-us/azure/search/search-get-started-nodejs, https://docs.microsoft.com/en-us/azure/search/search-howto-dotnet-sdk.
Throughout this section I have described how to use the REST API. As well as the REST API and the SDK, the Azure portal can be used. Performing most of the operations described can be done through the portal. It is often just as easy to use the REST API, and since this is how it will be used in development it is a good idea to use the API. However, it is possible to use the portal for most operations and can be the easiest way to get up and running quickly.
Next up I will describe deployment, local development and conclusion in my final blog.