# Conector de Google Cloud Storage para Amazon Athena El conector de Google Cloud Storage para Amazon Athena permite que Amazon Athena ejecute consultas en archivos Parquet y CSV almacenados en un bucket de Google Cloud Storage (GCS). Después de agrupar uno o varios archivos Parquet o CSV en una carpeta particionada o no participada de un bucket de GCS, puede organizarlos en una tabla de base de datos de [AWS Glue](https://aws.amazon.com/glue/). Este conector se puede registrar en el Catálogo de datos de Glue como un catálogo federado. Admite los controles de acceso a los 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. 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. Para consultar un artículo en el que se indica cómo utilizar Athena para ejecutar consultas en archivos Parquet o CSV en un bucket de GCS, consulte la publicación en el blog de Big Data de AWS [Utilizar Amazon Athena para consultar datos almacenados en Google Cloud Platform](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/). ## Requisitos previos + Configure una base de datos y una tabla de AWS Glue que se correspondan con el bucket y las carpetas de Google Cloud Storage. Para conocer los pasos, consulte [Configuración de bases de datos y tablas en AWS Glue](#connectors-gcs-setting-up-databases-and-tables-in-glue) más adelante en este documento. + 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](connect-to-a-data-source.md) o [Uso del AWS Serverless Application Repository para implementar un conector de origen de datos](connect-data-source-serverless-app-repo.md). ## Limitaciones + Las operaciones de escritura de DDL no son compatibles. + Cualquier límite de Lambda relevante. Para obtener más información, consulte [Cuotas de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) en la *Guía para desarrolladores de AWS Lambda*. + Actualmente, el conector solo admite el tipo `VARCHAR` para columnas de partición (`string` o `varchar` en un esquema de tabla de AWS Glue). Otros tipos de campos de partición generan errores cuando se los consulta en Athena. ## Términos Los siguientes términos tienen relación con el conector de GCS. + **Controlador**: controlador de Lambda que accede al bucket de GCS. Un controlador puede ser para los metadatos o para los registros de datos. + **Controlador de metadatos**: controlador de Lambda que recupera metadatos del bucket de GCS. + **Controlador de registros**: controlador de Lambda que recupera registros de datos del bucket de GCS. + **Controlador compuesto**: controlador de Lambda que recupera tanto metadatos como registros de datos del bucket de GCS. ## Tipos de archivo admitidos El conector GCS admite los tipos de archivo Parquet y CSV. **nota** Asegúrese de no colocar tanto archivos CSV como Parquet en el mismo bucket o ruta de GCS. Si lo hace, se puede producir un error de tiempo de ejecución cuando se intenten leer archivos Parquet como CSV o viceversa. ## Parameters Utilice los parámetros de esta sección para configurar el conector GCS. **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](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html). A partir del 3 de diciembre de 2024, utilice los parámetros que se indican a continuación únicamente al [implementar manualmente](connect-data-source-serverless-app-repo.md) una versión anterior de un conector de origen de datos de Athena. ### Conectores federados de AWS Glue Data Catalog Recomendamos configurar un conector de GCS por medio de un objeto de conexiones de Glue. Para ello, establezca la variable de entorno `glue_connection` de la función de Lambda del conector de GCS con el nombre de la conexión de Glue que desee utilizar. **Propiedades de las conexiones de Glue** Utilice el siguiente comando para obtener el esquema de un objeto de conexión de Glue. Este esquema contiene todos los parámetros que puede utilizar para controlar su conexión. ``` aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE ``` **Propiedades del entorno de Lambda** Las siguientes propiedades del entorno de Lambda se aplican solo cuando utiliza el conector con una función de Lambda en su cuenta. + **glue\_connection**: especifica el nombre de la conexión de Glue asociada al conector federado. **nota** Todos los conectores que utilizan una conexión federada de AWS Glue Data Catalog deben utilizar AWS Secrets Manager para almacenar credenciales. El conector de GCS creado por medio de una conexión federada de AWS Glue Data Catalog no admite el uso de un controlador de multiplexación. El conector de GCS creado por medio de una conexión federada de AWS Glue Data Catalog solo es compatible con `ConnectionSchemaVersion` 2. ### Conectores federados del catálogo 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **secret\_manager\_gcp\_creds\_name**: nombre del secreto de AWS Secrets Manager que contiene las credenciales de GCS en formato JSON (por ejemplo, `GoogleCloudPlatformCredentials`). ## Configuración de bases de datos y tablas en AWS Glue Dado que la capacidad de inferencia de esquemas integrada del conector de GCS es limitada, se recomienda utilizar AWS Glue para los metadatos. En los siguientes procedimientos se muestra cómo crear una base de datos y una tabla en AWS Glue a las que se puede acceder desde Athena. ### Creación de una base de datos en AWS Glue Puede utilizar la consola de AWS Glue para crear una base de datos y utilizarla con el conector de GCS. **Para crear una base de datos en AWS Glue** 1. Inicie sesión en la Consola de administración de AWS y abra la consola de AWS Glue en [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/). 1. Seleccione **Databases** (Bases de datos) en el panel de navegación. 1. Elija **Agregar una base de datos**. 1. En **Name** (Nombre), ingrese un nombre para la base de datos que desee utilizar con el conector de GCS. 1. En **Ubicación**, especifique `google-cloud-storage-flag`. Esta ubicación informa al conector GCS que la base de datos de AWS Glue contiene tablas para los datos de GCS que se consultarán en Athena. El conector reconoce las bases de datos de Athena que tienen esta marca e ignora aquellas que no la tienen. 1. Elija **Creación de base de datos**. ### Creación de una tabla en AWS Glue Ahora puede crear una tabla para la base de datos. Cuando se crea una tabla de AWS Glue para utilizarla con el conector de GCS, se deben especificar metadatos adicionales. **Para crear una tabla en la consola de AWS Glue** 1. En la consola de AWS Glue, seleccione **Tables** (Tablas) en el panel de navegación. 1. En la página **Tables** (Tablas), seleccione **Add table** (Agregar tabla). 1. En la página **Set table properties** (Establecer propiedades de la tabla), ingrese la siguiente información: + **Name** (Nombre): nombre exclusivo para la tabla. + **Database** (Base de datos): seleccione la base de datos de AWS Glue que haya creado para el conector de GCS. + **Include path** (Incluir ruta): en la sección **Data store** (Almacén de datos), en **Include path** (Incluir ruta), ingrese la ubicación URI de GCS con el prefijo `gs://` (por ejemplo,`gs://{{gcs_table}}/{{data}}/`). Si tiene una o varias carpetas de particiones, no las incluya en la ruta. **nota** Cuando se introduce la ruta de tabla no `s3://`, la consola de AWS Glue muestra un error. Puede omitir este error. La tabla se creará correctamente. + **Data format** (Formato de datos): en **Classification** (Clasificación), seleccione **CSV** o **Parquet**. 1. Seleccione **Siguiente**. 1. En la página **Choose or define schema** (Seleccionar o definir esquema), se recomienda encarecidamente definir un esquema de tabla, aunque no es obligatorio. Si no se define un esquema, el conector de GCS intentará inferirlo automáticamente. Realice una de las siguientes acciones: + Si desea que el conector de GCS intente inferir un esquema automáticamente, seleccione **Next** (Siguiente), y luego **Create** (Crear). + Para definir un esquema por sí mismo, ejecute los pasos de la siguiente sección. ### Definición de un esquema de tabla en AWS Glue Definir un esquema de tabla en AWS Glue requiere más pasos, pero ofrece un mayor control sobre el proceso de creación de tablas. **Para definir un esquema para una tabla en AWS Glue** 1. En la página **Choose or define schema** (Seleccionar o definir esquema), seleccione **Add** (Agregar). 1. Utilice el cuadro de diálogo **Add schema entry** (Agregar entrada de esquema) para proporcionar un nombre de columna y un tipo de datos. 1. Para designar la columna como columna de partición, seleccione la opción **Set as partition key** (Establecer como clave de partición). 1. Seleccione **Save** (Guardar) para guardar la columna. 1. Seleccione **Add** (Agregar) para agregar otra columna. 1. Cuando haya terminado de agregar columnas, seleccione **Next** (Siguiente). 1. En la página **Review and créate** (Revisar y crear), revise la tabla y, a continuación, seleccione **Create** (Crear). 1. Si el esquema contiene información sobre particiones, ejecute los pasos de la siguiente sección para agregar un patrón de partición a las propiedades de la tabla en AWS Glue. ### Adición de un patrón de partición a propiedades de tabla en AWS Glue Si los buckets de GCS tienen particiones, se debe agregar el patrón de partición a las propiedades de la tabla en AWS Glue. **Para agregar información de partición a propiedades de tabla en AWS Glue** 1. En la página de detalles de la tabla que haya creado en AWS Glue, seleccione **Actions** (Acciones), **Edit table** (Editar tabla). 1. En la página **Edit table** (Editar tabla), desplácese hacia abajo hasta la sección **Table properties** (Propiedades de la tabla). 1. Seleccione **Add** (Agregar) para agregar una clave de partición. 1. En **Clave**, escriba **partition.pattern**. Esta clave define el patrón de ruta de la carpeta. 1. En **Value** (Valor), introduzca un patrón de ruta de carpeta como **StateName=${statename}/ZipCode=${zipcode}/**, por ejemplo, donde **statename** y **zipcode**, que van dentro de **${}**, son nombres de columnas de partición. El conector de GCS admite esquemas de partición Hive y no Hive. 1. Cuando termine de actualizar las etiquetas, elija **Guardar**. 1. Para ver las propiedades de tabla que acaba de crear, seleccione la pestaña **Advanced properties** (Propiedades avanzadas). En este punto, puede navegar hasta la consola de Athena. La base de datos y la tabla que haya creado en AWS Glue están disponibles para realizar consultas en Athena. ## Compatibilidad con tipos de datos En las siguientes tablas se muestran los tipos de datos admitidos para CSV y Parquet. ### CSV **** | **Naturaleza de los datos** | **Tipo de datos inferidos** | | --- | --- | | Los datos parecen un número | BIGINT | | Los datos parecen una cadena | VARCHAR | | Los datos parecen de punto flotante (flotantes, dobles o decimales) | DOUBLE | | Los datos parecen una fecha | Marca de tiempo | | Datos que contienen valores verdadero/falso | BOOL | ### Parquet **** | **PARQUET** | **Athena (Arrow)** | | --- | --- | | BINARIO | VARCHAR | | BOOLEANO | BOOL | | DOUBLE | DOUBLE | | ENUM | VARCHAR | | FIXED\_LEN\_BYTE\_ARRAY | DECIMAL | | FLOAT | FLOAT (32 bits) | | INT32 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/es_es/athena/latest/ug/connectors-gcs.html) | | INT64 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/es_es/athena/latest/ug/connectors-gcs.html) | | INT96 | Marca de tiempo | | MAP | MAP | | STRUCT | STRUCT | | LIST | LIST | ## 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-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.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 GCS requiere acceso de solo lectura a AWS Glue Data Catalog para obtener información sobre un esquema. + **Registros de CloudWatch**: el conector requiere acceso a Registros de CloudWatch para almacenar registros. ## Rendimiento Cuando el esquema de la tabla contiene campos de partición y la propiedad de tabla `partition.pattern` está configurada correctamente, se puede incluir el campo de partición en la cláusula `WHERE` de las consultas. En esas consultas, el conector de GCS utiliza las columnas de partición para ajustar la ruta de la carpeta de GCS y evitar analizar archivos innecesarios en las carpetas de GCS. En el caso de los conjuntos de datos Parquet, seleccionar un subconjunto de columnas da como resultado que se analicen menos datos. Esto suele traducirse en un menor tiempo de ejecución de consultas cuando se aplica la proyección de columnas. En el caso de los conjuntos de datos CSV, no se admite la proyección de columnas y no se reduce la cantidad de datos que se analizan. Las cláusulas `LIMIT` reducen la cantidad de datos analizados; sin embargo, si no se proporciona un predicado, es probable que las consultas `SELECT` con una cláusula `LIMIT` analicen al menos 16 MB de datos. El conector de GCS analiza más datos para los conjuntos de datos de mayor tamaño que para los conjuntos de datos más pequeños, independientemente de la cláusula `LIMIT` aplicada. Por ejemplo, la consulta `SELECT * LIMIT 10000` analiza más datos para un conjunto de datos subyacente de mayor tamaño que para uno más pequeño. ### Información sobre licencias Al usar este conector, reconoce la inclusión de componentes de terceros, cuya lista se puede encontrar en el archivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) para este conector y acepta los términos de las licencias de terceros correspondientes que se proporcionan en el archivo [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) de GitHub.com. ### Recursos adicionales Para obtener más información acerca de este conector, consulte [el sitio correspondiente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs) en GitHub.com.