|
| 1 | +--- |
| 2 | +title: Simple query examples for Azure Search | Microsoft Docs |
| 3 | +description: Simple query examples for full text search, filter search, geo search, faceted search, and other query strings used to query an Azure Search index. |
| 4 | +author: HeidiSteen |
| 5 | +manager: cgronlun |
| 6 | +tags: Simple query analyzer syntax |
| 7 | +services: search |
| 8 | +ms.service: search |
| 9 | +ms.topic: conceptual |
| 10 | +ms.date: 07/16/2018 |
| 11 | +ms.author: heidist |
| 12 | +--- |
| 13 | + |
| 14 | +# Simple syntax query examples for building queries in Azure Search |
| 15 | + |
| 16 | +[Simple query syntax](https://docs.microsoft.com/rest/api/searchservice/simple-query-syntax-in-azure-search) invokes the default query parser for executing full text search queries against an Azure Search index. The simple query analyzer is fast and handles common scenarios in Azure Search, including full text search, filtered and faceted search, and geo-search. In this article, step through examples demonstrating query operations available when using the simple syntax. |
| 17 | + |
| 18 | +The alternative query syntax is [full Lucene](https://docs.microsoft.com/rest/api/searchservice/lucene-query-syntax-in-azure-search), supporting more complex query structures, such as fuzzy and wildcard search, which can take additional time to process. For more information and examples demonstrating full syntax, see [Lucene syntax query examples](search-query-lucene-examples.md). |
| 19 | + |
| 20 | +## Formulate requests in Postman |
| 21 | + |
| 22 | +The following examples leverage a NYC Jobs search index consisting of jobs available based on a dataset provided by the [City of New York OpenData](https://nycopendata.socrata.com/) initiative. This data should not be considered current or complete. The index is on a sandbox service provided by Microsoft, which means you do not need an Azure subscription or Azure Search to try these queries. |
| 23 | + |
| 24 | +What you do need is Postman or an equivalent tool for issuing HTTP request on GET. For more information, see [Test with REST clients](search-fiddler.md). |
| 25 | + |
| 26 | +### Set the request header |
| 27 | + |
| 28 | +1. In the request header, set **Content-Type** to `application/json`. |
| 29 | + |
| 30 | +2. Add an **api-key**, and set it to this string: `252044BE3886FE4A8E3BAA4F595114BB`. This is a query key for the sandbox search service hosting the NYC Jobs index. |
| 31 | + |
| 32 | +After you specify the request header, you can reuse it for all of the queries in this article, swapping out only the **search=** string. |
| 33 | + |
| 34 | +  |
| 35 | + |
| 36 | +### Set the request URL |
| 37 | + |
| 38 | +Request is a GET command paired with a URL containing the Azure Search endpoint and search string. |
| 39 | + |
| 40 | +  |
| 41 | + |
| 42 | +URL composition has the following elements: |
| 43 | + |
| 44 | ++ **`https://azs-playground.search.windows.net/`** is a sandbox search service maintained by the Azure Search development team. |
| 45 | ++ **`indexes/nycjobs/`** is the NYC Jobs index in the indexes collection of that service. Both the service name and index are required on the request. |
| 46 | ++ **`docs`** is the documents collection containing all searchable content. The query api-key provided in the request header only works on read operations targeting the documents collection. |
| 47 | ++ **`api-version=2017-11-11`** sets the api-version, which is a required parameter on every request. |
| 48 | ++ **`search=*`** is the query string, which in the initial query is null, returning the first 50 results (by default). |
| 49 | + |
| 50 | +## Send your first query |
| 51 | + |
| 52 | +As a verification step, paste the following request into GET and click **Send**. Results are returned as verbose JSON documents. You can copy-paste this URL in first example below. |
| 53 | + |
| 54 | + ```http |
| 55 | + https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&search=* |
| 56 | + ``` |
| 57 | + |
| 58 | +The query string, **`search=*`**, is an unspecified search equivalent to null or empty search. It's not especially useful, but it is the simplest search you can do. |
| 59 | + |
| 60 | +Optionally, you can add **`$count=true`** to the URL to return a count of the documents matching the search criteria. On an empty search string, this is all the documents in the index (2802 in the case of NYC Jobs). |
| 61 | + |
| 62 | +## How to invoke simple query parsing |
| 63 | + |
| 64 | +For interactive queries, you don't have to specify anything: simple is the default. In code, if you previously invoked **queryType=full** for full query syntax, you could reset back to default with **queryType=simple**. |
| 65 | + |
| 66 | +## Example 1: Field-scoped query |
| 67 | + |
| 68 | +The first query is not syntax-specific (the query works for both simple and full syntax) but we lead with this example to introduce a baseline query concept that produces a reasonably readable JSON response. For brevity, the query targets only the *business_title* field and specifies only business titles are returned. |
| 69 | + |
| 70 | +```http |
| 71 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&searchFields=business_title&$select=business_title&search=* |
| 72 | +``` |
| 73 | + |
| 74 | +The **searchFields** parameter restricts the search to just the business title field. The **select** parameter determines which fields are included in the result set. |
| 75 | + |
| 76 | +Response for this query should look similar to the following screenshot. |
| 77 | + |
| 78 | +  |
| 79 | + |
| 80 | +You might have noticed that the search score is also returned for every document even though search score is not specified. This is because search score is metadata, with the value indicating rank order of results. Uniform scores of 1 occur when there is no rank, either because the search was not full text search, or because there is no criteria to apply. For null search, there is no criteria and the rows coming back are in arbitrary order. As the search criteria takes on more definition, you will see search scores evolve into meaningful values. |
| 81 | + |
| 82 | +## Example 2: Look-up by ID |
| 83 | + |
| 84 | +This example is a bit atypical, but when evaluating search behaviors, you might want to inspect the entire contents of a document to understand why it was included or excluded from results. To return an entire document, use a [Lookup operation](https://docs.microsoft.com/rest/api/searchservice/lookup-document) to pass in the document ID. |
| 85 | + |
| 86 | +All documents have a unique identifier. To try out the syntax for a lookup query, first return a list of document IDs so that you can find one to use. For NYC Jobs, the identifiers are stored in the `id` field. |
| 87 | + |
| 88 | +```http |
| 89 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&searchFields=id&$select=id&search=* |
| 90 | + ``` |
| 91 | + |
| 92 | +The next example is a lookup query returning a specific document based on `id` "9E1E3AF9-0660-4E00-AF51-9B654925A2D5", which appeared first in the previous response. The following query returns the entire document, not just selected fields. |
| 93 | + |
| 94 | +```http |
| 95 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs/9E1E3AF9-0660-4E00-AF51-9B654925A2D5?api-version=2017-11-11&$count=true&search=* |
| 96 | + ``` |
| 97 | + |
| 98 | +## Example 3: Search precision |
| 99 | + |
| 100 | +Term queries are single terms, perhaps many of them, that are evaluated independently. Phrase queries are enclosed in quotation marks and evaluated as a verbatim string. Precision of the match is controlled by operators and searchMode. |
| 101 | + |
| 102 | +Example 1: **`&search=fire`** returns 150 results, where all matches contain the word fire somewhere in the document. |
| 103 | + |
| 104 | +``` |
| 105 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&search=fire |
| 106 | +``` |
| 107 | + |
| 108 | +Example 2: **`&search=fire department`** returns 2002 results. Matches are returned for documents containing either fire or department. |
| 109 | + |
| 110 | +``` |
| 111 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&search=fire department |
| 112 | +``` |
| 113 | + |
| 114 | +Example 3: **`&search="fire department"`** returns 82 results. Enclosing the string in quotation marks is a verbatim search on both terms, and matches are found on tokenized terms in the index consisting of the combined terms. This explains why a search like **`search=+fire +department`** is not equivalent. Both terms are required, but are scanned for independently. |
| 115 | + |
| 116 | +``` |
| 117 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&search="fire department" |
| 118 | +``` |
| 119 | + |
| 120 | +## Example 4: Booleans with searchMode |
| 121 | + |
| 122 | +Simple syntax supports boolean operators in the form of characters (`+, -, |`). The searchMode parameter informs tradeoffs between precision and recall, with `searchMode=any` favoring recall (matching on any criteria qualifies a document for the result set), and `searchMode=all` favoring precision (all criteria must be matched). The default is `searchMode=any`, which can be confusing if you are stacking a query with multiple operators and getting broader instead of narrower results. This is particularly true with NOT, where results include all documents "not containing" a specific term. |
| 123 | + |
| 124 | +Using the default searchMode (any), 2800 documents are returned: those containing the multi-part term "fire department", plus all documents that do not have the term "Metrotech Center". |
| 125 | + |
| 126 | +``` |
| 127 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&searchMode=any&search="fire department" -"Metrotech Center" |
| 128 | +``` |
| 129 | +Changing searchMode to `all` enforces a cumulative effect on criteria and returns a smaller result set - 21 documents - consisting of documents containing the entire phrase "fire department", minus those jobs at the Metrotech Center address. |
| 130 | + |
| 131 | +``` |
| 132 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&searchMode=all&search="fire department" -"Metrotech Center" |
| 133 | +``` |
| 134 | + |
| 135 | + |
| 136 | +## Example 5: Structuring results |
| 137 | + |
| 138 | +Several parameters control which fields are in the search results, the number of documents returned in each batch, and sort order. This example resurfaces a few of the previous examples, limiting results to specific fields using the **$select** statement and verbatim search criteria, returning 82 matches |
| 139 | + |
| 140 | +```http |
| 141 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department" |
| 142 | +``` |
| 143 | +Appended onto the previous example, you can sort by title. This sort works because civil_service_title is *sortable* in the index. |
| 144 | + |
| 145 | +```http |
| 146 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title |
| 147 | +``` |
| 148 | + |
| 149 | +Paging results is implemented using the **$top** parameter, in this case returning the top 5 documents: |
| 150 | + |
| 151 | +```http |
| 152 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title&$top=5&$skip=0 |
| 153 | +``` |
| 154 | + |
| 155 | +To get the next 5, skip the first batch: |
| 156 | + |
| 157 | +```http |
| 158 | +https://azs-playground.search.windows.net/indexes/nycjobs/docs?api-version=2017-11-11&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title&$top=5&$skip=5 |
| 159 | +``` |
| 160 | + |
| 161 | +## Next steps |
| 162 | +Try specifying queries in your code. The following links explain how to set up search queries for both .NET and the REST API using the default simple syntax. |
| 163 | + |
| 164 | +* [Query your Azure Search Index using the .NET SDK](search-query-dotnet.md) |
| 165 | +* [Query your Azure Search Index using the REST API](search-query-rest-api.md) |
| 166 | + |
| 167 | +Additional syntax reference, query architecture, and examples can be found in the following links: |
| 168 | + |
| 169 | ++ [Lucene syntax query examples for building advanced queries](search-query-lucene-examples.md) |
| 170 | ++ [How full text search works in Azure Search](search-lucene-query-architecture.md) |
| 171 | ++ [Simple query syntax](https://docs.microsoft.com/rest/api/searchservice/simple-query-syntax-in-azure-search) |
| 172 | ++ [Full Lucene query](https://docs.microsoft.com/rest/api/searchservice/lucene-query-syntax-in-azure-search) |
0 commit comments