Dela via

Indexering av data från Azure Cosmos DB för NoSQL för frågor i Azure AI Search

  • Artikel

I den här artikeln får du lära dig hur du konfigurerar en indexerare som importerar innehåll från Azure Cosmos DB för NoSQL och gör det sökbart i Azure AI Search.

Den här artikeln kompletterar Skapa en indexerare med information som är specifik för Cosmos DB. Den använder Azure Portal- och REST-API:er för att demonstrera ett arbetsflöde i tre delar som är gemensamt för alla indexerare: skapa en datakälla, skapa ett index, skapa en indexerare. Dataextrahering sker när du skickar begäran skapa indexerare.

Eftersom terminologin kan vara förvirrande är det värt att notera att Azure Cosmos DB-indexering och Azure AI Search-indexering är olika åtgärder. Indexering i Azure AI Search skapar och läser in ett sökindex i söktjänsten.

Förutsättningar

  • Ett Azure Cosmos DB-konto, en databas, en container och ett objekt. Använd samma region för både Azure AI Search och Azure Cosmos DB för lägre svarstid och för att undvika bandbreddsavgifter.

  • En automatisk indexeringsprincip för Azure Cosmos DB-samlingen, inställd på Konsekvent. Det här är standardkonfigurationen. Lat indexering rekommenderas inte och kan resultera i saknade data.

  • Läsbehörigheter. En "fullständig åtkomst" anslutningssträng innehåller en nyckel som ger åtkomst till innehållet, men om du använder identiteter (Microsoft Entra-ID) kontrollerar du att söktjänstens hanterade identitet har tilldelats både Cosmos DB-kontoläsarrollen och Cosmos DB-inbyggda dataläsarroll.

Om du vill gå igenom exemplen i den här artikeln behöver du Azure Portal eller en REST-klient. Om du använder Azure Portal kontrollerar du att åtkomsten till alla offentliga nätverk är aktiverad. Andra metoder för att skapa en Cosmos DB-indexerare är Azure SDK:er.

Prova med exempeldata

Använd de här anvisningarna för att skapa en container och databas i Cosmos DB i testsyfte.

  1. Ladda ned HotelsData_toCosmosDB.JSON från GitHub för att skapa en container i Cosmos DB som innehåller en delmängd av datauppsättningen exempelhotell.

  2. Logga in på Azure Portal och skapa ett konto, en databas och en container i Cosmos DB.

  3. I Cosmos DB väljer du Datautforskaren för den nya containern och anger följande värden.

    Property Värde
    Databas Skapa nya , och programformulär i
    Databas-ID hotelsdb
    Dela dataflöde mellan containrar Välj inte
    Container-ID hotell
    Partitionsnyckel /HotelId
    Containerdataflöde (autoskalning) Automatisk skalning
    Maximalt antal RU/s för container 1000

  4. I Datautforskaren expanderar du hotelsdb och *hotels och väljer sedan Objekt.

  5. Välj Ladda upp objekt och välj sedan HotelsData_toCosmosDB.JSON fil som du laddade ned från GitHub.

  6. Högerklicka på Objekt och välj Ny SQL-fråga. Standardfrågan är SELECT * FROM c.

  7. Välj Kör fråga för att köra frågan och visa resultat. Du bör ha 50 hotelldokument.

Nu när du har en container kan du använda Azure Portal, REST-klienten eller en Azure SDK för att indexera dina data.

Fältet Beskrivning innehåller det mest utförliga innehållet. Du bör rikta in dig på det här fältet för fulltextsökning och valfria vektorfrågor.

Använda Azure Portal

Du kan använda guiden Importera data eller guiden Importera och vektorisera data för att automatisera indexeringen från en SQL-databastabell eller -vy. Konfigurationen av datakällan liknar båda guiderna.

  1. Starta assistenten.

  2. På Anslut till dina data väljer eller verifierar du att datakälltypen antingen är Azure Cosmos DB eller ett NoSQL-konto.

    Namnet på datakällan refererar till datakällans anslutningsobjekt i Azure AI Search. Om du använder vektorguiden genereras datakällans namn automatiskt med ett anpassat prefix som anges i slutet av guidens arbetsflöde.

  3. Ange databasnamnet och samlingen. Frågan är valfri. Det är användbart om du har hierarkiska data och vill importera ett visst segment.

  4. Ange en autentiseringsmetod, antingen en hanterad identitet eller inbyggd API-nyckel. Om du inte anger en hanterad identitetsanslutning använder Azure Portal nyckeln.

    Om du konfigurerar Azure AI Search för att använda en hanterad identitet och du skapar en rolltilldelning i Cosmos DB som ger Cosmos DB-kontoläsaren och Cosmos DB inbyggda dataläsare behörigheter till identiteten, kan indexeraren ansluta till Cosmos DB med hjälp av Microsoft Entra-ID och roller.

  5. I guiden Importera och vektorisera data kan du ange alternativ för ändrings- och borttagningsspårning.

    Ändringsidentifiering stöds som standard via ett _ts fält (tidsstämpel). Om du laddar upp innehåll med den metod som beskrivs i Prova med exempeldata skapas samlingen med ett _ts fält.

    Borttagningsidentifiering kräver att du har ett befintligt fält på den översta nivån i samlingen som kan användas som en flagga för mjuk borttagning. Det bör vara ett booleskt fält (du kan ge det namnet IsDeleted). Ange true som värdet för mjuk borttagning. I sökindexet lägger du till ett motsvarande sökfält med namnet IsDeleted set till hämtningsbar och filterbar.

  6. Fortsätt med de återstående stegen för att slutföra guiden:

Använda REST-API:er

Det här avsnittet visar REST API-anrop som skapar en datakälla, ett index och en indexerare.

Definiera datakällan

Datakällans definition anger vilka data som ska indexeras, autentiseringsuppgifter och principer för att identifiera ändringar i data. En datakälla är en oberoende resurs som kan användas av flera indexerare.

  1. Skapa eller uppdatera en datakälla för att ange dess definition:

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-cosmos-db-collection]",
      "query": null
    },
    "dataChangeDetectionPolicy": {
      "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "  highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
}

  2. Ange "typ" till "cosmosdb" (krävs). Om du använder en äldre Search API-version 2017-11-11 är "documentdb"syntaxen för "type" . Annars använder du "cosmosdb"för 2019-05-06 och senare .

  3. Ange "autentiseringsuppgifter" till en anslutningssträng. I nästa avsnitt beskrivs de format som stöds.

  4. Ange "container" till samlingen. Egenskapen "name" krävs och anger ID för den databassamling som ska indexeras. Egenskapen "query" är valfri. Använd det för att platta ut ett godtyckligt JSON-dokument till ett platt schema som Azure AI Search kan indexera.

  5. Ange "dataChangeDetectionPolicy" om data är flyktiga och du vill att indexeraren bara ska hämta de nya och uppdaterade objekten vid efterföljande körningar.

  6. Ange "dataDeletionDetectionPolicy" om du vill ta bort sökdokument från ett sökindex när källobjektet tas bort.

Autentiseringsuppgifter och anslutningssträng som stöds

Indexerare kan ansluta till en samling med hjälp av följande anslutningar.

Undvik portnummer i slutpunkts-URL:en. Om du inkluderar portnumret misslyckas anslutningen.

Fullständig åtkomst anslutningssträng
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }`
Du kan hämta anslutningssträng från Azure Cosmos DB-kontosidan i Azure Portal genom att välja Nycklar i det vänstra navigeringsfönstret. Se till att välja en fullständig anslutningssträng och inte bara en nyckel.
Hanterad identitet anslutningssträng
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
Den här anslutningssträng kräver ingen kontonyckel, men du måste ha en söktjänst som kan ansluta med hjälp av en hanterad identitet. För anslutningar som riktar sig till SQL-API:et kan du utelämna ApiKind från anslutningssträng. Mer information om ApiKindfinns IdentityAuthType i Konfigurera en indexerareanslutning till en Azure Cosmos DB-databas med hjälp av en hanterad identitet.

Använda frågor för att forma indexerade data

I egenskapen "query" under "container" kan du ange en SQL-fråga för att platta ut kapslade egenskaper eller matriser, projekt-JSON-egenskaper och filtrera de data som ska indexeras.

Exempeldokument:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Filterfråga:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Platta ut fråga:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Projektionsfråga:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Matrisens utplattande fråga:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Frågor som inte stöds (DISTINCT och GROUP BY)

Frågor som använder DISTINCT-nyckelordet eller GROUP BY-satsen stöds inte. Azure AI Search förlitar sig på SQL-frågenumrering för att helt räkna upp resultatet av frågan. Varken DISTINCT-nyckelordet eller GROUP BY-satserna är kompatibla med fortsättningstoken som används för att sidnumrera resultat.

Exempel på frågor som inte stöds:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Även om Azure Cosmos DB har en lösning för att stödja SQL-frågenumrering med nyckelordet DISTINCT med hjälp av ORDER BY-satsen är den inte kompatibel med Azure AI Search. Frågan returnerar ett enda JSON-värde, medan Azure AI Search förväntar sig ett JSON-objekt.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Lägga till sökfält i ett index

I ett sökindex lägger du till fält för att acceptera JSON-källdokumenten eller utdata från din anpassade frågeprojektion. Kontrollera att sökindexschemat är kompatibelt med källdata. För innehåll i Azure Cosmos DB ska ditt sökindexschema motsvara Azure Cosmos DB-objekten i datakällan.

  1. Skapa eller uppdatera ett index för att definiera sökfält som lagrar data:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

  2. Skapa ett dokumentnyckelfält ("nyckel": sant). För partitionerade samlingar är standarddokumentnyckeln egenskapen Azure Cosmos DB _rid , som Azure AI Search automatiskt byter namn till rid eftersom fältnamn inte kan börja med ett understreck. Azure Cosmos DB-värden _rid innehåller också tecken som är ogiltiga i Azure AI Search-nycklar. Därför _rid är värdena Base64-kodade.

  3. Skapa fler fält för mer sökbart innehåll. Mer information finns i Skapa ett index .

Mappa datatyper

JSON-datatyper Fälttyper för Azure AI Search
Bool Edm.Boolean, Edm.String
Tal som ser ut som heltal Edm.Int32, Edm.Int64, Edm.String
Tal som ser ut som flyttalspunkter Edm.Double, Edm.String
String Edm.String
Matriser med primitiva typer som ["a", "b", "c"] Collection(Edm.String)
Strängar som ser ut som datum Edm.DateTimeOffset, Edm.String
GeoJSON-objekt som { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Andra JSON-objekt Ej tillämpligt

Konfigurera och köra Azure Cosmos DB för NoSQL-indexeraren

När indexet och datakällan har skapats är du redo att skapa indexeraren. Indexerarens konfiguration anger indata, parametrar och egenskaper som styr körningstidsbeteenden.

  1. Skapa eller uppdatera en indexerare genom att ge den ett namn och referera till datakällan och målindexet:

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Ange fältmappningar om det finns skillnader i fältnamn eller typ, eller om du behöver flera versioner av ett källfält i sökindexet.

  3. Mer information om andra egenskaper finns i Skapa en indexerare .

En indexerare körs automatiskt när den skapas. Du kan förhindra detta genom att ange "inaktiverad" till true. Om du vill kontrollera indexerarens körning kör du en indexerare på begäran eller sätter den enligt ett schema.

Kontrollera status för indexerare

Om du vill övervaka indexerarens status och körningshistorik kontrollerar du indexerarens körningshistorik i Azure Portal eller skickar rest-APIrequest för Get Indexer Status

  1. Öppna Indexerare för sökhantering>på söktjänstsidan.

  2. Välj en indexerare för att komma åt konfigurations- och körningshistoriken.

  3. Välj ett specifikt indexeringsjobb för att visa information, varningar och fel.

Körningshistoriken innehåller upp till 50 av de senast slutförda körningarna, som sorteras i omvänd kronologisk ordning så att den senaste körningen kommer först.

Indexera nya och ändrade dokument

När en indexerare har fyllt i ett sökindex helt kan det vara bra att efterföljande indexerare körs för att stegvis indexera bara de nya och ändrade dokumenten i databasen.

Om du vill aktivera inkrementell indexering anger du egenskapen "dataChangeDetectionPolicy" i datakälldefinitionen. Den här egenskapen talar om för indexeraren vilken mekanism för ändringsspårning som används för dina data.

För Azure Cosmos DB-indexerare är HighWaterMarkChangeDetectionPolicy den enda princip som stöds att använda _ts egenskapen (tidsstämpel) som tillhandahålls av Azure Cosmos DB.

I följande exempel visas en datakällans definition med en princip för ändringsidentifiering:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Kommentar

När du tilldelar ett null värde till ett fält i Azure Cosmos DB kan AI Search-indexeraren inte skilja mellan null och ett fältvärde som saknas. Om ett fält i indexet är tomt ersätts det därför inte med ett null värde, även om ändringen gjordes specifikt i databasen.

Inkrementell indexering och anpassade frågor

Om du använder en anpassad fråga för att hämta dokument kontrollerar du att frågan beställer resultatet efter _ts kolumnen. Detta möjliggör periodisk kontroll som Azure AI Search använder för att ge inkrementell förlopp i närvaro av fel.

I vissa fall, även om frågan innehåller en ORDER BY [collection alias]._ts -sats, kanske Azure AI Search inte kommer fram till att frågan sorteras efter _ts. Du kan berätta för Azure AI Search att resultaten ordnas genom att ange konfigurationsegenskapen assumeOrderByHighWaterMarkColumn .

Om du vill ange det här tipset skapar eller uppdaterar du indexerarens definition på följande sätt:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Indexera borttagna dokument

När rader tas bort från samlingen vill du normalt även ta bort dessa rader från sökindexet. Syftet med en princip för identifiering av databorttagning är att effektivt identifiera borttagna dataobjekt. För närvarande är Soft Delete den enda princip som stöds principen (borttagning markeras med en flagga av något slag), som anges i datakällans definition enligt följande:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Om du använder en anpassad fråga kontrollerar du att den egenskap som refereras av softDeleteColumnName projiceras av frågan.

Måste softDeleteColumnName vara ett fält på den översta nivån i indexet. Använda kapslade fält inom komplexa datatyper eftersom softDeleteColumnName de inte stöds.

I följande exempel skapas en datakälla med en princip för mjuk borttagning:

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Använda .NET

För data som nås via SQL API-protokollet kan du använda .NET SDK för att automatisera med indexerare. Vi rekommenderar att du läser de tidigare REST API-avsnitten för att lära dig begrepp, arbetsflöden och krav. Du kan sedan läsa följande .NET API-referensdokumentation för att implementera en JSON-indexerare i hanterad kod:

Nästa steg

Nu kan du styra hur du kör indexeraren, övervakar status eller schemalägger indexerarens körning. Följande artiklar gäller för indexerare som hämtar innehåll från Azure Cosmos DB: