# Conector Google Cloud Storage para Amazon Athena O conector Google Cloud Storage para Amazon Athena permite que o Amazon Athena execute consultas em arquivos Parquet e CSV armazenados em um bucket do Google Cloud Storage (GCS). Depois de agrupar um ou mais arquivos Parquet ou CSV em uma pasta não particionada ou particionada em um bucket do GCS, você poderá organizá-los em uma tabela de banco de dados do [AWS Glue](https://aws.amazon.com/glue/). Esse conector pode ser registrado como um catálogo federado no Glue Data Catalog. Ele é compatível com controles de acesso a dados definidos no Lake Formation nos níveis de catálogo, banco de dados, tabela, coluna, linha e tag. Esse conector usa o Glue Connections para centralizar as propriedades de configuração no Glue. Se você tiver o Lake Formation habilitado em sua conta, o perfil do IAM para seu conector Lambda federado para Athena que você implantou no AWS Serverless Application Repository deve ter acesso de leitura ao AWS Glue Data Catalog no Lake Formation. Para ver um artigo que mostra como usar o Athena para executar consultas em arquivos Parquet ou CSV em um bucket do GCS, consulte a postagem [Use Amazon Athena to query data stored in Google Cloud Platform](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/). no AWS Big Data Blog. ## Pré-requisitos + Configure um banco de dados e uma tabela do AWS Glue que correspondam ao seu bucket e suas pastas no Google Cloud Storage. Para ver as etapas, consulte [Configuração de bancos de dados e tabelas no AWS Glue](#connectors-gcs-setting-up-databases-and-tables-in-glue) mais adiante neste documento. + Implante o conector na sua Conta da AWS usando o console do Athena ou o AWS Serverless Application Repository. Para ter mais informações, consulte [Criar uma conexão de fonte de dados](connect-to-a-data-source.md) ou [Usar o AWS Serverless Application Repository para implantar um conector de fonte de dados](connect-data-source-serverless-app-repo.md). ## Limitações + Não há suporte para operações de gravação de DDL. + Quaisquer limites relevantes do Lambda. Para obter mais informações, consulte [Cotas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) no *Guia do desenvolvedor do AWS Lambda*. + Atualmente, o conector é compatível somente com o tipo `VARCHAR` de colunas de partição (`string` ou `varchar` em um esquema de tabela do AWS Glue). Outros tipos de campo de partição geram erros quando você os consulta no Athena. ## Termos Os termos a seguir estão relacionados ao conector GCS. + **Manipulador**: um manipulador Lambda que acessa seu bucket do GCS. Um manipulador pode ser para metadados ou para registros de dados. + **Manipulador de metadados**: um manipulador Lambda que recupera metadados do seu bucket do GCS. + **Manipulador de registros**: um manipulador Lambda que recupera registros de dados do seu bucket do GCS. + **Manipulador composto**: um manipulador Lambda que recupera tanto metadados quanto registros de dados do seu bucket do GCS. ## Tipos de arquivos compatíveis O conector GCS é compatível com os tipos de arquivo Parquet e CSV. **nota** Certifique-se de não colocar os arquivos CSV e Parquet no mesmo bucket ou caminho do GCS. Isso pode resultar em um erro de runtime se houver tentativa de ler os arquivos Parquet como CSV ou vice-versa. ## Parâmetros Use os parâmetros nesta seção para configurar o conector do GCS. **nota** Os conectores de fonte de dados do Athena criados a partir de 3 de dezembro de 2024 usam conexões do AWS Glue. Os nomes e definições dos parâmetros listados abaixo são para conectores de fonte de dados do Athena criados antes de 3 de dezembro de 2024. Eles podem diferir de suas [propriedades de conexão do AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html) correspondentes. A partir de 3 de dezembro de 2024, use os parâmetros abaixo somente ao [implantar manualmente](connect-data-source-serverless-app-repo.md) uma versão anterior de um conector de fonte de dados do Athena. ### Conectores federados do AWS Glue Data Catalog Recomendamos que você configure um conector do GCS usando um objeto de conexão do Glue. Para isso, defina a variável de ambiente `glue_connection` do Lambda do conector do GCS como o nome da conexão do Glue a ser usada. **Propriedades das conexões do Glue** Use o comando apresentado a seguir para obter o esquema de um objeto de conexão do Glue. Esse esquema contém todos os parâmetros que você pode usar para controlar a conexão. ``` aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE ``` **Propriedades do ambiente do Lambda** As propriedades do ambiente do Lambda a seguir se aplicam somente quando você usa o conector com uma função do Lambda em sua conta. + **glue\_connection**: especifica o nome da conexão do Glue associada ao conector federado. **nota** Todos os conectores que usam a conexão federada do AWS Glue Data Catalog devem usar o AWS Secrets Manager para armazenar as credenciais. O conector para GCS criado por meio de uma conexão federada do AWS Glue Data Catalog não é compatível com o uso de um manipulador de multiplexação. O conector para GCS criado por meio de uma conexão federada do AWS Glue Data Catalog é compatível apenas com `ConnectionSchemaVersion` 2. ### Conectores federados do catálogo de dados do Athena + **spill\_bucket**: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda. + **spill\_prefix**: (opcional) assume como padrão uma subpasta no `spill_bucket` especificado chamado `athena-federation-spill`. Recomendamos que você configure um [ciclo de vida de armazenamento](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) do Amazon S3 neste local para excluir derramamentos anteriores a um número predeterminado de dias ou horas. + **spill\_put\_request\_headers**: (opcional) um mapa codificado em JSON de cabeçalhos e valores de solicitações para a solicitação `putObject` do Amazon S3 usada para o derramamento (por exemplo, `{"x-amz-server-side-encryption" : "AES256"}`). Para outros cabeçalhos possíveis, consulte [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) na *Referência da API do Amazon Simple Storage Service*. + **kms\_key\_id**: (opcional) por padrão, todos os dados transmitidos para o Amazon S3 são criptografados usando o modo de criptografia autenticado AES-GCM e uma chave gerada aleatoriamente. Para que sua função do Lambda use chaves de criptografia mais fortes geradas pelo KMS, como `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`, é possível especificar um ID de chave do KMS. + **disable\_spill\_encryption**: (opcional) quando definido como `True`, desativa a criptografia do derramamento. É padronizado como `False`, para que os dados transmitidos para o S3 sejam criptografados usando o AES-GCM — usando uma chave gerada aleatoriamente ou o KMS para gerar chaves. Desativar a criptografia do derramamento pode melhorar a performance, especialmente se o local do derramamento usar [criptografia no lado do servidor](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **secret\_manager\_gcp\_creds\_name**: o nome do segredo no AWS Secrets Manager que contém suas credenciais do GCS no formato JSON (por exemplo, `GoogleCloudPlatformCredentials`). ## Configuração de bancos de dados e tabelas no AWS Glue Como a capacidade de inferência de esquema integrada do conector GCS é limitada, recomendamos que você use o AWS Glue para seus metadados. Os procedimentos a seguir mostram como criar um banco de dados e uma tabela do AWS Glue que você possa acessar a partir do Athena. ### Criação de um banco de dados no AWS Glue Você pode usar o console do AWS Glue para criar um banco de dados para uso com o conector GCS. **Para criar um banco de dados no AWS Glue** 1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/). 1. Escolha **Databases** (Bancos de dados) no painel de navegação. 1. Selecione **Adicionar banco de dados**. 1. Em **Name** (Nome), insira um nome para o banco de dados que você deseja usar com o conector GCS. 1. Em **Local**, especifique `google-cloud-storage-flag`. Esse local informa ao conector do GCS que o banco de dados do AWS Glue contém as tabelas para os dados do GCS para consulta no Athena. O conector reconhece bancos de dados no Athena que têm esse sinalizador e ignora bancos de dados que não o têm. 1. Selecione **Criar banco de dados**. ### Criar uma tabela no AWS Glue Agora você pode criar uma tabela para o banco de dados. Ao criar uma tabela do AWS Glue para usar com o conector GCS, você deve especificar metadados adicionais. **Para criar uma tabela no console do AWS Glue** 1. No painel de navegação do console do AWS Glue, escolha **Tables** (Tabelas). 1. Na página **Tables** (Tabelas), escolha **Add table** (Adicionar tabela). 1. Na página **Set table properties** (Definir propriedades da tabela), insira as informações a seguir. + **Name** (Tabela): um nome exclusivo para a tabela. + **Banco de dados**: escolha o banco de dados do AWS Glue que você criou para o conector GCS. + **Include path** (Incluir caminho): Na seção **Data store** (Armazenamento de dados), em **Include path** (Incluir caminho), insira a localização do URI para GCS prefixada por `gs://` (por exemplo, `gs://{{gcs_table}}/{{data}}/`). Se você tiver uma ou mais pastas de partição, não as inclua no caminho. **nota** Quando você insere um caminho de table que não é do `s3://` tabela, o console do AWS Glue mostra um erro. Você pode ignorar esse erro. A tabela será criada com êxito. + **Formato de dados**: para **Classification** (Classificação), selecione **CSV** ou **Parquet**. 1. Escolha **Próximo**. 1. Na página **Choose or define schema** (Escolher ou definir esquema), definir um esquema de tabela é altamente recomendado, mas não obrigatório. Se você não definir um esquema, o conector GCS tentará inferir um esquema para você. Execute um destes procedimentos: + Se você quiser que o conector GCS tente inferir um esquema para você, escolha **Next** (Próximo) e, em seguida, escolha **Create** (Criar). + Para definir um esquema você mesmo, siga as etapas da próxima seção. ### Definir um esquema de tabela no AWS Glue Definir um esquema de tabela no AWS Glue requer mais etapas, mas oferece maior controle sobre o processo de criação da tabela. **Para definir um esquema para sua tabela no AWS Glue** 1. Na página **Choose or define schema** (Escolher ou definir esquema), escolha **Add** (Adicionar). 1. Use a caixa de diálogo **Add schema entry** (Adicionar entrada de esquema) para fornecer um nome de coluna e um tipo de dados. 1. Para designar a coluna como uma coluna de partição, selecione a opção **Set as partition key** (Definir como chave de partição). 1. Escolha **Save** (Salvar) para salvar a alteração. 1. Selecione **Add** (Adicionar) para adicionar outra coluna. 1. Ao terminar de adicionar contas, escolha **Next** (Próximo). 1. Na página **Review and create** (Revisar e criar), revise a configuração e selecione **Create** (Criar). 1. Se o esquema contiver informações sobre partições, siga as etapas na próxima seção para adicionar um padrão de partição às propriedades da tabela em AWS Glue. ### Adicionar um padrão de partição às propriedades da tabela no AWS Glue Se seus buckets do GCS tiverem partições, você deverá adicionar o padrão de partição às propriedades da tabela no AWS Glue. **Para adicionar informações de partição às propriedades da tabela do AWS Glue** 1. Na página de detalhes da tabela que você criou em AWS Glue, escolha **Actions** (Ações), **Edit table** (Editar tabela). 1. Na página **Edit table** (Editar tabela), role para baixo até a seção **Table properties** (Propriedades da tabela). 1. Escolha **Add** (Adicionar) para adicionar uma chave de partição. 1. Em **Chave**, digite **partition.pattern**. Essa chave define o padrão do caminho da pasta. 1. Em **Value** (Valor), insira um padrão de caminho de pasta como **StateName=${statename}/ZipCode=${zipcode}/**, em que **statename** e **zipcode** delimitados por **${}** são nomes de colunas de partição. O conector GCS é compatível com esquemas de partição Hive e não Hive. 1. Quando terminar, escolha **Salvar**. 1. Para visualizar as propriedades da tabela que você acabou de criar, escolha a guia **Advanced properties** (Propriedades avançadas). Nesse ponto, você pode navegar até o console do Athena. O banco de dados e a tabela que você criou no AWS Glue estão disponíveis para consulta no Athena. ## Suporte ao tipo de dados As tabelas a seguir mostram os tipos de dados com suporte para CSV e Parquet. ### CSV **** | **Natureza dos dados** | **Tipo de dados inferido** | | --- | --- | | Os dados parecem um número | BIGINT | | Os dados parecem uma string | VARCHAR | | Os dados parecem de ponto flutuante (flutuante, duplo ou decimal) | DOUBLE | | Os dados parecem uma data | Timestamp | | Dados que contêm valores verdadeiros/falsos | BOOL | ### Parquet **** | **PARQUET** | **Athena (Seta)** | | --- | --- | | BINARY | VARCHAR | | BOOLEAN | 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/pt_br/athena/latest/ug/connectors-gcs.html) | | INT64 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/athena/latest/ug/connectors-gcs.html) | | INT96 | Timestamp | | MAP | MAP | | STRUCT | STRUCT | | LIST | LIST | ## Permissões obrigatórias Os detalhes completos sobre as políticas do IAM exigidas por esse conector podem ser encontrados na seção `Policies` do arquivo [athena-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.yaml). A lista a seguir resume as permissões necessárias. + **Acesso de gravação do Amazon S3**: o conector requer acesso de gravação a um local no Amazon S3 para mostrar resultados de grandes consultas. + **Athena GetQueryExecution**: o conector usa esta permissão para falhar rapidamente quando a consulta upstream do Athena é encerrada. + **AWS Glue Data Catalog**: o conector GCS requer acesso somente de leitura ao AWS Glue Data Catalog para obter informações do esquema. + **CloudWatch Logs**: o conector requer acesso ao CloudWatch Logs para armazenar registros. ## desempenho Quando o esquema da tabela contém campos de partição e a propriedade `partition.pattern` da tabela está configurada corretamente, você pode incluir o campo de partição na cláusula `WHERE` de suas consultas. Para essas consultas, o conector GCS usa as colunas de partição para refinar o caminho da pasta GCS e evitar a varredura de arquivos desnecessários nas pastas do GCS. Para conjuntos de dados Parquet, selecionar um subconjunto de colunas resulta em menos dados sendo verificados. Isso geralmente resulta em um runtime de consulta mais curto quando a projeção de coluna é aplicada. Para conjuntos de dados CSV, a projeção de colunas não é compatível e não reduz a quantidade de dados que estão sendo digitalizados. As cláusulas `LIMIT` reduzem a quantidade de dados verificados, mas se você não fornecer um predicado, deverá aguardar que as consultas `SELECT` com uma cláusula `LIMIT` verifiquem, no mínimo, 16 MB de dados. O conector GCS examina mais dados para conjuntos de dados maiores do que para conjuntos de dados menores, independentemente da cláusula `LIMIT` aplicada. Por exemplo, a consulta `SELECT * LIMIT 10000` examina mais dados em busca de um conjunto de dados subjacente maior do que de um menor. ### Informações de licença Ao usar esse conector, você reconhece a inclusão de componentes de terceiros, cuja lista pode ser encontrada no arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) desse conector, e concorda com os termos das respectivas licenças de terceiros fornecidas no arquivo [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) em GitHub.com. ### Recursos adicionais Para obter mais informações sobre esse conector, visite [o site correspondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs) em GitHub.com.