You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This article explains how to set up *output field mappings*, defining a data path between in-memory data structures created during [skillset processing](cognitive-search-concept-intro.md), and target fields in a search index. An output field mapping is defined in an [indexer](search-indexer-overview.md) and has the following elements:
18
+
This article explains how to set up *output field mappings*, defining a data path between in-memory data generated during [skillset processing](cognitive-search-concept-intro.md), and target fields in a search index. During indexer execution, skills-generated information exists in memory only. To persist this information in a search index, you need to tell the indexer where to send the data.
19
+
20
+
An output field mapping is defined in an [indexer](search-indexer-overview.md) and has the following elements:
19
21
20
22
```json
21
23
"outputFieldMappings": [
@@ -27,83 +29,110 @@ This article explains how to set up *output field mappings*, defining a data pat
27
29
],
28
30
```
29
31
30
-
In contrast with a [`fieldMappings`](search-indexer-field-mappings.md) definition that maps a path between two physical data structures, an `outputFieldMappings` definition maps in-memory enrichments to fields in a search index.
32
+
In contrast with a [`fieldMappings`](search-indexer-field-mappings.md) definition that maps a path between verbatim source fields and index fields, an `outputFieldMappings` definition maps in-memory enrichments to fields in a search index.
31
33
32
-
Output field mappings are required if your indexer has an attached [skillset](cognitive-search-working-with-skillsets.md) that creates new information, such as text translation or key phrase extraction. During indexer execution, AI-generated information exists in memory only. To persist this information in a search index, you'll need to tell the indexer where to send the data.
34
+
## Prerequisites
33
35
34
-
Output field mappings can also be used to retrieve specific nodes in a source document's complex type. For example, you might want just "FullName/LastName" in a multi-part "FullName" property. When you don't need the full complex structure, you can [flatten individual nodes in a nested data structures](#flattening-information-from-complex-types), and then use an output field mapping to send the output to a string collection in your search index.
36
+
- Indexer, index, data source, and skillset.
35
37
36
-
Output field mappings apply to:
38
+
- Index fields must be simple or top-level fields. You can't output to a [complex type](search-howto-complex-data-types.md), but if you have a complex type, you can use an output field definition to flatten parts of the complex type and send them to a collection in a search index.
37
39
38
-
+ In-memory content that's created by skills or extracted by an indexer. The source field is a node in an enriched document tree.
40
+
## When to use an output field mapping
39
41
40
-
+ Search indexes. If you're populating a [knowledge store](knowledge-store-concept-intro.md), use [projections](knowledge-store-projections-examples.md)for data path configuration. If you're populating vector fields, output field mappings aren't used.
42
+
Output field mappings are required if your indexer has an attached [skillset](cognitive-search-working-with-skillsets.md)that creates new information that you want in your index. Examples include:
41
43
42
-
Output field mappings are applied after [skillset execution](cognitive-search-working-with-skillsets.md) or after document cracking if there's no associated skillset.
44
+
- Vectors from embedding skills
45
+
- OCR text from image skills
46
+
- Locations, organizations, or people from entity recognition skills
43
47
44
-
## Define an output field mapping
48
+
Output field mappings can also be used to:
45
49
46
-
Output field mappings are added to the `outputFieldMappings` array in an indexer definition, typically placed after the `fieldMappings` array. An output field mapping consists of three parts.
50
+
- Create multiple copies of your generated content (one-to-many output field mappings).
- Flatten a source document's complex type. For example, assume source documents have a complex type, such as a multipart address, and you want just the city. You can use an output field mapping to [flatten a nested data structure](#flattening-information-from-complex-types), and then use an output field mapping to send the output to a string collection in your search index.
53
+
54
+
Output field mappings apply to search indexes only. If you're populating a [knowledge store](knowledge-store-concept-intro.md), use [projections](knowledge-store-projections-examples.md) for data path configuration.
58
55
59
-
| Property | Description |
60
-
|----------|-------------|
61
-
| 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. |
62
-
| 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. |
63
-
| mappingFunction | Optional. Adds extra processing provided by [mapping functions](search-indexer-field-mappings.md#mappingFunctions) supported by indexers. For enrichment nodes, encoding and decoding are the most commonly used functions. |
56
+
## Define an output field mapping
57
+
58
+
Output field mappings are added to the `outputFieldMappings` array in an indexer definition, typically placed after the `fieldMappings` array. An output field mapping consists of three parts.
64
59
65
60
You can use the REST API or an Azure SDK to define output field mappings.
66
61
67
62
> [!TIP]
68
-
> Indexers created by the [Import data wizard](search-import-data-portal.md) include output field mappings generated by the wizard. If you need examples, run the wizard over your data source to see the rendered definition.
63
+
> Indexers created by the [Import data wizard](search-import-data-portal.md) include output field mappings generated by the wizard. If you need examples, run the wizard over your data source to see the output field mappings in the indexer.
69
64
70
65
### [**REST APIs**](#tab/rest)
71
66
72
-
Use [Create Indexer (REST)](/rest/api/searchservice/create-Indexer) or [Update Indexer (REST)](/rest/api/searchservice/update-indexer), any API version.
67
+
1. Use [Create Indexer](/rest/api/searchservice/indexers/create) or [Create or Update Indexer](/rest/api/searchservice/indexers/create-or-update) or an equivalent method in an Azure SDK. Here's an example of an indexer definition.
68
+
69
+
```json
70
+
{
71
+
"name": "myindexer",
72
+
"description": null,
73
+
"dataSourceName": "mydatasource",
74
+
"targetIndexName": "myindex",
75
+
"schedule": { },
76
+
"parameters": { },
77
+
"fieldMappings": [],
78
+
"outputFieldMappings": [],
79
+
"disabled": false,
80
+
"encryptionKey": { }
81
+
}
82
+
```
73
83
74
-
This example adds entities and sentiment labels extracted from a blob's content property to fields in a search index.
84
+
1. Fill out the `outputFieldMappings` array to specify the mappings. A field mapping consists of three parts.
75
85
76
-
```JSON
77
-
PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
| 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. |
99
+
| 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. |
100
+
| mappingFunction | Optional. Adds extra processing provided by [mapping functions](search-indexer-field-mappings.md#mappingFunctions) supported by indexers. For enrichment nodes, encoding and decoding are the most commonly used functions. |
101
+
102
+
1. The `targetFieldName` is always the name of the field in the search index.
105
103
106
-
For each output field mapping, set the location of the data in the enriched document tree (sourceFieldName), and the name of the field as referenced in the index (targetFieldName). Assign any [mapping functions](search-indexer-field-mappings.md#mappingFunctions) needed to transform the content of a field before it's stored in the index.
104
+
1. The `sourceFieldName` is a path to a node in the enriched document. It's the output of a skill. The path always starts with `/document`, and if you're indexing from a blob, the second element of the path is `/content`. The third element is the value produced by the skill. For more information and examples, see [Reference enrichments in an Azure AI Search skillset](cognitive-search-concept-annotations-syntax.md).
105
+
106
+
This example adds entities and sentiment labels extracted from a blob's content property to fields in a search index.
1. Assign any [mapping functions](search-indexer-field-mappings.md#mappingFunctions) needed to transform the content of a field before it's stored in the index. For enrichment nodes, encoding and decoding are the most commonly used functions.
You can use an output field mapping to route a single source field to multiple fields in a search index. You might do this for comparison testing or if you want fields with different attributes.
167
+
168
+
Assume a skillset that generates embeddings for a vector field, and an index that has multiple vector fields that vary by algorithm and compression settings. Within the indexer, map the embedding skill's output to each of the multiple vector fields in a search index.
The source field path is skill output. In this example, the output is `text_vector`. Target name is an optional property. If you don't give the output mapping a target name, the path would be `embedding` or more precisely, `/document/content/embedding`.
0 commit comments