Fältmappningar och omvandlingar med hjälp av Azure AI Search-indexerare

Artikel
09/01/2024

Den här artikeln beskriver hur du anger explicita fältmappningar som upprättar datasökvägen mellan källfält i en datakälla och målfält som stöds i ett sökindex.

När du ska ange en fältmappning

När en Azure AI Search-indexerare läser in ett sökindex avgör den datasökvägen med hjälp av käll-till-mål-fältmappningar. Implicita fältmappningar är interna och inträffar när fältnamn och datatyper är kompatibla mellan källan och målet. Om indata och utdata inte matchar kan du definiera explicita fältmappningar för att konfigurera datasökvägen enligt beskrivningen i den här artikeln.

Fältmappningar kan också användas för datakonverteringar med låg vikt, till exempel kodning eller avkodning, via mappningsfunktioner. Om du behöver mer bearbetning bör du överväga att överbrygga klyftan i Azure Data Factory .

Fältmappningar gäller för:

Fysiska datastrukturer på båda sidor av datasökvägen. Logiska datastrukturer som skapats av färdigheter finns bara i minnet. Använd outputFieldMappings för att mappa minnesinterna noder till utdatafält i ett sökindex.
Endast överordnade AI Search-index. För "sekundära" index med "underordnade" dokument eller "segment" läser du scenarierna för avancerad fältmappning.
Endast sökfält på targetFieldName den översta nivån, där är antingen ett enkelt fält eller en samling. Ett målfält kan inte vara en komplex typ.

Stödda scenarier

Kontrollera att du använder en datakälla som stöds för indexering av indexerare.

Användningsfall	beskrivning
Namnavvikelse	Anta att datakällan har ett fält med namnet `_city`. Med tanke på att Azure AI Search inte tillåter fältnamn som börjar med ett understreck kan du med en fältmappning effektivt mappa "_city" till "stad". Om dina indexeringskrav omfattar att hämta innehåll från flera datakällor, där fältnamnen varierar mellan källorna, kan du använda en fältmappning för att klargöra sökvägen.
Typavvikelse	Anta att du vill att ett käll heltalsfält ska vara av typen `Edm.String` så att det kan sökas i sökindexet. Eftersom typerna är olika måste du definiera en fältmappning för att datasökvägen ska lyckas. Observera att Azure AI Search har en mindre uppsättning datatyper som stöds än många datakällor. Om du importerar SQL-data kan du med en fältmappning mappa den SQL-datatyp som du vill använda i ett sökindex.
En-till-många-datasökvägar	Du kan fylla i flera fält i indexet med innehåll från samma källfält. Du kanske till exempel vill använda olika analysverktyg för varje fält för att stödja olika användningsfall i klientappen.
Kodning och avkodning	Du kan använda mappningsfunktioner för att stödja Base64-kodning eller avkodning av data under indexering.
Dela upp strängar eller omarbeta matriser i samlingar	Du kan använda mappningsfunktioner för att dela en sträng som innehåller en avgränsare eller för att skicka en JSON-matris till ett sökfält av typen `Collection(Edm.String)`.

Kommentar

Om det inte finns några fältmappningar antar indexerarna att datakällfält ska mappas till indexfält med samma namn. Om du lägger till en fältmappning åsidosätts standardfältmappningarna för käll- och målfältet. Vissa indexerare, till exempel bloblagringsindexeraren, lägger automatiskt till standardfältmappningar för indexnyckelfältet.

Komplexa fält stöds inte i en fältmappning. Källstrukturen (kapslade eller hierarkiska strukturer) måste exakt matcha den komplexa typen i indexet så att standardmappningarna fungerar. Mer information finns i Självstudie: Indexera kapslade JSON-blobar för ett exempel. Om du får ett fel som liknar beror det på att "Field mapping specifies target field 'Address/city' that doesn't exist in the index"målfältmappningar inte kan vara en komplex typ.

Du kan också bara vilja ha några noder i den komplexa strukturen. Om du vill hämta enskilda noder kan du platta ut inkommande data till en strängsamling (se outputFieldMappings för den här lösningen).

Definiera en fältmappning

I det här avsnittet beskrivs stegen för att konfigurera fältmappningar.

REST API:er
.NET SDK (C#)

Använd Create Indexer eller Create or Update Indexer eller en motsvarande metod i en Azure SDK. Här är ett exempel på en indexeraredefinition.

{
   "name": "myindexer",
   "description": null,
   "dataSourceName": "mydatasource",
   "targetIndexName": "myindex",
   "schedule": { },
   "parameters": { },
   "fieldMappings": [],
   "disabled": false,
   "encryptionKey": { }
 }

Fyll i matrisen fieldMappings för att ange mappningarna. En fältmappning består av tre delar.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]

Property	beskrivning
sourceFieldName	Obligatoriskt. Representerar ett fält i datakällan.
targetFieldName	Valfritt. Representerar ett fält i sökindexet. Om det utelämnas antas värdet `sourceFieldName` för för målet. Målfält måste vara enkla fält eller samlingar på den översta nivån. Det kan inte vara en komplex typ eller samling. Om du hanterar ett problem med datatypen anges ett fälts datatyp i indexdefinitionen. Fältmappningen behöver bara ha fältets namn.
mappingFunction	Valfritt. Består av fördefinierade funktioner som transformerar data.

Exempel: Namn- eller typavvikelse

En explicit fältmappning upprättar en datasökväg för fall där namn och typ inte är identiska.

Azure AI Search använder skiftlägesokänslig jämförelse för att lösa fält- och funktionsnamnen i fältmappningar. Det här är praktiskt (du behöver inte få alla höljen rätt), men det innebär att datakällan eller indexet inte kan ha fält som bara skiljer sig åt från fall till fall.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

Exempel: En-till-många- eller förgrenade datasökvägar

I det här exemplet mappas ett enda källfält till flera målfält ("en-till-många"-mappningar). Du kan "förgrena" ett fält och kopiera samma källfältinnehåll till två olika indexfält som analyseras eller tilldelas på olika sätt i indexet.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

Du kan använda en liknande metod för kunskapsgenererat innehåll.

I Azure SDK för .NET använder du klassen FieldMapping som tillhandahåller SourceFieldName och TargetFieldName egenskaper och en valfri MappingFunction referens.

Ange fältmappningar när du skapar indexeraren eller senare genom att ange SearchIndexer.FieldMappings direkt. I följande C#-exempel anges fältmappningarna när du skapar en indexerare.

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Mappningsfunktioner och exempel

En fältmappningsfunktion transformerar innehållet i ett fält innan det lagras i indexet. Följande mappningsfunktioner stöds för närvarande:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Observera att dessa funktioner stöds exklusivt för överordnade index just nu. De är inte kompatibla med segmenterad indexmappning, därför kan dessa funktioner inte användas för indexprojektioner.

base64Encode-funktion

Utför URL-säker Base64-kodning av indatasträngen. Förutsätter att indata är UTF-8-kodade.

Exempel: Grundläggande kodning av en dokumentnyckel

Endast URL-säkra tecken kan visas i en Azure AI Search-dokumentnyckel (så att du kan adressera dokumentet med uppslags-API:et). Om källfältet för din nyckel innehåller URL-osäkra tecken, till exempel - och \, använder du base64Encode funktionen för att konvertera den vid indexeringstiden.

I följande exempel anges funktionen base64Encode på metadata_storage_name för att hantera tecken som inte stöds.

PUT /indexers?api-version=2024-07-01
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

En dokumentnyckel (både före och efter konverteringen) får inte vara längre än 1 024 tecken. När du hämtar den kodade nyckeln vid söktillfället använder du base64Decode funktionen för att hämta det ursprungliga nyckelvärdet och använder det för att hämta källdokumentet.

Exempel: Gör ett baskodat fält "sökbart"

Det finns tillfällen då du behöver använda en kodad version av ett fält som metadata_storage_path nyckeln, men du behöver också en okodad version för fulltextsökning. För att stödja båda scenarierna kan du mappa metadata_storage_path till två fält: ett för nyckeln (kodat) och ett andra för ett sökvägsfält som vi kan anta tillskrivs som searchable i indexschemat.

PUT /indexers/blob-indexer?api-version=2024-07-01
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Exempel – bevara ursprungliga värden

Blob Storage-indexeraren lägger automatiskt till en fältmappning från metadata_storage_path, blobens URI, till indexnyckelfältet om ingen fältmappning har angetts. Det här värdet är Base64-kodat så det är säkert att använda som en Azure AI Search-dokumentnyckel. I följande exempel visas hur du samtidigt mappar en URL-säker Base64-kodad version av metadata_storage_path till ett index_key fält och bevarar det ursprungliga värdet i ett metadata_storage_path fält:

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Om du inte inkluderar en parameteregenskap för din mappningsfunktion, är värdet {"useHttpServerUtilityUrlTokenEncode" : true}som standard .

Azure AI Search stöder två olika Base64-kodningar. Du bör använda samma parametrar när du kodar och avkodar samma fält. Mer information finns i base64-kodningsalternativ för att bestämma vilka parametrar som ska användas.

base64Decode-funktion

Utför Base64-avkodning av indatasträngen. Indata antas vara en URL-säker Base64-kodad sträng.

Exempel – avkoda blobmetadata eller URL:er

Dina källdata kan innehålla Base64-kodade strängar, till exempel blobmetadatasträngar eller webb-URL:er, som du vill göra sökbara som oformaterad text. Du kan använda base64Decode funktionen för att återställa kodade data till vanliga strängar när du fyller i ditt sökindex.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Om du inte inkluderar en parameteregenskap är värdet som standard {"useHttpServerUtilityUrlTokenEncode" : true}.

base64-kodningsalternativ

Azure AI Search stöder URL-säker base64-kodning och normal base64-kodning. En sträng som är base64-kodad under indexering bör avkodas senare med samma kodningsalternativ, annars matchar resultatet inte originalet.

Om parametrarna useHttpServerUtilityUrlTokenEncode eller useHttpServerUtilityUrlTokenDecode för kodning respektive avkodning är inställda på truebeter sig de base64Encode som HttpServerUtility.UrlTokenEncode och base64Decode fungerar som HttpServerUtility.UrlTokenDecode.

Varning

Om base64Encode används för att generera nyckelvärden useHttpServerUtilityUrlTokenEncode måste anges till true. Endast URL-säker base64-kodning kan användas för nyckelvärden. Se Namngivningsregler för den fullständiga uppsättningen begränsningar för tecken i nyckelvärden.

.NET-biblioteken i Azure AI Search förutsätter hela .NET Framework, som tillhandahåller inbyggd kodning. Alternativen useHttpServerUtilityUrlTokenEncode och useHttpServerUtilityUrlTokenDecode tillämpar den här inbyggda funktionen. Om du använder .NET Core eller något annat ramverk rekommenderar vi att du ställer in dessa alternativ på false och anropar ramverkets kodnings- och avkodningsfunktioner direkt.

I följande tabell jämförs olika base64-kodningar för strängen 00>00?00. Om du vill fastställa vilken bearbetning som krävs (om någon) för dina base64-funktioner använder du funktionen bibliotekskodning på strängen 00>00?00 och jämför utdata med förväntade utdata MDA-MDA_MDA.

Encoding	Base64-koda utdata	Extra bearbetning efter bibliotekskodning	Extra bearbetning före biblioteksdekodning
Base64 med utfyllnad	`MDA+MDA/MDA=`	Använda URL-säkra tecken och ta bort utfyllnad	Använd standardbas64-tecken och lägg till utfyllnad
Base64 utan utfyllnad	`MDA+MDA/MDA`	Använda URL-säkra tecken	Använda standardbas64-tecken
URL-säker base64 med utfyllnad	`MDA-MDA_MDA=`	Ta bort utfyllnad	Lägg till utfyllnad
URL-säker base64 utan utfyllnad	`MDA-MDA_MDA`	Ingen	Ingen

funktionen extractTokenAtPosition

Delar upp ett strängfält med den angivna avgränsaren och väljer token vid den angivna positionen i den resulterande delningen.

Den här funktionen använder följande parametrar:

delimiter: en sträng som ska användas som avgränsare när du delar indatasträngen.
position: en heltals nollbaserad position för token som ska väljas när indatasträngen har delats.

Om indata till exempel är , är (blanksteg) och position är 0, är Janeresultatet ; om position är 1 är Doeresultatet ." "delimiter Jane Doe Om positionen refererar till en token som inte finns returneras ett fel.

Exempel – extrahera ett namn

Datakällan innehåller ett PersonName fält och du vill indexera det som två separata FirstName fält och LastName fält. Du kan använda den här funktionen för att dela upp indata med hjälp av blankstegstecknet som avgränsare.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

jsonArrayToStringCollection-funktion

Omvandlar en sträng formaterad som en JSON-matris med strängar till en strängmatris som kan användas för att fylla i ett Collection(Edm.String) fält i indexet.

Om indatasträngen till exempel är ["red", "white", "blue"]fylls målfältet av typen Collection(Edm.String) med de tre värdena red, whiteoch blue. För indatavärden som inte kan parsas som JSON-strängmatriser returneras ett fel.

Exempel – fylla i insamling från relationsdata

Azure SQL Database har ingen inbyggd datatyp som naturligt mappar till Collection(Edm.String) fält i Azure AI Search. Om du vill fylla i strängsamlingsfält kan du förbearbeta dina källdata som en JSON-strängmatris och sedan använda mappningsfunktionen jsonArrayToStringCollection .

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

urlEncode-funktion

Den här funktionen kan användas för att koda en sträng så att den är "URL-säker". När den används med en sträng som innehåller tecken som inte tillåts i en URL konverterar den här funktionen dessa "osäkra" tecken till tecken-entitetsmotsvarigheter. Den här funktionen använder UTF-8-kodningsformatet.

Exempel – uppslag av dokumentnyckel

urlEncode funktionen kan användas som ett alternativ till base64Encode funktionen, om endast osäkra URL-tecken ska konverteras, samtidigt som andra tecken hålls som de är.

Anta att indatasträngen är <hello> – då fylls målfältet av typen (Edm.String) i med värdet %3chello%3e

När du hämtar den kodade nyckeln vid söktillfället kan du använda urlDecode funktionen för att hämta det ursprungliga nyckelvärdet och använda den för att hämta källdokumentet.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }
]

urlDecode-funktion

Den här funktionen konverterar en URL-kodad sträng till en avkodad sträng med UTF-8-kodningsformat.

Exempel – avkoda blobmetadata

Vissa Azure Storage-klienter URL-kodar automatiskt blobmetadata om de innehåller icke-ASCII-tecken. Men om du vill göra sådana metadata sökbara (som oformaterad text) kan du använda urlDecode funktionen för att återställa kodade data till vanliga strängar när du fyller i ditt sökindex.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

funktionen fixedLengthEncode

Den här funktionen konverterar en sträng med valfri längd till en sträng med fast längd.

Exempel – mappa dokumentnycklar som är för långa

När det uppstår fel som rör dokumentnyckelns längd på mer än 1 024 tecken kan den här funktionen användas för att minska längden på dokumentnyckeln.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

toJson-funktion

Den här funktionen konverterar en sträng till ett formaterat JSON-objekt. Detta kan användas för scenarier där datakällan, till exempel Azure SQL, inte har inbyggt stöd för sammansatta eller hierarkiska datatyper och sedan mappar den till komplexa fält.

Exempel – mappa textinnehåll till ett komplext fält

Anta att det finns en SQL-rad med en JSON-sträng som måste mappas till ett (motsvarande definierat) komplext fält i indexet toJson . Funktionen kan användas för att uppnå detta. Om till exempel ett komplext fält i indexet behöver fyllas med följande data:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Det kan uppnås med hjälp toJson av mappningsfunktionen på en JSON-strängkolumn i en SQL-rad som ser ut så här: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Fältmappningen måste anges enligt nedan.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

Avancerade fältmappningsscenarier

I scenarier där du har "en-till-många"-dokumentrelationer, till exempel segmentering av data eller delning, följer du dessa riktlinjer för att mappa fält från överordnade dokument till "underordnade" dokument (segment):

1. Hoppar över överordnad dokumentindexering

Om du hoppar över indexeringen av överordnade dokument (genom att ange projectionMode till skipIndexingParentDocuments i kunskapsuppsättningens indexProjections) använder du indexprojektioner för att mappa fält från de överordnade dokumenten till "underordnade" dokument.

2. Indexera både överordnade och "underordnade" dokument

Om du indexerar både överordnade dokument och "underordnade" dokument:

Använd fältmappningar för att mappa fält till de överordnade dokumenten.
Använd indexprojektioner för att mappa fält till "underordnade" dokument.

3. Mappa funktionsformade värden till överordnade och/eller "underordnade" dokument

Om ett fält i det överordnade dokumentet kräver en transformering (med hjälp av mappningsfunktioner som kodning) och måste mappas till de överordnade och/eller "underordnade" dokumenten:

Använd omvandlingen med hjälp av fältmappningsfunktionerna i indexeraren.
Använd indexprojektioner i kunskapsuppsättningen för att mappa det transformerade fältet till "underordnade" dokument.

Dela via