Gegevens indexeren uit Azure Cosmos DB voor NoSQL voor query's in Azure AI Search

Artikel
01/18/2024

In dit artikel leert u hoe u een indexeerfunctie configureert waarmee inhoud uit Azure Cosmos DB voor NoSQL wordt geïmporteerd en hoe u deze doorzoekbaar maakt in Azure AI Search.

Dit artikel is een aanvulling op Het maken van een indexeerfunctie met informatie die specifiek is voor Cosmos DB. Hierbij worden de REST API's gebruikt om een driedelige werkstroom te demonstreren die gebruikelijk is voor alle indexeerfuncties: een gegevensbron maken, een index maken, een indexeerfunctie maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken verzendt.

Omdat terminologie verwarrend kan zijn, is het de moeite waard om te vermelden dat azure Cosmos DB-indexering en Azure AI Search-indexering verschillende bewerkingen zijn. Indexering in Azure AI Search maakt en laadt een zoekindex in uw zoekservice.

Vereisten

Een Azure Cosmos DB-account, -database, -container en -items. Gebruik dezelfde regio voor zowel Azure AI Search als Azure Cosmos DB voor lagere latentie en om bandbreedtekosten te voorkomen.
Een automatisch indexeringsbeleid voor de Azure Cosmos DB-verzameling, ingesteld op Consistent. Dit is de standaard configuratie. Luie indexering wordt niet aanbevolen en kan leiden tot ontbrekende gegevens.
Leesmachtigingen. Een 'volledige toegang' verbindingsreeks bevat een sleutel die toegang verleent tot de inhoud, maar als u Azure RBAC (Microsoft Entra ID) gebruikt, moet u ervoor zorgen dat aan de beheerde identiteit van de zoekservice zowel de rol lezer van het Cosmos DB-account als de ingebouwde gegevenslezerrol van Cosmos DB is toegewezen.
Een REST-client voor het maken van de gegevensbron, index en indexeerfunctie.

De gegevensbron definiëren

De definitie van de gegevensbron geeft de gegevens op die moeten worden geïndexeerde, referenties en beleidsregels voor het identificeren van wijzigingen in de gegevens. Een gegevensbron is een onafhankelijke resource die kan worden gebruikt door meerdere indexeerfuncties.

Een gegevensbron maken of bijwerken om de definitie ervan in te stellen:

POST https://[service name].search.windows.net/datasources?api-version=2023-11-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
}

Stel 'type' in op "cosmosdb" (vereist). Als u een oudere Zoek-API-versie 2017-11-11 gebruikt, is "documentdb"de syntaxis voor 'type'. Gebruik anders voor 2019-05-06 en hoger "cosmosdb".
Stel referenties in op een verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.
Stel 'container' in op de verzameling. De eigenschap 'name' is vereist en geeft de id van de databaseverzameling op die moet worden geïndexeerd. De eigenschap 'query' is optioneel. Gebruik het om een willekeurig JSON-document plat te maken in een plat schema dat Azure AI Search kan indexeren.
Stel dataChangeDetectionPolicy in als de gegevens vluchtig zijn en u wilt dat de indexeerfunctie alleen de nieuwe en bijgewerkte items ophaalt bij volgende uitvoeringen.
Stel 'dataDeletionDetectionPolicy' in als u zoekdocumenten uit een zoekindex wilt verwijderen wanneer het bronitem wordt verwijderd.

Ondersteunde referenties en verbindingsreeks s

Indexeerfuncties kunnen verbinding maken met een verzameling met behulp van de volgende verbindingen.

Vermijd poortnummers in de eindpunt-URL. Als u het poortnummer opneemt, mislukt de verbinding.

Volledige toegang verbindingsreeks
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>`" }'
U kunt de verbindingsreeks ophalen op de azure Cosmos DB-accountpagina in Azure Portal door Sleutels te selecteren in het linkernavigatiedeelvenster. Zorg ervoor dat u een volledige verbindingsreeks en niet alleen een sleutel selecteert.

Beheerde identiteit verbindingsreeks

Beheerde identiteit verbindingsreeks
`{ "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])" }`
Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet een zoekservice hebben die verbinding kan maken met een beheerde identiteit. Voor verbindingen die zijn gericht op de SQL-API, kunt u weglaten `ApiKind` uit de verbindingsreeks. Zie Voor meer informatie over `ApiKindIdentityAuthType`het instellen van een indexeerfunctieverbinding met een Azure Cosmos DB-database met behulp van een beheerde identiteit.

{ "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])" }

Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet een zoekservice hebben die verbinding kan maken met een beheerde identiteit. Voor verbindingen die zijn gericht op de SQL-API, kunt u weglaten ApiKind uit de verbindingsreeks. Zie Voor meer informatie over ApiKindIdentityAuthTypehet instellen van een indexeerfunctieverbinding met een Azure Cosmos DB-database met behulp van een beheerde identiteit.

Query's gebruiken om geïndexeerde gegevens vorm te geven

In de eigenschap 'query' onder 'container' kunt u een SQL-query opgeven om geneste eigenschappen of matrices, JSON-eigenschappen van het project te plat te maken en de gegevens te filteren die moeten worden geïndexeerd.

Voorbeelddocument:

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

Filterquery:

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

Afvlakkende query:

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

Projectiequery:

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

Matrix platmakende query:

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

Niet-ondersteunde query's (DISTINCT en GROUP BY)

Query's met behulp van het sleutelwoord DISTINCT of GROUP BY-component worden niet ondersteund. Azure AI Search is afhankelijk van paginering van SQL-query's om de resultaten van de query volledig op te sommen. Het sleutelwoord DISTINCT of group BY-componenten zijn niet compatibel met de vervolgtokens die worden gebruikt om resultaten te pagineren.

Voorbeelden van niet-ondersteunde query's:

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

Hoewel Azure Cosmos DB een tijdelijke oplossing heeft om paginering van SQL-query's te ondersteunen met het sleutelwoord DISTINCT met behulp van de ORDER BY-component, is deze niet compatibel met Azure AI Search. De query retourneert één JSON-waarde, terwijl Azure AI Search een JSON-object verwacht.

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

Zoekvelden toevoegen aan een index

Voeg in een zoekindex velden toe om de bron-JSON-documenten of de uitvoer van uw aangepaste queryprojectie te accepteren. Zorg ervoor dat het zoekindexschema compatibel is met brongegevens. Voor inhoud in Azure Cosmos DB moet uw zoekindexschema overeenkomen met de Azure Cosmos DB-items in uw gegevensbron.

Een index maken of bijwerken om zoekvelden te definiëren waarmee gegevens worden opgeslagen:

POST https://[service name].search.windows.net/indexes?api-version=2023-11-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
    }
  ]
}

Maak een documentsleutelveld ('sleutel': true'). Voor gepartitioneerde verzamelingen is de standaarddocumentsleutel de Azure Cosmos DB-eigenschap _rid , waarvan Azure AI Search automatisch een andere naam krijgt rid omdat veldnamen niet kunnen beginnen met een onderstrepingsteken. Azure Cosmos DB-waarden _rid bevatten ook tekens die ongeldig zijn in Azure AI Search-sleutels. Daarom zijn de _rid waarden base64 gecodeerd.
Maak meer velden voor meer doorzoekbare inhoud. Zie Een index maken voor meer informatie.

Toewijzingsgegevenstypen

JSON-gegevenstypen	Azure AI Search-veldtypen
Bool	Edm.Boolean, Edm.String
Getallen die eruitzien als gehele getallen	Edm.Int32, Edm.Int64, Edm.String
Getallen die eruitzien als drijvende punten	Edm.Double, Edm.String
String	Edm.String
Matrices van primitieve typen, zoals ["a", "b", "c"]	Collection(Edm.String)
Tekenreeksen die eruitzien als datums	Edm.DateTimeOffset, Edm.String
GeoJSON-objecten zoals { "type": "Point", "coördinaten": [long, lat] }	Edm.GeographyPoint
Andere JSON-objecten	N.v.t.

De Indexeerfunctie van Azure Cosmos DB for NoSQL configureren en uitvoeren

Zodra de index en de gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen aan die het gedrag van de uitvoeringstijd regelen.

Maak of werk een indexeerfunctie bij door deze een naam te geven en te verwijzen naar de gegevensbron en doelindex:

POST https://[service name].search.windows.net/indexers?api-version=2023-11-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
}

Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt.
Zie Een indexeerfunctie maken voor meer informatie over andere eigenschappen.

Een indexeerfunctie wordt automatisch uitgevoerd wanneer deze wordt gemaakt. U kunt dit voorkomen door 'uitgeschakeld' in te stellen op waar. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt controleren, verzendt u een get-indexeerstatusaanvraag :

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

Het antwoord bevat de status en het aantal verwerkte items. Het moet er ongeveer uitzien als in het volgende voorbeeld:

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

De uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in de omgekeerde chronologische volgorde worden gesorteerd, zodat de laatste uitvoering als eerste wordt uitgevoerd.

Nieuwe en gewijzigde documenten indexeren

Zodra een indexeerfunctie een zoekindex volledig heeft ingevuld, wilt u mogelijk dat de volgende indexeerfunctie alleen de nieuwe en gewijzigde documenten in uw database incrementeel indexeren.

Als u incrementele indexering wilt inschakelen, stelt u de eigenschap dataChangeDetectionPolicy in uw gegevensbrondefinitie in. Deze eigenschap vertelt de indexeerfunctie welk mechanisme voor het bijhouden van wijzigingen wordt gebruikt voor uw gegevens.

Voor Indexeerfuncties van Azure Cosmos DB is het enige ondersteunde beleid het HighWaterMarkChangeDetectionPolicy gebruik van de _ts eigenschap (timestamp) van Azure Cosmos DB.

In het volgende voorbeeld ziet u een definitie van een gegevensbron met een wijzigingsdetectiebeleid:

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

Incrementele indexering en aangepaste query's

Als u een aangepaste query gebruikt om documenten op te halen, moet u ervoor zorgen dat de query de resultaten op de _ts kolom bestelt. Dit maakt periodieke controlepunten mogelijk die door Azure AI Search worden gebruikt om incrementele voortgang te bieden in de aanwezigheid van fouten.

In sommige gevallen, zelfs als uw query een ORDER BY [collection alias]._ts component bevat, kan Azure AI Search mogelijk niet afleiden dat de query door de _tsquery is gerangschikt. U kunt Azure AI Search laten weten dat de resultaten worden gerangschikt door de assumeOrderByHighWaterMarkColumn configuratie-eigenschap in te stellen.

Als u deze hint wilt opgeven, maakt of werkt u de definitie van de indexeerfunctie als volgt bij:

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

Verwijderde documenten indexeren

Wanneer rijen uit de verzameling worden verwijderd, wilt u deze rijen normaal gesproken ook uit de zoekindex verwijderen. Het doel van een beleid voor het detecteren van gegevensverwijdering is om verwijderde gegevensitems efficiënt te identificeren. Op dit moment is het enige ondersteunde beleid het Soft Delete beleid (verwijderen is gemarkeerd met een vlag van een bepaalde soort), die als volgt is opgegeven in de definitie van de gegevensbron:

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

Als u een aangepaste query gebruikt, moet u ervoor zorgen dat de eigenschap waarnaar wordt verwezen softDeleteColumnName door de query wordt geprojecteerd.

Het softDeleteColumnName moet een veld op het hoogste niveau in de index zijn. Het gebruik van geneste velden binnen complexe gegevenstypen, omdat dit softDeleteColumnName niet wordt ondersteund.

In het volgende voorbeeld wordt een gegevensbron gemaakt met een beleid voor voorlopig verwijderen:

POST https://[service name].search.windows.net/datasources?api-version=2023-11-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"
    }
}

.NET gebruiken

Voor gegevens die worden geopend via het SQL API-protocol, kunt u de .NET SDK gebruiken om te automatiseren met indexeerfuncties. U wordt aangeraden de vorige REST API-secties te bekijken voor meer informatie over concepten, werkstromen en vereisten. U kunt vervolgens verwijzen naar de volgende .NET API-referentiedocumentatie voor het implementeren van een JSON-indexeerfunctie in beheerde code:

Volgende stappen

U kunt nu bepalen hoe u de indexeerfunctie uitvoert, de status bewaakt of de uitvoering van de indexeerfunctie plant. De volgende artikelen zijn van toepassing op indexeerfuncties die inhoud ophalen uit Azure Cosmos DB: