Indizieren von Daten aus Azure Cosmos DB für Apache Gremlin für Abfragen in Azure KI-Suche
Wichtig
Der Azure Cosmos DB for Apache Gremlin-Indexer befindet sich derzeit in der öffentlichen Vorschauphase und unterliegt zusätzlichen Nutzungsbestimmungen. Derzeit gibt es keine SDK-Unterstützung.
In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus Azure Cosmos DB für Apache Gremlin importiert und sie in Azure AI Search durchsuchbar macht.
Dieser Artikel ergänzt den Artikel Erstellen von Indexern mit Informationen, die Cosmos DB-spezifisch sind. Er verwendet die REST-APIs, um einen dreiteiligen Workflow zu veranschaulichen, der allen Indexern gemeinsam ist: Erstellen einer Datenquelle, Erstellen eines Indexes und Erstellen eines Indexers. Die Datenextraktion erfolgt, wenn Sie die Anforderung für die Indexererstellung übermitteln.
Da die Terminologie verwirrend sein kann, sei darauf hingewiesen, dass Azure Cosmos DB-Indizierung und Azure AI Search-Indizierung unterschiedliche Vorgänge sind. Die Indexierung in Azure AI Search erstellt und lädt einen Suchindex auf Ihren Suchdienst.
Voraussetzungen
Registrieren Sie sich für die Preview, um Feedback zum Szenario zu geben. Sie können die Funktion automatisch nach dem Absenden des Formulars aufrufen.
Ein Azure Cosmos DB-Konto, eine Datenbank, einen Container und Elemente. Verwenden Sie dieselbe Region für Azure AI Search und Azure Cosmos DB, um die Latenz zu verringern und Bandbreitengebühren zu vermeiden.
Eine auf Konsistent festgelegte automatische Indizierungsrichtlinie für die Azure Cosmos DB-Sammlung. Dies ist die Standardkonfiguration. Verzögerte Indizierung wird nicht empfohlen und kann zu fehlenden Daten führen.
Leseberechtigungen. Eine Vollzugriff-Verbindungszeichenfolge enthält einen Schlüssel, der Zugriff auf den Inhalt gewährt. Wenn Sie jedoch Azure-Rollen verwenden, stellen Sie sicher, dass die verwaltete Identität des Suchdiensts über die Berechtigungen der Cosmos DB-Rolle „Kontoleser“ verfügt.
Ein REST-Client, um die Datenquelle, den Index und den Indexer zu erstellen.
Definieren der Datenquelle
Die Datenquellendefinition gibt die zu indizierenden Daten, die Anmeldeinformationen und die Richtlinien für die Identifizierung von Datenänderungen an. Eine Datenquelle wird als unabhängige Ressource definiert, sodass sie von mehreren Indexern verwendet werden kann.
Geben Sie für diesen Aufruf eine REST-API-Vorschauversion an, um eine Datenquelle zu erstellen, die über Azure Cosmos DB for Apache Gremlin verbunden ist. Sie können 2021-04-01-preview oder höher verwenden. Wir empfehlen die neueste Vorschau-API.
Erstellen oder aktualisieren Sie eine Datenquelle, um ihre Definition festzulegen:
POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-gremlin-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;" }, "container": { "name": "[cosmos-db-collection]", "query": "g.V()" }, "dataChangeDetectionPolicy": { "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName": "_ts" }, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null } }
Legen Sie "type" auf
"cosmosdb"
fest (erforderlich).Legen Sie „credentials“ auf eine Verbindungszeichenfolge fest. Im nächsten Abschnitt werden die unterstützten Formate beschrieben.
Legen Sie „container“ auf die Auflistung fest. Die Eigenschaft „name“ ist erforderlich und gibt die ID des Graphen an.
Die Eigenschaft „query“ ist optional. Standardmäßig macht der Azure AI Search Indexer für Azure Cosmos DB for Apache Gremlin jeden Vertex in Ihrem Graphen zu einem Dokument im Index. Kanten werden ignoriert. Der Standardwert der Abfrage ist
g.V()
. Alternativ können Sie die Abfrage so festlegen, dass nur die Kanten indexiert werden. Um die Kanten zu indexieren, setzen Sie die Abfrage aufg.E()
.Legen Sie „dataChangeDetectionPolicy“ fest, wenn Daten flüchtig sind und der Indexer bei nachfolgenden Läufen immer nur die neuen und aktualisierten Elemente erfassen soll. Standardmäßig wird der inkrementelle Fortschritt aktiviert, indem
_ts
als Spalte für die Hochwassermarke verwendet wird.Legen Sie „dataDeletionDetectionPolicy“ fest, wenn Sie Suchdokumente aus einem Suchindex entfernen möchten, wenn das Quellelement gelöscht wird.
Unterstützte Anmeldeinformationen und Verbindungszeichenfolgen
Indexer können mithilfe der folgenden Verbindungen eine Verbindung mit einer Sammlung herstellen. Stellen Sie bei Verbindungen mit dem Ziel Azure Cosmos DB for Apache Gremlin sicher, dass Sie „ApiKind“ in die Verbindungszeichenfolge einschließen.
Vermeiden Sie Portnummern in der Endpunkt-URL. Wenn Sie die Portnummer einschließen, tritt beim Herstellen der Verbindung ein Fehler auf.
„Vollzugriff“-Verbindungszeichenfolge |
---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" } |
Sie können die Verbindungszeichenfolge von der Azure Cosmos DB-Kontoseite im Azure-Portal abrufen, indem Sie im linken Navigationsbereich die Option Schlüssel auswählen. Stellen Sie sicher, dass Sie eine vollständige Verbindungszeichenfolge und nicht nur einen Schlüssel auswählen. |
Verbindungszeichenfolge für verwaltete Identitäten |
---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
Diese Verbindungszeichenfolge erfordert keinen Kontoschlüssel, aber Sie müssen zuvor einen Suchdienst für die Verbindungsherstellung mithilfe einer verwalteten Identität konfiguriert und eine Rollenzuweisung erstellt haben, die Berechtigungen der Cosmos DB-Rolle „Kontoleser“ gewährt. Weitere Informationen finden Sie unter Einrichten einer Indexerverbindung mit einer Azure Cosmos DB-Datenbank mithilfe einer verwalteten Identität. |
Hinzufügen von Suchfeldern zu einem Index
Fügen Sie in einem Suchindex Felder hinzu, um die JSON-Quelldokumente oder die Ausgabe Ihrer benutzerdefinierten Abfrageprojektion zu akzeptieren. Stellen Sie sicher, dass das Suchindexschema mit Ihrem Graphen kompatibel ist. Für Inhalte in Azure Cosmos DB muss Ihr Suchindexschema den Azure Cosmos DB-Elementen in Ihrer Datenquelle entsprechen.
Erstellen oder aktualisieren Sie einen Index, um Suchfelder zu definieren, in denen Daten gespeichert werden:
POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [ { "name": "rid", "type": "Edm.String", "facetable": false, "filterable": false, "key": true, "retrievable": true, "searchable": true, "sortable": false, "analyzer": "standard.lucene", "indexAnalyzer": null, "searchAnalyzer": null, "synonymMaps": [], "fields": [] },{ }, { "name": "label", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false, "key": false, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": "standard.lucene", "synonymMaps": [] }] }
Erstellen Sie ein Dokumentschlüsselfeld („key“: true). Bei partitionierten Sammlungen ist der Standarddokumentschlüssel die Azure Cosmos DB
_rid
-Eigenschaft, die Azure AI Search automatisch inrid
umbenennt, da Feldnamen nicht mit einem Unterstrich beginnen dürfen. Außerdem enthalten Azure Cosmos DB_rid
-Werte Zeichen, die in Azure AI Search-Schlüsseln ungültig sind. Deshalb sind die_rid
-Werte Base64-codiert.Erstellen Sie zusätzliche Felder für mehr durchsuchbare Inhalte. Weitere Informationen finden Sie unter Erstellen eines Suchindex in Azure Cognitive Search.
Abbildung von Datentypen
JSON-Datentyp | Azure AI Search Feldtypen |
---|---|
Bool | Edm.Boolean, Edm.String |
Zahlen, die wie Ganzzahlen aussehen | Edm.Int32, Edm.Int64, Edm.String |
Zahlen, die wie Gleitkommas aussehen | Edm.Double, Edm.String |
String | Edm.String |
Arrays primitiver Typen, z. B ["a", "b", "c"] | Collection(Edm.String) |
Zeichenfolgen, die wie Datumsangaben aussehen | Edm.DateTimeOffset, Edm.String |
GeoJSON-Objekte z. B. { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
Andere JSON-Objekte | Nicht zutreffend |
Konfigurieren und Ausführen des Azure Cosmos DB-Indexers
Nach der Erstellung von Index und Datenquelle können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern.
Erstellen oder aktualisieren Sie den Indexer, indem Sie ihm einen Namen geben und einen Verweis auf die Datenquelle und den Zielindex hinzufügen:
POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-gremlin-ds]", "targetIndexName" : "[my-search-index]", "disabled": null, "schedule": null, "parameters": { "batchSize": null, "maxFailedItems": 0, "maxFailedItemsPerBatch": 0, "base64EncodeKeys": false, "configuration": {} }, "fieldMappings": [], "encryptionKey": null }
Geben Sie Feldzuordnungen an, wenn es Unterschiede beim Feldnamen oder -typ gibt, oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen.
Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen von Indexern in Azure Cognitive Search.
Ein Indexer wird automatisch ausgeführt, wenn er erstellt wird. Sie können dies verhindern, indem Sie „disabled“ (Deaktiviert) auf „true“ festlegen. Um die Ausführung des Indexers zu steuern, führen Sie einen Indexer nach Bedarf aus, oder legen Sie für ihn einen Zeitplan fest.
Überprüfen des Indexerstatus
Um den Indexerstatus und den Ausführungsverlauf zu überwachen, senden Sie eine Anforderung zum Abrufen des Indexerstatus:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]
Die Antwort enthält den Status und die Anzahl der verarbeiteten Elemente. Sie sollte in etwa wie das folgende Beispiel aussehen:
{
"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
]
}
Der Ausführungsverlauf enthält bis zu 50 der zuletzt abgeschlossenen Ausführungen. Diese sind in umgekehrter chronologischer Reihenfolge sortiert, sodass die neueste Ausführung als Erstes aufgelistet wird.
Indizieren neuer und geänderter Dokumente
Wenn ein Indexer einen Suchindex vollständig aufgefüllt hat, sollen bei nachfolgenden Indexerausführungen möglicherweise nur die neuen und geänderten Dokumente in Ihrer Datenbank inkrementell indiziert werden.
Um die inkrementelle Indizierung zu aktivieren, legen Sie die Eigenschaft „dataChangeDetectionPolicy“ in Ihrer Datenquellendefinition fest. Diese Eigenschaft teilt dem Indexer mit, welcher Mechanismus für die Änderungsnachverfolgung für Ihre Daten verwendet wird.
Für Azure Cosmos DB-Indexer wird nur die Richtlinie HighWaterMarkChangeDetectionPolicy
unterstützt, bei der die von Azure Cosmos DB bereitgestellte Eigenschaft _ts
(Zeitstempel) verwendet wird.
Das folgende Beispiel zeigt eine Datenquellendefinition mit einer Änderungserkennungsrichtlinie:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
Indizieren von gelöschten Dokumenten
Wenn Diagrammdaten gelöscht werden, sollten Sie eventuell auch das zugehörige Dokument aus dem Suchindex löschen. Der Zweck einer Richtlinie zur Erkennung von Datenlöschung besteht darin, gelöschte Datenelemente effizient zu identifizieren und das vollständige Dokument aus dem Index zu löschen. Die Richtlinie zur Erkennung von Datenlöschung dient nicht zum Löschen teilweiser Dokumentinformationen. Zurzeit ist Soft Delete
die einzige unterstützte Richtlinie (die Löschung wird durch ein bestimmtes Kennzeichen markiert), die in der Datenquellendefinition folgendermaßen festgelegt wird:
"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"
}
Im folgenden Beispiel wird eine Datenquelle mit einer Richtlinie zum vorläufigen Löschen erstellt:
POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
"name": "[my-cosmosdb-gremlin-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
},
"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"
}
}
Auch wenn Sie die Löscherkennungsrichtlinie aktivieren, wird das Löschen komplexer (Edm.ComplexType
) Felder aus dem Index nicht unterstützt. Diese Richtlinie erfordert, dass die Spalte „aktiv“ in der Gremlin-Datenbank vom Typ Integer, Zeichenfolge oder boolescher Wert sein soll.
Zuordnen von Graphdaten zu Feldern in einem Suchindex
Der Azure Cosmos DB for Apache Gremlin-Indexer ordnet einige Diagrammdaten automatisch zu:
Der Indexer ordnet
_rid
dem Feldrid
im Index zu (sofern vorhanden) und wendet eine Base64-Codierung an.Der Indexer wird
_id
einem Feld im Indexid
zugeordnet, sofern vorhanden.Beim Abfragen Ihrer Azure Cosmos DB-Datenbank mit Azure Cosmos DB for Apache Gremlin stellen Sie möglicherweise fest, dass die JSON-Ausgabe für jede Eigenschaft eine
id
und einenvalue
enthält. Der Indexer ordnet dievalue
-Eigenschaften automatisch einem Feld in Ihrem Suchindex zu, das den gleichen Namen wie die Eigenschaft hat, sofern es vorhanden ist. In dem folgenden Beispiel würde 450 auf einpages
-Feld im Suchindex abgebildet werden.
{
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6285-a145-42c8-a0aa-d39079277b71",
"value": "450"
}
]
}
}
Möglicherweise müssen Sie Output Field Mappings verwenden, um Ihre Abfrageausgabe auf die Felder in Ihrem Index abzubilden. Wahrscheinlich werden Sie Output Field Mappings statt Field Mappings verwenden wollen, da die benutzerdefinierte Abfrage wahrscheinlich komplexe Daten enthalten wird.
Angenommen, Ihre Abfrage erzeugt die folgende Ausgabe:
[
{
"vertex": {
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6085-a211-42d8-a8ea-d38642987a71",
"value": "450"
}
],
}
},
"written_by": [
{
"yearStarted": "2017"
}
]
}
]
Falls Sie den Wert von pages
im obigen JSON auf ein totalpages
Feld in Ihrem Index zuordnen möchten, können Sie die folgende Ausgabefeldzuordnung zu Ihrer Indexerdefinition hinzufügen:
... // rest of indexer definition
"outputFieldMappings": [
{
"sourceFieldName": "/document/vertex/pages",
"targetFieldName": "totalpages"
}
]
Achten Sie darauf, dass das Output Field Mapping mit /document
beginnt und keinen Verweis auf den Eigenschaftenschlüssel im JSON enthält. Dies geschieht, weil der Indexer beim Einlesen der Diagrammdaten jedes Dokument unter den /document
-Knoten legt und der Indexer es Ihnen zudem automatisch ermöglicht, den Wert von pages
durch einfaches Referenzieren von pages
zu referenzieren, anstatt auf das erste Objekt im Array von pages
verweisen zu müssen.
Nächste Schritte
Weitere Informationen zu Azure Cosmos DB for Apache Gremlin finden Sie unter Einführung in Azure Cosmos DB: Azure Cosmos DB for Apache Gremlin.
Weitere Informationen über Azure AI Search-Szenarien und Preise finden Sie auf der Seite Search service auf azure.microsoft.com.
Informationen zur Netzwerkkonfiguration für Indexer finden Sie unter Indexerzugriff auf Datenquellen mit Azure-Netzwerksicherheitsfeatures.