Veldtoewijzingen en transformaties met behulp van Azure AI Search-indexeerfuncties
In dit artikel wordt uitgelegd hoe u expliciete veldtoewijzingen instelt die het gegevenspad tussen bronvelden in een ondersteunde gegevensbron en doelvelden in een zoekindex tot stand brengen.
Wanneer moet u een veldtoewijzing instellen
Wanneer een Azure AI Search-indexeerfunctie een zoekindex laadt, wordt het gegevenspad bepaald met behulp van bron-naar-doelveldtoewijzingen. Impliciete veldtoewijzingen zijn intern en vinden plaats wanneer veldnamen en gegevenstypen compatibel zijn tussen de bron en bestemming. Als invoer en uitvoer niet overeenkomen, kunt u expliciete veldtoewijzingen definiëren om het gegevenspad in te stellen, zoals beschreven in dit artikel.
Veldtoewijzingen kunnen ook worden gebruikt voor lichte gegevensconversies, zoals codering of decodering, via toewijzingsfuncties. Als er meer verwerking is vereist, kunt u Azure Data Factory overwegen om de kloof te overbruggen.
Veldtoewijzingen zijn van toepassing op:
Fysieke gegevensstructuren aan beide zijden van het gegevenspad. Logische gegevensstructuren die door vaardigheden zijn gemaakt, bevinden zich alleen in het geheugen. Gebruik outputFieldMappings om in-memory knooppunten toe te wijzen aan uitvoervelden in een zoekindex.
Alleen bovenliggende AI Search-indexen. Raadpleeg de geavanceerde veldtoewijzingsscenario's voor 'secundaire' indexen met 'onderliggende' documenten of 'segmenten'.
Alleen zoekvelden op het hoogste niveau, waarbij het
targetFieldName
een eenvoudig veld of een verzameling is. Een doelveld kan geen complex type zijn.
Ondersteunde scenario's
Zorg ervoor dat u een ondersteunde gegevensbron gebruikt voor indexeerfunctie voor indexering.
Use-case | Beschrijving |
---|---|
Naamverschillen | Stel dat uw gegevensbron een veld heeft met de naam _city . Aangezien Azure AI Search geen veldnamen toestaat die beginnen met een onderstrepingsteken, kunt u met een veldtoewijzing '_city' effectief toewijzen aan 'plaats'. Als uw indexeringsvereisten bestaan uit het ophalen van inhoud uit meerdere gegevensbronnen, waarbij veldnamen per bron verschillen, kunt u een veldtoewijzing gebruiken om het pad te verduidelijken. |
Typeverschillen | U moet een bron-geheel getalveld van het type Edm.String zijn, zodat het doorzoekbaar is in de zoekindex. Omdat de typen verschillen, moet u een veldtoewijzing definiëren om het gegevenspad te laten slagen. Houd er rekening mee dat Azure AI Search een kleinere set ondersteunde gegevenstypen heeft dan veel gegevensbronnen. Als u SQL-gegevens importeert, kunt u met een veldtoewijzing het gewenste SQL-gegevenstype toewijzen in een zoekindex. |
Een-op-veel-gegevenspaden | U kunt meerdere velden in de index vullen met inhoud uit hetzelfde bronveld. U kunt bijvoorbeeld verschillende analyses toepassen op elk veld om verschillende use cases in uw client-app te ondersteunen. |
Codering en decodering | U kunt toewijzingsfuncties toepassen ter ondersteuning van Base64-codering of -decodering van gegevens tijdens het indexeren. |
Tekenreeksen splitsen of matrices herschikken in verzamelingen | U kunt toewijzingsfuncties toepassen om een tekenreeks te splitsen die een scheidingsteken bevat of om een JSON-matrix te verzenden naar een zoekveld van het typeCollection(Edm.String) . |
Notitie
Als er geen veldtoewijzingen aanwezig zijn, gaan indexeerfuncties ervan uit dat gegevensbronvelden moeten worden toegewezen aan indexvelden met dezelfde naam. Als u een veldtoewijzing toevoegt, worden de standaardveldtoewijzingen voor het bron- en doelveld overschreven. Sommige indexeerfuncties, zoals de indexeerfunctie voor blobopslag, voegen automatisch standaardveldtoewijzingen toe voor het indexsleutelveld.
Complexe velden worden niet ondersteund in een veldtoewijzing. De bronstructuur (geneste of hiërarchische structuren) moet exact overeenkomen met het complexe type in de index, zodat de standaardtoewijzingen werken. Zie Zelfstudie: Geneste JSON-blobs indexeren voor een voorbeeld voor meer informatie. Als u een fout krijgt die vergelijkbaar is met "Field mapping specifies target field 'Address/city' that doesn't exist in the index"
, komt dit doordat doelveldtoewijzingen geen complex type kunnen zijn.
Desgewenst wilt u slechts enkele knooppunten in de complexe structuur. Als u afzonderlijke knooppunten wilt ophalen, kunt u binnenkomende gegevens platzetten in een tekenreeksverzameling (zie outputFieldMappings voor deze tijdelijke oplossing).
Een veldtoewijzing definiëren
In deze sectie worden de stappen voor het instellen van veldtoewijzingen uitgelegd.
Gebruik Indexeerfunctie maken of Indexeerfunctie maken of bijwerken of een equivalente methode in een Azure SDK. Hier volgt een voorbeeld van een definitie van een indexeerfunctie.
{ "name": "myindexer", "description": null, "dataSourceName": "mydatasource", "targetIndexName": "myindex", "schedule": { }, "parameters": { }, "fieldMappings": [], "disabled": false, "encryptionKey": { } }
Vul de
fieldMappings
matrix in om de toewijzingen op te geven. Een veldtoewijzing bestaat uit drie delen."fieldMappings": [ { "sourceFieldName": "_city", "targetFieldName": "city", "mappingFunction": null } ]
Eigenschappen Beschrijving sourceFieldName Vereist. Vertegenwoordigt een veld in uw gegevensbron. targetFieldName Optioneel. Vertegenwoordigt een veld in uw zoekindex. Als u dit weglaat, wordt de waarde sourceFieldName
ervan uitgegaan voor het doel. Doelvelden moeten eenvoudige velden of verzamelingen op het hoogste niveau zijn. Het kan geen complex type of verzameling zijn. Als u een probleem met een gegevenstype verwerkt, wordt het gegevenstype van een veld opgegeven in de indexdefinitie. De veldtoewijzing moet alleen de naam van het veld hebben.mappingFunction Optioneel. Bestaat uit vooraf gedefinieerde functies waarmee gegevens worden getransformeerd.
Voorbeeld: Naam of typeverschillen
Met een expliciete veldtoewijzing wordt een gegevenspad tot stand gebracht voor gevallen waarin de naam en het type niet identiek zijn.
Azure AI Search maakt gebruik van hoofdlettergevoelige vergelijkingen om de veld- en functienamen in veldtoewijzingen op te lossen. Dit is handig (u hoeft niet alle hoofdletters op te halen), maar dit betekent dat uw gegevensbron of index geen velden kan bevatten die alleen per geval verschillen.
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" } ]
}
Voorbeeld: Een-op-veel- of geforkte gegevenspaden
In dit voorbeeld wordt één bronveld toegewezen aan meerdere doelvelden ('een-op-veel'-toewijzingen). U kunt een veld 'splitsen' en dezelfde inhoud van het bronveld kopiëren naar twee verschillende indexvelden die anders in de index worden geanalyseerd of toegeschreven.
"fieldMappings" : [
{ "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
{ "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]
U kunt een vergelijkbare benadering gebruiken voor door vaardigheden gegenereerde inhoud.
Toewijzingsfuncties en voorbeelden
Met een functie voor veldtoewijzing wordt de inhoud van een veld getransformeerd voordat deze in de index wordt opgeslagen. De volgende toewijzingsfuncties worden momenteel ondersteund:
Houd er rekening mee dat deze functies momenteel uitsluitend worden ondersteund voor bovenliggende indexen. Ze zijn niet compatibel met gesegmenteerde indextoewijzing. Deze functies kunnen daarom niet worden gebruikt voor indexprojecties.
base64Encode, functie
Voert URL-veilige Base64-codering van de invoertekenreeks uit. Wordt ervan uitgegaan dat de invoer UTF-8 is gecodeerd.
Voorbeeld: Een documentsleutel basiscodering
Alleen URL-veilige tekens kunnen worden weergegeven in een Azure AI Search-documentsleutel (zodat u het document kunt adresseren met behulp van de Zoek-API). Als het bronveld voor uw sleutel URL-onveilige tekens bevat, zoals -
en \
, gebruikt u de base64Encode
functie om het te converteren tijdens het indexeren.
In het volgende voorbeeld wordt de base64Encode-functie metadata_storage_name
opgegeven voor het verwerken van niet-ondersteunde tekens.
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 }
}
}
]
}
Een documentsleutel (zowel vóór als na conversie) mag niet langer zijn dan 1024 tekens. Wanneer u de gecodeerde sleutel tijdens het zoeken ophaalt, gebruikt u de base64Decode
functie om de oorspronkelijke sleutelwaarde op te halen en gebruikt u deze om het brondocument op te halen.
Voorbeeld: Een met base gecodeerd veld 'doorzoekbaar' maken
Er zijn momenten waarop u een gecodeerde versie van een veld zoals metadata_storage_path
de sleutel moet gebruiken, maar ook een niet-gecodeerde versie nodig hebt voor zoeken in volledige tekst. Ter ondersteuning van beide scenario's kunt metadata_storage_path
u toewijzen aan twee velden: één voor de sleutel (gecodeerd) en een seconde voor een padveld dat we kunnen aannemen, wordt toegeschreven als searchable
in het indexschema.
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" }
]
}
Voorbeeld: oorspronkelijke waarden behouden
De indexeerfunctie voor blobopslag voegt automatisch een veldtoewijzing toe van metadata_storage_path
, de URI van de blob, aan het indexsleutelveld als er geen veldtoewijzing is opgegeven. Deze waarde is Base64 gecodeerd, zodat deze veilig kan worden gebruikt als een Azure AI Search-documentsleutel. In het volgende voorbeeld ziet u hoe u tegelijkertijd een met URL veilige Base64 gecodeerde versie van metadata_storage_path
een index_key
veld kunt toewijzen en de oorspronkelijke waarde in een metadata_storage_path
veld kunt behouden:
"fieldMappings": [
{
"sourceFieldName": "metadata_storage_path",
"targetFieldName": "metadata_storage_path"
},
{
"sourceFieldName": "metadata_storage_path",
"targetFieldName": "index_key",
"mappingFunction": {
"name": "base64Encode"
}
}
]
Als u geen parametereigenschap voor uw toewijzingsfunctie opneemt, wordt deze standaard ingesteld op de waarde {"useHttpServerUtilityUrlTokenEncode" : true}
.
Azure AI Search ondersteunt twee verschillende Base64-coderingen. U moet dezelfde parameters gebruiken bij het coderen en decoderen van hetzelfde veld. Zie base64-coderingsopties om te bepalen welke parameters moeten worden gebruikt voor meer informatie.
base64Decode, functie
Hiermee wordt Base64-decodering van de invoertekenreeks uitgevoerd. De invoer wordt ervan uitgegaan dat het een url-veilige Base64-gecodeerde tekenreeks is.
Voorbeeld: blobmetagegevens of -URL's decoderen
Uw brongegevens bevatten mogelijk met Base64 gecodeerde tekenreeksen, zoals tekenreeksen voor blobmetagegevens of web-URL's, die u doorzoekbaar wilt maken als tekst zonder opmaak. U kunt de base64Decode
functie gebruiken om de gecodeerde gegevens terug te zetten in reguliere tekenreeksen bij het invullen van uw zoekindex.
"fieldMappings" : [
{
"sourceFieldName" : "Base64EncodedMetadata",
"targetFieldName" : "SearchableMetadata",
"mappingFunction" : {
"name" : "base64Decode",
"parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
}
}
]
Als u geen eigenschap parameters opneemt, wordt deze standaard ingesteld op de waarde {"useHttpServerUtilityUrlTokenEncode" : true}
.
Azure AI Search ondersteunt twee verschillende Base64-coderingen. U moet dezelfde parameters gebruiken bij het coderen en decoderen van hetzelfde veld. Zie base64-coderingsopties om te bepalen welke parameters moeten worden gebruikt voor meer informatie.
Opties voor base64-codering
Azure AI Search biedt ondersteuning voor URL-veilige base64-codering en normale base64-codering. Een tekenreeks die base64 is gecodeerd tijdens het indexeren, moet later worden gedecodeerd met dezelfde coderingsopties, anders komt het resultaat niet overeen met het origineel.
Als de useHttpServerUtilityUrlTokenEncode
of useHttpServerUtilityUrlTokenDecode
parameters voor respectievelijk codering en decodering zijn ingesteld true
op , gedraagt base64Encode
zich als HttpServerUtility.UrlTokenEncode en base64Decode
gedraagt zich als HttpServerUtility.UrlTokenDecode.
Waarschuwing
Als base64Encode
wordt gebruikt om sleutelwaarden te produceren, useHttpServerUtilityUrlTokenEncode
moet deze worden ingesteld op waar. Alleen URL-veilige base64-codering kan worden gebruikt voor sleutelwaarden. Zie Naamgevingsregels voor de volledige set beperkingen voor tekens in sleutelwaarden.
Voor de .NET-bibliotheken in Azure AI Search wordt ervan uitgegaan dat het volledige .NET Framework, dat ingebouwde codering biedt. De useHttpServerUtilityUrlTokenEncode
en useHttpServerUtilityUrlTokenDecode
opties passen deze ingebouwde functionaliteit toe. Als u .NET Core of een ander framework gebruikt, raden we u aan deze opties rechtstreeks in te false
stellen en de coderings- en decoderingsfuncties van uw framework aan te roepen.
In de volgende tabel worden verschillende base64-coderingen van de tekenreeks vergeleken 00>00?00
. Als u de vereiste verwerking (indien aanwezig) voor uw base64-functies wilt bepalen, past u de codefunctie van de bibliotheek toe op de tekenreeks 00>00?00
en vergelijkt u de uitvoer met de verwachte uitvoer MDA-MDA_MDA
.
Codering | Uitvoer van Base64-codering | Extra verwerking na bibliotheekcodering | Extra verwerking vóór bibliotheekdecodering |
---|---|---|---|
Base64 met opvulling | MDA+MDA/MDA= |
URL-veilige tekens gebruiken en opvulling verwijderen | Standaard base64-tekens gebruiken en opvulling toevoegen |
Base64 zonder opvulling | MDA+MDA/MDA |
URL-veilige tekens gebruiken | Standaard base64-tekens gebruiken |
URL-veilig base64 met opvulling | MDA-MDA_MDA= |
Opvulling verwijderen | Opvulling toevoegen |
URL-veilig base64 zonder opvulling | MDA-MDA_MDA |
Geen | Geen |
extractTokenAtPosition, functie
Splitst een tekenreeksveld met behulp van het opgegeven scheidingsteken en kiest het token op de opgegeven positie in de resulterende splitsing.
Deze functie gebruikt de volgende parameters:
delimiter
: een tekenreeks die moet worden gebruikt als scheidingsteken bij het splitsen van de invoertekenreeks.position
: een geheel getal op basis van nul van het token dat moet worden gekozen nadat de invoertekenreeks is gesplitst.
Als de invoer Jane Doe
bijvoorbeeld is, is de delimiter
( " "
spatie) en de position
0, het resultaat is Jane
; als het position
1 is, is Doe
het resultaat . Als de positie verwijst naar een token dat niet bestaat, wordt er een fout geretourneerd.
Voorbeeld: een naam extraheren
Uw gegevensbron bevat een PersonName
veld en u wilt deze indexeren als twee afzonderlijke FirstName
LastName
velden. U kunt deze functie gebruiken om de invoer te splitsen met behulp van het spatieteken als scheidingsteken.
"fieldMappings" : [
{
"sourceFieldName" : "PersonName",
"targetFieldName" : "FirstName",
"mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
},
{
"sourceFieldName" : "PersonName",
"targetFieldName" : "LastName",
"mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
}]
jsonArrayToStringCollection, functie
Transformeert een tekenreeks die is opgemaakt als een JSON-matrix met tekenreeksen in een tekenreeksmatrix die kan worden gebruikt om een Collection(Edm.String)
veld in de index te vullen.
Als de invoertekenreeks bijvoorbeeld is ["red", "white", "blue"]
, wordt het doelveld van het type Collection(Edm.String)
gevuld met de drie waarden red
, white
en blue
. Voor invoerwaarden die niet kunnen worden geparseerd als JSON-tekenreeksmatrices, wordt een fout geretourneerd.
Voorbeeld: verzameling van relationele gegevens vullen
Azure SQL Database heeft geen ingebouwd gegevenstype dat op natuurlijke wijze wordt toegewezen aan Collection(Edm.String)
velden in Azure AI Search. Als u tekenreeksverzamelingsvelden wilt vullen, kunt u de brongegevens vooraf verwerken als een JSON-tekenreeksmatrix en vervolgens de jsonArrayToStringCollection
toewijzingsfunctie gebruiken.
"fieldMappings" : [
{
"sourceFieldName" : "tags",
"mappingFunction" : { "name" : "jsonArrayToStringCollection" }
}]
urlEncode, functie
Deze functie kan worden gebruikt om een tekenreeks te coderen, zodat deze 'URL veilig' is. Wanneer deze functie wordt gebruikt met een tekenreeks die tekens bevat die niet zijn toegestaan in een URL, worden deze 'onveilige' tekens geconverteerd naar equivalenten van tekens. Deze functie maakt gebruik van de UTF-8-coderingsindeling.
Voorbeeld: opzoeken van documentsleutels
urlEncode
de functie kan worden gebruikt als alternatief voor de base64Encode
functie, als alleen onveilige URL-tekens moeten worden geconverteerd, terwijl andere tekens als zodanig worden behouden.
Stel dat de invoertekenreeks is <hello>
: het doelveld van het type (Edm.String)
wordt gevuld met de waarde %3chello%3e
Wanneer u de gecodeerde sleutel tijdens het zoeken ophaalt, kunt u vervolgens de urlDecode
functie gebruiken om de oorspronkelijke sleutelwaarde op te halen en dat te gebruiken om het brondocument op te halen.
"fieldMappings" : [
{
"sourceFieldName" : "SourceKey",
"targetFieldName" : "IndexKey",
"mappingFunction" : {
"name" : "urlEncode"
}
}
]
urlDecode, functie
Met deze functie wordt een tekenreeks met URL-codering geconverteerd naar een gedecodeerde tekenreeks met behulp van UTF-8-coderingsindeling.
Voorbeeld: blobmetagegevens decoderen
Sommige Azure Storage-clients coderen automatisch metagegevens van blob-URL's als deze niet-ASCII-tekens bevatten. Als u dergelijke metagegevens echter doorzoekbaar wilt maken (als tekst zonder opmaak), kunt u de urlDecode
functie gebruiken om de gecodeerde gegevens terug te zetten in gewone tekenreeksen bij het invullen van uw zoekindex.
"fieldMappings" : [
{
"sourceFieldName" : "UrlEncodedMetadata",
"targetFieldName" : "SearchableMetadata",
"mappingFunction" : {
"name" : "urlDecode"
}
}
]
fixedLengthEncode, functie
Met deze functie wordt een tekenreeks van elke lengte geconverteerd naar een tekenreeks met een vaste lengte.
Voorbeeld: documentsleutels toewijzen die te lang zijn
Wanneer er fouten optreden die betrekking hebben op de lengte van de documentsleutel die langer is dan 1024 tekens, kan deze functie worden toegepast om de lengte van de documentsleutel te verminderen.
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "your key field",
"mappingFunction" : {
"name" : "fixedLengthEncode"
}
}
]
toJson, functie
Met deze functie wordt een tekenreeks geconverteerd naar een opgemaakt JSON-object. Dit kan worden gebruikt voor scenario's waarin de gegevensbron, zoals Azure SQL, geen systeemeigen ondersteuning biedt voor samengestelde of hiërarchische gegevenstypen en deze vervolgens toe te wijzen aan complexe velden.
Voorbeeld: tekstinhoud toewijzen aan een complex veld
Stel dat er een SQL-rij is met een JSON-tekenreeks die moet worden toegewezen aan een (bijbehorend gedefinieerd) complex veld in de index. De toJson
functie kan hiervoor worden gebruikt. Als een complex veld in de index bijvoorbeeld moet worden gevuld met de volgende gegevens:
{
"id": "5",
"info": {
"name": "Jane",
"surname": "Smith",
"skills": [
"SQL",
"C#",
"Azure"
],
"dob": "2005-11-04T12:00:00"
}
}
Dit kan worden bereikt met behulp van de toJson
toewijzingsfunctie in een JSON-tekenreekskolom in een SQL-rij die er als volgt uitziet: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}
.
De veldtoewijzing moet worden opgegeven zoals hieronder wordt weergegeven.
"fieldMappings" : [
{
"sourceFieldName" : "content",
"targetFieldName" : "complexField",
"mappingFunction" : {
"name" : "toJson"
}
}
]
Geavanceerde scenario's voor veldtoewijzing
In scenario's waarin u 'een-op-veel'-documentrelaties hebt, zoals gegevenssegmenteren of splitsen, volgt u deze richtlijnen voor het toewijzen van velden van bovenliggende documenten aan 'onderliggende' documenten (segmenten):
1. Bovenliggende documentindexering overslaan
Als u de indexering van bovenliggende documenten overslaat (door in te stellen projectionMode
skipIndexingParentDocuments
in de vaardighedensetsindexProjections
), gebruikt u indexprojecties om velden van de bovenliggende documenten toe te wijzen aan de onderliggende documenten.
2. Zowel bovenliggende als onderliggende documenten indexeren
Als u zowel bovenliggende documenten als onderliggende documenten indexeert:
- Gebruik veldtoewijzingen om velden toe te wijzen aan de bovenliggende documenten.
- Gebruik indexprojecties om velden toe te wijzen aan de onderliggende documenten.
3. Door functie getransformeerde waarden toewijzen aan bovenliggende en/of onderliggende documenten
Als een veld in het bovenliggende document een transformatie vereist (met behulp van de toewijzingsfuncties zoals codering) en moet worden toegewezen aan de bovenliggende en/of onderliggende documenten:
- Pas de transformatie toe met behulp van de functies van veldtoewijzingen in de indexeerfunctie.
- Gebruik indexprojecties in de vaardighedenset om het getransformeerde veld toe te wijzen aan de onderliggende documenten.