Indizieren von Daten aus Azure Cosmos DB für Apache Gremlin für Abfragen in Azure KI-Suche (Vorschau)

Note

Azure KI-Suche ist über das Azure Portal, REST-APIs und Azure SDKs verfügbar. Es unterstützt auch Foundry IQ, die verwaltete Wissensschicht, die Unternehmensinhalte in wiederverwendbare, berechtigungsfähige Wissensbasen für Agenten im Microsoft Foundry-Portal transformiert.

Wichtig

Features, Funktionen oder Eigenschaften, die als (Vorschau) gekennzeichnet sind, werden von keiner Dienstebenenvereinbarung (SLA) abgedeckt, werden für Produktionsworkloads nicht empfohlen und können geändert oder eingeschränkt werden, bevor sie allgemein verfügbar sind. Die Azure KI-Suche Vorschaubedingungen gelten für alle Vorschaufunktionen, unabhängig davon, ob sie eigenständig oder Teil eines allgemein verfügbaren Features ist.

Wichtig

Diese Features und Funktionen unterstützen Verbindungen mit anderen Microsoft-Dienste und Drittanbieterdiensten. Die Nutzung dieser Dienste unterliegt den jeweiligen Bestimmungen und kann dazu führen, dass Daten außerhalb der Azure-Compliancegrenze verarbeitet oder gespeichert werden und dass Daten in die Azure-Compliancegrenze fließen.

Es liegt in Ihrer Verantwortung, zu verwalten, ob Ihre Daten außerhalb der Compliance- und geografischen Grenzen Ihrer Organisation und alle damit verbundenen Auswirkungen fließen und dass entsprechende Berechtigungen, Grenzen und Genehmigungen bereitgestellt werden.

Sie sind dafür verantwortlich, Anwendungen, die Sie im Kontext Ihrer spezifischen Anwendungsfälle erstellen, sorgfältig zu überprüfen und zu testen und alle geeigneten Entscheidungen und Anpassungen zu treffen. Dazu gehört die Implementierung ihrer eigenen verantwortungsvollen KI-Entschärfungen, wie Metaprompts, Inhaltsfilter oder andere Sicherheitssysteme, und sicherzustellen, dass Ihre Anwendungen angemessene Qualität, Zuverlässigkeit, Sicherheit und Vertrauenswürdigkeitsstandards erfüllen. Weitere Informationen finden Sie im Azure KI-Suche Transparenzhinweis.

Die Azure Cosmos DB für Apache Gremlin Indexer (Vorschau) importiert Inhalte aus Azure Cosmos DB für Apache Gremlin und macht sie in Azure KI-Suche durchsuchbar.

Dieser Artikel ergänzt das Erstellen eines Indexers mit Informationen, die für Cosmos DB spezifisch sind. Es verwendet die REST-APIs, um einen dreiteiligen Workflow zu veranschaulichen, der allen Indexern gemeinsam ist: Erstellen einer Datenquelle, Erstellen eines Indexes, Erstellen eines Indexers. Die Datenextraktion tritt auf, wenn Sie die Anforderung zum Erstellen von Indexer übermitteln.

Da die Terminologie verwirrend sein kann, ist es erwähnenswert, dass Azure Cosmos DB Indizierung und Azure KI-Suche Indizierung unterschiedliche Vorgänge sind. Die Indizierung in Azure KI-Suche erstellt und lädt einen Suchindex in Ihrem Suchdienst.

Voraussetzungen

Definieren der Datenquelle

Die Datenquellendefinition gibt die Daten an, die indiziert werden sollen, Anmeldeinformationen und Richtlinien zum Identifizieren von Änderungen in den Daten. Eine Datenquelle wird als unabhängige Ressource definiert, sodass sie von mehreren Indexern verwendet werden kann.

Geben Sie für diesen Aufruf eine Vorschau-REST-API-Version an, um eine Datenquelle zu erstellen, die über Azure Cosmos DB für Apache Gremlin eine Verbindung herstellt. Sie können 2021-04-01-preview oder höher verwenden. Wir empfehlen die neueste Vorschau-REST-API.

  1. Erstellen oder Aktualisieren einer Datenquelle zum Festlegen der Definition:

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

  2. Legen Sie "Type" auf "cosmosdb" (erforderlich) fest.

  3. Legen Sie „credentials“ auf eine Verbindungszeichenfolge fest. Im nächsten Abschnitt werden die unterstützten Formate beschrieben.

  4. Legen Sie „container“ auf die Auflistung fest. Die Eigenschaft "name" ist erforderlich und gibt die ID des Diagramms an.

    Die Eigenschaft "query" ist optional. Standardmäßig macht der Azure KI-Suche Indexer für Azure Cosmos DB für Apache Gremlin jeden Scheitelpunkt in Ihrem Diagramm zu einem Dokument im Index. Kanten werden ignoriert. Der Abfragestandard ist g.V(). Alternativ können Sie die Abfrage so festlegen, dass nur die Kanten indiziert werden. Zum Indizieren der Ränder legen Sie die Abfrage auf g.E().

  5. Legen Sie "dataChangeDetectionPolicy" fest, wenn Ihre Daten veränderlich sind und der Indexer nur die neuen und aktualisierten Elemente bei nachfolgenden Ausführungen aufnehmen soll. Standardmäßig ist der inkrementelle Fortschritt aktiviert, indem _ts als Spalte für die Obergrenzenmarkierung verwendet wird.

  6. 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 Auflistung herstellen. Achten Sie bei Verbindungen, die auf Azure Cosmos DB für Apache Gremlin abzielen, unbedingt darauf, "ApiKind" in die Verbindungszeichenfolge einzufügen.

Vermeiden Sie Portnummern in der Endpunkt-URL. Wenn Sie die Portnummer einschließen, tritt beim Herstellen der Verbindung ein Fehler auf.

Vollzugriffs-Verbindungszeichenfolge
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" }
Sie können die Verbindungszeichenfolge über die Azure Cosmos DB Kontoseite im Azure Portal abrufen, indem Sie im linken Bereich Keys auswählen. Stellen Sie sicher, dass Sie eine vollständige Verbindungszeichenfolge und nicht nur einen Schlüssel auswählen.
Verwaltete Identitäts-Verbindungszeichenfolge
{ "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 zu einer Azure Cosmos DB-Datenbank mit 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 Diagramm kompatibel ist. Für Inhalte in Azure Cosmos DB sollte Ihr Suchindexschema den Azure Cosmos DB Items in Der Datenquelle entsprechen.

  1. 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=2026-08-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": []
    }]
  }

  2. Erstellen Sie ein Dokumentschlüsselfeld ("Schlüssel": true). Bei partitionierten Auflistungen ist der Standarddokumentschlüssel die eigenschaft Azure Cosmos DB _rid, die Azure KI-Suche automatisch in rid umbenannt wird, da Feldnamen nicht mit einem Unterstrich beginnen können. Außerdem enthalten Azure Cosmos DB _rid-Werte Zeichen, die in Azure KI-Suche-Schlüsseln ungültig sind. Aus diesem Grund sind die _rid Werte Base64-codiert.

  3. Erstellen Sie zusätzliche Felder für mehr durchsuchbare Inhalte. Details finden Sie unter Erstellen eines Indexes .

Zuordnen von Datentypen

JSON-Datentyp Azure KI-Suche Feldtypen
Bool Edm.Boolean, Edm.String
Zahlen, die wie ganze Zahlen aussehen Edm.Int32, Edm.Int64, Edm.String
Zahlen, die wie Gleitkommapunkte aussehen Edm.Double, Edm.String
Schnur Edm.String
Arrays von Grundtypen wie ["a", "b", "c"] Collection(Edm.String)
Zeichenfolgen, die wie Datumsangaben aussehen Edm.DateTimeOffset, Edm.String
GeoJSON-Objekte wie { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Andere JSON-Objekte N/A

Konfigurieren und Ausführen des Azure Cosmos DB Indexers

Nachdem der Index und die Datenquelle erstellt wurden, können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern.

  1. Erstellen oder aktualisieren Sie einen Indexer , indem Sie ihm einen Namen geben und auf die Datenquelle und den Zielindex verweisen:

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

  2. Geben Sie Feldzuordnungen an, wenn Es Unterschiede im Feldnamen oder Typ gibt oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen.

  3. Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen eines Indexers .

Ein Indexer wird automatisch ausgeführt, wenn er erstellt wird. Sie können dies verhindern, indem Sie "deaktiviert" auf "true" festlegen. Um die Indexerausführung zu steuern, führen Sie einen Indexer bei Bedarf aus, oder setzen Sie ihn in einen Zeitplan.

Indexerstatus überprüfen

Um den Indexerstatus und den Ausführungsverlauf zu überwachen, senden Sie eine Get Indexer Status-Anforderung :

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

Die Antwort enthält den Status und die Anzahl der verarbeiteten Elemente. Es sollte ähnlich wie im folgenden 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, die in umgekehrter chronologischer Reihenfolge sortiert sind, sodass die neueste Ausführung zuerst erfolgt.

Indizieren neuer und geänderter Dokumente

Nachdem ein Indexer einen Suchindex vollständig aufgefüllt hat, möchten Sie möglicherweise, dass nachfolgende Indexerläufe nur die neuen und geänderten Dokumente in Ihrer Datenbank schrittweise indizieren.

Um die inkrementelle Indizierung zu aktivieren, legen Sie die Eigenschaft "dataChangeDetectionPolicy" in Ihrer Datenquellendefinition fest. Diese Eigenschaft teilt dem Indexer mit, welcher Änderungsnachverfolgungsmechanismus für Ihre Daten verwendet wird.

Für Azure Cosmos DB Indexer ist die einzige unterstützte Richtlinie die HighWaterMarkChangeDetectionPolicy unter Verwendung der _ts -Eigenschaft (Timestamp), die von Azure Cosmos DB bereitgestellt wird.

Das folgende Beispiel zeigt eine Datenquellendefinition mit einer Änderungserkennungsrichtlinie:

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

Indizieren gelöschter Dokumente

Wenn Diagrammdaten gelöscht werden, können Sie auch das entsprechende Dokument aus dem Suchindex löschen. Der Zweck einer Datenlöscherkennungsrichtlinie besteht darin, gelöschte Datenelemente effizient zu identifizieren und das vollständige Dokument aus dem Index zu löschen. Die Datenlöscherkennungsrichtlinie soll keine Teildokumentinformationen löschen. Derzeit ist die einzige unterstützte Richtlinie die Soft Delete-Richtlinie (Löschvorgang wird mit einer Art Kennzeichnung versehen), die in der Datenquellendefinition wie folgt angegeben 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 für das vorläufige Löschen erstellt:

POST https://[service name].search.windows.net/datasources?api-version=2026-08-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, werden das Löschen komplexer (Edm.ComplexType) Felder aus dem Index nicht unterstützt. Diese Richtlinie verlangt, dass die Spalte "aktiv" in der Gremlin-Datenbank vom Typ "Ganzzahl", "Zeichenkette" oder "Boolescher Wert" ist.

Zuordnen von Diagrammdaten zu Feldern in einem Suchindex

Der Azure Cosmos DB for Apache Gremlin-Indexer ordnet einige Diagrammdaten automatisch zu:

  1. Der Indexer ordnet _rid einem rid-Feld im Index zu, falls es vorhanden ist, und Base64-kodiert es.

  2. Der Indexer ordnet _id einem id Feld im Index zu, falls vorhanden.

  3. Wenn Sie Ihre Azure Cosmos DB-Datenbank mithilfe von Azure Cosmos DB für Apache Gremlin abfragen, stellen Sie möglicherweise fest, dass die JSON-Ausgabe für jede Eigenschaft jeweils ein id und ein value enthält. Der Indexer ordnet die Eigenschaft value automatisch einem Feld in Ihrem Suchindex zu, das denselben Namen wie die Eigenschaft hat, falls vorhanden. Im folgenden Beispiel wird 450 einem pages Feld im Suchindex zugeordnet.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

Möglicherweise stellen Sie fest, dass Sie Die Ausgabefeldzuordnungen verwenden müssen, um die Abfrageausgabe den Feldern in Ihrem Index zuzuordnen. Wahrscheinlich möchten Sie Ausgabefeldzuordnungen anstelle von Feldzuordnungen verwenden, da die benutzerdefinierte Abfrage wahrscheinlich komplexe Daten enthält.

Angenommen, Ihre Abfrage erzeugt diese Ausgabe:

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Wenn Sie den Wert pages im obigen JSON-Code einem totalpages Feld in Ihrem Index zuordnen möchten, können Sie der Indexerdefinition die folgende Ausgabefeldzuordnung hinzufügen:

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Beachten Sie, dass die Ausgabefeldzuordnung mit /document beginnt und keinen Verweis auf den Feldeigenschaftenschlüssel im JSON-Code enthält. Dies liegt daran, dass der Indexer jedes Dokument beim Aufnehmen der Diagrammdaten unter den /document Knoten platziert, und der Indexer ermöglicht es Ihnen auch automatisch, auf den Wert pages zu verweisen, indem Sie einfach darauf verweisen pages , anstatt auf das erste Objekt im Array von pagesverweisen zu müssen.

Nächste Schritte

  • Last updated on