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

Artikel
09/01/2024

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 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 Azure RBAC (Microsoft Entra ID) kontrollerar du att söktjänstens hanterade identitet har tilldelats både Cosmos DB-kontoläsarrollen och den inbyggda dataläsarrollen i Cosmos DB.
En REST-klient för att skapa datakällan, indexet och indexeraren.

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.

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
}

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 .
Ange "autentiseringsuppgifter" till en anslutningssträng. I nästa avsnitt beskrivs de format som stöds.
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.
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.
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

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 `ApiKind`finns `IdentityAuthType` i Konfigurera en indexerareanslutning till en Azure Cosmos DB-databas med hjälp av en hanterad identitet.

{ "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.

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
    }
  ]
}

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.
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.

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
}

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.
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 skickar du en get indexer-statusbegäran :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

Svaret innehåller status och antalet bearbetade objekt. Det bör se ut ungefär som i följande exempel:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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 i komplexa datatyper eftersom det softDeleteColumnName 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:

Dela via