Merge pull request #281442 from HeidiSteen/heidist-freshness

[azure search] July freshness pass #1

Author: v-dirichards

articles/search/cognitive-search-debug-session.md

@@ -10,59 +10,53 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 09/29/2023
+ms.date: 07/21/2024
 ---
 
 # Debug Sessions in Azure AI Search
 
-Debug Sessions is a visual editor that works with an existing skillset in the Azure portal, exposing the structure and content of a single enriched document, as it's produced by an indexer and skillset for the duration of the session. Because you're working with a live document, the session is interactive - you can identify errors, modify and invoke skill execution, and validate the results in real time. If your changes resolve the problem, you can commit them to a published skillset to apply the fixes globally.
+Debug Sessions is a visual editor that works with an existing skillset in the Azure portal, exposing the structure and content of a single enriched document as it's produced by an indexer and skillset for the duration of the session. Because you're working with a live document, the session is interactive - you can identify errors, modify and invoke skill execution, and validate the results in real time. If your changes resolve the problem, you can commit them to a published skillset to apply the fixes globally.
 
-## How a debug session works
-
-When you start a session, the search service creates a copy of the skillset, indexer, and a data source containing a single document used to test the skillset. All session state is saved to a new blob container created by the Azure AI Search service in an Azure Storage account that you provide. The name of the generated container has a prefix of "ms-az-cognitive-search-debugsession". The prefix is required because it mitigates the chance of accidentally exporting session data to another container in your account. 
-
-A cached copy of the enriched document and skillset is loaded into the visual editor so that you can inspect the content and metadata of the enriched document, with the ability to check each document node and edit any aspect of the skillset definition. Any changes made within the session are cached. Those changes will not affect the published skillset unless you commit them. Committing changes will overwrite the production skillset.
+This article explains how the editor is organized. Tabs and sections of the editor unpack different layers of the skillset so that you can examine skillset structure, flow, and the content it generates at run time.
 
-If the enrichment pipeline does not have any errors, a debug session can be used to incrementally enrich a document, test and validate each change before committing the changes.
+## How a debug session works
 
-## Managing the Debug Session state
+When you start a session, the search service creates a copy of the skillset, indexer, and a data source containing a single document used to test the skillset. All session state is saved to a new blob container created by the Azure AI Search service in an Azure Storage account that you provide. The name of the generated container has a prefix of `ms-az-cognitive-search-debugsession`. The prefix is required because it mitigates the chance of accidentally exporting session data to another container in your account. 
 
-You can rerun a debug session using the **Start** button, or cancel an in-progress session using the **Cancel** button.
+A cached copy of the enriched document and skillset is loaded into the visual editor so that you can inspect the content and metadata of the enriched document, with the ability to check each document node and edit any aspect of the skillset definition. Any changes made within the session are cached. Those changes won't affect the published skillset unless you commit them. Committing changes will overwrite the production skillset.
 
-:::image type="content" source="media/cognitive-search-debug/debug-session-commands.png" alt-text="Screenshot of the Debug Session control buttons." border="true":::
+If the enrichment pipeline doesn't have any errors, a debug session can be used to incrementally enrich a document, test and validate each change before committing the changes.
 
 ## AI Enrichments tab > Skill Graph
 
 The visual editor is organized into tabs and panes. This section introduces the components of the visual editor.
 
 The **Skill Graph** provides a visual hierarchy of the skillset and its order of execution from top to bottom. Skills that are dependent upon the output of other skills are positioned lower in the graph. Skills at the same level in the hierarchy can execute in parallel. Color coded labels of skills in the graph indicate the types of skills that are being executed in the skillset (TEXT or VISION).
 
-Selecting a skill in the graph will display the details of that instance of the skill in the right pane, including its definition, errors or warnings, and execution history. The **Skill Graph** is where you will select which skill to debug or enhance. The details pane to the right is where you edit and explore.
+The **Skill Graph** is where you select which skill to debug or enhance. The details pane to the right is where you edit and explore.
 
 :::image type="content" source="media/cognitive-search-debug/skills-graph.png" alt-text="Screenshot of Skills Graph tab." border="true":::
 
 ### Skill details pane
 
-When you select an object in the **Skill Graph**, the adjacent pane provides interactive work areas in a tabbed layout. An illustration of the details pane can be found in the previous screenshot.
-
-Skill details include the following areas:
+Skill details are presented in a tabbed layout and include the following areas:
 
-+ **Skill Settings** shows a formatted version of the skill definition.
-+ **Skill JSON Editor** shows the raw JSON document of the definition.
-+ **Executions** shows the data corresponding to each time a skill was executed.
-+ **Errors and warnings** shows the messages generated upon session start or refresh.
++ **Skill Settings**: a formatted version of the skill definition.
++ **Skill JSON Editor**: the raw JSON document of the definition.
++ **Executions**: the data corresponding to each time a skill was executed.
++ **Errors and warnings**: the messages generated upon session start or refresh.
 
 On Executions or Skill Settings, select the **`</>`** symbol to open the [**Expression Evaluator**](#expression-evaluator) used for viewing and editing the expressions of the skills inputs and outputs.
 
 Nested input controls in Skill Settings can be used to build complex shapes for [projections](knowledge-store-projection-overview.md), [output field mappings](cognitive-search-output-field-mapping.md) for a complex type field, or an input to a skill. When used with the Expression Evaluator, nested inputs provide an easy test and validate expression builder.
 
 ### Executions pane
 
-A skill can execute multiple times in a skillset for a single document. For example, the OCR skill will execute once for each image extracted from a single document. The Executions pane displays the skill's execution history providing a deeper look into each invocation of the skill. 
+A skill can execute multiple times in a skillset for a single document. For example, the OCR skill executes once for each image extracted from a single document. The Executions pane displays the skill's execution history providing a deeper look into each invocation of the skill. 
 
 The execution history enables tracking a specific enrichment back to the skill that generated it. Clicking on a skill input navigates to the skill that generated that input, providing a stack-trace like feature. This allows identification of the root cause of a problem that might manifest in a downstream skill. 
 
-When you debug an error with a custom skill, there is the option to generate a request for a skill invocation in the execution history.
+When you debug an error with a custom skill, there's the option to generate a request for a skill invocation in the execution history.
 
 ## AI Enrichments tab > Enriched Data Structure
 
@@ -72,9 +66,9 @@ The **Enriched Data Structure** pane shows the document's enrichments through th
 
 ## Expression Evaluator
 
-**Expression Evaluator** gives a quick peek into the value of any path. It allows for editing the path and testing the results before updating any of the inputs or context for a skill or projection.
+**Expression Evaluator** shows the executable elements of the kil. It allows for editing the path and testing the results before updating any of the inputs or context for a skill or projection.
 
-You can open the window from any node or element that shows the **`</>`** symbol, including parts of a dependency graph or nodes in an enrichment tree.
+You can open the evaluator from any node or element that shows the **`</>`** symbol, including parts of a dependency graph or nodes in an enrichment tree.
 
 Expression Evaluator gives you full interactive access for testing skill context, inputs, and checking outputs.
 

articles/search/cognitive-search-how-to-debug-skillset.md

@@ -10,14 +10,14 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 01/10/2024
+ms.date: 07/22/2024
 ---
 
 # Debug an Azure AI Search skillset in Azure portal
 
-Start a portal-based debug session to identify and resolve errors, validate changes, and push changes to a published skillset in your Azure AI Search service.
+Start a portal-based debug session to identify and resolve errors, validate changes, and push changes to an existing skillset in your Azure AI Search service.
 
-A debug session is a cached indexer and skillset execution, scoped to a single document, that you can use to edit and test your changes interactively. When you're finished debugging, you can save your changes to the skillset. 
+A debug session is a cached indexer and skillset execution, scoped to a single document, that you can use to edit and test skillset changes interactively. When you're finished debugging, you can save your changes to the skillset. 
 
 For background on how a debug session works, see [Debug sessions in Azure AI Search](cognitive-search-debug-session.md). To practice a debug workflow with a sample document, see [Tutorial: Debug sessions](cognitive-search-tutorial-debug-sessions.md).
 
@@ -35,7 +35,7 @@ For background on how a debug session works, see [Debug sessions in Azure AI Sea
 
 ## Limitations
 
-Debug sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources. The following list notes the exceptions:
+Debug sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources, with the following exceptions:
 
 + Azure Cosmos DB for MongoDB is currently not supported.
 
@@ -51,15 +51,15 @@ The portal doesn't support customer-managed key encryption (CMK), which means th
 
 1. Sign in to the [Azure portal](https://portal.azure.com) and find your search service.
 
-1. In the left navigation page, select **Debug sessions**.
+1. In the left menu, select **Search management** > **Debug sessions**.
 
 1. In the action bar at the top, select **Add debug session**.
 
    :::image type="content" source="media/cognitive-search-debug/new-debug-session.png" alt-text="Screenshot of the debug sessions commands in the portal page." border="true":::
 
 1. In **Debug session name**, provide a name that will help you remember which skillset, indexer, and data source the debug session is about.
 
-1. In **Storage connection**, find a general-purpose storage account for caching the debug session. You'll be prompted to select and optionally create a blob container in Blob Storage or Azure Data Lake Storage Gen2. You can reuse the same container for all subsequent debug sessions you create. A helpful container name might be "cognitive-search-debug-sessions".
+1. In **Storage connection**, find a general-purpose storage account for caching the debug session. You're prompted to select and optionally create a blob container in Blob Storage or Azure Data Lake Storage Gen2. You can reuse the same container for all subsequent debug sessions you create. An obvious container name might be "debug-sessions".
 
 1. In **Managed identity authentication**, choose **None** if the connection to Azure Storage doesn't use a managed identity. Otherwise, choose the managed identity to which you've granted **Storage Blob Data Contributor** permissions.
 
@@ -77,7 +77,7 @@ The portal doesn't support customer-managed key encryption (CMK), which means th
 
    :::image type="content" source="media/cognitive-search-debug/debug-session-new.png" alt-text="Screenshot of a debug session page." border="true":::
 
-The debug session begins by executing the indexer and skillset on the selected document. The document's content and metadata created will be visible and available in the session.
+The debug session begins by executing the indexer and skillset on the selected document. The document's content and metadata are visible and available in the session.
 
 A debug session can be canceled while it's executing using the **Cancel** button. If you hit the **Cancel** button you should be able to analyze partial results.
 

articles/search/includes/quickstarts/javascript.md

@@ -129,7 +129,7 @@ With that in place, we're ready to create an index.
 
 Create a file **hotels_quickstart_index.json**.  This file defines how Azure AI Search works with the documents you'll be loading in the next step. Each field will be identified by a `name` and have a specified `type`. Each field also has a series of index attributes that specify whether Azure AI Search can search, filter, sort, and facet upon the field. Most of the fields are simple data types, but some, like `AddressType` are complex types that allow you to create rich data structures in your index.  You can read more about [supported data types](/rest/api/searchservice/supported-data-types) and index attributes described in [Create Index (REST)](/rest/api/searchservice/create-index). 
 
-Add the following content to **hotels_quickstart_index.json** or [download the file](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/main/quickstart/v11/hotels_quickstart_index.json). 
+Add the following content to **hotels_quickstart_index.json** or [download the file](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/main/quickstart/hotels_quickstart_index.json). 
 
 ```json
 {
@@ -316,7 +316,7 @@ At this point, you're ready to run the sample. Use a terminal window to run the
 node index.js
 ```
 
-If you [downloaded the source code](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart/v11) and haven't installed the required packages yet, run `npm install` first.
+If you [downloaded the source code](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart) and haven't installed the required packages yet, run `npm install` first.
 
 You should see a series of messages describing the actions being taken by the program. 
 
@@ -331,7 +331,7 @@ In the next step, you'll add data to index.
 
 In Azure AI Search, documents are data structures that are both inputs to indexing and outputs from queries. You can push such data to the index or use an [indexer](/azure/search/search-indexer-overview). In this case, we'll programatically push the documents to the index.
 
-Document inputs might be rows in a database, blobs in Blob storage, or, as in this sample, JSON documents on disk. You can either download [hotels.json](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/main/quickstart/v11/hotels.json) or create your own **hotels.json** file with the following content:
+Document inputs might be rows in a database, blobs in Blob storage, or, as in this sample, JSON documents on disk. You can either download [hotels.json](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/main/quickstart/hotels.json) or create your own **hotels.json** file with the following content:
 
 ```json
 {

articles/search/index-ranking-similarity.md

@@ -8,7 +8,7 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 09/25/2023
+ms.date: 07/22/2024
 ---
 
 # Configure BM25 relevance scoring

articles/search/resource-demo-sites.md

@@ -9,17 +9,16 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 09/18/2023
+ms.date: 07/22/2024
 ---
 
 # Demos - Azure AI Search
 
-Demos are hosted apps that showcase search and AI enrichment functionality in Azure AI Search. Several of these demos include source code on GitHub so that you can see how they were made.
+Demos are hosted apps that showcase search and AI enrichment functionality in Azure AI Search. Demos sometimes include source code on GitHub so that you can see how they were made.
 
-Microsoft built and hosts the following demos.
+The Azure AI Search currently builds and hosts the following demos.
 
 | Demo name | Description | Source code |
 |-----------|------------ |-------------|
 | [Chat with your data](https://entgptsearch.azurewebsites.net/) | An Azure web app that uses ChatGPT in Azure OpenAI with fictitious health plan data in a search index. | [https://github.com/Azure-Samples/azure-search-openai-demo/](https://github.com/Azure-Samples/azure-search-openai-demo/)  |
-| [JFK files demo](https://jfk-demo-2019.azurewebsites.net/#/) | An ASP.NET web app built on a public data set, transformed with custom and predefined skills to extract searchable content from scanned document (JPEG) files. [Learn more...](https://www.microsoft.com/ai/ai-lab-jfk-files) | [https://github.com/Microsoft/AzureSearch_JFK_Files](https://github.com/Microsoft/AzureSearch_JFK_Files) |
 | [Semantic ranking for retail](https://brave-meadow-0f59c9b1e.1.azurestaticapps.net/) | Web app for a fictitious online retailer, "Terra" | Not available |

articles/search/samples-javascript.md

@@ -58,7 +58,7 @@ Code samples from the Azure AI Search team demonstrate features and workflows. M
 
 | Samples | Article |
 |---------|---------|
-| [quickstart](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart/v11) | Source code for the JavaScript portion of [Quickstart: Full text search using the Azure SDKs](search-get-started-text.md). Covers the basic workflow for creating, loading, and querying a search index using sample data. |
+| [quickstart](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart) | Source code for the JavaScript portion of [Quickstart: Full text search using the Azure SDKs](search-get-started-text.md). Covers the basic workflow for creating, loading, and querying a search index using sample data. |
 | [search-website](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/search-website-functions-v4) | Source code for [Tutorial: Add search to web apps](tutorial-javascript-overview.md). Demonstrates an end-to-end search app that includes a rich client plus components for hosting the app and handling search requests.|
 
 > [!TIP]