Partager via

Indexer des données dans Azure Cosmos DB for NoSQL pour les requêtes dans la Recherche Azure AI

  • Article

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir d’Azure Cosmos DB for NoSQL et le rend recherchable dans une recherche Azure AI.

Cet article est un complément de Créer un indexeur avec des informations propres à Cosmos DB. Il utilise le portail Azure et des API REST pour montrer 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

Pour utiliser les exemples de cet article, vous avez besoin du portail Azure ou d’un client REST. Si vous utilisez le portail Azure, vérifiez que l’accès à tous les réseaux publics est activé. Les Kits de développement logiciel (SDK) Azure font partie des autres approches pour créer un indexeur Cosmos DB.

Essayer avec des exemples de données

Utilisez ces instructions pour créer un conteneur et une base de données dans Cosmos DB à des fins de test.

  1. Téléchargez HotelsData_toCosmosDB.JSON depuis GitHub pour créer un conteneur dans Cosmos DB qui contient un sous-ensemble de l'échantillon de données sur les hôtels.

  2. Connectez-vous au portail Azure et créez un compte, une base de données et un conteneur sur Cosmos DB.

  3. Dans Cosmos DB, sélectionnez Explorateur de données pour le nouveau conteneur, fournissez les valeurs suivantes.

    Propriété Valeur
    Base de données Création
    ID de base de données hotelsdb
    Partager le débit entre les conteneurs Ne sélectionnez rien
    ID de conteneur hôtels
    Clé de partition /HotelId
    Débit du conteneur (mise à l’échelle automatique) Mise à l’échelle automatique
    Nombre maximal de RU/s du conteneur 1 000

  4. Dans Data Explorer, développez hotelsdb et *hotels », puis sélectionnez Éléments.

  5. Sélectionnez Charger l’article et sélectionnez le fichier HotelsData_toCosmosDB.JSON que vous avez téléchargé depuis GitHub.

  6. Cliquez avec le bouton droit sur Éléments, puis sélectionnez nouvelle requête SQL. La requête par défaut est SELECT * FROM c.

  7. Sélectionnez Exécuter la requête pour exécuter la requête et afficher les résultats. Vous devriez avoir 50 documents d’hôtel.

Maintenant que vous disposez d’un conteneur, vous pouvez utiliser le portail Azure, le client REST ou un Kit de développement logiciel (SDK) Azure pour indexer vos données.

Le champ Description fournit le contenu le plus détaillé. Vous devez cibler ce champ pour la recherche en texte intégral et des requêtes vectorielles facultatives.

Utilisation du portail Azure

Vous pouvez utiliser l’Assistant Importation de données ou l’Assistant Importation et vectorisation de données pour automatiser l’indexation depuis une table ou d’une vue de base de données SQL. La configuration de la source de données est similaire pour les deux Assistants.

  1. Démarrez l’assistant.

  2. Sur Connecter vos données, sélectionnez ou vérifiez que le type de source de données est soit Azure Cosmos DB soit un compte NoSQL.

    Le nom de la source de données fait référence à l’objet de connexion de source de données dans Recherche Azure AI. Si vous utilisez l’Assistant Vecteur, le nom de votre source de données est généré automatiquement en utilisant un préfixe personnalisé spécifié à la fin du workflow de l’Assistant.

  3. Spécifiez le nom de la base de données et la collection. La requête est facultative. Il est utile si vous avez des données hiérarchiques et que vous souhaitez importer une tranche spécifique.

  4. Spécifiez une méthode d’authentification : une identité managée ou une clé API intégrée. Si vous ne spécifiez pas de connexion d’identité managée, le portail Azure utilise la clé.

    Si vous configurez Recherche Azure AI pour utiliser une identité managée et que vous créez une attribution de rôle sur Cosmos DB qui accorde des autorisations Lecteur et accès aux données à l’identité, votre indexeur peut se connecter à Stockage Table en utilisant Microsoft Entra ID et des rôles.

  5. Pour l’Assistant Importation et vectorisation de données, vous pouvez spécifier des options pour le suivi des modifications et des suppressions.

    La détection des modifications est pris en charge par défaut par le biais d’un champ _ts (horodatage). Si vous chargez du contenu à l’aide de l’approche décrite dans Essayer avec des exemples de données, la collection est créée avec un champ _ts.

    La détection des suppressions nécessite l'existence d'un champ de premier niveau préexistant dans la collection qui peut être utilisé comme indicateur de suppression douce. Il doit s’agir d’un champ booléen (vous pouvez le nommer par exemple IsDeleted). Spécifiez true comme valeur de suppression réversible. Dans l’index de recherche, ajoutez un champ de recherche correspondant appelé IsDeleted défini comme récupérable et filtrable.

  6. Suivez les étapes restantes pour terminer l’Assistant :

Utiliser les API REST

Cette section montre les appels d’API REST qui créent une source de données, un index et un indexeur.

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 une ressource indépendante pouvant être utilisée par plusieurs indexeurs.

  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-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-cosmos-db-collection]",
      "query": null
    },
    "dataChangeDetectionPolicy": {
      "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "  highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
}

  2. Définissez « type » sur "cosmosdb" (obligatoire). Si vous utilisez une API de recherche plus ancienne que la version 2017-11-11, la syntaxe du « type » est "documentdb". Dans le cas contraire, pour 2019-05-06 et versions ultérieures, utilisez "cosmosdb".

  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 de la collection de bases de données à indexer. La propriété « query » est facultative. Utilisez-la pour aplatir un document JSON arbitraire en schéma plat que la recherche Azure AI peut indexer.

  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.

  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.

É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>" }`
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];)/(IdentityAuthType=[identity-auth-type])" }
Cette chaîne de connexion ne nécessite pas de clé de compte, mais vous devez avoir un service de recherche pouvant se connecter en utilisant une identité managée. Pour les connexions ciblant l’API SQL, vous pouvez ignorer ApiKind dans la chaîne de connexion. Pour plus d’informations sur ApiKind, IdentityAuthType consultez Configuration d’une connexion d’indexeur à une base de données Azure Cosmos DB à l’aide d’une identité managée.

Utilisation de requêtes pour formater les données indexées

Dans la propriété « query » sous « container », vous pouvez spécifier une requête SQL pour aplatir les propriétés ou les tableaux imbriqués, projeter des propriétés JSON et filtrer les données à indexer.

Exemple de document :

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Requête de filtre :

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Requête d’aplatissage :

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Requête de projection :

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Requête d’aplatissage de tableau :

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Requêtes non prises en charge (DISTINCT et GROUP BY)

Les requêtes utilisant le mot clé DISTINCT ou la clause GROUP BY ne sont pas prises en charge. La recherche Azure AI s’appuie sur la pagination des requêtes SQL pour énumérer entièrement les résultats de la requête. Ni le mot clé DISTINCT ni la clause GROUP BY ne sont compatibles avec les jetons de continuation utilisés pour paginer les résultats.

Exemples de requêtes non prises en charge :

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Bien qu’Azure Cosmos DB ait une solution de contournement pour prendre en charge la pagination des requêtes SQL avec le mot clé DISTINCT en utilisant la clause ORDER BY, elle n’est pas compatible avec la recherche Azure AI. La requête renvoie une seule valeur JSON, alors que la recherche Azure AI attend un objet JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

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. Vérifiez que le schéma d’index de recherche est compatible avec vos données sources. 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 dans lesquels sont stockées les données :

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

  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 davantage de champs pour du contenu avec possibilité de recherche. Pour plus d’informations, consultez Créer un index.

Types de données de mappage

Types 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 S/O

Configurer et exécuter l’indexeur Azure Cosmos DB for NoSQL

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-07-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-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 surveiller l’état et l’historique d’exécution de l’indexeur, vérifiez l’historique d’exécution de l’indexeur dans le portail Azure ou envoyez une requête d’API REST Obtenir l’état de l’indexeur

  1. Dans la page du service de recherche, ouvrez Gestion de la recherche>Indexeurs.

  2. Sélectionnez un indexeur pour accéder à la configuration et à l’historique d’exécution.

  3. Sélectionnez un travail d’indexeur spécifique pour voir les détails, les avertissements et les erreurs.

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

Remarque

Lorsque vous attribuez une valeur null à un champ dans votre Azure Cosmos DB, l’indexeur de recherche AI n’est pas en mesure de faire la distinction entre null et une valeur de champ manquante. Par conséquent, si un champ de l’index est vide, il ne sera pas remplacé par une valeur null, même si cette modification a été spécifiquement effectuée dans votre base de données.

Indexation incrémentielle et requêtes personnalisées

Si vous utilisez une requête personnalisée pour récupérer des documents, vérifiez que la requête classe les résultats en fonction de la colonne _ts. Ceci permet de créer des points de contrôle périodiques dont la recherche Azure AI se sert pour proposer la progression incrémentielle en cas de défaillances.

Dans certains cas, il est possible que la recherche Azure AI ne déduise pas que la requête est ordonnée par _ts, même si elle contient une clause ORDER BY [collection alias]._ts. Vous pouvez indiquer à la recherche Azure AI que les résultats sont triés en définissant la propriété de configuration assumeOrderByHighWaterMarkColumn.

Pour spécifier cet indicateur, créez ou mettez à jour la définition de votre indexeur de la façon suivante :

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Indexation des documents supprimés

Lorsque des lignes sont supprimées de la collection, vous devez normalement supprimer ces lignes de l'index de recherche. L'objectif d'une stratégie de détection des suppressions de données est d'identifier efficacement les données supprimées. 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"
}

Si vous utilisez une requête personnalisée, vérifiez que la propriété référencée par softDeleteColumnName est projetée par la requête.

softDeleteColumnName doit être un champ de niveau supérieur dans l’index. Utilisation de champs imbriqués dans des types de données complexes, car softDeleteColumnName n’est pas pris en charge.

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-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "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"
    }
}

Utiliser .NET

Pour les données accessibles à travers le protocole de l’API SQL, vous pouvez utiliser le SDK .NET pour une automatisation avec les indexeurs. Nous vous recommandons de consulter les sections précédente sur l’API REST pour découvrir les concepts, les workflows et les exigences. Vous pouvez ensuite consulter la documentation de référence suivante sur l’API .NET pour implémenter un indexeur JSON dans du code managé :

Étapes suivantes

Vous pouvez maintenant contrôler comment exécuter l’indexeur, monitorer l’état ou planifier l’exécution de l’indexeur. Les articles suivants s’appliquent aux indexeurs qui tirent du contenu d’Azure Cosmos DB :