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

Article
09/03/2024

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

Un compte, une base de données, un conteneur et des éléments Azure Cosmos DB. Utilisez la même région pour la recherche Azure AI et Azure Cosmos DB afin de réduire la latence et d’éviter les frais de bande passante.
Une stratégie d’indexation automatique sur la collection Azure Cosmos DB, définie sur Cohérente. Il s’agit de la configuration par défaut. L’indexation différée n’est pas recommandée et peut entraîner des données manquantes.
Autorisations de lecture. Une chaîne de connexion « accès total » comprend une clé qui accorde l’accès au contenu, mais si vous utilisez le contrôle d’accès en fonction du rôle (RBAC) Azure (Microsoft Entra ID), assurez-vous que l’identité managée du service de recherche dispose des autorisations des rôles de lecteur de compte Azure Cosmos DB et lecteur de données intégrées Azure Cosmos DB.
Un client REST pour créer la source de données, l’index et l’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.

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
}

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".
Définissez « credentials » sur une chaîne de connexion. La section suivante décrit les formats pris en charge.
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.
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.
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

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.

{ "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.

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

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

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
}

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.
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-07-01
  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"
},

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 :

Partage via