Simple Query Syntax in Azure AI Search: A Complete Guide to Keyword, Boolean, and Prefix Search

Azure AI Search offers two Lucene-based query languages for full text search. The Simple Query Parser is the default and is designed to interpret requests even when they are not perfectly composed. The Lucene Query Parser supports more advanced query constructions. This guide focuses on the simple syntax, which is based on the Apache Lucene Simple Query Parser but excludes fuzzy search. Query syntax applies to the search parameter of a query request and is distinct from the OData syntax used for filter and orderby expressions. A basic example sets "queryType": "simple" with a search string such as budget hotel +pool and searchMode set to all to ensure every criterion is matched.

Search strings can contain terms, phrases, boolean operators, precedence operators, prefix characters, escape characters, and URL-encoded characters. A term search matches documents containing any of the supplied terms. A phrase search, enclosed in quotation marks, matches only the exact phrase in order, such as "Roach Motel". Depending on the client, quotation marks may need escaping in raw request bodies. All search strings pass through lexical analysis, so reviewing the tokenization behavior of the chosen analyzer is essential for predictable results. If no search text is provided, the query returns the top 50 documents in unranked order.

Boolean operators in the simple syntax are character-based: + performs AND, | performs OR (and OR is the default when terms are simply adjacent), and - performs NOT. The searchMode parameter controls how a NOT term combines with other terms. With searchMode=any, which favors recall, pool - ocean is interpreted as an OR NOT and returns documents containing pool or lacking ocean. With searchMode=all, which favors precision, the same query is interpreted as AND NOT, returning documents containing pool but not ocean. Choose all for precision-focused applications, especially when users frequently rely on the - operator, and choose any when broader recall is preferred.

Prefix queries use the asterisk (*) suffix operator to match terms that begin with a given string, such as lingui* matching linguistic or linguini. A prefix must start with at least one plain text character. Prefix matches are exact, so every result receives a score of 1.0 and no relevance ranking is applied. Prefix queries can be slow on large indexes when the prefix is short, and alternatives such as edge n-gram tokenization may perform better. Prefix terms cannot exceed 1000 characters. Suffix and infix wildcard matching require the full Lucene syntax.

Parentheses create subqueries and control evaluation order. For example, motel+(wifi|luxury) returns documents containing motel together with either wifi or luxury, or both. Use grouping whenever mixing AND and OR logic to ensure the intended match behavior.

The simple syntax treats the characters + | " ( ) ' and \ as operators. When these characters appear as part of an indexed token, prefix them with a single backslash. For instance, to match the indexed token Luxury+Hotel, use search=luxury\+hotel. Two cases do not require escaping: a hyphen is only treated as NOT when it follows whitespace, so identifiers like 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD need no escape, and an asterisk is only a prefix operator when it ends a term before whitespace, so expressions like 4*4=16 are safe.

Characters that are unsafe in URLs, including " ` < > # % { } | \ ^ ~ [ ], must be percent-encoded. Reserved characters, including ; / ? : @ = + &, have structural meaning in URLs and must be encoded when used as data. For example, the # symbol must be encoded as %23 in a URL. Many web clients perform this encoding automatically, but programmatically built queries should verify it explicitly.

Special characters such as currency symbols or emojis may be dropped by default analyzers like the standard analyzer. To preserve them, choose an analyzer suited to the requirement: the whitespace analyzer treats whitespace-separated sequences as tokens, while language analyzers such as en.microsoft may retain symbols like $ or €. A common workaround is to index the same content into multiple fields with different analyzers. Test tokenization to confirm behavior, and when using Unicode characters in URLs, ensure they are properly escaped, for example ❤ as %E2%9D%A4.

Applications generating queries programmatically should bound query size. GET request URLs cannot exceed 8 KB. POST requests, which carry search, filter, and orderby parameters in the body, can be up to 16 MB. The search clause is limited to 100,000 characters and 1024 clauses joined by AND or OR. Prefix search terms cannot exceed 1000 characters, and individual terms in a query are limited to roughly 32 KB. Consult the API request limits documentation for complete details.

For programmatic query construction, review Full text search in Azure AI Search to understand query processing stages and the effects of text analysis. Additional resources include query examples for simple and full Lucene search, the Search Documents REST API reference, Lucene query syntax documentation, and the OData expression syntax reference for filter and select operations.