@@ -0,0 +1,609 @@
+---
+manager: nitinme
+author: KarlErickson
+ms.author: karler
+ms.service: azure-ai-search
+ms.topic: include
+ms.date: 08/08/2025
+---
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
+- An [Azure OpenAI resource](/azure/ai-services/openai/how-to/create-resource).
+  - [Choose a region](/azure/ai-services/openai/concepts/models?tabs=global-standard%2Cstandard-chat-completions#global-standard-model-availability) that supports the chat completion model you want to use (gpt-4o, gpt-4o-mini, or an equivalent model).
+  - [Deploy the chat completion model](/azure/ai-foundry/how-to/deploy-models-openai) in Azure AI Foundry or [use another approach](/azure/ai-services/openai/how-to/working-with-models).
+- An [Azure AI Search resource](../../search-create-service-portal.md).
+  - We recommend using the Basic tier or higher.
+  - [Enable semantic ranking](../../semantic-how-to-enable-disable.md).
+- [Visual Studio Code](https://code.visualstudio.com/download).
+- [Java 21 (LTS)](/java/openjdk/install).
+- [Maven](https://maven.apache.org/download.cgi).
+
+## Configure access
+
+Requests to the search endpoint must be authenticated and authorized. You can use API keys or roles for this task. Keys are easier to start with, but roles are more secure. This quickstart assumes roles.
+
+You're setting up two clients, so you need permissions on both resources.
+
+Azure AI Search receives the query request from your local system. Assign yourself the **Search Index Data Reader** role assignment if the hotels sample index already exists. If it doesn't exist, assign yourself **Search Service Contributor** and **Search Index Data Contributor** roles so that you can create and query the index.
+
+Azure OpenAI receives the query and the search results from your local system. Assign yourself the **Cognitive Services OpenAI User** role on Azure OpenAI.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+1. Configure Azure AI Search for role-based access:
+
+    1. In the Azure portal, find your Azure AI Search service.
+
+    1. On the left menu, select **Settings** > **Keys**, then select either **Role-based access control** or **Both**.
+
+1. Assign roles:
+
+    1. On the left menu, select **Access control (IAM)**.
+
+    1. On Azure AI Search, select these roles to create, load, and query a search index, then assign them to your Microsoft Entra ID user identity:
+
+       - **Search Index Data Contributor**
+       - **Search Service Contributor**
+
+    1. On Azure OpenAI, select **Access control (IAM)** to assign this role to yourself on Azure OpenAI:
+
+       - **Cognitive Services OpenAI User**
+
+It can take several minutes for permissions to take effect.
+
+## Create an index
+
+A search index provides grounding data for the chat model. We recommend the **hotels-sample-index**, which you can create in minutes and runs on any search service tier. This index uses built-in sample data.
+
+1. In the Azure portal, [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
+
+1. On the **Overview** home page, select [**Import data**](../../search-get-started-portal.md) to start the wizard.
+
+1. On the **Connect to your data** page, select **Samples** from the dropdown list.
+
+1. Choose the **hotels-sample**.
+
+1. Select **Next** through the remaining pages, accepting the default values.
+
+1. Once the index is created, select **Search management** > **Indexes** from the left menu to open the index.
+
+1. Select **Edit JSON**. 
+
+1. Scroll to the end of the index, where you find placeholders for constructs that you can add to an index.
+
+   ```json
+   "analyzers": [],
+   "tokenizers": [],
+   "tokenFilters": [],
+   "charFilters": [],
+   "normalizers": [],
+   ```
+
+1. On a new line after "normalizers", paste in the following semantic configuration. This example specifies a `"defaultConfiguration"`, which is important to the running of this quickstart.
+
+    ```json
+    "semantic":{
+       "defaultConfiguration":"semantic-config",
+       "configurations":[
+          {
+             "name":"semantic-config",
+             "prioritizedFields":{
+                "titleField":{
+                   "fieldName":"HotelName"
+                },
+                "prioritizedContentFields":[
+                   {
+                      "fieldName":"Description"
+                   }
+                ],
+                "prioritizedKeywordsFields":[
+                   {
+                      "fieldName":"Category"
+                   },
+                   {
+                      "fieldName":"Tags"
+                   }
+                ]
+             }
+          }
+       ]
+    },
+    ```
+
+1. **Save** your changes.
+
+1. Run the following query in [Search Explorer](../../search-explorer.md) to test your index: `complimentary breakfast`.
+
+   The output should look similar to the following example. Results that are returned directly from the search engine consist of fields and their verbatim values, along with metadata like a search score and a semantic ranking score and caption if you use semantic ranker. We used a [select statement](../../search-query-odata-select.md) to return just the HotelName, Description, and Tags fields.
+
+   ```
+   {
+   "@odata.count": 18,
+   "@search.answers": [],
+   "value": [
+      {
+         "@search.score": 2.2896252,
+         "@search.rerankerScore": 2.506816864013672,
+         "@search.captions": [
+         {
+            "text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
+            "highlights": ""
+         }
+         ],
+         "HotelName": "Head Wind Resort",
+         "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
+         "Tags": [
+         "coffee in lobby",
+         "free wifi",
+         "view"
+         ]
+      },
+      {
+         "@search.score": 2.2158256,
+         "@search.rerankerScore": 2.288334846496582,
+         "@search.captions": [
+         {
+            "text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
+            "highlights": ""
+         }
+         ],
+         "HotelName": "Swan Bird Lake Inn",
+         "Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
+         "Tags": [
+         "continental breakfast",
+         "free wifi",
+         "24-hour front desk service"
+         ]
+      },
+      {
+         "@search.score": 0.92481667,
+         "@search.rerankerScore": 2.221315860748291,
+         "@search.captions": [
+         {
+            "text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings..",
+            "highlights": ""
+         }
+         ],
+         "HotelName": "White Mountain Lodge & Suites",
+         "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.",
+         "Tags": [
+         "continental breakfast",
+         "pool",
+         "restaurant"
+         ]
+      },
+      . . .
+   ]}
+   ```
+
+## Get service endpoints
+
+In the following sections, you set up API calls to Azure OpenAI and Azure AI Search. Get the service endpoints so that you can provide them as variables in your code.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+1. [Find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
+
+1. On the **Overview** home page, copy the URL. An example endpoint might look like `https://example.search.windows.net`. 
+
+1. [Find your Azure OpenAI service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.CognitiveServices%2Faccounts).
+
+1. On the **Overview** home page, select the link to view the endpoints. Copy the URL. An example endpoint might look like `https://example.openai.azure.com/`.
+
+## Set up environment variables for local development
+
+Define environment variables by using the following commands. Replace the placeholders with your actual values.
+
+```bash
+export AZURE_SEARCH_ENDPOINT=<YOUR AZURE AI SEARCH ENDPOINT>
+export AZURE_SEARCH_INDEX_NAME=hotels-sample-index
+export AZURE_OPENAI_ENDPOINT=<YOUR AZURE OPENAI ENDPOINT>
+export AZURE_DEPLOYMENT_MODEL=<YOUR DEPLOYMENT NAME>
+```
+
+## Sign in to Azure
+
+You're using Microsoft Entra ID and role assignments for the connection. Make sure you're signed in to the same tenant and subscription as Azure AI Search and Azure OpenAI. You can use the Azure CLI on the command line to show current properties, change properties, and to sign in. For more information, see [Connect without keys](../../search-get-started-rbac.md). 
+
+Run each of the following commands in sequence.
+
+```azure-cli
+az account show
+
+az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>
+
+az login --tenant <PUT YOUR TENANT ID HERE>
+```
+
+You're now signed in to Azure from your local device.
+
+## Set up the Java project
+
+Set up a Maven project with the required dependencies.
+
+1. Create a new directory and navigate to it:
+
+   ```bash
+   mkdir rag-quickstart && cd rag-quickstart
+   ```
+
+1. Create a Maven project structure:
+
+   ```bash
+   mkdir -p src/main/java/com/example/rag
+   ```
+
+1. Create a `pom.xml` file with the following content:
+
+   ```xml
+   <?xml version="1.0" encoding="UTF-8"?>
+   <project xmlns="http://maven.apache.org/POM/4.0.0"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
+            http://maven.apache.org/xsd/maven-4.0.0.xsd">
+       <modelVersion>4.0.0</modelVersion>
+       
+       <groupId>com.example.rag</groupId>
+       <artifactId>rag-quickstart</artifactId>
+       <version>1.0-SNAPSHOT</version>
+       
+       <properties>
+           <maven.compiler.source>21</maven.compiler.source>
+           <maven.compiler.target>21</maven.compiler.target>
+           <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+       </properties>
+       
+       <dependencies>
+           <dependency>
+               <groupId>com.azure</groupId>
+               <artifactId>azure-search-documents</artifactId>
+               <version>11.7.8</version>
+           </dependency>
+           <dependency>
+               <groupId>com.azure</groupId>
+               <artifactId>azure-identity</artifactId>
+               <version>1.16.3</version>
+           </dependency>
+           <dependency>
+               <groupId>com.azure</groupId>
+               <artifactId>azure-ai-openai</artifactId>
+               <version>1.0.0-beta.16</version>
+           </dependency>
+       </dependencies>
+   </project>
+   ```
+
+## Set up query and chat thread
+
+Create a query script that uses the Azure AI Search index and the chat model to generate responses based on grounding data. The following steps guide you through setting up the query script.
+
+1. Create a `Query.java` file in the `src/main/java/com/example/rag` directory with the following code:
+
+    ```java
+    package com.example.rag;
+    
+    import com.azure.ai.openai.OpenAIClient;
+    import com.azure.ai.openai.OpenAIClientBuilder;
+    import com.azure.ai.openai.models.ChatCompletions;
+    import com.azure.ai.openai.models.ChatCompletionsOptions;
+    import com.azure.ai.openai.models.ChatRequestSystemMessage;
+    import com.azure.ai.openai.models.ChatRequestUserMessage;
+    import com.azure.identity.DefaultAzureCredentialBuilder;
+    import com.azure.search.documents.SearchClient;
+    import com.azure.search.documents.SearchClientBuilder;
+    import com.azure.search.documents.models.SearchOptions;
+    import com.azure.search.documents.models.SearchResult;
+    
+    import java.util.List;
+    
+    public class Query {
+        private static SearchClient getSearchClient() {
+            String searchEndpoint = System.getenv("AZURE_SEARCH_ENDPOINT");
+            String searchIndex = System.getenv("AZURE_SEARCH_INDEX_NAME");
+    
+            return new SearchClientBuilder()
+                    .endpoint(searchEndpoint)
+                    .indexName(searchIndex)
+                    .credential(new DefaultAzureCredentialBuilder().build())
+                    .buildClient();
+        }
+    
+        private static OpenAIClient getOpenAIClient() {
+            String openaiEndpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
+    
+            return new OpenAIClientBuilder()
+                    .endpoint(openaiEndpoint)
+                    .credential(new DefaultAzureCredentialBuilder().build())
+                    .buildClient();
+        }
+    
+        private static List<SearchResult> searchDocuments(
+            SearchClient searchClient, String query) {
+            var searchOptions = new SearchOptions()
+                    .setTop(5)
+                    .setQueryType(com.azure.search.documents.models.QueryType.SEMANTIC)
+                    .setSemanticSearchOptions(new com.azure.search.documents.models.SemanticSearchOptions()
+                            .setSemanticConfigurationName("semantic-config"))
+                    .setSelect("HotelName", "Description", "Tags");
+    
+            return searchClient.search(query, searchOptions, null)
+                    .stream()
+                    .limit(5)
+                    .toList();
+        }
+    
+        private static String queryOpenAI(OpenAIClient openAIClient,
+            String userQuery, List<SearchResult> sources) {
+            String deploymentModel = System.getenv("AZURE_DEPLOYMENT_MODEL");
+    
+            String sourcesText = sources.stream()
+                    .map(source -> source.getDocument(Object.class).toString())
+                    .collect(java.util.stream.Collectors.joining("\n"));
+    
+            var messages = List.of(
+                    new ChatRequestSystemMessage("""
+                        You are an assistant that recommends hotels based on 
+                        search results."""),
+                    new ChatRequestUserMessage("""
+                        Can you recommend a few hotels that offer %s?
+                        Here are the search results:
+                        %s""".formatted(userQuery, sourcesText))
+            );
+    
+            var chatOptions = new ChatCompletionsOptions(messages);
+            ChatCompletions response = openAIClient.getChatCompletions(deploymentModel, chatOptions);
+    
+            return response.getChoices().get(0).getMessage().getContent();
+        }
+    
+        public static void main(String[] args) {
+            SearchClient searchClient = getSearchClient();
+            OpenAIClient openAIClient = getOpenAIClient();
+    
+            String userQuery = "complimentary breakfast";
+            List<SearchResult> sources = searchDocuments(searchClient, userQuery);
+            String response = queryOpenAI(openAIClient, userQuery, sources);
+    
+            System.out.println(response);
+            System.exit(0);
+        }
+    }
+    ```
+
+    The preceding code does the following steps:
+    - Loads environment variables by using `System.getenv`.
+    - Configures Azure AI Search and Azure OpenAI clients by using role-based authentication.
+    - Queries Azure AI Search for hotels with complimentary breakfast by using semantic search.
+    - Sends the search results to Azure OpenAI as context for a chat completion.
+    - Prints the model's response.
+
+1. Run the following command in a terminal to execute the query script:
+
+    ```bash
+    mvn compile exec:java -Dexec.mainClass="com.example.rag.Query"
+    ```
+
+1. View the output, which consists of recommendations for several hotels. Here's an example of what the output might look like:
+
+    ```
+    Sure! Here are a few hotels that offer complimentary breakfast:
+
+    - **Head Wind Resort**
+    - Complimentary continental breakfast in the lobby
+    - Free Wi-Fi throughout the hotel
+
+    - **Double Sanctuary Resort**
+    - Continental breakfast included
+
+    - **White Mountain Lodge & Suites**
+    - Continental breakfast available
+
+    - **Swan Bird Lake Inn**
+    - Continental-style breakfast each morning with a variety of food and drinks 
+        such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
+        instant oatmeal, bagels, and muffins
+    ```
+
+## Troubleshooting
+
+If you get a **Forbidden** error message, check your Azure AI Search configuration to make sure you enable role-based access.
+
+If you get an **Authorization failed** error message, wait a few minutes and try again. It can take several minutes for role assignments to become operational.
+
+If you get a **Resource not found** error message, check the resource URIs and make sure the API version on the chat model is valid.
+
+Otherwise, to experiment further, change the query and rerun the last step to better understand how the model works with the grounding data.
+
+You can also modify the prompt to change the tone or structure of the output.
+
+You might also try the query without semantic ranking by removing the semantic search options in the query parameters step. Semantic ranking can noticeably improve the relevance of query results and the ability of the LLM to return useful information. Experimentation can help you decide whether it makes a difference for your content.
+
+## Send a complex RAG query
+
+Azure AI Search supports [complex types](../../search-howto-complex-data-types.md) for nested JSON structures. In the hotels-sample-index, `Address` is an example of a complex type, consisting of `Address.StreetAddress`, `Address.City`, `Address.StateProvince`, `Address.PostalCode`, and `Address.Country`. The index also has complex collection of `Rooms` for each hotel.
+
+If your index has complex types, change your prompt to include formatting instructions: 
+
+```text
+Can you recommend a few hotels that offer complimentary breakfast? 
+Tell me their description, address, tags, and the rate for one room that sleeps 4 people.
+```
+
+1. Create a new file `QueryComplex.java` in the `src/main/java/com/example/rag` directory.
+1. Copy the following code to the file:
+
+    ```java
+    package com.example.rag;
+    
+    import com.azure.ai.openai.OpenAIClient;
+    import com.azure.ai.openai.OpenAIClientBuilder;
+    import com.azure.ai.openai.models.ChatCompletions;
+    import com.azure.ai.openai.models.ChatCompletionsOptions;
+    import com.azure.ai.openai.models.ChatRequestSystemMessage;
+    import com.azure.ai.openai.models.ChatRequestUserMessage;
+    import com.azure.identity.DefaultAzureCredentialBuilder;
+    import com.azure.search.documents.SearchClient;
+    import com.azure.search.documents.SearchClientBuilder;
+    import com.azure.search.documents.models.SearchOptions;
+    import com.azure.search.documents.models.SearchResult;
+    
+    import java.util.List;
+    
+    public class QueryComplex {
+        private static SearchClient getSearchClient() {
+            String searchEndpoint = System.getenv("AZURE_SEARCH_ENDPOINT");
+            String searchIndex = System.getenv("AZURE_SEARCH_INDEX_NAME");
+    
+            return new SearchClientBuilder()
+                    .endpoint(searchEndpoint)
+                    .indexName(searchIndex)
+                    .credential(new DefaultAzureCredentialBuilder().build())
+                    .buildClient();
+        }
+    
+        private static OpenAIClient getOpenAIClient() {
+            String openaiEndpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
+    
+            return new OpenAIClientBuilder()
+                    .endpoint(openaiEndpoint)
+                    .credential(new DefaultAzureCredentialBuilder().build())
+                    .buildClient();
+        }
+    
+        private static List<SearchResult> searchDocuments(
+            SearchClient searchClient, String query) {
+            var searchOptions = new SearchOptions()
+                    .setTop(5)
+                    .setQueryType(com.azure.search.documents.models.QueryType.SEMANTIC)
+                    .setSemanticSearchOptions(new com.azure.search.documents.models.SemanticSearchOptions()
+                            .setSemanticConfigurationName("semantic-config"))
+                    .setSelect("HotelName", "Description", "Address", "Rooms", "Tags");
+    
+            return searchClient.search(query, searchOptions, null)
+                    .stream()
+                    .limit(5)
+                    .toList();
+        }
+    
+        private static String queryOpenAI(OpenAIClient openAIClient,
+            String userQuery, List<SearchResult> sources) {
+            String deploymentModel = System.getenv("AZURE_DEPLOYMENT_MODEL");
+    
+            String sourcesText = sources.stream()
+                    .map(source -> source.getDocument(Object.class).toString())
+                    .collect(java.util.stream.Collectors.joining("\n"));
+    
+            var messages = List.of(
+                    new ChatRequestSystemMessage("""
+                        You are an assistant that recommends hotels based on 
+                        search results."""),
+                    new ChatRequestUserMessage("""
+                        Can you recommend a few hotels that offer %s?
+                        Tell me their description, address, tags,
+                        and the rate for one room that sleeps 4 people.
+                        Here are the search results:
+                        %s""".formatted(userQuery, sourcesText))
+            );
+    
+            var chatOptions = new ChatCompletionsOptions(messages);
+            ChatCompletions response = openAIClient.getChatCompletions(
+                deploymentModel, chatOptions);
+    
+            return response.getChoices().get(0).getMessage().getContent();
+        }
+    
+        public static void main(String[] args) {
+            SearchClient searchClient = getSearchClient();
+            OpenAIClient openAIClient = getOpenAIClient();
+    
+            String userQuery = "complimentary breakfast";
+            List<SearchResult> sources = searchDocuments(searchClient, userQuery);
+            String response = queryOpenAI(openAIClient, userQuery, sources);
+    
+            System.out.println(response);
+            System.exit(0);
+        }
+    }
+    ```
+
+1. Run the following command in a terminal to execute the query script:
+
+    ```bash
+    mvn compile exec:java -Dexec.mainClass="com.example.rag.QueryComplex"
+    ```
+
+1. View the output from Azure OpenAI, and it adds content from complex types.
+
+    ```
+    Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:
+
+    1. **Head Wind Resort**
+       - **Description:** The best of old town hospitality combined with views of the river and 
+       cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
+       and free Wi-Fi throughout the hotel.
+       - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
+       - **Tags:** Coffee in lobby, free Wi-Fi, view
+       - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99
+
+    2. **Double Sanctuary Resort**
+       - **Description:** 5-star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area 
+       listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso 
+       in room. Offers continental breakfast.
+       - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
+       - **Tags:** View, pool, restaurant, bar, continental breakfast
+       - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99
+
+    3. **Swan Bird Lake Inn**
+       - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
+       Locally made caramel cinnamon rolls are a favorite.
+       - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
+       - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
+       - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99
+
+    4. **Gastronomic Landscape Hotel**
+       - **Description:** Known for its culinary excellence under the management of William Dough, 
+       offers continental breakfast.
+       - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
+       - **Tags:** Restaurant, bar, continental breakfast
+       - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
+    ...
+       - **Tags:** Pool, continental breakfast, free parking
+       - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99
+
+    Enjoy your stay! Let me know if you need any more information.
+    ```
+
+## Troubleshooting errors
+
+To debug Azure SDK errors, enable logging by adding the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>org.slf4j</groupId>
+    <artifactId>slf4j-simple</artifactId>
+    <version>2.0.7</version>
+</dependency>
+```
+
+Then set the following system properties when running your application:
+
+```bash
+mvn compile exec:java -Dexec.mainClass="com.example.rag.Query" \
+    -Dorg.slf4j.simpleLogger.defaultLogLevel=debug
+```
+
+This configuration enables detailed logging for the Azure SDK, which can help you identify [issues with authentication](https://github.com/Azure/azure-sdk-for-java/wiki/Azure-Identity-Troubleshooting), network connectivity, or other problems.
+
+Rerun the query script. You should now see informational statements from the SDKs in the output that provide more detail about any issues.
+
+If you see output messages related to `ManagedIdentityCredential` and token acquisition failures, it might be that you have multiple tenants, and your Azure sign-in uses a tenant that doesn't have your search service. To get your tenant ID, search the Azure portal for "tenant properties" or run `az login tenant list`.
+
+After you get your tenant ID, run `az login --tenant <YOUR-TENANT-ID>` at a command prompt, then rerun the script.
+
+## Clean up
+
+When you're working in your own subscription, it's a good idea at the end of a project to check if you still need the resources you created. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.
+
+You can find and manage resources in the Azure portal by using the **All resources** or **Resource groups** link in the leftmost pane.

@@ -23,6 +23,12 @@ In this quickstart, you send queries to a chat completion model for a conversati
 
 ::: zone-end
 
+::: zone pivot="java"
+
+[!INCLUDE [Java quickstart](includes/quickstarts/search-get-started-rag-java.md)]
+
+::: zone-end
+
 ::: zone pivot="javascript"
 
 [!INCLUDE [JavaScript quickstart](includes/quickstarts/search-get-started-rag-javascript.md)]

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 07/11/2025
+ms.date: 08/08/2025
 ms.custom:
   - devx-track-csharp
   - ignite-2023
@@ -32,6 +32,8 @@ Every time you update a resource, its ETag changes automatically. When you imple
 > [!Note]
 > There is only one mechanism for concurrency. It's always used regardless of which API or SDK is used for resource updates.
 
+Starting July 18, 2025, Azure AI Search began enforcing serialization for index creation and update operations to ensure consistency and reliability. This change aligns with long-standing best practices and the established behavior of the rest of operations in the service. As the rollout progresses across regions, you may begin seeing 409 conflict errors when sending concurrent or closely timed requests. To avoid these errors, ensure operations are not sent in parallel and follow the concurrency guidance outlined in this document.
+
 ## Example
 
 The following code demonstrates optimistic concurrency for an update operation. It fails the second update because the object's ETag is changed by a previous update. More specifically, when the ETag in the request header no longer matches the ETag of the object, the search service return a status code of 400 (bad request), and the update fails.