Indexer les données de Azure Cosmos DB pour Apache Gremlin pour les requêtes dans Recherche Azure AI (préversion)

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Important

Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.

Important

Ces fonctionnalités et fonctions prennent en charge les connexions à d’autres services Microsoft et services tiers. L’utilisation de ces services est soumise à leurs conditions respectives et peut entraîner le traitement ou le stockage des données en dehors de la limite de conformité Azure, ainsi que des données entrant dans la limite de conformité Azure.

Il est de votre responsabilité de gérer si vos données circulent en dehors des limites géographiques et de conformité de votre organisation, ainsi que des implications connexes, et que les autorisations, les limites et les approbations appropriées sont provisionnés.

Vous êtes responsable de l’examen et du test des applications que vous créez dans le contexte de vos cas d’usage spécifiques et de prendre toutes les décisions et personnalisations appropriées. Cela inclut l’implémentation de vos propres atténuations d’IA responsables, telles que les métaprompts, les filtres de contenu ou d’autres systèmes de sécurité, et la garantie que vos applications répondent aux normes de qualité, de fiabilité, de sécurité et de fiabilité appropriées. Pour plus d’informations, consultez la note de transparence Recherche Azure AI.

Le Azure Cosmos DB pour l’indexeur Apache Gremlin (préversion) importe du contenu à partir de Azure Cosmos DB pour Apache Gremlin et le rend accessible à la recherche dans Recherche Azure AI.

Cet article complète la création d’un indexeur avec des informations spécifiques à Cosmos DB. Il utilise les API REST pour illustrer un workflow en trois parties commune à tous les indexeurs : créer une source de données, créer un indexeur, créer un indexeur. L’extraction de données se produit lorsque vous envoyez la demande Create Indexer.

Étant donné que la terminologie peut prêter à confusion, il est important de noter que l'indexation Azure Cosmos DB et l'indexation Recherche Azure AI sont des opérations différentes. L’indexation dans Recherche Azure AI crée et charge un index de recherche sur votre service de recherche.

Conditions préalables

Définir la source de données

La définition de la source de données spécifie les données à indexer, les informations d’identification et les stratégies pour identifier les modifications apportées aux données. Une source de données est définie comme une ressource indépendante afin qu’elle puisse être utilisée par plusieurs indexeurs.

Pour cet appel, spécifiez une version préliminaire de l’API REST pour créer une source de données qui se connecte via Azure Cosmos DB pour Apache Gremlin. Vous pouvez utiliser 2021-04-01-preview ou une version ultérieure. Nous vous recommandons la dernière API REST en préversion.

  1. Créez ou mettez à jour une source de données pour définir sa définition :

     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. Définissez « type » sur "cosmosdb" (obligatoire).

  3. Définissez « credentials » sur un chaîne de connexion. La section suivante décrit les formats pris en charge.

  4. Définissez « conteneur » dans la collection. La propriété « name » est requise et spécifie l’ID du graphique.

    La propriété « query » est facultative. Par défaut, l’indexeur Recherche Azure AI pour Azure Cosmos DB pour Apache Gremlin rend chaque vertex de votre graphique un document dans l’index. Les arêtes sont ignorées. La requête par défaut est g.V(). Vous pouvez également définir la requête pour indexer uniquement les arêtes. Pour indexer les arêtes, définissez la requête sur g.E().

  5. Définissez « dataChangeDetectionPolicy » si vos données sont volatiles et que vous souhaitez que l’indexeur récupère uniquement les éléments nouveaux et mis à jour lors des exécutions suivantes. La progression incrémentielle est activée par défaut en utilisant _ts comme colonne de repère de limite haute.

  6. Définissez « dataDeletionDetectionPolicy » si vous souhaitez supprimer des documents de recherche d’un index de recherche lorsque l’élément source est supprimé.

Identifiants et chaînes de connexion prises en charge

Les indexeurs peuvent se connecter à une collection à l’aide des connexions suivantes. Pour les connexions qui ciblent Azure Cosmos DB pour Apache Gremlin, veillez à inclure « ApiKind » dans le chaîne de connexion.

Évitez les numéros de port dans l’URL du point de terminaison. Si vous ajoutez le numéro de port, la connexion échoue.

Accès complet à la chaîne de connexion
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" }
Vous pouvez obtenir le chaîne de connexion à partir de la page du compte Azure Cosmos DB dans Azure portail en sélectionnant Keys dans le volet gauche. Veillez à sélectionner une chaîne de connexion complète et pas seulement une clé.
Chaîne de connexion d'identité managée
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Cette chaîne de connexion ne nécessite pas de clé de compte, mais vous devez avoir précédemment configuré un service de recherche pour connecter à l'aide d'une identité managée et créer une attribution de rôle qui accorde Cosmos DB Account Reader Role autorisations. Pour plus d'informations, voir Configuration d'une connexion d'indexeur à une base de données Azure Cosmos DB à l'aide d'une identité gérée.

Ajouter des champs de recherche à un index

Dans un index de recherche, ajoutez des champs pour accepter les documents JSON sources ou la sortie de votre projection de requête personnalisée. Vérifiez que le schéma d’index de recherche est compatible avec votre graphique. Pour le contenu de Azure Cosmos DB, votre schéma d’index de recherche doit correspondre aux éléments Azure Cosmos DB dans votre source de données.

  1. Créez ou mettez à jour un index pour définir les champs de recherche dans lesquels sont stockées les données :

     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. Créez un champ de clé de document (« clé » : true). Pour les collections partitionnées, la clé de document par défaut est la propriété _rid d'Azure Cosmos DB, que Recherche Azure AI renomme automatiquement en rid, car les noms de champs ne peuvent pas commencer par un caractère de soulignement. De plus, les valeurs d'Azure Cosmos DB _rid contiennent des caractères invalides pour les clés d'Recherche Azure AI. Pour cette raison, les _rid valeurs sont encodées en Base64.

  3. Créez des champs supplémentaires pour plus de contenu pouvant faire l’objet d’une recherche. Pour plus d’informations, consultez Créer un index .

Types de données de mappage

Type de données JSON types de champs Recherche Azure AI
Bool Edm.Booléen, Edm.String
Nombres qui ressemblent à des entiers Edm.Int32, Edm.Int64, Edm.String
Nombres qui ressemblent à des virgules flottantes Edm.Double, Edm.String
Chaîne Edm.String
Tableaux de types primitifs tels que ["a », « b », « c"] Collection(Edm.String)
Chaînes qui ressemblent à des dates Edm.DateTimeOffset, Edm.String
Objets GeoJSON tels que { « type » : « Point », « coordinates » : [long, lat] } Edm.GeographyPoint
Autres objets JSON N/A

Configurer et exécuter l’indexeur Azure Cosmos DB

Une fois l’index et la source de données créés, vous êtes prêt à créer l’indexeur. La configuration de l’indexeur spécifie les entrées, les paramètres et les propriétés qui contrôlent les comportements de temps d’exécution.

  1. Créez ou mettez à jour un indexeur en lui donnant un nom et en référençant la source de données et l’index cible :

    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. Spécifiez des mappages de champs s’il existe des différences dans le nom ou le type de champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

  3. Pour plus d’informations sur d’autres propriétés, consultez Créer un indexeur .

Un indexeur s’exécute automatiquement lors de sa création. Vous pouvez empêcher cela en définissant « désactivé » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le selon une planification.

Vérifier l’état de l’indexeur

Pour surveiller l'état de l'indexeur et l'historique d'exécution, envoyez une requête Get Indexer Status :

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

La réponse inclut l’état et le nombre d’éléments traités. Il doit ressembler à l’exemple suivant :

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

L’historique d’exécution contient jusqu’à 50 des dernières exécutions terminées, triées dans l’ordre chronologique inverse afin que la dernière exécution soit effectuée en premier.

Indexation de documents nouveaux et modifiés

Une fois qu’un indexeur a rempli entièrement un index de recherche, vous pouvez souhaiter que l’indexeur ultérieur s’exécute de manière incrémentielle pour indexer uniquement les documents nouveaux et modifiés dans votre base de données.

Pour activer l’indexation incrémentielle, définissez la propriété « dataChangeDetectionPolicy » dans votre définition de source de données. Cette propriété indique à l’indexeur quel mécanisme de suivi des modifications est utilisé sur vos données.

Pour les indexeurs Azure Cosmos DB, la seule stratégie prise en charge est la HighWaterMarkChangeDetectionPolicy à l’aide de la propriété _ts (timestamp) fournie par Azure Cosmos DB.

L’exemple suivant montre une définition de source de données avec une stratégie de détection des modifications :

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

Indexation de documents supprimés

Lorsque des données de graphe sont supprimées, vous pouvez également supprimer son document correspondant de l’index de recherche. L’objectif d’une stratégie de détection de suppression de données consiste à identifier efficacement les éléments de données supprimés et à supprimer le document complet de l’index. La stratégie de détection de suppression de données n’est pas destinée à supprimer des informations partielles sur le document. Actuellement, la seule politique prise en charge est la politique Soft Delete (la suppression est marquée par un indicateur quelconque), qui est spécifiée dans la définition de la source de données comme suit :

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

L’exemple suivant crée une source de données avec une stratégie de suppression réversible :

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

Même si vous activez la stratégie de détection de suppression, la suppression de champs complexes (Edm.ComplexType) de l’index n’est pas prise en charge. Cette stratégie exige que la colonne « active » de la base de données Gremlin soit de type entier, chaîne ou booléen.

Mappage des données de graphe aux champs d’un index de recherche

Le Azure Cosmos DB pour l’indexeur Apache Gremlin mappe automatiquement quelques éléments de données de graphe :

  1. L’indexeur mappe _rid à un rid champ dans l’index s’il existe, et base64 l’encode.

  2. L’indexeur associe _id à un champ id de l’index s’il existe.

  3. Lorsque vous interrogez votre base de données Azure Cosmos DB à l’aide de l’Azure Cosmos DB pour Apache Gremlin, vous remarquerez peut-être que la sortie JSON de chaque propriété a un id et un value. L’indexeur value mappe automatiquement la propriété dans un champ de votre index de recherche portant le même nom que la propriété s’il existe. Dans l’exemple suivant, 450 est mappé à un pages champ dans l’index de recherche.

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

Vous pouvez constater que vous devez utiliser des mappages de champs de sortie pour mapper votre sortie de requête aux champs de votre index. Vous souhaiterez probablement utiliser des mappages de champs de sortie plutôt que des mappages de champs , car la requête personnalisée a probablement des données complexes.

Par exemple, supposons que votre requête génère cette sortie :

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

Si vous souhaitez mapper la valeur de pages dans le JSON ci-dessus à un champ de votre index, vous pouvez ajouter le totalpages suivant à votre définition d’indexeur :

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

Notez que le mappage de champs de sortie commence par /document et n’inclut pas de référence à la clé de propriétés dans le JSON. Cela est dû au fait que l’indexeur place chaque document sous le /document nœud lors de l’ingestion des données de graphe et que l’indexeur vous permet également de référencer automatiquement la valeur en pages faisant référence simple pages au lieu de devoir référencer le premier objet dans le tableau de pages.

Étapes suivantes

  • Last updated on