Added example

Author: HeidiSteen

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 large schema changes on 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.
 
 ## 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.
++ For updating 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.
+
++ For merging 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 is 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": "I'm changing the description and city for Secret Point Hotel, and keeping 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
 

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.
 

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-data-import-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.