Partager via

Indexer des données à partir d’Azure Cosmos DB for Apache Gremlin pour les requêtes dans Recherche Azure AI

  • Article

Important

L’indexeur Azure Cosmos DB for Apache Gremlin est actuellement en préversion publique dans le cadre de Conditions d’utilisation supplémentaires. Il n’existe actuellement aucune prise en charge du Kit de développement logiciel (SDK).

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir d' Azure Cosmos DB for Apache Gremlin et le rend accessible dans Recherche Azure AI.

Cet article est un complément de Créer un indexeur avec des informations propres à Cosmos DB. Il utilise les API REST pour illustrer un workflow en trois parties commun à tous les indexeurs : créer une source de données, créer un index, créer un indexeur. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Étant donné que la terminologie peut être déroutante, 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 la recherche Azure AI crée et charge un index de recherche sur votre service de recherche.

Prérequis

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 permettant d’identifier les changements de données. Une source de données est définie comme une ressource indépendante de manière à pouvoir être utilisée par plusieurs indexeurs.

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

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

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

  2. Définissez « type » sur "cosmosdb" (obligatoire).

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

  4. Définissez « container » sur la collection. La propriété « name » est obligatoire 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 for Apache Gremlin rend chaque vertex de votre graphique un document dans l’index. Les arêtes seront ignorées. La valeur par défaut de la requête est g.V(). Vous pouvez également définir la requête pour qu’elle indexe uniquement les arêtes. Pour indexer les arêtes, définissez la requête sur g.E().

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

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

Informations d’identification 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 for Apache Gremlin, veillez à inclure « ApiKind » dans la 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.

Chaîne de connexion d’accès complet
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Vous pouvez obtenir la chaîne de connexion à partir de la page du compte Azure Cosmos DB dans le portail Azure en sélectionnant Clés dans le volet de navigation de 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éalablement configuré un service de recherche pour vous connecter en utilisant une identité managée et créé une attribution de rôle qui accorde les autorisations du rôle Lecteur de compte Cosmos DB. Consultez Configuration d’une connexion d’indexeur à une base de données Azure Cosmos DB avec une identité managée pour plus d’informations.

Ajouter des champs de recherche à un index

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

  1. Créez ou mettez à jour un index pour définir les champs de recherche qui stockeront les données :

     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": []
    }]
  }

  2. Créez un champ de clé de document ("key": true). Pour les collections partitionnées, la clé de document par défaut est la propriété d’_ridAzure Cosmos DB, que la recherche Azure AI renomme automatiquement en rid, car les noms de champs ne peuvent pas commencer par un trait de soulignement. En outre, les valeurs _rid Azure Cosmos DB contiennent des caractères non valides dans les clés de recherche Azure AI. Par conséquent, les valeurs _rid sont codées en Base64.

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

Mappage des types de données

Type de données JSON Types de champs Recherche Azure AI
Bool Edm.Boolean, Edm.String
Nombres qui ressemblent à des nombres entiers Edm.Int32, Edm.Int64, Edm.String
Nombres qui ressemblent à des nombres avec points flottants Edm.Double, Edm.String
Chaîne Edm.String
Tableaux de types primitifs, par exemple ["a", "b", "c"] Collection(Edm.String)
Chaînes qui ressemblent à des dates Edm.DateTimeOffset, Edm.String
Objets GeoJSON, par exemple { "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 d’exécution.

  1. Créez ou mettez à jour un indexeur en lui attribuant 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=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
}

  2. Spécifiez les mappages de champs s’il existe des différences dans le nom ou le type du champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

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

Un indexeur s’exécute automatiquement quand il est créé. Vous pouvez l’éviter en définissant « disabled » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le dans une planification.

Vérifier l’état de l’indexeur

Pour monitorer l’état de l’indexeur et l’historique d’exécution, envoyez une demande Obtenir l’état de l’indexeur :

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

La réponse comprend l’état et le nombre d’éléments traités. Le résultat 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 exécutions les plus récentes, classées par ordre chronologique inversé, la dernière exécution apparaissant en premier.

Indexation des documents nouveaux et modifiés

Dès qu’un indexeur a entièrement rempli un index de recherche, vous pouvez définir que les exécutions suivantes de l’indexeur indexent de manière incrémentielle 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 la définition de votre source de données. Cette propriété indique à l’indexeur le mécanisme de suivi des changements utilisé sur vos données.

Pour les indexeurs Azure Cosmos DB, la seule stratégie prise en charge est HighWaterMarkChangeDetectionPolicy utilisant la propriété _ts (horodateur) 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 changements :

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

Indexation des documents supprimés

Lorsque les données d’un graphique sont supprimées, vous pouvez également supprimer le document correspondant de l’index de recherche. L’objectif d’une stratégie de détection de la suppression des données est d’identifier efficacement les éléments de données supprimés et de supprimer le document complet de l’index. La stratégie de détection de la suppression des données n’est pas destinée à supprimer des documents partiels. La seule stratégie actuellement prise en charge est la stratégie Soft Delete (où la suppression est signalée par un indicateur quelconque), spécifiée dans la définition de source de données de la façon suivante :

"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 des conseils pour une stratégie de suppression en douceur :

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

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 » dans la base de données Gremlin soit de type entier, chaîne ou booléen.

Mappage de données de graphique à des champs dans un index de recherche

L’indexeur Azure Cosmos DB for Apache Gremlin mappe automatiquement quelques éléments de données de graphique pour vous :

  1. L’indexeur mappera _rid à un champ rid dans l’index, s’il existe, et l’encodera en Base64.

  2. L’indexeur mappera _id à un champ id dans l’index, s’il existe.

  3. Lorsque vous interrogez votre base de données Azure Cosmos DB à l’aide d’Azure Cosmos DB for Apache Gremlin, vous pouvez remarquer que la sortie JSON de chaque propriété comporte un id et une value. L’indexeur mappe automatiquement les propriétés value dans un champ de votre index de recherche portant le même nom que la propriété, le cas échéant. Dans l’exemple suivant, 450 est mappé à un champ pages dans l’index de recherche.

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

Il se peut que vous deviez utiliser des mappages de champs de sortie afin de mapper la sortie de votre 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 contiendra probablement des données complexes.

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

    [
      {
        "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 totalpages de votre index, vous pouvez ajouter le mappage de champs de sortie 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é dans le JSON. Cela s’explique par le fait que l’indexeur place chaque document sous le nœud /document lors de l’ingestion des données du graphique. L’indexeur vous permet également de référencer automatiquement la valeur de pages en référençant simplement pages au lieu de devoir référencer le premier objet dans le tableau de pages.

Étapes suivantes