Merge pull request #48206 from HeidiSteen/heidist-master2

Heidist master2

Author: GitHubber17

articles/search/search-query-overview.md

@@ -7,44 +7,65 @@ ms.author: heidist
 services: search
 ms.service: search
 ms.topic: conceptual
-ms.date: 07/27/2018
+ms.date: 08/03/2018
 
 ---
 # Query fundamentals in Azure Search
 
-A query definition in Azure Search is a full specification of a request that includes these parts: service URL endpoint, target index, api-key used to authenticate the request, api-version, and a query string. 
+Query composition in Azure Search is a full specification of a request: match criteria, plus parameters for directing query execution and shaping the response. A request specifies which fields to include, which fields to return, whether to sort or filter, and so forth. Unspecified, a query runs against all searchable fields as a full text search operation, returning an unscored result set in arbitrary order.
 
-Query string composition consists of parameters as defined in [Search Documents API](https://docs.microsoft.com/rest/api/searchservice/search-documents). Most important is the **search=** parameter, which could be undefined (`search=*`) but more likely consists of terms, phrases, and operators similar to the following example:
+## Introduction by example
 
-```
-"search": "seattle townhouse +\"lake\""
-```
-
-Other parameters are used to direct query processing or enhance the response. Examples of how parameters are used include scoping search to specific fields, setting a search mode to modulate the precision-to-recall bias, and adding a count so that you can keep track of results. 
+Examples are useful for illustrating key concepts. The following example, formulated as a search request using the [Search Documents REST API](https://docs.microsoft.com/rest/api/searchservice/search-documents), informs both the request and response. In Azure Search, query execution is always against one index, authenticated using an api-key provided in the request. 
 
 ```
 {  
-    "search": "seattle townhouse* +\"lake\"",  
+    "queryType": "simple" 
+    "search": "seattle townhouse* +\"lake\"", 
     "searchFields": "description, city",  
-    "searchMode": "all",
     "count": "true", 
-    "queryType": "simple" 
+    "select": "listingId, street, status, daysOnMarket, description",
+    "top": "10",
+    "orderby": "listingId"
  } 
 ```
+As a representative query, this example demonstrates several important aspects of query definition, from parser inputs, to shaping the result set. Query execution is always against one index, authenticated using an api-key provided in the request. 
 
-Although query definition is fundamental, your index schema is equally important in how it specifies allowable operations on a field-by-field basis. During index development, attributes on fields determine allowed operations. For example, to qualify for full text search and inclusion in search results, a field must be marked as both *searchable* and *retrievable*.
+To run this query, use [Search explorer and the real estate demo index](search-get-started-portal.md). You can paste this query string into the explorer's search bar: `search=seattle townhouse +lake&searchFields=description, city&$count=true&$select=listingId, street, status, daysOnMarket, description&$top=10&orderby=listingId`
 
-At query time, execution is always against one index, authenticated using an api-key provided in the request. You cannot join indexes or create custom or temporary data structures as a query target.  
+**Searching the index**
 
-Query results are streamed as JSON documents in the REST API, although if you use .NET APIs, serialization is built in. You can shape results by setting parameters on the query, selecting specific fields for the result
++ Query parser is a choice, set through `queryType`. Most developers use the default [simple parser](search-query-simple-examples.md) for full text search, but [full Lucene](search-query-lucene-examples.md) parsing is required for specialized query forms such as fuzzy search or regular expressions.
++ Match criteria on documents in the index is set through the `search` parameter.
++ Scope can be the entire index, or specific fields as determined through `searchFields`.
+
+**Structuring the response**
+
+Other parameters in the example pertain to the results of query:
+
++ `count` is the number of documents matching the query.
++ `select` limits the fields returned in the response.
++ `top` limits the rows or documents returned in the response. The default is 50; the example reduces that to 10.
++ `orderby` sorts the results by a field.
 
-To summarize, the substance of the query request specifies scope and operations: which fields to include in search, which fields to include in the result set, whether to sort or filter, and so forth. Unspecified, a query runs against all searchable fields as a full text search operation, returning an unscored result set in arbitrary order.
+**Enabling operations through index attributes**
+
+Index design and query design are tightly coupled in Azure Search. While not shown here, a critical point to know up front is that the *index schema*, with attributes on each field, determines the kind of query you can build. Index attributes on a field determine allowed operations - whether a field is *searchable* in the index, *retrievable* in results, *sortable*, *filterable*, and so forth. In the example, `"orderby": "listingId"` only works if the listingId field is marked as *sortable* in the index schema. For more information about index attributes, see [Create Index REST API](https://docs.microsoft.com/rest/api/searchservice/create-index).
+
+Allowed operations on a per-field basis are just one way that index definition informs query execution. Other capabilities enabled in the index include the following:
+
++ [Synonyms](https://docs.microsoft.com/rest/api/searchservice/synonym-map-operations)
++ [Text (linguistic) analysis](https://docs.microsoft.com//rest/api/searchservice/language-support) and [custom analysis](https://docs.microsoft.com/rest/api/searchservice/custom-analyzers-in-azure-search)
++ [Suggester constructs](https://docs.microsoft.com/rest/api/searchservice/suggesters) that enable autocomplete and auto-suggestion
++ [Scoring profiles](https://docs.microsoft.com/rest/api/searchservice/add-scoring-profiles-to-a-search-index) that add logic to ranking search results
+
+The above capabilities are exercised during query execution, but are generally implemented in your code as attributes on the field rather than as parameters on the query.
 
 <a name="types-of-queries"></a>
 
 ## Types of queries: search and filter
 
-Azure Search offers many options to create extremely powerful queries. The two main types of query you will use are `search` and `filter`. 
+In the introductory example, the search parameter was identified as the means by which search criteria is passed to the engine. In practice, there are two main types of query: `search` and `filter`. 
 
 + `search` queries scan for one or more terms in all *searchable* fields in your index, and works the way you would expect a search engine like Google or Bing to work. The examples in the introduction use the `search` parameter.
 
@@ -63,14 +84,14 @@ POST /indexes/nycjobs/docs/search?api-version=2017-11-11
 
 Used together, the filter is applied first to the entire index, and then the search is performed on the results of the filter. Filters can therefore be a useful technique to improve query performance since they reduce the set of documents that the search query needs to process.
 
-The syntax for filter expressions is a subset of the [OData filter language](https://docs.microsoft.com/rest/api/searchservice/OData-Expression-Syntax-for-Azure-Search). For search queries you can use either the [simplified syntax](https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search) or the [Lucene query syntax](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search) which are discussed below.
+The syntax for filter expressions is a subset of the [OData filter language](https://docs.microsoft.com/rest/api/searchservice/OData-Expression-Syntax-for-Azure-Search). For search queries, you can use either the [simplified syntax](https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search) or the [Lucene query syntax](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search) which are discussed below.
 
 
 ## Choose a syntax: simple or full
 
 Azure Search sits on top of Apache Lucene and gives you a choice between two query parsers for handling typical and specialized queries. Typical search requests are formulated using the default [simple query syntax](https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search). This syntax supports a number of common search operators including the AND, OR, NOT, phrase, suffix, and precedence operators.
 
-The [Lucene query syntax](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search#bkmk_syntax), enabled when you add **queryType=full** to the request, exposes the widely-adopted and expressive query language developed as part of [Apache Lucene](https://lucene.apache.org/core/4_10_2/queryparser/org/apache/lucene/queryparser/classic/package-summary.html). Using this query syntax allows specialized queries:
+The [Lucene query syntax](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search#bkmk_syntax), enabled when you add `queryType=full` to the request, exposes the widely adopted and expressive query language developed as part of [Apache Lucene](https://lucene.apache.org/core/4_10_2/queryparser/org/apache/lucene/queryparser/classic/package-summary.html). Using this query syntax allows specialized queries:
 
 + [Field-scoped queries](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search#bkmk_fields)
 + [fuzzy search](https://docs.microsoft.com/rest/api/searchservice/Lucene-query-syntax-in-Azure-Search#bkmk_fuzzy)
@@ -86,30 +107,23 @@ Boolean operators are mostly the same in both syntax, with additional formats in
 
 ## Required and optional elements
 
+Queries are always directed at a single index. You cannot join indexes or create custom or temporary data structures as a query target. 
+
 When submitting search requests to Azure Search, there are a number of parameters that can be specified alongside the actual words that are typed into the search box of your application. These query parameters allow you to achieve some deeper control of the [full-text search experience](search-lucene-query-architecture.md).
 
 Required elements on a query request include the following components:
 
 + Service endpoint and index documents collection, expressed here as a URL `https://<your-service-name>.search.windows.net/indexes/<your-index-name>/docs`.
-+ API version (REST only), expressed as **api-version=**
-+ query or admin api-key, expressed as **api-key=**
-+ query string expressed as **search=**, which can be unspecified if you want to perform an empty search. You can also send just a filter expression as **$filter=**.
-+ **queryType=**, either simple or full, which can be omitted if you want to use the default simple syntax.
++ API version (REST only), expressed as `api-version`
++ query or admin api-key, expressed as `api-key`
++ query string expressed as `search`, which can be unspecified if you want to perform an empty search. You can also send just a filter expression as `$filter`.
++ `queryType`, either simple or full, which can be omitted if you want to use the default simple syntax.
 
 All other search parameters are optional.
 
-## APIs and tools for testing
-
-The following table lists the APIs and tool-based approaches for submitting queries.
-
-| Methodology | Description |
-|-------------|-------------|
-| [SearchIndexClient (.NET)](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.searchindexclient?view=azure-dotnet) | Client that can be used to query an Azure Search index.  <br/>[Learn more.](search-howto-dotnet-sdk.md#core-scenarios)  |
-| [Search Documents (REST API)](https://docs.microsoft.com/rest/api/searchservice/search-documents) | GET or POST methods on an index, using query parameters for additional input.  |
-| [Fiddler, Postman, or other HTTP testing tool](search-fiddler.md) | Explains how to set up a request header and body for sending queries to Azure Search.  |
-| [Search explorer in Azure portal](search-explorer.md) | Provides a search bar and options for index and api-version selections. Results are returned as JSON documents. <br/>[Learn more.](search-get-started-portal.md#query-index) | 
+## Manage search results 
 
-## Manage search results
+Query results are streamed as JSON documents in the REST API, although if you use .NET APIs, serialization is built in. You can shape results by setting parameters on the query, selecting specific fields for the result
 
 Parameters on the query can be used to structure the result set in the following ways:
 
@@ -140,6 +154,17 @@ If you want Azure Search to return your results ordered by a value other than th
 ### Hit highlighting
 In Azure Search, emphasizing the exact portion of search results that match the search query is made easy by using the `highlight`, `highlightPreTag`, and `highlightPostTag` parameters. You can specify which *searchable* fields should have their matched text emphasized as well as specifying the exact string tags to append to the start and end of the matched text that Azure Search returns.
 
+## APIs and tools for testing
+
+The following table lists the APIs and tool-based approaches for submitting queries.
+
+| Methodology | Description |
+|-------------|-------------|
+| [SearchIndexClient (.NET)](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.searchindexclient?view=azure-dotnet) | Client that can be used to query an Azure Search index.  <br/>[Learn more.](search-howto-dotnet-sdk.md#core-scenarios)  |
+| [Search Documents (REST API)](https://docs.microsoft.com/rest/api/searchservice/search-documents) | GET or POST methods on an index, using query parameters for additional input.  |
+| [Fiddler, Postman, or other HTTP testing tool](search-fiddler.md) | Explains how to set up a request header and body for sending queries to Azure Search.  |
+| [Search explorer in Azure portal](search-explorer.md) | Provides a search bar and options for index and api-version selections. Results are returned as JSON documents. <br/>[Learn more.](search-get-started-portal.md#query-index) | 
+
 ## See also
 
 + [How full text search works in Azure Search (query parsing architecture](search-lucene-query-architecture.md)