Indexeer gegevens uit Azure Cosmos DB voor Apache Gremlin voor query's in Azure AI Zoeken (preview)

Opmerking

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Belangrijk

Functies, mogelijkheden of eigenschappen die zijn gemarkeerd (preview) vallen niet onder een service level agreement, worden niet aanbevolen voor productieworkloads en kunnen worden gewijzigd of beperkt voordat ze algemeen beschikbaar worden. De Azure AI Zoeken preview-voorwaarden zijn van toepassing op alle preview-functionaliteit, ongeacht of deze zelfstandig is of deel uitmaakt van een algemeen beschikbare functie.

Belangrijk

Deze functies en functionaliteit ondersteunen verbindingen met andere Microsoft-services en services van derden. Het gebruik van deze services is onderhevig aan hun respectieve voorwaarden en kan leiden tot gegevensverwerking of opslag buiten de grens van Azure naleving, evenals gegevens die naar de grens van de Azure naleving stromen.

Het is uw verantwoordelijkheid om te beheren of uw gegevens buiten de nalevings- en geografische grenzen van uw organisatie en eventuele gerelateerde implicaties stromen, en dat de juiste machtigingen, grenzen en goedkeuringen worden ingericht.

U bent verantwoordelijk voor het zorgvuldig beoordelen en testen van toepassingen die u bouwt in de context van uw specifieke use cases en het nemen van alle juiste beslissingen en aanpassingen. Dit omvat het implementeren van uw eigen verantwoorde AI-oplossingen, zoals metaprompts, inhoudsfilters of andere veiligheidssystemen, en ervoor zorgen dat uw toepassingen voldoen aan de juiste kwaliteit, betrouwbaarheid, beveiliging en betrouwbaarheidsstandaarden. Zie de Azure AI Zoeken Transparantienotitie voor meer informatie.

De Azure Cosmos DB voor Apache Gremlin-indexeerfunctie (preview) importeert inhoud uit Azure Cosmos DB voor Apache Gremlin en maakt het doorzoekbaar in Azure AI Zoeken.

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 Zoeken indexering verschillende bewerkingen zijn. Indexeren in Azure AI Zoeken maakt en laadt een zoekindex in uw zoekservice.

Voorwaarden

  • Vul het registratieformulier voor de indexeerfunctie in. Registratie wordt automatisch goedgekeurd.

  • Een Azure Cosmos DB-account, database, container en items. Gebruik dezelfde regio voor zowel Azure AI Zoeken als Azure Cosmos DB voor lagere latentie en om bandbreedtekosten te voorkomen.

  • Een automatische indexeringsbeleid in de verzameling Azure Cosmos DB ingesteld op Consistent. Deze instelling is de standaardconfiguratie. 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-rollen gebruikt, moet u ervoor zorgen dat de beheerde identiteit van de searchservice de rechten voor de rol Cosmos DB-accountlezer heeft.

  • 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 wordt gedefinieerd als een onafhankelijke resource, zodat deze kan worden gebruikt door meerdere indexeerfuncties.

Geef voor deze aanroep een preview-REST API-versie op om een gegevensbron te maken die verbinding maakt via Azure Cosmos DB voor Apache Gremlin. U kunt 2021-04-01-preview of hoger gebruiken. We raden de nieuwste preview-REST API aan.

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

     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. Stel 'type' in op "cosmosdb" (vereist).

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

  4. Stel 'container' in op de collectie. De eigenschap 'name' is vereist en geeft de id van de grafiek op.

    De eigenschap 'query' is optioneel. Standaard maakt de Azure AI Zoeken indexeerfunctie voor Azure Cosmos DB voor Apache Gremlin elk hoekpunt in uw grafiek een document in de index. Randen worden genegeerd. De standaardinstelling voor de query is g.V(). U kunt de query ook instellen om alleen de randen te indexeren. Als u de randen wilt indexeren, stelt u de query in op g.E().

  5. Stel 'dataChangeDetectionPolicy' in als uw gegevens vluchtig zijn en u wilt dat de indexeerfunctie alleen de nieuwe en bijgewerkte items ophaalt bij volgende uitvoeringen. Incrementele voortgang is standaard ingeschakeld, waarbij _ts als high-watermarkkolom wordt gebruikt.

  6. Stel 'dataDeletionDetectionPolicy' in als u zoekdocumenten uit een zoekindex wilt verwijderen wanneer het bronitem wordt verwijderd.

Ondersteunde referenties en verbindingsreeksen

Indexeerfuncties kunnen verbinding maken met een verzameling met behulp van de volgende verbindingen. Voor verbindingen die zijn gericht op Azure Cosmos DB voor Apache Gremlin moet u 'ApiKind' opnemen in de verbindingsreeks.

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

Volledige toegangsverbindingsreeks
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" }
U kunt de verbindingstekenreeks ophalen op de Azure Cosmos DB-accountpagina in de Azure portal door in het linkerdeelvenster Sleutels te selecteren. Zorg ervoor dat u een volledige verbindingsreeks en niet alleen een sleutel selecteert.
Beheerde identiteit verbindingstekenreeks
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet eerder een zoekservice hebben geconfigureerd om verbinding te maken met behulp van een beheerde identiteit en een roltoewijzing hebben gemaakt die machtigingen verleent voor de Cosmos DB Account Reader Role. Zie Een indexerverbinding tot stand brengen met een Azure Cosmos DB-database met gebruik van een beheerde identiteit voor meer informatie.

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 uw grafiek. 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=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. Maak een documentsleutelveld ('sleutel': true'). Voor gepartitioneerde verzamelingen is de standaarddocumentsleutel de eigenschap Azure Cosmos DB _rid, die Azure AI Zoeken automatisch wijzigt in rid omdat veldnamen niet kunnen beginnen met een onderstrepingsteken. Azure Cosmos DB _rid-waarden bevatten ook tekens die ongeldig zijn in Azure AI Zoeken sleutels. Daarom zijn de _rid waarden base64 gecodeerd.

  3. Maak extra velden voor meer doorzoekbare inhoud. Zie Een index maken voor meer informatie.

Toewijzen van gegevenstypen

JSON-gegevenstype Azure AI Zoeken 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
Tekenreeks Edm.String
Matrices van primitieve typen, zoals ["a", "b", "c"] Collection(Edm.String)
Tekenreeksen die lijken op data Edm.DateTimeOffset, Edm.String
GeoJSON-objecten zoals { "type": "Point", "coördinaten": [long, lat] } Edm.GeographyPoint
Andere JSON-objecten N/A

De Azure Cosmos DB-indexeerfunctie 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=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. 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 true. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

Status van 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=2026-08-01-preview
  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 Azure Cosmos DB indexeerfuncties is het enige ondersteunde beleid de HighWaterMarkChangeDetectionPolicy met behulp van de eigenschap _ts (timestamp) die wordt geleverd door 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"
},

Verwijderde documenten indexeren

Wanneer grafiekgegevens worden verwijderd, wilt u mogelijk ook het bijbehorende document uit de zoekindex verwijderen. Het doel van een beleid voor het detecteren van gegevensverwijdering is om verwijderde gegevensitems efficiënt te identificeren en het volledige document uit de index te verwijderen. Het detectiebeleid voor gegevensverwijdering is niet bedoeld om gedeeltelijke documentgegevens te verwijderen. 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"
}

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

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

Zelfs als u verwijderingsdetectiebeleid inschakelt, wordt het verwijderen van complexe (Edm.ComplexType) velden uit de index niet ondersteund. Voor dit beleid moet de kolom Actief in de Gremlin-database van het type geheel getal, tekenreeks of booleaanse waarde zijn.

Grafiekgegevens toewijzen aan velden in een zoekindex

De indexeerfunctie van Azure Cosmos DB voor Apache Gremlin brengt automatisch enkele onderdelen van de grafiekgegevens in kaart:

  1. De indexeerfunctie wijst _rid toe aan een rid-veld in de index, als dat veld bestaat, en codeert het in Base64.

  2. Het indexeerprogramma wijst _id toe aan een id-veld in de index als dit bestaat.

  3. Wanneer u een query uitvoert op uw Azure Cosmos DB-database met behulp van de Azure Cosmos DB voor Apache Gremlin, ziet u mogelijk dat de JSON-uitvoer voor elke eigenschap een id en een valueheeft. De indexeerfunctie wijst de eigenschap value automatisch toe aan een veld in uw zoekindex met dezelfde naam als de eigenschap als deze bestaat. In het volgende voorbeeld wordt 450 toegewezen aan een pages veld in de zoekindex.

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

Mogelijk moet u uitvoerveldtoewijzingen gebruiken om de queryuitvoer toe te wijzen aan de velden in uw index. Waarschijnlijk wilt u uitvoerveldtoewijzingen gebruiken in plaats van veldtoewijzingen , omdat de aangepaste query waarschijnlijk complexe gegevens bevat.

Stel dat uw query deze uitvoer produceert:

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

Als u de waarde van pages de bovenstaande JSON wilt toewijzen aan een totalpages veld in uw index, kunt u de volgende uitvoerveldtoewijzing toevoegen aan de definitie van de indexeerfunctie:

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

U ziet hoe de uitvoerveldtoewijzing begint met /document en geen verwijzing naar de eigenschappensleutel in de JSON bevat. Dit komt doordat de indexeerder elk document onder de /document-node plaatst bij het invoeren van de grafiekgegevens, en de indexeerder u ook automatisch in staat stelt om naar de waarde van pages te verwijzen door simpelweg pages te gebruiken in plaats van het eerste object in de array van pages te moeten verwijzen.

Volgende stappen

  • Laatst bijgewerkt om