Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Connecteur Amazon Athena pour DocumentDB Le connecteur Amazon Athena DocumentDB permet à Amazon Athena de communiquer avec vos instances DocumentDB afin que vous puissiez interroger vos données DocumentDB avec SQL. Le connecteur fonctionne également avec n'importe quel point de terminaison compatible avec MongoDB. Contrairement aux magasins de données relatives traditionnels, les collections Amazon DocumentDB n’ont pas de schéma défini. DocumentDB n’a pas de magasin de métadonnées. Chaque entrée d’une collection DocumentDB peut comporter des champs et des types de données différents. Le connecteur DocumentDB prend en charge deux mécanismes pour générer des informations de schéma de table : l'inférence de schéma de base et les métadonnées. AWS Glue Data Catalog L’inférence de schéma est la valeur par défaut. Cette option analyse un petit nombre de documents de votre collection, réunit tous les champs et impose des champs dont les types de données ne se chevauchent pas. Cette option fonctionne bien pour les collections dont les entrées sont généralement uniformes. Pour les collections comportant une plus grande variété de types de données, le connecteur prend en charge la récupération de métadonnées à partir du AWS Glue Data Catalog. Si le connecteur détecte une AWS Glue base de données et une table qui correspondent aux noms de votre base de données et de collection DocumentDB, il obtient ses informations de schéma dans la table correspondante AWS Glue . Lorsque vous créez votre AWS Glue table, nous vous recommandons d'en faire un sur-ensemble de tous les champs auxquels vous souhaitez accéder depuis votre collection DocumentDB. Si Lake Formation est activé sur votre compte, le rôle IAM de votre connecteur Lambda fédéré Athena que vous avez déployé dans AWS Serverless Application Repository le doit avoir un accès en lecture dans Lake Formation au. AWS Glue Data Catalog Ce connecteur peut être enregistré auprès du Catalogue de données Glue en tant que catalogue fédéré. Il prend en charge les contrôles d’accès aux données définis dans Lake Formation aux niveaux catalogue, base de données, table, colonne, ligne et balise. Ce connecteur utilise les connexions Glue pour centraliser les propriétés de configuration dans Glue. ## Conditions préalables + Déployez le connecteur sur votre Compte AWS à l’aide de la console Athena ou du AWS Serverless Application Repository. Pour plus d’informations, consultez [Création d’une connexion à une source de données](connect-to-a-data-source.md) ou [Utilisez le AWS Serverless Application Repository pour déployer un connecteur de source de données](connect-data-source-serverless-app-repo.md). ## Parameters Utilisez les paramètres de cette section pour configurer le connecteur DocumentDB. **Note** Les connecteurs de source de données Athena créés le 3 décembre 2024 et les versions ultérieures utilisent AWS Glue des connexions. Les noms et définitions de paramètres répertoriés ci-dessous concernent les connecteurs de source de données Athena créés avant le 3 décembre 2024. Ces noms et définitions peuvent différer de ceux des [propriétés de connexion AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html) correspondantes. À compter du 3 décembre 2024, utilisez les paramètres ci-dessous uniquement lorsque vous [déployez manuellement](connect-data-source-serverless-app-repo.md) une version antérieure d’un connecteur de source de données Athena. ### Connexions Glue (recommandé) Nous vous recommandons de configurer un connecteur DocumentDB en utilisant un objet des connexions Glue. Pour ce faire, définissez la variable d’environnement `glue_connection` du connecteur DocumentDB Lambda sur le nom de la connexion Glue à utiliser. **Propriétés des connexions Glue** Utilisez la commande suivante afin d’obtenir le schéma d’un objet de connexion Glue. Ce schéma contient tous les paramètres que vous pouvez utiliser pour contrôler votre connexion. ``` aws glue describe-connection-type --connection-type DOCUMENTDB ``` **Propriétés d’environnement Lambda** + **glue\$1connection** : spécifie le nom de la connexion Glue associée au connecteur fédéré. **Note** Tous les connecteurs qui utilisent des connexions Glue doivent être utilisés AWS Secrets Manager pour stocker les informations d'identification. Le connecteur DocumentDB créé à l’aide des connexions Glue ne prend pas en charge l’utilisation d’un gestionnaire de multiplexage. Le connecteur DocumentDB créé à l’aide des connexions Glue prend uniquement en charge `ConnectionSchemaVersion` 2. ### Connexions héritées + **spill\$1bucket** – Spécifie le compartiment Amazon S3 pour les données qui dépassent les limites des fonctions Lambda. + **spill\$1prefix** – (Facultatif) Par défaut, il s’agit d’un sous-dossier dans le `spill_bucket` spécifié appelé `athena-federation-spill`. Nous vous recommandons de configurer un [cycle de vie de stockage](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) Amazon S3 à cet endroit pour supprimer les déversements supérieurs à un nombre de jours ou d’heures prédéterminé. + **spill\$1put\$1request\$1headers** – (Facultatif) Une carte codée au format JSON des en-têtes et des valeurs des demandes pour la demande `putObject` Amazon S3 utilisée pour le déversement (par exemple, `{"x-amz-server-side-encryption" : "AES256"}`). Pour les autres en-têtes possibles, consultez le [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)manuel *Amazon Simple Storage Service API Reference*. + **kms\$1key\$1id** – (Facultatif) Par défaut, toutes les données déversées vers Amazon S3 sont chiffrées à l'aide du mode de chiffrement authentifié AES-GCM et d'une clé générée de manière aléatoire. Pour que votre fonction Lambda utilise des clés de chiffrement plus puissantes générées par KMS, comme `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`, vous pouvez spécifier l’ID d’une clé KMS. + **disable\$1spill\$1encryption** – (Facultatif) Lorsque la valeur est définie sur `True`, le chiffrement des déversements est désactivé. La valeur par défaut est `False` afin que les données déversées vers S3 soient chiffrées à l’aide d’AES-GCM, soit à l’aide d’une clé générée de manière aléatoire soit à l’aide de KMS pour générer des clés. La désactivation du chiffrement des déversements peut améliorer les performances, surtout si votre lieu de déversement utilise le [chiffrement côté serveur](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **disable\$1glue** — (Facultatif) S'il est présent et défini sur true, le connecteur ne tente pas de récupérer des métadonnées supplémentaires à partir de. AWS Glue + **glue\$1catalog** – (Facultatif) Utilisez cette option pour spécifier un [catalogue AWS Glue entre compte](data-sources-glue-cross-account.md). Par défaut, le connecteur tente d'obtenir des métadonnées à partir de son propre AWS Glue compte. + **default\$1docdb** – S’il est présent, il spécifie une chaîne de connexion DocumentDB à utiliser lorsqu’aucune variable d’environnement spécifique au catalogue n’existe. + **disable\$1projection\$1and\$1casing** – (Facultatif) Désactive la projection et la casse. À utiliser si vous souhaitez interroger des tables Amazon DocumentDB qui utilisent des noms de colonnes sensibles à la casse. Le paramètre `disable_projection_and_casing` utilise les valeurs suivantes pour spécifier le comportement de la casse et du mappage des colonnes : + **false** (faux) : il s'agit du paramètre par défaut. La projection est activée et le connecteur s'attend à ce que tous les noms de colonnes soient en minuscules. + **true** (vrai) : désactive la projection et la casse. Lorsque vous utilisez le paramètre `disable_projection_and_casing`, gardez à l'esprit les points suivants : + L'utilisation de ce paramètre peut augmenter l'utilisation de la bande passante. En outre, si votre fonction Lambda ne se trouve pas dans la même Région AWS que votre source de données, vous devrez supporter des coûts de transfert interrégionaux AWS standard plus élevés en raison de l'utilisation plus importante de la bande passante. Pour plus d'informations sur les coûts de transfert entre régions, consultez la section [Frais de transfert de AWS données pour les architectures serveur et sans](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/) serveur sur le blog du réseau AWS partenaire. + Étant donné qu'un plus grand nombre d'octets est transféré et qu'un plus grand nombre d'octets nécessite un délai de désérialisation plus long, la latence globale peut augmenter. + **enable\$1case\$1insensitive\$1match** (facultatif) : lorsqu’elle est définie sur `true`, cette option réalise des recherches non sensibles à la casse sur les noms de schéma et de table dans Amazon DocumentDB. La valeur par défaut est `false`. À utiliser si votre requête contient des noms de schéma ou de table en majuscules. #### Définition des chaînes de connexion Vous pouvez fournir une ou plusieurs propriétés qui définissent les détails de connexion DocumentDB pour les instances de DocumentDB que vous utilisez avec le connecteur. Pour ce faire, définissez une variable d’environnement Lambda qui correspond au nom du catalogue que vous souhaitez utiliser dans Athena. Supposons, par exemple, que vous souhaitiez utiliser les requêtes suivantes pour interroger deux instances DocumentDB différentes depuis Athena : ``` SELECT * FROM "docdb_instance_1".database.table ``` ``` SELECT * FROM "docdb_instance_2".database.table ``` Avant de pouvoir utiliser ces deux instructions SQL, vous devez ajouter deux variables d’environnement à votre fonction Lambda : `docdb_instance_1` et `docdb_instance_2`. La valeur pour chacune d’elles doit être une chaîne de connexion DocumentDB au format suivant : ``` mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` ##### Utilisation de secrets Vous pouvez éventuellement utiliser AWS Secrets Manager une partie ou la totalité de la valeur pour les détails de votre chaîne de connexion. Pour utiliser la fonctionnalité de requête fédérée d’Athena avec Secrets Manager, le VPC connecté à votre fonction Lambda doit avoir un [accès internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) ou un [point de terminaison de VPC](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) pour vous connecter à Secrets Manager. Si vous utilisez la syntaxe `${my_secret}` pour indiquer le nom d'un secret provenant de Secrets Manager dans votre chaîne de connexion, le connecteur remplace exactement `${my_secret}` par sa valeur en texte brut provenant de Secrets Manager. Les secrets doivent être stockés sous forme de texte brut avec la valeur `:`. Les secrets stockés sous la forme `{username:,password:}` ne seront pas transmis correctement à la chaîne de connexion. Les secrets peuvent également être utilisés pour l'ensemble de la chaîne de connexion, le nom d'utilisateur et le mot de passe pouvant être définis dans le secret. Supposons, par exemple, que vous définissiez la variable d’environnement Lambda pour `docdb_instance_1` sur la valeur suivante : ``` mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` Le SDK Athena Query Federation tente automatiquement de récupérer un secret nommé `docdb_instance_1_creds` à partir de Secrets Manager et d’injecte cette valeur à la place de `${docdb_instance_1_creds}`. Toute partie de la chaîne de connexion qui est entourée par la combinaison de caractères `${ }` est interprétée comme un secret de Secrets Manager. Si vous spécifiez un nom de secret que le connecteur ne trouve pas dans Secrets Manager, le connecteur ne remplace pas le texte. ## Récupération de métadonnées supplémentaires Pour récupérer des métadonnées supplémentaires, procédez comme suit afin de configurer la base de données et la table Glue. ### Configuration de la base de données Glue 1. Créez une base de données Glue portant le même nom que votre collection DocumentDB. 1. Dans le champ URI de l’emplacement, saisissez `docdb-metadata-flag`. ### Configuration de la table Glue Ajoutez les paramètres suivants à votre table Glue : + `docdb-metadata-flag = true` + `columnMapping = apple=APPLE` Dans cet exemple, `apple` représente le nom de colonne en minuscules dans Glue et `APPLE` représente le nom de colonne sensible à la casse réel dans votre collection DocumentDB. ### Vérification de la récupération des métadonnées 1. Exécutez votre requête. 1. Consultez les CloudWatch journaux de la fonction Lambda pour vérifier si la récupération des métadonnées est réussie. Une récupération réussie présentera l’entrée de journal suivante : ``` doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue. ``` **Note** Si un champ `columnMapping` est déjà configuré dans votre table, il vous suffit d’ajouter le paramètre `docdb-metadata-flag = true` aux propriétés de la table. ## Configuration de bases de données et de tables dans AWS Glue Étant donné que la fonctionnalité d'inférence de schéma intégrée du connecteur scanne un nombre limité de documents et ne prend en charge qu'un sous-ensemble de types de données, vous pouvez préférer l'utiliser AWS Glue pour les métadonnées. Pour activer une AWS Glue table à utiliser avec Amazon DocumentDB, vous devez disposer d'une base de AWS Glue données et d'une table pour la base de données et la collection DocumentDB pour lesquelles vous souhaitez fournir des métadonnées supplémentaires. **Pour utiliser une AWS Glue table pour des métadonnées supplémentaires** 1. Utilisez la AWS Glue console pour créer une AWS Glue base de données portant le même nom que le nom de votre base de données Amazon DocumentDB. 1. Définissez la propriété URI de la base de données à inclure **docdb-metadata-flag**. 1. (Facultatif) Ajoutez la propriété de table **sourceTable**. Cette propriété définit le nom de la table source dans Amazon DocumentDB. Utilisez cette propriété si le nom de votre AWS Glue table est différent de celui de la table dans Amazon DocumentDB. Les différences entre les règles de dénomination AWS Glue et Amazon DocumentDB peuvent rendre cela nécessaire. Par exemple, les majuscules ne sont pas autorisées dans les noms de AWS Glue table, mais elles le sont dans les noms de table Amazon DocumentDB. 1. (Facultatif) Ajoutez la propriété de table **columnMapping**. Cette propriété définit les mappages de noms de colonnes. Utilisez cette propriété si les règles de dénomination des AWS Glue colonnes vous empêchent de créer une AWS Glue table portant les mêmes noms de colonne que ceux de votre table Amazon DocumentDB. Cela peut être utile, car les majuscules sont autorisées dans les noms de colonnes Amazon DocumentDB, mais elles ne le sont pas dans les noms de colonnes AWS Glue . La valeur de la propriété `columnMapping` est censée être un ensemble de mappages au format `col1=Col1,col2=Col2`. **Note** Le mappage des colonnes s'applique uniquement aux noms de colonnes de niveau supérieur et non aux champs imbriqués. Après avoir ajouté la propriété AWS Glue `columnMapping` table, vous pouvez supprimer la variable d'environnement `disable_projection_and_casing` Lambda. 1. Assurez-vous d'utiliser les types de données appropriés AWS Glue tels que listés dans ce document. ## Prise en charge du type de données Cette section répertorie les types de données que le connecteur DocumentDB utilise pour l'inférence de schéma, ainsi que les types de données lorsque des AWS Glue métadonnées sont utilisées. ### Types de données d’inférence de schéma La fonction d’inférence de schéma du connecteur DocumentDB tente de déduire des valeurs comme appartenant à l’un des types de données suivants. Le tableau indique les types de données correspondants pour Amazon DocumentDB, Java et Apache Arrow. **** | Apache | Java ou DocDB | | --- | --- | | VARCHAR | String | | INT | Entier | | BIGINT | Long | | BIT | Booléen | | FLOAT4 | Float | | FLOAT8 | Double | | TIMESTAMPSEC | Date | | VARCHAR | ObjectId | | LIST | List | | STRUCT | Document | ### AWS Glue types de données Si vous utilisez AWS Glue des métadonnées supplémentaires, vous pouvez configurer les types de données suivants. Le tableau indique les types de données correspondants pour AWS Glue et Apache Arrow. **** | AWS Glue | Apache | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | float | FLOAT4 | | boolean | BIT | | binary | VARBINARY | | chaîne | VARCHAR | | List | LIST | | Struct | STRUCT | ## Autorisations nécessaires Pour plus de détails sur les politiques IAM requises par ce connecteur, reportez-vous à la section `Policies` du fichier [athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml). La liste suivante résume les autorisations requises. + **Amazon S3 write access** (Accès en écriture Amazon S3) – Le connecteur nécessite un accès en écriture à un emplacement dans Amazon S3 pour déverser les résultats à partir de requêtes volumineuses. + **Athena GetQueryExecution** — Le connecteur utilise cette autorisation pour échouer rapidement lorsque la requête Athena en amont est terminée. + **AWS Glue Data Catalog**— Le connecteur DocumentDB nécessite un accès en lecture seule au pour AWS Glue Data Catalog obtenir des informations sur le schéma. + **CloudWatch Journaux** : le connecteur a besoin d'accéder aux CloudWatch journaux pour stocker les journaux. + **AWS Secrets Manager accès en lecture** — Si vous choisissez de stocker les détails du point de terminaison DocumentDB dans Secrets Manager, vous devez autoriser le connecteur à accéder à ces secrets. + **Accès VPC** – Le connecteur nécessite la possibilité d’attacher des interfaces à votre VPC et de les détacher afin qu’il puisse s’y connecter et communiquer avec vos instances DocumentDB. ## Performance Le connecteur Amazon DocumentDB d'Athena ne prend pas actuellement en charge les analyses parallèles, mais tente de pousser les prédicats vers le bas dans le cadre de ses requêtes DocumentDB, et les prédicats contre les index de votre collection DocumentDB entraînent une réduction significative des données analysées. La fonction Lambda effectue une poussée vers le bas de projection pour réduire les données analysées par la requête. Cependant, la sélection d’un sous-ensemble de colonnes entraîne parfois un temps d’exécution plus long de la requête. Les clauses `LIMIT` réduisent la quantité de données analysées, mais si vous ne fournissez pas de prédicat, vous devez vous attendre à ce que les requêtes `SELECT` avec une clause `LIMIT` analysent au moins 16 Mo de données. ## Requêtes de transmission Basé sur NoSQL, le connecteur Athena pour Amazon DocumentDB prend en charge les [requêtes de transmission](federated-query-passthrough.md). Pour plus d’informations sur les interrogations avec Amazon DocumentDB, consultez [Querying](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html) dans le *Guide de développement d’Amazon DocumentDB*. Pour utiliser les requêtes de transmission avec Amazon DocumentDB, utilisez la syntaxe suivante : ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` L’exemple suivant interroge la base de données `example` dans la collection `TPCDS`, en filtrant tous les livres portant le titre *Bill of Rights*. ``` SELECT * FROM TABLE( system.query( database => 'example', collection => 'tpcds', filter => '{title: "Bill of Rights"}' )) ``` ## Ressources supplémentaires + *Pour un article sur l'utilisation d'[Amazon Athena Federated Query pour connecter une base de données MongoDB à [Quick](https://aws.amazon.com/quicksight/)](federated-queries.md) afin de créer des tableaux de bord et des visualisations, consultez Visualiser les données [MongoDB depuis Quick à l'aide d'Amazon Athena Federated Query sur le blog Big Data](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/).AWS * + Pour plus d'informations sur ce connecteur, rendez-vous sur [le site correspondant](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb) sur GitHub .com.