Merge pull request #263528 from HeidiSteen/heidist-jan

[azure search] January refresh #5

Author: v-dirichards

articles/search/TOC.yml

@@ -13,12 +13,12 @@
     href: search-faq-frequently-asked-questions.yml
 - name: Quickstarts
   items:
+  - name: Vector search
+    href: search-get-started-vector.md
   - name: Full text search
     href: search-get-started-text.md
   - name: Semantic ranking
     href: search-get-started-semantic.md
-  - name: Vector search
-    href: search-get-started-vector.md
   - name: Portal
     items:
     - name: Create an index
@@ -232,14 +232,6 @@
       href: search-how-to-create-search-index.md
     - name: Create an index alias
       href: search-how-to-alias.md
-    - name: Create a vector index
-      href: vector-search-how-to-create-index.md
-    - name: Configure a vectorizer (vectors)
-      href: vector-search-how-to-configure-vectorizer.md
-    - name: Chunk documents (vectors)
-      href: vector-search-how-to-chunk-documents.md
-    - name: Generate embeddings (vectors)
-      href: vector-search-how-to-generate-embeddings.md
     - name: Load an index
       href: search-how-to-load-search-index.md
     - name: Index large data sets
@@ -254,6 +246,17 @@
       href: search-howto-complex-data-types.md
     - name: Model relational data
       href: index-sql-relational-data.md
+  - name: Vector stores
+    items:
+    - name: Create a vector index
+      href: vector-search-how-to-create-index.md
+    - name: Configure a vectorizer (vectors)
+      href: vector-search-how-to-configure-vectorizer.md
+    - name: Chunk documents (vectors)
+      href: vector-search-how-to-chunk-documents.md
+    - name: Generate embeddings (vectors)
+      href: vector-search-how-to-generate-embeddings.md
+
   - name: Analyzers
     items:
     - name: Add a language analyzer
@@ -366,19 +369,19 @@
         href: cognitive-search-custom-skill-scale.md
       - name: Example - Bing Entity Search
         href: cognitive-search-create-custom-skill-example.md
-    - name: Knowledge store
-      items:
-      - name: Create using REST
-        href: knowledge-store-create-rest.md
-      - name: Shaping data
-        href: knowledge-store-projection-shape.md
-      - name: Define projections
-        href: knowledge-store-projections-examples.md 
-      - name: Projection example
-        href: knowledge-store-projection-example-long.md
-      - name: Connect with Power BI
-        href: knowledge-store-connect-power-bi.md
-  - name: Queries
+  - name: Knowledge stores
+    items:
+    - name: Create using REST
+      href: knowledge-store-create-rest.md
+    - name: Shaping data
+      href: knowledge-store-projection-shape.md
+    - name: Define projections
+      href: knowledge-store-projections-examples.md 
+    - name: Projection example
+      href: knowledge-store-projection-example-long.md
+    - name: Connect with Power BI
+      href: knowledge-store-connect-power-bi.md
+  - name: Queries (text and vector)
     items:
     - name: Full text query
       href: search-query-create.md
@@ -438,7 +441,7 @@
       href: performance-benchmarks.md
     - name: Tips for better performance
       href: search-performance-tips.md
-    - name: Monitoring Azure AI Search
+    - name: Monitor Azure AI Search
       href: monitor-azure-cognitive-search.md
     - name: Visualize resource logs
       href: search-monitor-logs-powerbi.md
@@ -617,7 +620,7 @@
         href: cognitive-search-skill-sentiment-v3.md
       - name: Text Translation
         href: cognitive-search-skill-text-translation.md
-    - name: Azure AI Search utility skills (non-billable)
+    - name: Azure AI Search utility skills (nonbillable)
       items:
       - name: Conditional
         href: cognitive-search-skill-conditional.md

articles/search/cognitive-search-concept-annotations-syntax.md

@@ -1,45 +1,44 @@
 ---
-title: Reference inputs and outputs in skillsets
+title: Reference enriched nodes during skillset execution
 titleSuffix: Azure AI Search
 description: Explains the annotation syntax and how to reference inputs and outputs of a skillset in an AI enrichment pipeline in Azure AI Search.
 author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.custom:
   - ignite-2023
-ms.topic: conceptual
-ms.date: 09/16/2022
+ms.topic: how-to
+ms.date: 01/18/2024
 ---
-# Reference an annotation in an Azure AI Search skillset
 
-In this article, you'll learn how to reference *annotations* (or an enrichment node) in skill definitions, using examples to illustrate various scenarios. 
+# Reference a path to enriched nodes using context and source properties an Azure AI Search skillset
 
-Skills read inputs and write outputs to nodes in an [enriched document](cognitive-search-working-with-skillsets.md#enrichment-tree) tree, building the tree as the enrichments progress. Any node can be referenced in an input for further downstream enrichment, or mapped to an output field in an index. This article introduces the syntax and provides examples for specifying a path to a node. For the full syntax, see [Skill context and input annotation language language](cognitive-search-skill-annotation-language.md).
+During skillset execution, the engine builds an in-memory [enrichment tree](cognitive-search-working-with-skillsets.md#enrichment-tree) that captures each enrichment, such as recognized entities or translated text. In this article, learn how to reference an enrichment node in the enrichment tree so that you can pass output to downstream skills or specify an output field mapping for a search index field. 
 
-Paths to an annotation are specified in the "context" and "source" properties of a skillset, and in [output field mappings](cognitive-search-output-field-mapping.md) in an indexer. Here's an example of what paths might look like in a skillset:
-
-:::image type="content" source="media/cognitive-search-annotations-syntax/content-source-annotation-path.png" alt-text="Screenshot of a skillset definition with context and source elements highlighted.":::
-
-The example in the screenshot illustrates the path for an item in an Azure Cosmos DB collection.
-
-+ "context" path is `/document/HotelId` because the collection is partitioned into documents by the `/HotelId` field.
-
-+ "source" path is `/document/Description` because the skill is a translation skill, and the field that you'll want the skill to translate is the `Description` field in each document.
+This article uses examples to illustrate various scenarios. For the full syntax, see [Skill context and input annotation language language](cognitive-search-skill-annotation-language.md).
 
 ## Background concepts
 
 Before reviewing the syntax, let's revisit a few important concepts to better understand the examples provided later in this article.
 
 | Term | Description |
 |------|-------------|
-| "enriched document" | An enriched document is an internal structure that collects skill output as it's created and it holds all annotations related to a document. Think of an enriched document as a tree of annotations. Generally, an annotation created from a previous annotation becomes its child. </p>Enriched documents only exist for the duration of skillset execution. Once content is mapped to the search index, the enriched document is no longer needed. Although you don't interact with enriched documents directly, it's useful to have a mental model of the documents when creating a skillset. |
-| "annotation" | Within an enriched document, a node that is created and populated by a skill, such as "text" and "layoutText" in the OCR skill, is called an annotation. An enriched document is populated with both annotations and unchanged field values or metadata copied from the source. |
+| "enriched document" | An enriched document is an in-memory structure that collects skill output as it's created and it holds all enrichments related to a document. Think of an enriched document as a tree. Generally, the tree starts at the root document level, and each new enrichment is created from a previous as its child.  |
+| "node" | Within an enriched document, a node (sometimes referred to as an "annotation") is created and populated by a skill, such as "text" and "layoutText" in the OCR skill. An enriched document is populated with both enrichments and original source field values or metadata copied from the source. |
 | "context" | The scope of enrichment, which is either the entire document, a portion of a document, or if you're working with images, the extracted images from a document. By default, the enrichment context is at the `"/document"` level, scoped to individual documents contained in the data source. When a skill runs, the outputs of that skill become [properties of the defined context](#example-2). |
 
 ## Paths for different scenarios
 
 Paths are specified in the "context" and "source" properties of a skillset, and in the [output field mappings](cognitive-search-output-field-mapping.md) in an indexer.
 
+:::image type="content" source="media/cognitive-search-annotations-syntax/content-source-annotation-path.png" alt-text="Screenshot of a skillset definition with context and source elements highlighted.":::
+
+The example in the screenshot illustrates the path for an item in an Azure Cosmos DB collection.
+
++ `context` path is `/document/HotelId` because the collection is partitioned into documents by the `/HotelId` field.
+
++ `source` path is `/document/Description` because the skill is a translation skill, and the field that you'll want the skill to translate is the `Description` field in each document.
+
 All paths start with `/document`. An enriched document is created in the "document cracking" stage of indexer execution, when the indexer opens a document or reads in a row from the data source. Initially, the only node in an enriched document is the [root node (`/document`)](cognitive-search-skill-annotation-language.md#document-root), and it's the node from which all other enrichments occur. 
 
 The following list includes several common examples:
@@ -57,7 +56,7 @@ Examples in the remainder of this article are based on the "content" field gener
 
 ## Example 1: Simple annotation reference
 
-In Azure Blob Storage, suppose you have a variety of files containing references to people's names that you want to extract using entity recognition. In the skill definition below, `"/document/content"` is the textual representation of the entire document, and "people" is an extraction of full names for entities identified as persons.
+In Azure Blob Storage, suppose you have a variety of files containing references to people's names that you want to extract using entity recognition. In the following skill definition, `"/document/content"` is the textual representation of the entire document, and "people" is an extraction of full names for entities identified as persons.
 
 Because the default context is `"/document"`, the list of people can now be referenced as `"/document/people"`. In this specific case `"/document/people"` is an annotation, which could now be mapped to a field in an index, or used in another skill in the same skillset.
 

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

@@ -117,7 +117,7 @@ Enriched documents are internal, but a debug session gives you access to the con
 
 If the field mappings are correct, check individual skills for configuration and content. If a skill fails to produce output, it might be missing a property or parameter, which can be determined through error and validation messages. 
 
-Other issues, such as an invalid context or input expression, can be harder to resolve because the error will tell you what is wrong, but not how to fix it. For help with context and input syntax, see [Reference annotations in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md#background-concepts). For help with individual messages, see [Troubleshooting common indexer errors and warnings](cognitive-search-common-errors-warnings.md).
+Other issues, such as an invalid context or input expression, can be harder to resolve because the error will tell you what is wrong, but not how to fix it. For help with context and input syntax, see [Reference enrichments in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md#background-concepts). For help with individual messages, see [Troubleshooting common indexer errors and warnings](cognitive-search-common-errors-warnings.md).
 
 The following steps show you how to get information about a skill.
 
@@ -203,7 +203,7 @@ You can edit the skill definition in the portal.
 
 ### Test your code
 
-At this point, new requests from your debug session should now be sent to your local Azure Function. You can use breakpoints in your Visual Studio code to debug your code or run step by step.
+At this point, new requests from your debug session should now be sent to your local Azure Function. You can use breakpoints in your Visual Studio Code to debug your code or run step by step.
 
 ## Next steps
 

articles/search/cognitive-search-output-field-mapping.md

@@ -58,7 +58,7 @@ Output field mappings are added to the `outputFieldMappings` array in an indexer
 
 | Property | Description |
 |----------|-------------|
-| sourceFieldName | Required. Specifies a path to enriched content. An example might be `/document/content`. See [Reference annotations in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md) for path syntax and examples. |
+| sourceFieldName | Required. Specifies a path to enriched content. An example might be `/document/content`. See [Reference enrichments in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md) for path syntax and examples. |
 | targetFieldName | Optional. Specifies the search field that receives the enriched content. Target fields must be top-level simple fields or collections. It can't be a path to a subfield in a complex type. If you want to retrieve specific nodes in a complex structure, you can [flatten individual nodes](#flattening-information-from-complex-types) in memory, and then send the output to a string collection in your index. |
 | mappingFunction | Optional. Adds extra processing provided by [mapping functions](search-indexer-field-mappings.md#mappingFunctions) supported by indexers. In the case of enrichment nodes, encoding and decoding are the most commonly used functions. |
 

articles/search/cognitive-search-skill-annotation-language.md

@@ -269,4 +269,4 @@ Parentheses can be used to change or disambiguate evaluation order.
 
 ## See also
 + [Create a skillset in Azure AI Search](cognitive-search-defining-skillset.md)
-+ [Reference annotations in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md)
++ [Reference enrichments in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md)

articles/search/cognitive-search-working-with-skillsets.md

@@ -64,7 +64,7 @@ Skills can execute independently and in parallel, or sequentially if you feed th
 
 + Skill #2 is a [Sentiment Detection skill](cognitive-search-skill-sentiment.md) accepts "pages" as input, and produces a new field called "Sentiment" as output that contains the results of sentiment analysis.
 
-Notice how the output of the first skill ("pages") is used in sentiment analysis, where "/document/reviews_text/pages/*" is both the context and input. For more information about path formulation, see [How to reference annotations](cognitive-search-concept-annotations-syntax.md).
+Notice how the output of the first skill ("pages") is used in sentiment analysis, where "/document/reviews_text/pages/*" is both the context and input. For more information about path formulation, see [How to reference enrichments](cognitive-search-concept-annotations-syntax.md).
 
 ```json
 {
@@ -222,7 +222,7 @@ The enrichment tree now has a new node placed under the context of the skill. Th
 
 ![enrichment tree after skill #1](media/cognitive-search-working-with-skillsets/enrichment-tree-skill1.png "Enrichment tree after  skill #1 executes")
 
-To access any of the enrichments added to a node by a skill, the full path for the enrichment is needed. For example, if you want to use the text from the ```pages``` node as an input to another skill, you'll need to specify it as ```"/document/reviews_text/pages/*"```. For more information about paths, see [Reference annotations](cognitive-search-concept-annotations-syntax.md).
+To access any of the enrichments added to a node by a skill, the full path for the enrichment is needed. For example, if you want to use the text from the ```pages``` node as an input to another skill, you'll need to specify it as ```"/document/reviews_text/pages/*"```. For more information about paths, see [Reference enrichments](cognitive-search-concept-annotations-syntax.md).
 
 ### Skill #2 Language detection