Conector para DocumentDB de Amazon Athena

El conector de DocumentDB de Amazon Athena permite a Athena comunicarse con sus instancias de DocumentDB para que pueda consultar los datos de DocumentDB con SQL. El conector también funciona con cualquier punto de conexión compatible con MongoDB.

A diferencia de los almacenes de datos relacionales tradicionales, las colecciones de Amazon DocumentDB no tienen ningún esquema establecido. DocumentDB no tiene un almacén de metadatos. Cada entrada de una colección de DocumentDB puede tener diferentes campos y tipos de datos.

El conector de DocumentDB admite dos mecanismos para generar información de esquema de tabla: inferencia básica de esquemas y metadatos de AWS Glue Data Catalog.

La inferencia de esquemas es la opción predeterminada. Esta opción escanea una pequeña cantidad de documentos de la colección, forma una unión de todos los campos y fuerza los campos que tienen tipos de datos no superpuestos. Esta opción funciona bien para colecciones que, en su mayoría, tienen entradas uniformes.

Para las recopilaciones con una mayor variedad de tipos de datos, el conector admite la recuperación de metadatos de AWS Glue Data Catalog. Si el conector ve una base de datos y una tabla de AWS Glue que coinciden con los nombres de la colección y la base de datos de DocumentDB, obtiene la información del esquema de la tabla de AWS Glue correspondiente. Al crear la tabla de AWS Glue, le recomendamos que la convierta en un superconjunto de todos los campos a los que quiera acceder desde su colección de DocumentDB.

Si Lake Formation está habilitado en la cuenta, el rol de IAM del conector de Lambda federado de Athena que haya implementado en AWS Serverless Application Repository debe tener acceso de lectura en Lake Formation para AWS Glue Data Catalog.

Este conector no se puede registrar en el Catálogo de datos de Glue como catálogo federado. Este conector no es compatible con los controles de acceso a datos definidos en Lake Formation a nivel de catálogo, base de datos, tabla, columna, fila y etiqueta. Este conector utiliza Conexiones de Glue para centralizar las propiedades de configuración en Glue.

Requisitos previos

• Implemente el conector en su Cuenta de AWS mediante la consola de Athena o AWS Serverless Application Repository. Para obtener más información, consulte Cómo crear una conexión de origen de datos o Uso del AWS Serverless Application Repository para implementar un conector de origen de datos.

Parámetros

Utilice los parámetros de esta sección para configurar el conector DocumentDB.

nota

Los conectores de orígenes de datos de Athena creados a partir del 3 de diciembre de 2024 utilizan conexiones de AWS Glue.

Los nombres y definiciones de los parámetros que se indican a continuación corresponden a conectores de orígenes de datos de Athena creados antes del 3 de diciembre de 2024. Estos pueden variar respecto a las propiedades de conexión de AWS Glue correspondientes. A partir del 3 de diciembre de 2024, utilice los parámetros que se indican a continuación únicamente al implementar manualmente una versión anterior de un conector de origen de datos de Athena.

• spill_bucket: especifica el bucket de Amazon S3 para los datos que superen los límites de la función de Lambda.

• spill_prefix: (opcional) de forma predeterminada, se establece una subcarpeta en la carpeta especificada spill_bucket llamada athena-federation-spill. Le recomendamos configurar un ciclo de vida de almacenamiento de Amazon S3 en esta ubicación para eliminar vertidos de más de un número predeterminado de días u horas.

• spill_put_request_headers: (opcional) un mapa codificado en JSON de encabezados y valores de solicitudes para la solicitud putObject de Amazon S3 que se usa para el vertidos (por ejemplo, {"x-amz-server-side-encryption" : "AES256"}). Para ver otros encabezados posibles, consulte PutObject en la referencia de la API de Amazon Simple Storage Service.

• kms_key_id: (opcional) de forma predeterminada, los datos que se vierten a Amazon S3 se cifran mediante el modo de cifrado autenticado AES-GCM y una clave generada aleatoriamente. Para que la función de Lambda use claves de cifrado más seguras generadas por KMS, como a7e63k4b-8loc-40db-a2a1-4d0en2cd8331, puede especificar un ID de clave de KMS.

• disable_spill_encryption: (opcional) cuando se establece en True, desactiva el cifrado del vertido. El valor predeterminado es False, de modo que los datos que se vierten a S3 se cifran mediante AES-GCM, ya sea mediante una clave generada aleatoriamente o KMS para generar claves. La desactivación del cifrado de vertido puede mejorar el rendimiento, especialmente si su ubicación de vertido usa cifrado del servidor.

• disable_glue: (opcional) si está presente y se establece en true (verdadero), el conector no intentará recuperar metadatos complementarios de AWS Glue.

• glue_catalog: (opcional) use esta opción para especificar un catálogo de AWS Glue entre cuentas. De forma predeterminada, el conector intenta obtener los metadatos de su propia cuenta de AWS Glue.

• default_docdb: si está presente, especifica una cadena de conexión de DocumentDB que se utilizará cuando no exista ninguna variable de entorno específica del catálogo.

• disable_projection_and_casing: (opcional) desactiva la proyección y la distinción entre mayúsculas y minúsculas. Utilícelo si desea consultar tablas de Amazon DocumentDB que utilizan nombres de columna que distinguen mayúsculas de minúsculas El parámetro disable_projection_and_casing utiliza los siguientes valores para especificar el comportamiento de las mayúsculas y minúsculas y la asignación de columnas:

  • false (falso): esta es la configuración predeterminada. La proyección está habilitada y el conector espera que todos los nombres de las columnas estén en minúsculas.

  • true (verdadero): desactiva la proyección y la distinción entre mayúsculas y minúsculas. Al usar la el parámetro disable_projection_and_casing, tenga en cuenta los siguientes puntos:

    • El uso del parámetro puede dar lugar a un mayor uso del ancho de banda. Además, si su función de Lambda no está en la misma Región de AWS que su origen de datos, se generarán mayores costos por transferencia estándar entre regiones de AWS como resultado del mayor uso del ancho de banda. Para obtener más información sobre los costos por transferencia entre regiones, consulte AWS Data Transfer Charges for Server and Serverless Architectures en el blog de la Red de socios de AWS.

    • Debido a que se transfiere una mayor cantidad de bytes y a que esta requiere un mayor tiempo de deserialización, la latencia general puede aumentar.

• enable_case_insensitive_match: (Opcional) cuando true realiza búsquedas sin distinción de mayúsculas y minúsculas en nombres de esquemas y tablas en Amazon DocumentDB. El valor predeterminado es false. Utilícelo si la consulta contiene nombres de tablas o esquemas en mayúsculas.

Especificación de cadenas de conexión

Puede proporcionar una o más propiedades que definan los detalles de conexión de DocumentDB para las instancias de DocumentDB que utiliza con el conector. Para ello, defina una variable de entorno de Lambda que corresponda al nombre del catálogo que quiere usar en Athena. Por ejemplo, suponga que quiere usar las siguientes consultas para consultar dos instancias de DocumentDB diferentes desde Athena:

SELECT * FROM "docdb_instance_1".database.table

SELECT * FROM "docdb_instance_2".database.table

Antes de poder usar estas dos instrucciones SQL, debe agregar dos variables de entorno a la función de Lambda: docdb_instance_1 y docdb_instance_2. El valor de cada una debe ser una cadena de conexión de DocumentDB con el siguiente formato:

mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0      

Uso de los secretos

Si lo desea, puede usar AWS Secrets Manager para obtener parte o la totalidad del valor de los detalles de la cadena de conexión. Para utilizar la característica Consulta federada de Athena con Secrets Manager, la VPC conectada a la función de Lambda debe tener acceso a Internet o un punto de conexión de VPC para conectarse a Secrets Manager.

Si usa la sintaxis ${my_secret} para poner el nombre de un secreto de Secrets Manager en la cadena de conexión, el conector reemplaza ${my_secret} por los valores de texto plano de Secrets Manager. Los secretos deben almacenarse como un secreto de texto plano con valor <username>:<password>. Los secretos almacenados como {username:<username>,password:<password>} no se pasarán correctamente a la cadena de conexión.

Los secretos también se pueden usar para toda la cadena de conexión, y el nombre de usuario y la contraseña se pueden definir dentro del secreto.

Por ejemplo, supongamos que establece la variable de entorno de Lambda para docdb_instance_1 en el siguiente valor:

mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0         

El SDK de federación de consultas de Athena intenta recuperar automáticamente un secreto llamado docdb_instance_1_creds de Secrets Manager e inyecta ese valor en lugar de ${docdb_instance_1_creds}. Cualquier parte de la cadena de conexión que se incluya en la combinación de caracteres ${ } se interpreta como un secreto de Secrets Manager. Si especifica un nombre secreto que el conector no puede encontrar en Secrets Manager, el conector no reemplaza el texto.

Configuración de bases de datos y tablas en AWS Glue

Debido a que la capacidad de inferencia de esquemas integrada del conector escanea un número limitado de documentos y solo admite un subconjunto de tipos de datos, es posible que quiera usar AWS Glue para obtener metadatos en su lugar.

Habilitar una tabla de AWS Glue para usar con Amazon DocumentDB, debe tener una base de datos y tabla de AWS Glue para la base de datos y la colección de DocumentDB para las que desea proporcionar metadatos complementarios.

Para usar una tabla de AWS Glue para metadatos complementarios

1. Utilice la consola de AWS Glue para crear una base de datos AWS Glue que tenga el mismo nombre que su base de datos de Amazon DocumentDB.

2. Establezca la propiedad URI de la base de datos para incluir docdb-metadata-flag.

3. (Opcional) Agregue la propiedad de la tabla sourceTable. Esta propiedad define el nombre de la tabla de origen en Amazon DocumentDB. Utilice esta propiedad si su tabla de AWS Glue tiene un nombre diferente al de la tabla en Amazon DocumentDB. Las diferencias en las reglas de nomenclatura entre AWS Glue y Amazon DocumentDB pueden hacer que esto sea necesario. Por ejemplo, no se permiten mayúsculas en nombres de tablas de AWS Glue, pero se permiten en los de tablas de Amazon DocumentDB.

4. (Opcional) Agregue la propiedad de tabla columnMapping. Esta propiedad define las asignaciones de nombres de columnas. Use esta propiedad si las reglas de denominación de columnas de AWS Glue le impiden crear una tabla de AWS Glue con los mismos nombres que la tabla de Amazon DocumentDB. Esto puede resultar útil porque se permiten mayúsculas en nombres de columnas de Amazon DocumentDB, pero no se permiten en los nombres de columnas de AWS Glue.

   Se espera que el valor de la propiedad columnMapping sea un conjunto de asignaciones en el formato col1=Col1,col2=Col2.

   nota

   La asignación de columnas solo se aplica a los nombres de las columnas de nivel superior y no a los campos anidados.

   Tras agregar la propiedad de la tabla columnMapping de AWS Glue, puede eliminar la variable de entorno de Lambda disable_projection_and_casing.

5. Asegúrese de usar los tipos de datos adecuados para AWS Glue, como se indica en este documento.

Compatibilidad con tipos de datos

En esta sección, se enumeran los tipos de datos que el conector de DocumentDB utiliza para la inferencia de esquemas y los tipos de datos cuando se utilizan metadatos de AWS Glue.

Tipos de datos de inferencia de esquemas

La característica de inferencia de esquemas del conector de DocumentDB intenta inferir valores que pertenecen a uno de los siguientes tipos de datos. En la tabla se muestran los tipos de datos correspondientes para Amazon DocumentDB, Java y Apache Arrow.

Apache Arrow	Java o DocDB
VARCHAR	Cadena
INT	Entero
BIGINT	Largo
BIT	Booleano
FLOAT4	Flotante
FLOAT8	Doble
TIMESTAMPSEC	Date
VARCHAR	ObjectId
LIST	Enumeración
STRUCT	Documento

Tipos de datos de AWS Glue

Si usa AWS Glue para obtener metadatos adicionales, puede configurar los siguientes tipos de datos. En la tabla se muestran los tipos de datos correspondientes para AWS Glue y Apache Arrow.

AWS Glue	Apache Arrow
int	INT
bigint	BIGINT
double	FLOAT8
float	FLOAT4
boolean	BIT
binario	VARBINARY
cadena	VARCHAR
Enumeración	LIST
Struct	STRUCT

Permisos necesarios

Para obtener información completa sobre las políticas de IAM que requiere este conector, consulte la sección Policies del archivo athena-docdb.yaml. En la siguiente lista se resumen los permisos requeridos.

• Acceso de escritura a Amazon S3: el conector requiere acceso de escritura a una ubicación de Amazon S3 para volcar los resultados de consultas de gran tamaño.

• Athena GetQueryExecution: el conector usa este permiso para fallar rápidamente cuando finaliza la consulta ascendente de Athena.

• AWS Glue Data Catalog: el conector de DocumentDB requiere acceso de solo lectura a AWS Glue Data Catalog para obtener información sobre el esquema.

• Registros de CloudWatch: el conector requiere acceso a Registros de CloudWatch para almacenar registros.

• Acceso de lectura a AWS Secrets Manager: si decide almacenar los detalles del punto de conexión de DocumentDB en Secrets Manager, debe conceder al conector acceso a esos secretos.

• Acceso a la VPC: el conector requiere la capacidad de conectar y desconectar interfaces a la VPC para que pueda conectarse a ella y comunicarse con las instancias de DocumentDB.

Rendimiento

El conector para Amazon DocumentDB de Athena no admite actualmente análisis paralelos. En cambio, intenta insertar predicados como parte de sus consultas de DocumentDB, y los predicados de los índices de la colección de DocumentDB dan lugar a una cantidad mucho menor de datos analizados.

La función de Lambda inserta proyecciones para reducir los datos analizados por la consulta. Sin embargo, a veces, la selección de un subconjunto de columnas provoca un tiempo de ejecución de consultas más prolongado. Las cláusulas LIMIT reducen la cantidad de datos analizados; sin embargo, si no proporciona un predicado, es probable que las consultas SELECT con una cláusula LIMIT analicen al menos 16 MB de datos.

Consultas de acceso directo

El conector de Amazon DocumentDB de Athena admite consultas de acceso directo y está basado en NoSQL. Para obtener más información sobre consultas en Amazon DocumentDB, diríjase a Consultas en la Guía para desarrolladores de Amazon DocumentDB.

Para usar consultas de acceso directo con Amazon DocumentDB, utilice la siguiente sintaxis:

SELECT * FROM TABLE(
        system.query(
            database => 'database_name',
            collection => 'collection_name',
            filter => '{query_syntax}'
        ))

El siguiente ejemplo consulta la base de datos example de la colección TPCDS y filtra todos los libros con el título Bill of Rights.

SELECT * FROM TABLE(
        system.query(
            database => 'example',
            collection => 'tpcds',
            filter => '{title: "Bill of Rights"}'
        ))

Recursos adicionales

• Para obtener información sobre cómo usar Amazon Athena Federated Query a fin de conectar una base de datos de MongoDB a Amazon QuickSight y crear cuadros de mando y visualizaciones, consulte el artículo Visualización de datos de MongoDB desde Amazon QuickSight mediante Amazon Athena Federated Query en el Blog de macrodatos de AWS.

• Para obtener más información acerca de este conector, consulte el sitio correspondiente en GitHub.com.