Merge pull request #280040 from HeidiSteen/heidist-june28

[azure search]  Example for index updates

Author: prmerger-automator[bot]

articles/search/search-howto-reindex.md

@@ -14,17 +14,17 @@ ms.date: 07/01/2024
 
 # Update or rebuild an index in Azure AI Search
 
-This article explains how to update an existing index in Azure AI Search with incremental indexing. It explains the circumstances under which rebuilds are required, and provides recommendations for mitigating the effects of rebuilds on ongoing query requests.
+This article explains how to update an existing index in Azure AI Search with schema changes or content changes through incremental indexing. It explains the circumstances under which rebuilds are required, and provides recommendations for mitigating the effects of rebuilds on ongoing query requests.
 
 During active development, it's common to drop and rebuild indexes when you're iterating over index design. Most developers work with a small representative sample of their data so that reindexing goes faster.
 
-For applications already in production, we recommend creating a new index that runs side by side an existing index to avoid query downtime and using an [index alias](search-how-to-alias.md) to avoid changing your application code.
+For schema changes on applications already in production, we recommend creating and testing a new index that runs side by side an existing index. Use an [index alias](search-how-to-alias.md) to swap in the new index while avoiding changes your application code.
 
 ## Update content
 
-Incremental indexing and synchronizing an index against changes in source data is a basic requirement for most search applications. This section explains the workflow for overwriting field contents in a search index.
+Incremental indexing and synchronizing an index against changes in source data is fundamental to most search applications. This section explains the workflow for updating field contents in a search index.
 
-1. Use the same techniques for loading documents: [Documents - Index (REST)](/rest/api/searchservice/documents) or an equivalent API in the Azure SDKs. For more information about indexing, see [Load documents](search-how-to-load-search-index.md).
+1. Use the same techniques for loading documents: [Documents - Index (REST)](/rest/api/searchservice/documents) or an equivalent API in the Azure SDKs. For more information about indexing techniques, see [Load documents](search-how-to-load-search-index.md).
 
 1. Set the `@search.action` parameter to determine the effect on existing documents:
 
@@ -41,13 +41,47 @@ Queries continue to run, but if you're updating or removing existing fields, you
 
 ## Tips for incremental indexing
 
-+ Use `mergeOrUpload` as the search action.
++ [Indexers automate incremental indexing](search-indexer-overview.md). If you can use an indexer, and if the data source supports change tracking, you can run the indexer on a recurring schedule to add, update, or overwrite searchable content so that it's synchronized to your external data.
 
-+ The payload must include the keys or identifiers of every document you want to add, update, or delete.
++ If you're making index calls directly, use `mergeOrUpload` as the search action.
 
-+ For merging, avoid listing fields that contain content you want to preserve. For example, if you populated vector fields, but only need to update a few nonvector fields, the payload should list just those fields you want to update. Specifying an empty field overwrites the existing value with a null value.
++ The payload must include the keys or identifiers of every document you want to add, update, or delete.
 
-+ [Indexers automate incremental indexing](search-indexer-overview.md). If you can use an indexer, and if the data source supports change tracking, you can run the indexer on a recurring schedule to add, update, and delete an index so that it's synchronized to your external data.
++ To update the contents of simple fields and subfields in complex types, list only the fields you want to change. For example, if you only need to update a description field, the payload should consist of the document key and the modified description. Omitting other fields retains their existing values.
+
++ To merge the inline changes into string collection, provide the entire value. Recall the `tags` field example from the previous section. New values overwrite the old values, and there's no merging at the field content level.
+
+Here's a [REST API example](search-get-started-rest.md) demonstrating these tips:
+
+```rest
+### Get Secret Point Hotel by ID
+GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2023-11-01  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{apiKey}}
+
+### Change the description and city for Secret Point Hotel
+POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2023-11-01  HTTP/1.1
+  Content-Type: application/json
+  api-key: {{apiKey}}
+
+    {
+        "value": [
+            {
+            "@search.action": "mergeOrUpload",
+            "HotelId": "1",
+            "Description": "Change the description and city for Secret Point Hotel. Keep everything else."
+            "Address": {
+                "City": "Miami"
+                }
+            }
+        ]
+    }
+       
+### Retrieve the same document, confirm the overwrites and retention of all other values
+GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2023-11-01  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{apiKey}}
+```
 
 ## Change an index schema
 
@@ -123,7 +157,7 @@ The Azure portal provides index size and vector index size. You can check these
 
 Azure AI Search supports document-level operations so that you can look up, update, and delete a specific document in isolation. The following example shows how to delete a document. 
 
-Recall that deleted documents don't immediately free up space in the index. Every few minutes, a background process performs the physical deletion. Whether you use the portal or an API to return index statistics, you can expect a small delay before the deletion is reflected in the portal and through APIs.
+Deleting a document doesn't immediately free up space in the index. Every few minutes, a background process performs the physical deletion. Whether you use the portal or an API to return index statistics, you can expect a small delay before the deletion is reflected in the portal and API metrics.
 
 1. Identify which field is the document key. In the portal, you can view the fields of each index. Document keys are string fields and are denoted with a key icon to make them easier to spot.
 

articles/search/search-security-enable-roles.md

@@ -25,10 +25,10 @@ Roles for service administration (control plane) are built in and can't be enabl
 
 ## Prerequisites
 
-+ Owner, User Access Administrator, or a custom role with [Microsoft.Authorization/roleAssignments/write](/azure/templates/microsoft.authorization/roleassignments) permissions.
-
 + A search service in any region, on any tier, including free.
 
++ Owner, User Access Administrator, or a custom role with [Microsoft.Authorization/roleAssignments/write](/azure/templates/microsoft.authorization/roleassignments) permissions.
+
 ## Enable role-based access for data plane operations
 
 Configure your search service to recognize an **authorization** header on data requests that provide an OAuth2 access token.

articles/search/search-security-rbac.md

@@ -30,10 +30,10 @@ Role-based access is optional, but recommended. The alternative is [key-based au
 
 ## Prerequisites
 
-+ **Owner**, **User Access Administrator**, or a custom role with [Microsoft.Authorization/roleAssignments/write](/azure/templates/microsoft.authorization/roleassignments) permissions.
-
 + A search service in any region, on any tier, [enabled for role-based access](search-security-enable-roles.md).
 
++ Owner, User Access Administrator, or a custom role with [Microsoft.Authorization/roleAssignments/write](/azure/templates/microsoft.authorization/roleassignments) permissions.
+
 <a name = "built-in-roles-used-in-search"></a>
 
 ## Built-in roles used in Azure AI Search
@@ -51,7 +51,6 @@ The following roles are built in. If these roles are insufficient, [create a cus
 
 Combine these roles to get sufficient permissions for your use case.
 
-
 > [!NOTE]
 > If you disable Azure role-based access, built-in roles for the control plane (Owner, Contributor, Reader) continue to be available. Disabling role-based access removes just the data-related permissions associated with those roles. If data plane roles are disabled, Search Service Contributor is equivalent to control-plane Contributor.
 
@@ -278,15 +277,15 @@ This approach assumes Visual Studio Code with a REST client extension.
    az account get-access-token --query accessToken --output tsv
    ```
 
-1. In a new text file in Visual Studio Code, paste in these variables:
+1. Paste these variables in a new text file in Visual Studio Code.
 
    ```http
    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
    @index-name = PASTE-YOUR-INDEX-NAME-HERE
    @token = PASTE-YOUR-TOKEN-HERE
    ```
 
-1. Paste in and then send a request that uses the variables you've specified. For the "Search Index Data Reader" role, you can send a query. You can use any [supported API version](/rest/api/searchservice/search-service-api-versions).
+1. Paste and then send a request that uses the variables you've specified. For the "Search Index Data Reader" role, you can send a query. You can use any [supported API version](/rest/api/searchservice/search-service-api-versions).
 
    ```http
    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
@@ -381,7 +380,7 @@ If you're already a Contributor or Owner of your search service, you can present
    Get-AzAccessToken -ResourceUrl https://search.azure.com
    ```
 
-1. In a new text file in Visual Studio Code, paste in these variables:
+1. Paste these variables into a new text file in Visual Studio Code.
 
    ```http
    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@@ -539,15 +538,15 @@ The PowerShell example shows the JSON syntax for creating a custom role that's a
 
 1. See [Create or update Azure custom roles using the REST API](../role-based-access-control/custom-roles-rest.md) for steps.
 
-1. Clone or create a role, or use JSON to specify the custom role (see the PowerShell tab for JSON syntax).
+1. Copy or create a role, or use JSON to specify the custom role (see the PowerShell tab for JSON syntax).
 
 ### [**Azure CLI**](#tab/custom-role-cli)
 
 1. Review the [list of atomic permissions](../role-based-access-control/resource-provider-operations.md#microsoftsearch) to determine which ones you need.
 
 1. See [Create or update Azure custom roles using Azure CLI](../role-based-access-control/custom-roles-cli.md) for steps.
 
-1. Clone or create a role, or use JSON to specify the custom role (see the PowerShell tab for JSON syntax).
+1. See the PowerShell tab for JSON syntax.
 
 ---
 

articles/search/service-configure-firewall.md

@@ -15,9 +15,9 @@ ms.date: 06/27/2024
 
 # Configure network access and firewall rules for Azure AI Search
 
-This article explains how to configure network access to a search service's public endpoint. To block *all* data plane access to the public endpoint, use [private endpoints](service-create-private-endpoint.md) and an Azure virtual network.
+This article explains how to restrict network access to a search service's public endpoint. To block *all* data plane access to the public endpoint, use [private endpoints](service-create-private-endpoint.md) and an Azure virtual network.
 
-This article assumes the Azure portal to configure network access options. You can also use the [Management REST API](/rest/api/searchmanagement/), [Azure PowerShell](/powershell/module/az.search), or the [Azure CLI](/cli/azure/search).
+This article assumes the Azure portal for configuring network access options. You can also use the [Management REST API](/rest/api/searchmanagement/), [Azure PowerShell](/powershell/module/az.search), or the [Azure CLI](/cli/azure/search).
 
 ## Prerequisites
 
@@ -29,7 +29,9 @@ This article assumes the Azure portal to configure network access options. You c
 
 By default, Azure AI Search is configured to allow connections over a public endpoint. Access to a search service *through* the public endpoint is protected by authentication and authorization protocols, but the endpoint itself is open to the internet at the network layer for data plane requests.
 
-If you aren't hosting a public web site, you might want to configure network access to automatically refuse requests unless they originate from an approved set of devices and cloud services. There are two mechanisms:
+If you aren't hosting a public web site, you might want to configure network access to automatically refuse requests unless they originate from an approved set of devices and cloud services. 
+
+There are two mechanisms for restricting access to the public endpoint:
 
 + Inbound rules listing the IP addresses, ranges, or subnets from which requests are admitted
 + Exceptions to network rules, where requests are admitted with no checks, as long as the request originates from a [trusted service](#grant-access-to-trusted-azure-services)
@@ -44,7 +46,7 @@ There are a few drawbacks to locking down the public endpoint.
 
 + It takes time to fully identify IP ranges and set up firewalls, and if you're in early stages of proof-of-concept testing and investigation and using sample data, you might want to defer network access controls until you actually need them.
 
-+ Some workflows require access to a public endpoint. Specifically, the import wizards in the Azure portal, such as the [Import data wizard](search-get-started-portal.md) and [Import and vectorize data wizard](search-get-started-portal-import-vectors.md), connect to built-in (hosted) sample data and embedding models over the public endpoint. You can switch to code or script to complete the same tasks with firewall rules in place, but if you want to run the wizards, the public endpoint must be available. For more information, see [Secure connections in the import wizards](search-import-data-portal.md#secure-connections).
++ Some workflows require access to a public endpoint. Specifically, the [**import wizards**](search-import-data-portal.md) in the Azure portal connect to built-in (hosted) sample data and embedding models over the public endpoint. You can switch to code or script to complete the same tasks when firewall rules in place, but if you want to run the wizards, the public endpoint must be available. For more information, see [Secure connections in the import wizards](search-import-data-portal.md#secure-connections).
 
 <a id="configure-ip-policy"></a> 
 
@@ -62,7 +64,7 @@ There are a few drawbacks to locking down the public endpoint.
 
    :::image type="content" source="media/service-configure-firewall/azure-portal-firewall-all.png" alt-text="Screenshot showing how to configure the IP firewall in the Azure portal.":::
 
-1. Under **IP Firewall**, select **Add your client IP address** to create an inbound rule for the public IP address of your system. See [Allow access from the Azure portal IP address](#allow-access-from-the-azure-portal-ip-address) for details.
+1. Under **IP Firewall**, select **Add your client IP address** to create an inbound rule for the public IP address of your personal device. See [Allow access from the Azure portal IP address](#allow-access-from-the-azure-portal-ip-address) for details.
 
 1. Add other client IP addresses for other devices and services that send requests to a search service.