Merge pull request #327 from HeidiSteen/main

[azure search] BULK EDIT: REST API updates for autocomplete and data sources, plus preview API links

Author: Jill Grant

articles/search/cognitive-search-common-errors-warnings.md

@@ -385,7 +385,7 @@ Output field mappings that reference non-existent/null data will produce warning
 <a name="the-data-change-detection-policy-is-configured-to-use-key-column-x"></a>
 
 ## `Warning: The data change detection policy is configured to use key column 'X'`
-[Data change detection policies](/rest/api/searchservice/create-data-source#data-change-detection-policies) have specific requirements for the columns they use to detect change. One of these requirements is that this column is updated every time the source item is changed. Another requirement is that the new value for this column is greater than the previous value. Key columns don't fulfill this requirement because they don't change on every update. To work around this issue, select a different column for the change detection policy.
+[Data change detection policies](/rest/api/searchservice/data-sources/create#request-body) have specific requirements for the columns they use to detect change. One of these requirements is that this column is updated every time the source item is changed. Another requirement is that the new value for this column is greater than the previous value. Key columns don't fulfill this requirement because they don't change on every update. To work around this issue, select a different column for the change detection policy.
 
 <a name="document-text-appears-to-be-utf-16-encoded-but-is-missing-a-byte-order-mark"></a>
 

articles/search/cognitive-search-concept-intro.md

@@ -116,7 +116,7 @@ An enrichment pipeline consists of [*indexers*](search-indexer-overview.md) that
 
 Start with a subset of data in a [supported data source](search-indexer-overview.md#supported-data-sources). Indexer and skillset design is an iterative process. The work goes faster with a small representative data set.
 
-1. Create a [data source](/rest/api/searchservice/create-data-source) that specifies a connection to your data.
+1. Create a [data source](/rest/api/searchservice/data-sources/create) that specifies a connection to your data.
 
 1. [Create a skillset](cognitive-search-defining-skillset.md). Unless your project is small, you should [attach an Azure AI multi-service resource](cognitive-search-attach-cognitive-services.md). If you're [creating a knowledge store](knowledge-store-create-rest.md), define it within the skillset.
 

articles/search/cognitive-search-tutorial-blob.md

@@ -97,7 +97,7 @@ AI enrichment is indexer-driven. This part of the walkthrough creates four objec
 
 ### Step 1: Create a data source
 
-Call [Create Data Source](/rest/api/searchservice/create-data-source) to set the connection string to the Blob container containing the sample data files.
+Call [Create Data Source](/rest/api/searchservice/data-sources/create) to set the connection string to the Blob container containing the sample data files.
 
 ```http
 ### Create a data source

articles/search/index-add-suggesters.md

@@ -152,7 +152,7 @@ private static void CreateIndex(string indexName, SearchIndexClient indexClient)
 A suggester is used in a query. After a suggester is created, call one of the following APIs for a search-as-you-type experience:
 
 + [Suggestions REST API](/rest/api/searchservice/suggestions)
-+ [Autocomplete REST API](/rest/api/searchservice/autocomplete)
++ [Autocomplete REST API](/rest/api/searchservice/documents/autocomplete-post)
 + [SuggestAsync method](/dotnet/api/azure.search.documents.searchclient.suggestasync)
 + [AutocompleteAsync method](/dotnet/api/azure.search.documents.searchclient.autocompleteasync)
 

articles/search/index-similarity-and-scoring.md

@@ -137,7 +137,9 @@ In Azure AI Search, you can configure BM25 algorithm parameters, and tune search
 
 ## featuresMode parameter (preview)
 
-[Search Documents](/rest/api/searchservice/preview-api/search-documents) requests have a new [featuresMode](/rest/api/searchservice/preview-api/search-documents#featuresmode) parameter that can provide more detail about relevance at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), through featuresMode you can get information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index). For each field, you get the following values:
+[Search Documents](/rest/api/searchservice/documents/search-post) requests support a featuresMode parameter that provides more detail about a relevance score at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), featuresMode reveals information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index). 
+
+For each field, `@search.features` give you the following values:
 
 + Number of unique tokens found in the field
 + Similarity score, or a measure of how similar the content of the field is, relative to the query term
@@ -167,6 +169,8 @@ For a query that targets the "description" and "title" fields, a response that i
 
 You can consume these data points in [custom scoring solutions](https://github.com/Azure-Samples/search-ranking-tutorial) or use the information to debug search relevance problems.
 
+The featuresMode parameter isn't documented in the REST APIs, but you can use it on a preview REST API call to Search Documents.
+
 ## Number of ranked results in a full text query response
 
 By default, if you aren't using pagination, the search engine returns the top 50 highest ranking matches for full text search. You can use the `top` parameter to return a smaller or larger number of items (up to 1000 in a single response). Full text search is subject to a maximum limit of 1,000 matches (see [API response limits](search-limits-quotas-capacity.md#api-response-limits)). Once 1,000 matches are found, the search engine no longer looks for more.

articles/search/knowledge-store-create-rest.md

@@ -113,7 +113,7 @@ A valid API key establishes trust, on a per request basis, between the applicati
 
 ## Create a data source
 
-[Create Data Source](/rest/api/searchservice/create-data-source) creates a data source connection on Azure AI Search.
+[Create Data Source](/rest/api/searchservice/data-sources/create) creates a data source connection on Azure AI Search.
 
 1. Paste in the following example to create the data source.
 

articles/search/query-odata-filter-orderby-syntax.md

@@ -90,8 +90,8 @@ Field paths are used in many parameters of the [Azure AI Search REST APIs](/rest
 | [Search](/rest/api/searchservice/documents/search-post) | `facet` | Can only refer to **facetable** fields |
 | [Search](/rest/api/searchservice/documents/search-post) | `highlight` | Can only refer to **searchable** fields |
 | [Search](/rest/api/searchservice/documents/search-post) | `searchFields` | Can only refer to **searchable** fields |
-| [Suggest](/rest/api/searchservice/suggestions) and [Autocomplete](/rest/api/searchservice/autocomplete) | `searchFields` | Can only refer to fields that are part of a [suggester](index-add-suggesters.md) |
-| [Search](/rest/api/searchservice/documents/search-post), [Suggest](/rest/api/searchservice/suggestions), and [Autocomplete](/rest/api/searchservice/autocomplete) | `$filter` | Can only refer to **filterable** fields |
+| [Suggest](/rest/api/searchservice/suggestions) and [Autocomplete](/rest/api/searchservice/documents/autocomplete-post) | `searchFields` | Can only refer to fields that are part of a [suggester](index-add-suggesters.md) |
+| [Search](/rest/api/searchservice/documents/search-post), [Suggest](/rest/api/searchservice/suggestions), and [Autocomplete](/rest/api/searchservice/documents/autocomplete-post) | `$filter` | Can only refer to **filterable** fields |
 | [Search](/rest/api/searchservice/documents/search-post) and [Suggest](/rest/api/searchservice/suggestions) | `$orderby` | Can only refer to **sortable** fields |
 | [Search](/rest/api/searchservice/documents/search-post), [Suggest](/rest/api/searchservice/suggestions), and [Lookup](/rest/api/searchservice/lookup-document) | `$select` | Can only refer to **retrievable** fields |
 

articles/search/search-add-autocomplete-suggestions.md

@@ -20,7 +20,7 @@ Search-as-you-type is a common technique for improving query productivity. In Az
 To implement these experiences in Azure AI Search:
 
 + Add a `suggester` to an index schema.
-+ Build a query that calls the [Autocomplete](/rest/api/searchservice/autocomplete) or [Suggestions](/rest/api/searchservice/suggestions) API on the request.
++ Build a query that calls the [Autocomplete](/rest/api/searchservice/documents/autocomplete-post) or [Suggestions](/rest/api/searchservice/suggestions) API on the request.
 + Add a UI control to handle search-as-you-type interactions in your client app. We recommend using an existing JavaScript library for this purpose.
 
 In Azure AI Search, autocompleted queries and suggested results are retrieved from the search index, from selected fields that you register with a suggester. A suggester is part of the index, and it specifies which fields provide content that either completes a query, suggests a result, or does both. When the index is created and loaded, a suggester data structure is created internally to store prefixes used for matching on partial queries. For suggestions, choosing suitable fields that are unique, or at least not repetitive, is essential to the experience. For more information, see [Create a suggester](index-add-suggesters.md).
@@ -52,17 +52,17 @@ Matches are on the beginning of a term anywhere in the input string. Given "the
 Follow these links for the REST and .NET SDK reference pages:
 
 + [Suggestions REST API](/rest/api/searchservice/suggestions) 
-+ [Autocomplete REST API](/rest/api/searchservice/autocomplete) 
++ [Autocomplete REST API](/rest/api/searchservice/documents/autocomplete-post) 
 + [SuggestAsync method](/dotnet/api/azure.search.documents.searchclient.suggestasync)
 + [AutocompleteAsync method](/dotnet/api/azure.search.documents.searchclient.autocompleteasync)
 
 ## Structure a response
 
-Responses for autocomplete and suggestions are what you might expect for the pattern: [Autocomplete](/rest/api/searchservice/autocomplete#response) returns a list of terms, [Suggestions](/rest/api/searchservice/suggestions#response) returns terms plus a document ID so that you can fetch the document (use the [Lookup Document](/rest/api/searchservice/lookup-document) API to fetch the specific document for a detail page).
+Responses for autocomplete and suggestions are what you might expect for the pattern: [Autocomplete](/rest/api/searchservice/documents/autocomplete-post#responses) returns a list of terms, [Suggestions](/rest/api/searchservice/suggestions#response) returns terms plus a document ID so that you can fetch the document (use the [Lookup Document](/rest/api/searchservice/lookup-document) API to fetch the specific document for a detail page).
 
 Responses are shaped by the parameters on the request:
 
-+ For Autocomplete, set the [autocompleteMode](/rest/api/searchservice/autocomplete#query-parameters) to determine whether text completion occurs on one or two terms. 
++ For Autocomplete, set the [autocompleteMode](/rest/api/searchservice/documents/autocomplete-post#autocompletemode) to determine whether text completion occurs on one or two terms. 
 
 + For Suggestions, set [$select](/rest/api/searchservice/suggestions#query-parameters) to return fields containing unique or differentiating values, such as names and description. Avoid fields that contain duplicate values (such as a category or city).
 
@@ -242,7 +242,7 @@ public async Task<ActionResult> AutoCompleteAsync(string term)
 }
 ```
 
-The Autocomplete function takes the search term input. The method creates an [AutoCompleteParameters object](/rest/api/searchservice/autocomplete). The result is then converted to JSON so it can be shown in the client.
+The Autocomplete function takes the search term input. The method creates an [AutoCompleteParameters object](/rest/api/searchservice/documents/autocomplete-post). The result is then converted to JSON so it can be shown in the client.
 
 ## Next steps
 

articles/search/search-howto-connecting-azure-sql-database-to-azure-search-using-indexers.md

@@ -46,7 +46,7 @@ Other approaches for creating an Azure SQL indexer include Azure SDKs or [Import
 
 The data source definition specifies the data to index, credentials, and policies for identifying changes in the data. A data source is defined as an independent resource so that it can be used by multiple indexers.
 
-1. [Create data source](/rest/api/searchservice/create-data-source) or [Update data source](/rest/api/searchservice/update-data-source) to set its definition: 
+1. [Create Data Source](/rest/api/searchservice/data-sources/create) or [Create or Update Data Source](/rest/api/searchservice/data-sources/create-or-update) to set its definition: 
 
    ```http
     POST https://myservice.search.windows.net/datasources?api-version=2024-07-01

articles/search/search-howto-create-indexers.md

@@ -127,7 +127,7 @@ Indexers require a data source that specifies the type, container, and connectio
 
 1. Make sure you're using a [supported data source type](search-indexer-overview.md#supported-data-sources).
 
-1. [Create a data source](/rest/api/searchservice/create-data-source) definition. The following list is a few of the more frequently used data sources:
+1. [Create a data source](/rest/api/searchservice/data-sources/create) definition. The following list is a few of the more frequently used data sources:
 
    + [Azure Blob Storage](search-howto-indexing-azure-blob-storage.md)
    + [Azure Cosmos DB](search-howto-index-cosmosdb.md)
@@ -243,7 +243,7 @@ Change detection logic is built into the data platforms. How an indexer supports
 
 Indexers keep track of the last document it processed from the data source through an internal *high water mark*. The marker is never exposed in the API, but internally the indexer keeps track of where it stopped. When indexing resumes, either through a scheduled run or an on-demand invocation, the indexer references the high water mark so that it can pick up where it left off.
 
-If you need to clear the high water mark to reindex in full, you can use [Reset Indexer](/rest/api/searchservice/reset-indexer). For more selective reindexing, use [Reset Skills](/rest/api/searchservice/preview-api/reset-skills) or [Reset Documents](/rest/api/searchservice/indexers/reset-docs?view=rest-searchservice-2024-05-01-preview&preserve-view=true). Through the reset APIs, you can clear internal state, and also flush the cache if you enabled [incremental enrichment](search-howto-incremental-index.md). For more background and comparison of each reset option, see [Run or reset indexers, skills, and documents](search-howto-run-reset-indexers.md).
+If you need to clear the high water mark to reindex in full, you can use [Reset Indexer](/rest/api/searchservice/reset-indexer). For more selective reindexing, use [Reset Skills](/rest/api/searchservice/skillsets/reset-skills?view=rest-searchservice-2024-05-01-preview&preserve-view=true) or [Reset Documents](/rest/api/searchservice/indexers/reset-docs?view=rest-searchservice-2024-05-01-preview&preserve-view=true). Through the reset APIs, you can clear internal state, and also flush the cache if you enabled [incremental enrichment](search-howto-incremental-index.md). For more background and comparison of each reset option, see [Run or reset indexers, skills, and documents](search-howto-run-reset-indexers.md).
 
 ## Next steps