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

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

Paramètres

Utilisez les variables d’environnement Lambda de cette section pour configurer le connecteur DocumentDB.

• 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 le PutObjectmanuel Amazon Simple Storage Service API Reference.

• 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 à partir de. 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 à partir de son propre AWS Glue compte.

• 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 coûts de transfert entre régions, consultez la section Frais de transfert de AWS données pour les architectures serveur et sans 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_case_insensitive_match — (Facultatif) Lorsquetrue, effectue des recherches sans distinction majuscules/minuscules sur les noms de schéma et de table dans Amazon DocumentDB. L’argument 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 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.

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. Lorsque vous modifiez la table et la base de données dans la AWS Glue console, ajoutez la propriété de table suivante.

   • docdb-metadata-flag— Cette propriété indique au connecteur DocumentDB que le connecteur peut utiliser la table pour des métadonnées supplémentaires. Vous pouvez fournir n’importe quelle valeur pour docdb-metadata-flag tant que la propriété docdb-metadata-flag est présente dans la liste des propriétés de la table.

2. (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 les règles de dénomination des AWS Glue tables vous empêchent de créer une AWS Glue table portant le même nom que votre table Amazon DocumentDB. 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.

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

4. 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	Chaîne
INT	Entier
BIGINT	Long
BIT	Booléen
FLOAT4	Float
FLOAT8	Double
TIMESTAMPSEC	Date
VARCHAR	ObjectId
LIST	Liste
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
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 é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 passthrough

Le connecteur Athena Amazon DocumentDB prend en charge les requêtes passthrough et est basé sur NoSQL. Pour plus d'informations sur l'interrogation d'Amazon DocumentDB, consultez la section Requête dans le manuel du développeur Amazon DocumentDB.

Pour utiliser des requêtes directes 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 example base de données de la TPCDS collection, 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 à QuickSightAmazon afin de créer des tableaux de bord et des visualisations, consultez Visualiser les données MongoDB d'Amazon à l' QuickSight aide d'Amazon Athena Federated Query sur le blog Big Data.AWS

• Pour plus d'informations sur ce connecteur, rendez-vous sur le site correspondant sur GitHub .com.