Prérequis Paramètres Récupération de métadonnées supplémentaires Configuration de bases de données et de tables dans AWS Glue Prise en charge du type de données Autorisations nécessaires Performances Requêtes de transmission Ressources supplémentaires

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 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 base de données AWS Glue et une table qui correspondent aux noms de votre base de données et de votre collection DocumentDB, il obtient ses informations de schéma à partir de la table AWS Glue correspondante. Lorsque vous créez votre table AWS Glue, 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 le AWS Serverless Application Repository doit avoir un accès en lecture au AWS Glue Data Catalog dans Lake Formation.

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.

Prérequis

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 ou Utilisation d’AWS Serverless Application Repository pour déployer un connecteur de source de données.

Paramètres

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 des connexions AWS Glue.

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 correspondantes. À compter du 3 décembre 2024, utilisez les paramètres ci-dessous uniquement lorsque vous déployez manuellement une version antérieure d’un connecteur de source de données Athena.

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_connection – 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 utiliser 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.

spill_bucket – Spécifie le compartiment Amazon S3 pour les données qui dépassent les limites des fonctions Lambda.
spill_prefix – (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 Amazon S3 à cet endroit pour supprimer les déversements supérieurs à un nombre de jours ou d’heures prédéterminé.
spill_put_request_headers – (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 PutObject dans la Référence d'API Amazon Simple Storage Service.
kms_key_id – (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_spill_encryption – (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.
disable_glue – (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 depuis AWS Glue.
glue_catalog – (Facultatif) Utilisez cette option pour spécifier un catalogue AWS Glue entre compte. Par défaut, le connecteur tente d’obtenir des métadonnées depuis son propre compte AWS Glue.
default_docdb – 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_projection_and_casing – (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 frais de transfert interrégionaux, consultez la page Frais de transfert de données AWS pour les architectures avec et sans serveur sur le blog du réseau de partenaires AWS.
  - É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_case_insensitive_match – (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 pour une partie ou la totalité de la valeur des 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 ou un point de terminaison de VPC 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 <username>:<password>. Les secrets stockés sous la forme {username:<username>,password:<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

Créez une base de données Glue portant le même nom que votre collection DocumentDB.
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

Exécutez votre requête.
Consultez les journaux CloudWatch de la fonction Lambda pour vérifier la réussite de la récupération des métadonnées. 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

Comme la fonctionnalité d’inférence de schéma intégrée au connecteur analyse un nombre limité de documents et ne prend en charge qu’un sous-ensemble de types de données, vous pouvez utiliser à la place AWS Glue pour les métadonnées.

Pour activer une table AWS Glue à utiliser avec Amazon DocumentDB, vous devez disposer d’une base de données et d’une table AWS Glue pour la base de données et la collection DocumentDB pour lesquelles vous souhaitez fournir des métadonnées supplémentaires.

Pour utiliser une table AWS Glue pour des métadonnées supplémentaires

Utilisez la console AWS Glue pour créer une base de données AWS Glue portant le même nom que le nom de votre base de données Amazon DocumentDB.
Définissez la propriété URI de la base de données pour inclure docdb-metadata-flag.
(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 votre table AWS Glue porte un nom différent du nom de la table dans Amazon DocumentDB. Les différences de règles de dénomination entre AWS Glue et Amazon DocumentDB peuvent rendre cette action nécessaire. Par exemple, les majuscules ne sont pas autorisées dans les noms de tables AWS Glue, mais elles le sont dans les noms de tables Amazon DocumentDB.
(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 colonnes AWS Glue vous empêchent de créer une table AWS Glue portant les mêmes noms de colonnes 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é de table AWS Glue columnMapping, vous pouvez supprimer la variable d'environnement Lambda disable_projection_and_casing.
Veillez à utiliser les types de données appropriés pour AWS Glue, comme indiqué dans ce document.

Prise en charge du type de données

Cette section répertorie les types de données utilisés par le connecteur DocumentDB pour l’inférence de schéma, ainsi que les types de données lorsque des métadonnées AWS Glue 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	Chaîne
INT	Entier
BIGINT	Long
BIT	Booléen
FLOAT4	Float
FLOAT8	Double
TIMESTAMPSEC	Date
VARCHAR	ObjectId
LIST	Liste
STRUCT	Document

AWS GlueTypes de données

Si vous utilisez AWS Glue pour des métadonnées supplémentaires, vous pouvez configurer les types de données suivants. Le tableau montre 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
Liste	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. 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 aboutir à un échec rapide 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 AWS Glue Data Catalog pour obtenir des informations sur le schéma.
CloudWatch Logs – Le connecteur nécessite un accès à CloudWatch Logs pour stocker les journaux.
Accès en lecture à AWS Secrets Manager— 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.

Performances

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. Pour plus d’informations sur les interrogations avec Amazon DocumentDB, consultez Querying 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 obtenir un article concernant l’utilisation d’une requête fédérée Amazon Athena afin de connecter une base de données MongoDB à Quick Suite et créer des tableaux de bord et des visualisations, consultez Visualize MongoDB data from Quick Suite using Amazon Athena Federated Query dans le blog AWS Big Data Blog.
Pour plus d'informations sur ce connecteur, consultez le site correspondant sur GitHub.com.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Db2 iSeries

DynamoDB