Edit

Creating queries in Azure Cognitive Search

  • Article
  • 6 minutes to read

If you are building a query for the first time, this article describes approaches and methods for setting up the request. It also introduces a query structure, and explains how field attributes and linguistic analyzers can impact query outcomes.

What's a query request?

A query is a read-only request against the docs collection of a single search index. It specifies a 'search' parameter, which contains the query expression consisting of terms, quote-enclosed phrases, and operators.

Additional parameters on the request provide more definition to the query and response. For example, 'searchFields' scopes query execution to specific fields, 'select' specifies which fields are returned in results, and 'count' returns the number of matches found in the index.

The following example gives you a general idea of a query request by showing some of the available parameters. For more information about query composition, see Query types and compositions and Search Documents (REST).

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": "true"
}

Choose a client

You'll need a tool like Azure portal or Postman, or code that instantiates a query client using APIs. We recommend the Azure portal or REST APIs for early development and proof-of-concept testing.

Permissions

A query request requires read permissions, granted via an API key passed in the header. Any operation, including query requests, will work under an admin API key, but query requests can optionally use a query API key. Query API keys are strongly recommended. You can create up to 50 per service and assign different keys to different applications.

In Azure portal, access to tools, wizards, and objects require membership in the Contributor role or above on the service.

Use Azure portal to query an index

Search explorer (portal) is a query interface in the Azure portal that runs queries against indexes on the underlying search service. Internally, the portal makes Search Documents requests, but cannot invoke Autocomplete, Suggestions, or Document Lookup.

You can select any index and REST API version, including preview. A query string can use simple or full syntax, with support for all query parameters (filter, select, searchFields, and so on). In the portal, when you open an index, you can work with Search Explorer alongside the index JSON definition in side-by-side tabs for easy access to field attributes. Check what fields are searchable, sortable, filterable, and facetable while testing queries.

Use a REST client

The Postman desktop app can function as a query client. Using the app, you can connect to your search service and send Search Documents (REST) requests. Numerous tutorials and examples demonstrate REST clients for querying indexing.

Start with Create a search index using REST and Postman for step-by-step instructions for setting up requests.

Each request is standalone, so you must provide the endpoint, index name, and API version on every request. Other properties, Content-Type and API key, are passed on the request header. For more information, see Search Documents (REST) for help with formulating query requests.

Use an SDK

For Cognitive Search, the Azure SDKs implement generally available features. As such, you can use any of the SDKs to query an index. All of them provide a SearchClient that has methods to interacting with an index, from loading an index with search documents, to formulating query requests.

Azure SDK Client Examples
.NET SearchClient DotNetHowTo
Java SearchClient SearchForDynamicDocumentsExample.java
JavaScript SearchClient Pending.
Python SearchClient sample_simple_query.py

Choose a query type: simple | full

If your query is full text search, a query parser will be used to process any text that's passed as search terms and phrases. Azure Cognitive Search offers two query parsers.

  • The simple parser understands the simple query syntax. This parser was selected as the default for its speed and effectiveness in free form text queries. The syntax supports common search operators (AND, OR, NOT) for term and phrase searches, and prefix (*) search (as in "sea*" for Seattle and Seaside). A general recommendation is to try the simple parser first, and then move on to full parser if application requirements call for more powerful queries.

  • The full Lucene query syntax, enabled when you add queryType=full to the request, is based on the Apache Lucene Parser.

Full syntax and simple syntax overlap to the extent that both support the same prefix and boolean operations, but the full syntax provides more operators. In full, there are more operators for boolean expressions, and more operators for advanced queries such as fuzzy search, wildcard search, proximity search, and regular expressions.

Choose query methods

Search is fundamentally a user-driven exercise, where terms or phrases are collected from a search box, or from click events on a page. The following table summarizes the mechanisms by which you can collect user input, along with the expected search experience.

Input Experience
Search method A user types the terms or phrases into a search box, with or without operators, and clicks Search to send the request. Search can be used with filters on the same request, but not with autocomplete or suggestions.
Autocomplete method A user types a few characters, and queries are initiated after each new character is typed. The response is a completed string from the index. If the string provided is valid, the user clicks Search to send that query to the service.
Suggestions method As with autocomplete, a user types a few characters and incremental queries are generated. The response is a dropdown list of matching documents, typically represented by a few unique or descriptive fields. If any of the selections are valid, the user clicks one and the matching document is returned.
Faceted navigation A page shows clickable navigation links or breadcrumbs that narrow the scope of the search. A faceted navigation structure is composed dynamically based on an initial query. For example, search=* to populate a faceted navigation tree composed of every possible category. A faceted navigation structure is created from a query response, but it's also a mechanism for expressing the next query. n REST API reference, facets is documented as a query parameter of a Search Documents operation, but it can be used without the search parameter.
Filter method Filters are used with facets to narrow results. You can also implement a filter behind the page, for example to initialize the page with language-specific fields. In REST API reference, $filter is documented as a query parameter of a Search Documents operation, but it can be used without the search parameter.

Effect of field attributes on queries

If you're familiar with query types and composition, you might remember that the parameters on a query request depend on field attributes in an index. For example, only fields marked as searchable and retrievable can be used in queries and search results. When setting the search, filter, and orderby parameters in your request, you should check attributes to avoid unexpected results.

In the portal screenshot below of the hotels sample index, only the last two fields "LastRenovationDate" and "Rating" can be used in an "$orderby" only clause.

Index definition for the hotel sample

For field attribute definitions, see Create Index (REST API).

Effect of tokens on queries

During indexing, the search engine uses a text analyzer on strings to maximize the potential for finding a match at query time. At a minimum, strings are lower-cased, but depending on the analyzer, might also undergo lemmatization and stop word removal. Larger strings or compound words are typically broken up by whitespace, hyphens, or dashes, and indexed as separate tokens.

The point to take away here is that what you think your index contains, and what's actually in it, can be different. If queries do not return expected results, you can inspect the tokens created by the analyzer through the Analyze Text (REST API). For more information about tokenization and the impact on queries, see Partial term search and patterns with special characters.

Next steps

Now that you have a better understanding of how query requests work, try the following quickstarts for hands-on experience.