Delen via

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

  • Artikel

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. Azure Portal en REST API's worden 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

Als u de voorbeelden in dit artikel wilt doorlopen, hebt u Azure Portal of een REST-client nodig. Als u Azure Portal gebruikt, moet u ervoor zorgen dat toegang tot alle openbare netwerken is ingeschakeld. Andere methoden voor het maken van een Cosmos DB-indexeerfunctie zijn Azure SDK's.

Proberen met voorbeeldgegevens

Gebruik deze instructies om een container en database te maken in Cosmos DB voor testdoeleinden.

  1. Download HotelsData_toCosmosDB.JSON van GitHub om een container te maken in Cosmos DB die een subset van de gegevensset met voorbeeldhotels bevat.

  2. Meld u aan bij Azure Portal en maak een account, database en container in Cosmos DB.

  3. Selecteer Data Explorer voor de nieuwe container in Cosmos DB en geef de volgende waarden op.

    Eigenschappen Weergegeven als
    Database Nieuwe
    Database-id hotelsdb
    Doorvoer delen tussen containers Niet selecteren
    Container-id hotels
    Partitiesleutel /HotelId
    Containerdoorvoer (automatisch schalen) Automatisch schalen
    Maximum aantal RU/s voor containers 1000

  4. Vouw in Data Explorer hotelsdb en *hotels uit en selecteer vervolgens Items.

  5. Selecteer Item uploaden en selecteer vervolgens HotelsData_toCosmosDB.JSON bestand dat u hebt gedownload vanuit GitHub.

  6. Klik met de rechtermuisknop op Items en selecteer Nieuwe SQL-query. De standaardquery is SELECT * FROM c.

  7. Selecteer Query uitvoeren om de query uit te voeren en resultaten weer te geven. U moet 50 hoteldocumenten hebben.

Nu u een container hebt, kunt u de Azure-portal, REST-client of een Azure SDK gebruiken om uw gegevens te indexeren.

Het veld Beschrijving biedt de meest uitgebreide inhoud. U moet dit veld richten op zoekopdrachten in volledige tekst en optionele vectorquery's.

De Azure-portal gebruiken

U kunt de wizard Gegevens importeren of de wizard Gegevens importeren en vectoriseren gebruiken om indexering vanuit een SQL-databasetabel of -weergave te automatiseren. De configuratie van de gegevensbron is vergelijkbaar voor beide wizards.

  1. De wizard starten.

  2. Bij Verbinding maken met uw gegevens selecteert of controleert u of het gegevensbrontype Azure Cosmos DB of een NoSQL-account is.

    De naam van de gegevensbron verwijst naar het verbindingsobject voor de gegevensbron in Azure AI Search. Als u de vectorwizard gebruikt, wordt de naam van uw gegevensbron automatisch gegenereerd met behulp van een aangepast voorvoegsel dat is opgegeven aan het einde van de wizardwerkstroom.

  3. Geef de naam en verzameling van de database op. De query is optioneel. Het is handig als u hiërarchische gegevens hebt en u een specifiek segment wilt importeren.

  4. Geef een verificatiemethode op, ofwel een beheerde identiteit of ingebouwde API-sleutel. Als u geen beheerde identiteitsverbinding opgeeft, gebruikt Azure Portal de sleutel.

    Als u Azure AI Search configureert voor het gebruik van een beheerde identiteit en u een roltoewijzing maakt in Cosmos DB die cosmos DB-accountlezer- en Cosmos DB-machtigingen voor ingebouwde gegevenslezer toekent aan de identiteit, kan uw indexeerfunctie verbinding maken met Cosmos DB met behulp van Microsoft Entra-id en -rollen.

  5. Voor de wizard Gegevens importeren en vectoriseren kunt u opties opgeven voor het bijhouden van wijzigingen en verwijderingen.

    Wijzigingsdetectie wordt standaard ondersteund via een _ts veld (tijdstempel). Als u inhoud uploadt met behulp van de methode die wordt beschreven in Try with sample data, wordt de verzameling gemaakt met een _ts veld.

    Verwijderingsdetectie vereist dat u een vooraf bestaand veld op het hoogste niveau in de verzameling hebt die kan worden gebruikt als een vlag voor voorlopig verwijderen. Het moet een Booleaans veld zijn (u kunt het isDeleted een naam geven). Geef true op als de voorlopig verwijderde waarde. Voeg in de zoekindex een bijbehorend zoekveld met de naam IsDeleted toe dat deze kan worden opgehaald en gefilterd.

  6. Ga verder met de resterende stappen om de wizard te voltooien:

De REST API’s gebruiken

In deze sectie ziet u de REST API-aanroepen die een gegevensbron, index en indexeerfunctie maken.

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.

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

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

  3. Stel referenties in op een verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.

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

  5. Stel dataChangeDetectionPolicy in als de gegevens vluchtig zijn en u wilt dat de indexeerfunctie alleen de nieuwe en bijgewerkte items ophaalt bij volgende uitvoeringen.

  6. 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.
(Moderne benadering) Beheerde identiteit verbindingsreeks voor NoSQL-accounts
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccessToken)" }
Deze verbindingsreeks, die alleen worden ondersteund voor Azure Cosmos DB voor NoSQL-accounts, zorgt ervoor dat de zoekservice nooit accountsleutels (zelfs op de achtergrond) gebruikt bij het openen van gegevens uit Cosmos DB. Dit wordt aanbevolen, omdat dit werkt, zelfs als het NoSQL-account accountsleutels heeft uitgeschakeld. Zie Een indexeerfunctieverbinding met een Azure Cosmos DB-database instellen met behulp van een beheerde identiteit voor meer informatie
(Verouderde benadering) 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=AccountKey)" }
Deze verbindingsreeks vereist niet dat er rechtstreeks een accountsleutel wordt opgegeven, maar de zoekservice gebruikt de beheerde identiteit om de accountsleutels op de achtergrond op te halen. Hoewel dit wordt ondersteund voor alle Cosmos DB-accounttypen, wordt dit niet aanbevolen voor het NoSQL-accounttype. Een dergelijke verbindingsreeks werkt niet als accountsleutels zijn uitgeschakeld voor het Cosmos DB-account. Als de IdentityAuthType eigenschap wordt weggelaten, wordt de standaardwaarde van de zoekservice nog steeds gebruikt om de accountsleutel op de achtergrond op te halen. Voor verbindingen die zijn gericht op de SQL-API, kunt u weglaten ApiKind uit de verbindingsreeks. Zie Voor meer informatie over ApiKindhet IdentityAuthType 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.

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

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

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

  1. 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=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. Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt.

  3. 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, controleert u de uitvoeringsgeschiedenis van de indexeerfunctie in Azure Portal of verzendt u een GET Indexer Status REST APIrequest

  1. Open zoekbeheerindexeerfuncties> op de pagina van de zoekservice.

  2. Selecteer een indexeerfunctie voor toegang tot de configuratie- en uitvoeringsgeschiedenis.

  3. Selecteer een specifieke indexeerfunctie om details, waarschuwingen en fouten weer te geven.

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

Notitie

Wanneer u een null waarde toewijst aan een veld in uw Azure Cosmos DB, kan de AI Search-indexeerfunctie geen onderscheid maken tussen null en een ontbrekende veldwaarde. Als een veld in de index leeg is, wordt dit dus niet vervangen door een null waarde, zelfs niet als die wijziging is aangebracht in uw database.

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

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